Link

Configuration

HawkScan Configuration

HawkScan uses a YAML configuration file to supply operational settings to the scanner. The behavior of the vulnerability scan can be modified by setting these configuration options.

When HawkScan starts up, it will first look for a file in the working directory named stackhawk.yml . This is the YAML configuration file that describes how the application should be scanned.

The bare-minimum configuration for the stackhawk.yml file needed to run HawkScan is:

stackhawk.yml

app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Test
  host: http://localhost:3000

The stackhawk.yml configuration is split into two top level sections:

  • hawk configuration for the scanner, and how it should look for vulnerabilities.
  • app configuration for the application, and specifics for how it should be scanned.

Configuration Options

Below is a description of the configuration sections and their default values.

hawk

Configuration block for the scanner, independent of the scanned application. Sub-configuration blocks are defined below.

Parameter Default Description
.startupTimeoutMinutes 5 Maximum time to allow for the scanner application to start up.
.spider {} Read more
.failureThreshold The lowest alert level that returns a failed scan status.

hawk.spider

Configuration block for the application web crawler / spider.

Parameter Default Description
.base true Enable the basic web crawler for discovering your application’s routes. This spider is appropriate for most traditional web applications.
.ajax false Enable the ajax web crawler for discovering your application’s routes. This spider is appropriate for single-page web applications.
.maxDurationMinutes 2 Maximum allowed time for enabled spiders to crawl your web application.

app

Configuration block for the scanned application, independent of the scanner. Sub-configuration blocks are defined below.

Parameter Default Description
.applicationId (required) The applicationId created in the StackHawk Platform.
.env (required) The env created in the StackHawk Platform.
.host (required) The url of the application to scan, provided as a string. The only required configuration for HawkScan. If the url cannot be reached, the scan will not proceed.
.sessionTokens [] The names of any session tokens used by your application, provided as an array of strings (Hint: these are the names of session cookies used by your application).
.antiCsrfParam "" The name of your CSRF security parameter used in any application form inputs. Globally set, HawkScan will parse this parameter value from form responses to use in subsequent requests. For more information, see the page on CSRF Defense Recommendations.
.appDataType ""

Indicates to HawkScan the type of data sensitivity of the application, provided as a string. Possible values include:

  • "" (empty string)
  • "PII"
  • "PCI"
  • "FIN"
  • "PKI"
  • "HIPPA"
  • "FERPA"

If in doubt, this setting can be safely left unconfigured.

.riskLevel "MEDIUM" How important is this application to the business? This should be set to either"HIGH", "MEDIUM", or "LOW" (ex. Critical application that the business runs on = HIGH, Internal employee phone directory = LOW).
.api ... Either a string relative path to an OpenAPI v2 specification file (JSON or YAML) or the specification block itself (YAML). For more information, see the OpenAPI configuration section.
.excludePaths [] An array of strings, used as regexes to match against routes that should be ignored entirely by HawkScan.

ex: /images will exclude specifically one route, while /images/.* will exclude all routes starting with /images/

This field is useful for prohibiting asset directories or other resources that don't require vulnerability scanning.
.authentication {} Read more

app.authentication

Optional configuration block for application authentication to enable scanning as the provided user of your application. If provided, HawkScan will first attempt to sign into your web application with the provided login credentials. Only after successfully verifying will scanning occur. For more information, see the Authenticated Scanning section.

Parameter Default Description
.loggedInIndicator (required) A regex to match against http responses from pages in the web application to determine if the scanned pages user session is still logged in to the app, provided as a string (ex. "\\Qsigned in as\\E").

The regex pattern is matched against the header and body of each response the scanner receives from your application.
.loggedOutIndicator (required)

A regex to match against http responses from pages in the web application to determine if the scanned pages user session is logged out of the app, provided as a string (ex. "\\Qlog in\\E").

The regex pattern is matched against the header and body of each response the scanner receives from your application.

If the content of a response matches the regex it will trigger a re-authentication. Currently this is only supported by usernamePassword authentication.

.usernamePassword {} Do not configure if using external. Read more
.external {} Do not configure if using usernamePassword. Read more
.tokenExtraction {} Read more
.cookieAuthorization {} Do not configure if using tokenAuthorization. Read more
.tokenAuthorization {} Do not configure if using cookieAuthorization. Read more
.testPath {} Read more

app.authentication.usernamePassword

Optional configuration specifying a username and password based authentication configuration. Currently POSTing the credentials via FORM or JSON type is supported. Use in conjunction cookieAuthorization or tokenAuthorization to maintain authorized access to your application.

Parameter Default Description
.type FORM

An enum value describing the type of POST data expected by the loginPath,FORM and JSON values are supported.

JSON=application/json

FORM=application/x-www-form-urlencoded

.loginPath (required) Your login route to POSTcredentials for a user in the application, provided as a string (ex./login). An http POST request using as the type specified will be made to this path.
.loginPagePath (optional) The path to your login form, if applicable. This is an optional path but is often required if the POST to the loginPath requires an anti csrf token to be passed as part of the POST . The app.antiCsrfParam will be extracted from the response body of a GET request to this page.
.usernameField (required) The username field used in your application form or json, provided as a string.
.usernameField (required) The password field used in your application form or json, provided as a string.
.otherParams []

Other request parameters required by your login payload, provided as an array of objects with name and value string keys. For example, providing otherParams as:

otherParams:
- name: "remember_me"
val: "true"
- name: "utf8"
val: "&#x2713"

will then attach remember_me=true&utf8=✓ to the form parameters or {"remember_me" : "true, "utf8" : "✓"}
to the JSON payload.


This setting is helpful if your authentication process requires other parameters included in the form POST besides the username and password parameters. If in doubt, this setting can be safely left unconfigured.

.scanUsername (required) The username credentials provided to authentication when attempting to login to the web application, provided as a string. HawkScan best practices recommend using environment variable runtime overrides for this value (ex. "${SCAN_USERNAME:admin}" will use the $SCAN_USERNAME environment variable as the scanUsername, or fallback to admin ).
.scanPassword (required) The password credentials provided to authentication when attempting to login to the web application, provided as a string. HawkScan best practices recommend using environment variable runtime overrides for this value (ex. "${SCAN_PASSWORD}" will use the $SCAN_PASSWORD environment variable as the scanPassword) .

app.authentication.external

Optional configuration block for specifying an externally supplied authorization token, HawkScan will attempt to access a protected path in your web application withe the supplied token before scanning. For more information, see the Authenticated Scanning section.

Parameter Default Description
.type TOKEN An enum value representing the type of token being specified. Currently TOKEN and COOKIE are the only values allowed. If COOKIE is specified the .external.value should be in the form of a cookie value <cookie-name>=<cookie-value> .
.value (required) The value containing the token that will authorize requests. How the token is passed to your application is determined by the

app.authentication.tokenExtraction

Token extraction is optional unless you’re using the tokenAuthorization in combination with usernamePassword authentication. The tokenExtractionconfiguration specifies how to extract the authorization token from the authentication response.

Parameter Default Description
.type TOKEN_PATH An enum value representing the method of extraction. TOKEN_PATH or HEADER are the only supported values. Specifying TOKEN_PATH tells HawkScan to extract the token from the JSON payload of the response from authentication. HEADER tells HawkScan to extract the token from a header in the response from authentication.
.value (required) String containing the path to the token in the JSON payload authentication response or the name of the response header containing the token. Example if the authentication response JSON payload looks like,{"auth" : {"token": "<my-auth-token>"}} the value would be auth.token. If the authentication response has a header named AuthToken: <my-token>, then the value should be AuthToken.

app.authentication.cookieAuthorization

An optional configuration specifying if authorization is maintained via a cookie session.

Parameter Default Description
.cookieNames [] A list of strings that are the names of cookie(s) that will be used for maintaining a session. Typically this is one value like jsessionid or PHPSESS. When used in combination with authentication HawkScan will use this value to persist authenticated session state with your application.

app.authentication.tokenAuthorization

An optional configuration telling HawkScan how to pass the authorization token to your application on each request to maintain authorized access.

Parameter Default Description
.type HEADER An enum value representing how to pass the authorization token to your application. HEADER or QUERY_PARAM are the only supported values. HEADER indicates that each request should have the authorization token added a header to the requests. QUERY_PARAM indicates that the token should be passed as a query parameter.
.value (required) The name of the HEADER or QUERY_PARAM the token should be passed as.
.tokenType (optional) A string that will be pre-pended to value of the token describing its type. This is often required for Bearer or JWT Authorization headers as a modifier signaling the type of token expected.

app.authentication.testPath

A configuration specifying how to verify authentication/authorization is working before running a scan. User either success or fail criteria to determine if authorized access is working correctly.

Parameter Default Description
.type HEADER An enum value representing the what to match against in the response from issuing a GET request to the testPath.path. The supported values are HEADER and BODY.
.path (required) The path to a protected route in your application that requires authorization. For example /mysettings. A GET request will be made to this path using the configured authentication.
.success (one of)

A regex that will match against the response header or body, specified by type, of the GET request to the path. A match of the regex supplied will indicate that the GET request to path was successful and scanning should proceed with the specified authentication.

One of types success ,fail

.fail (one of)

A regex that will match against the response header or body, specified by type, of the GET request to the path. A match of the regex supplied will indicate that the GET request to path failed and scanning should not proceed with the specified authentication.

One of types success ,fail

.requestMethod (one of)

The request method to use for authentication verification. If using POST or PUT methods, a value must also be provided to the requestBody.

One of types GET ,POST, PUT

.requestBody ...

The request content to send along with POST or PUT requests for authentication verification.

Environment Variable Runtime Overrides

HawkScan will attempt to interpolate any environment variables from the stackhawk.yml at runtime in place of existing configuration. When defining any string in your stackhawk.yml configuration, the ${ENV_VAR:default_value} syntax can be used to supply the defined ENV_VAR into the string (or if the ENV_VAR environment variable is not set, it will instead use the alternative default_value ). A default value is not required for interpolation; if no default is provided and ENV_VAR is not assigned, the value will be interpreted as an empty string "" .

For example:

app:
  formAuth:
    scanUsername: "${SCAN_USERNAME:admin}"
    scanPassword: "${SCAN_PASSWORD}"

The ${ENV_VAR:default_value} runtime override serves many purposes, including:

  • Provides ease of configuration in different operational environments / developer machines.
  • Dynamic runtime configuration for running HawkScan in build pipelines.
  • Discourages the use of including sensitive credentials in configuration files.

HawkScan best practices recommends using environment variable runtime overrides for all of the above scenarios.

Environment Variable Configuration

HawkScan also accepts certain environment variables for modifying the behavior of the runtime scanner. The presence of a nonempty value for any of these variables will enable them for the scanner at runtime:

Environment Variable Description
SHAWK_DEBUG Run the scanner with verbose logging
NO_COLOR Disables colored terminal output from the scanner

Environment Variables are passed into the docker command line with the -e parameter:

docker run -e SHAWK_DEBUG=true -e API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx --rm -v $(pwd):/hawk:rw -it stackhawk/hawkscan:latest

Using Custom YAML Configurations

The default YAML file used by HawkScan is the stackhawk.yml file located in the current working directory. However this file can be changed by supplying the file name as an argument to the docker command.

This may be required for your project if you have multiple web applications in a single project, or if you have vastly different configuration needs across environments.

For example, you could define separate configurations stackhawk-app1.yml and stackhawk-prod.yml , and then invoke the scanner with:

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx -it stackhawk/hawkscan stackhawk-app1.yml

and then in a different environment you can run the scanner with:

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk.xxxxxxxxxxxxxxxxxxxx.xxxxxxxxxxxxxxxxxxxx -it stackhawk/hawkscan stackhawk-prod.yml

Multiple Configuration Files

To support multiple environments and other custom configuration needs you can provide multiple configuration files as overrides to a base configuration.

For example if you have different authentication styles between environments, or if you simply prefer to manage configuration with files instead of environment variable overrides.

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk... -it stackhawk/hawkscan stackhawk.yml stackhawk-dev.yml

Each configuration file will be merged on top of the prior. For example…

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk... -it stackhawk/hawkscan stackhawk.yml stackhawk-test.yml docker-test.yml

stackhawk.yml

app:
    applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
    env: Development
    host: http://localhost:3000

stackhawk-test.yml

app:
    env: Test
    host: https://myapp.test.example.com:3000

docker-test.yml

app:
    host: http://myapp:3000

ruintime-config

app:
    applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
    env: Test
    host: http://myapp:3000

Detailed Configuration Example

This is an example full-featured stackhawk.yml file with added inline documentation.

  • default denotes the value when not supplied in your YAML file. Defaulted parameters must have a valid value.
  • required denotes that the value is required and must be set to enable the feature of the scanner.
  • optional denotes that the parameter is optional and may or may not have a default value.
# Information for the scan that is independent of the application
hawk:
  # Web crawler / spider configuration
  spider:
    # Enable the base spider for discovering your app's routes
    base: true # (default)
    # Enable the ajax spider for discovering your single page app
    ajax: false # (default)
    # Maximum time for spider to discover routes in your app
    maxDurationMinutes: 2 # (default)
  # Maximum time to wait for the scanner to start up
  startupTimeoutMinutes: 5 # (default)
  # Minimum alert level for a scan fail result:
  # LOW|MED|HIGH 
  failureThreshold: HIGH # (optional)
   


# Application specific configuration
app:
  # An applicationId obtained from the StackHawk platform.
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX # (required)
  # The environment for the applicationId defined in the StackHawk platform.
  env: Development # (required)
  # The url of your application to scan
  host: http://localhost:3000 # (required)
  # The risk level of the app
  riskLevel: MEDIUM # (optional)
  # The type of data sensitivity the web app mantains
  appDataType: PII # (optional)
  # Regex paths you want excluded entirely from the scan
  excludePaths:
    - "/assets/.*"
    - "/dont-scan-this-page"
  # The names of your session tokens aka: cookie names
  sessionTokens: # (optional)
    - "_toy_app_session"
  # The name of your anti csrf parameter
  antiCsrfParam: authenticity_token # (optional)

  # Authentication configuration for scanning as a user.
  # Enabling will force the scanner to scan as an
  # authenticated user of your app.
  authentication:
    # A regex to match against http responses to determine if the scan user is
    # still logged in to your app
    loggedInIndicator: "\\QLog out\\E" # (required)
    # A regex to match against http responses to determine if the scan user is
    # logged out of your app
    loggedOutIndicator: "\\QLog in\\E" # (required)
    # Username password based authentication method.
    usernamePassword:
      # POST authentication credentials as application/x-www-form-urlencoded
      # Set type to JSON to POST as application/json.
      type: FORM
      # The route to POST credentials to authenticate as a user
      loginPath: /login # (required)
      # The route that serves the login form. The anti-csrf parameter
      # returned from a GET request will be extracted from the response.
      loginPagePath: /login # (optional)
      # The username field name in your authentication payload.
      usernameField: session[email] # (required)
      # The password field name in your authentication payload.
      passwordField: session[password] # (required)
      # The username to authenticate as when scanning
      scanUsername: ${SCAN_USERNAME} # (required)
      # The password of the scanUsername
      scanPassword: ${SCAN_PASSWORD} # (required)
      # Other request parameters that may be required by your log in payload
      otherParams: # (optional)
        - name: utf8
          val: "&#x2713;"
        - name: "session[remember_me]"
          val: "0"
    # Maintain authorized session via cookie.
    cookieAuthorization:
      # Names of cookies used to track a users session
      cookieNames:
        - "_toy_app_session"
    # A path and criteria for asserting authentication is working correctly.
    # The path should be a protected route that can only be accesed
    # by an authenticated user. Before running a scan this path will be
    # requested to verify authenticated access is working correctly.
    testPath:
      # Match criteria against the HEADERs. Set to BODY to match against
      # reponse body instead.
      type: HEADER
      # The protected path to issue a GET/POST request to.
      path: /profile
      # A regex to match against that will indicate a successful authorized
      # request. Configure fail criteria to match against a failed
      # authorized request. Example: fail:".*302.*Location.*/login.*"
      success: ".*200.*"
      # The request method for authentication validation.
      # GET/POST/PUT
      requestMethod: GET # (optional) 
      # The request body for POST/PUT authentication validation.
      requestBody: foo=bar&hawk=foo  # (optional)
#    # Externally supplied authorization token.
#    # Use as an alternative to usernamePassword authentication
#    external:
#      # A token type external credential.
#      # Set to COOKIE to supply an externally sourced cookie
#      type: TOKEN
#      # The value of the token passed as an environment variable at runtime.
#      # When type=COOKIE the value format should be <cookie-name>=<cookie-value>
#      value: ${AUTH_TOKEN}
#    # Describe how to extract your apps authorization token.
#    # This should only be used with tokenAuthorization
#    tokenExtraction:
#      # The type of extraction to use. TOKEN_PATH is the path to the token in
#      # the JSON payload returned from usernamePassword authenticsation.
#      # Set to HEADER if youtr authorizarion token is retuned as a response header.   
#      type: TOKEN_PATH
#      # The path to the token or name of the header.
#      value: "auth.token"
#    # Use token based authorization instead of cookie based.
#    # Tokens are passed on all requests to maintain authorized access
#    # to your application
#    tokenAuthorization:
#      # The way to pass the token on requests. Set to QUERY_PARAM
#      # to pass your token as psrt of the query string instead of a header.
#      type: HEADER
#      # The name of the header or query param.
#      value: Authorization
#      # The token type which will be prepended to your authorization header.
#      # ie: Authorization: Bearer <token>
#      # Leave undefined if not applicable.
#      tokenType: Bearer

  # Path to openapi 2 spec file or inline openapi 2 spec yaml
  api: "app.openapi.json" # (optional)

Copyright © 2019-2020 StackHawk, Inc.