Configuration

hawk.spider.custom

Configuration block to enable Custom Scan Discovery by using a third-party developer tool. See the Custom Scan Discovery page for more details.

hawk.scan

Configuration block for HawkScan runtime.

hawk.config

A list of strings passed to the scanner as configuration overrides, such as:

  hawk:
    config:
      - spider.processform=false
      - spider.postform=false

Some useful overrides include:

hawk.outboundProxy

Configuration block for an outbound proxy including

hawk.outboundProxy.credentials

Configuration block for an outbound proxy including

hawkAddOn

Configuration block for HawkScan add-ons and custom scripts.

hawkAddOn.scripts

Configuration block for custom scripts.

hawkAddOn.replacer

Configuration block for the Replacer add-on.

hawkAddOn.replacer.rules

A list of configuration blocks for the Replacer add-on rules. Each configuration block in the list is made up of the following elements. See Configuration Examples for more information.

app

Scanned application parameters, independent of the scanner.

app.graphqlConf

GraphQL scanner parameters.

app.graphql.introspection

GraphQL introspection parameters control enumeration request rate. Useful if the application limits or throttles requests. Adjust the values below to help get the best coverage on application endpoints. May also be adjusted to increase request rates.

app.openApiConf

OpenApi (Swagger) configuration parameters. Use methods (path, filePath, inline) to specify the application’s OpenAPI specification.

app.soapConf

SOAP API scanner parameters.

app.authentication

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.

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.

otherParams:
  - name: "remember_me"
    val: "true"  
  - name: "utf8"
    val: "✓"

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 with the supplied token before scanning. For more information, see the Authenticated Scanning section.

app.authentication.script

Optional configuration block for specifying an authentication script. HawkScan will use this script to perform authentication. Your authentication script will be called before beginning any scanning operations and when re-authentication is required as determined by the authentication.loggedOutIndicator. To learn more about authentication scripts, reference the HawkScan Examples repository.

app.authentication.tokenExtraction

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

app.authentication.cookieAuthorization

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

app.authentication.tokenAuthorization

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

app.authentication.sessionScript

Optional configuration block for specifying a session management script. To learn more about session scripts, reference the HawkScan Examples repository.

app.authentication.testPath

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

Example configuration of app.authentication.testPath

...
    testPath:
      type: HEADER
      path: /user/profile
      success: ".*200.*"
      requestMethod: POST
      requestBody: '{"feeling": "KaaKaww!"}'
      requestHeaders:
        Content-Type: "application/json"

app.waitForAppTarget

Wait for Target scanner parameters.

app.redact

Redaction policy of scan logs and stdout when scanning this application.

HawkScan maintains a list of redacted tokens; strings that are sensitive and should be scrubbed preemptively from logs and collected messages. By default, HawkScan redacts app.authentication credentials, and any provided script / discovery credentials.

tags BETA

Scan tags are name value pairs that represent metadata you can use to capture additional state or context around a scan. Examples could include commit SHAs, branch names, or project management issue titles.

Tag names can use any combination of the following characters: a-zA-Z-_, and their values can be any string. Tag entries can also be interpolated from the environment.

NOTE: Tag names beginning with _STACKHAWK are in a reserved tag name space.

The following selection of YAML is an example of how you can configure your stackhawk.yml file to include scan tags:

stackhawk.yml

app:
  applicationId: <application-uuid>
  env: localhost
  host: http://localhost:8080
tags:
  - name: category
    value: hawksome
  - name: Another-Value
    value: ${SOMETHING_FROM_ENV:default}
  - name: _GIT_COMMIT_SHA
    value: ${MY_COMMIT_SHA_ENV:HEAD}
...

Currently, scan tags are not visible in the StackHawk Platform, but can be accessed by the StackHawk Webhook Integration or using the StackHawk API.

Environment Variable Runtime Overrides

HawkScan will attempt to interpolate any environment variables from the stackhawk.yml at runtime in place of existing configuration values. When defining any value for any parameter in your stackhawk.yml configuration, the ${ENV_VAR:default_value} syntax can be used to supply the defined ENV_VAR (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}

Note that HawkScan will not interpolate the value of a variable into a larger string, such as "this-will-not-work-${ENV_VAR}".

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

• Providing ease of configuration in different operational environments / developer machines.
• Dynamic runtime configuration for running HawkScan in build pipelines.
• Discouraging 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 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 -t 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 -t 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 -t 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... -t 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... -t 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

runtime-config

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

Examples

Replacer Plugin Configuration

The replacer plugin allows you to either replace or inject headers on each HTTP request.

Example: Inject a New Header

Configure the replacer addOn in the following way to force a new header in every request.

Note that if the header exists in a request it will also be replaced by the replacement value.

Explanation:

• matchString is a string value to set the injected header’s key (e.g. x-requested-with)
• replacement is the injected header’s value (e.g. fetch)
• replaceOnly is set to false to enable header injection

...
hawkAddOn:
  replacer:
    rules:
      - matchString: "x-requested-with"
        replacement: "fetch"
        replaceOnly: false
...

Resulting Request Header:

POST http://localhost:9000/ws HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:82.0) Gecko/20100101 Firefox/82.0
Pragma: no-cache
Cache-Control: no-cache
Content-Length: 999
Content-Type: text/xml;charset=UTF-8
x-requested-with: fetch
Host: localhost:9000

Example: Replace an Existing Header - Simple

Configure the replacer addOn in the following way to exactly match and replace an existing header in every request.

Explanation:

• matchString is a string value that exactly matches the header text to be replaced
  • In this example, matchString is an exact match of the full header pair with both the header key and value
• replacement is the replacement for matchString
  • The replacement string should include both the replacement header’s key and value if an entire header pair is to be replaced
• replaceOnly set to true to avoid injecting a new header
• isRegex set to false makes this replacement dependent on an exact string match
  • Note: partial matches of a header line will occur if, for example, only the header key is provided in matchString (e.g. User-Agent). In this case, starting at the beginning of the header line, only the matching portion will be replaced. Any text following the match on the line will remain the same.

...
hawkAddOn:
  replacer:
    rules:
      - matchString: "User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:82.0) Gecko/20100101 Firefox/82.0"
        replacement: "User-Agent: HawkScan custom User Agent (v9.42)"
        replaceOnly: true
        isRegex: false
...

Resulting Request Header:

POST http://localhost:9000/ws HTTP/1.1
User-Agent: HawkScan custom User Agent (v9.42)
Pragma: no-cache
Cache-Control: no-cache
Content-Length: 999
Content-Type: text/xml;charset=UTF-8
Host: localhost:9000

Example: Replace an Existing Header - Regex

Explanation:

• matchString is a regex value matching the header text to be replaced
  • In this example, User-Agent.* matches the entire header line beginning with User-Agent
• replacement is the replacement for matchString
  • The replacement string will replace everything found within the regex match group
• replaceOnly set to true to avoid injecting a new header
• isRegex sets the matchString as a PCRE regex value rather than a simple string value
  • Note: partial matches of a header line will occur if only part of the header value or the header key is provided in matchString. In this way, any portion of a header line may be by the replacement text.

Full Line Replacement

...
hawkAddOn:
  replacer:
    rules:
      - matchString: "User-Agent.*"
        replacement: "User-Agent: HawkScan custom User Agent (v9.42)"
        replaceOnly: true
        isRegex: true
...

Resulting Request Header:

POST http://localhost:9000/ws HTTP/1.1
User-Agent: HawkScan custom User Agent (v9.42)
Pragma: no-cache
Cache-Control: no-cache
Content-Length: 999
Content-Type: text/xml;charset=UTF-8
Host: localhost:9000

Partial Line Replacement

...
hawkAddOn:
  replacer:
    rules:
      - matchString: "Gecko/20100101.*"
        replacement: "Gecko/99999999 Chrome/99.42"
        replaceOnly: true
        isRegex: true
...

Resulting Request Header:

POST http://localhost:9000/ws HTTP/1.1
User-Agent: Mozilla/5.0 (Windows NT 10.0; Win64; x64; rv:82.0) Gecko/99999999 Chrome/99.42
Pragma: no-cache
Cache-Control: no-cache
Content-Length: 999
Content-Type: text/xml;charset=UTF-8
Host: localhost:9000

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.

# Application specific configuration
app:
  # An applicationId obtained from the StackHawk Platform.
  applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW # (required)
  # The environment for the applicationId defined in the StackHawk Platform.
  env: Development # (required)
  # The url of your application to scan
  # Note: Must use port range 1024..65535 when scanning localhost
  host: ${authority}://${host}:${port} # https://localhost:3000 (required)
  # The risk level of the app
  riskLevel: MEDIUM # (deprecated)
  # The type of data sensitivity the web app maintains
  appDataType: PII # (deprecated)
  # Regex paths you want excluded entirely from the scan
#  excludePaths: # (optional)
#    # - "/assets/.*" (required)
#    # - "/dont-scan-this-page"
#  # The names of your session tokens aka: cookie names
#  sessionTokens: # (optional)
#    # - "_toy_app_session" (required)
#  # 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: # (optional)
#    # 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: # (optional)
#      # POST authentication credentials as application/x-www-form-urlencoded
#      # Set type to JSON to POST as application/json.
#      type: # FORM (required)
#      # The route to POST credentials to authenticate as a user
#      loginPath: # /login (required)
#      # The route that serves the login form. The anti-csrf parameter
#      # 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)
#      # returned from a GET request will be extracted from the response.
#      loginPagePath: # /login (optional)
#      # Other request parameters that may be required by your log in payload
#      otherParams: # (optional)
#        # - name: utf8 (required)
#        #   val: "✓" (required)
#        # - name: "session[remember_me]"
#        #   val: "0"
#    # Maintain authorized session via cookie.
#    cookieAuthorization: # (optional)
#      # Names of cookies used to track a users session
#      cookieNames: # (required)
#        # - "_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: # (optional)
#      # Set to BODY to match against response body instead of HEADER.
#      type: # HEADER (default)
#      # Protected path to send GET/POST request validation.
#      path: # /profile (required)
#      # 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.*" (required)
#      # The request method for authentication validation.
#      # GET/POST/PUT
#      requestMethod: # GET (default)
#      # The request body for POST/PUT authentication validation.
#      requestBody: # foo=bar&hawk=foo  (optional)
#      # Key/value pairs containing valid arbitrary headers e.g.
#      requestHeaders:  # (optional) 
#        Content-Type: application/json
#    # Externally supplied authorization token.
#    # Use as an alternative to usernamePassword authentication
#    external: # (optional)
#       # A token type external credential.
#       # Set to COOKIE to supply an externally sourced cookie
#       type: # TOKEN (required)
#       # 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} (required)
#    # 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 authentication.
#       # Set to HEADER_NAME if your authorization token is returned as a response header.
#       type: # TOKEN_PATH (required)
#       # The path to the token or name of the header.
#       value: # "auth.token" (required)
#    # Use token based authorization instead of cookie based.
#    # Tokens are passed on all requests to maintain authorized access
#    # to your application
#    tokenAuthorization: # (optional)
#      # The way to pass the token on requests. Set to QUERY_PARAM
#      # to pass your token as part of the query string instead of a header.
#      type: # HEADER (required)
#      # The name of the header or query param.
#      value: # Authorization (required)
#      # The token type which will be prepended to your authorization header.
#      # ie: Authorization: Bearer <token>
#      # Leave undefined if not applicable.
#      tokenType: # Bearer <token> (optional)
#  # Path to openapi 2 spec file or inline openapi 2 spec yaml
#  # Note: default '/' == '{app.host}/openapi.json'
#  api: # "/myopenapi.json" # (deprecated) Use app.openApiConf instead
#  # Enable GraphQL support
#  graphqlConf:
#    # GraphQL introspection path [default: /graphql]
#    schemaPath: /
#    # Request method to use for queries [POST|GET]
#    requestMethod: POST
#    # Request method to use for queries [ALL|QUERY|MUTATION]
#    operation: ALL
#    # Set the max length of URIs when generating GET queries
#    uriMaxLength: 4000
#    # Provide the relative path to a JSON formatted schema file [default: None]
#    # Note: also requires schemaPath to be set if not at the standard /graphql endpoint  
#    filePath: schema.json
#    # Set the request parameters for introspection and enumeration
#    introspection:
#      # Number of requests to make at each interval
#      requestsPerCycle: 20
#      # Delay interval for request cycles
#      requestDelay: 1000
#  soapConf:
#    # Host path to the SOAP WSDL, prefixed with a /
#    path: /ws/descriptor.wsdl
#    # Relative path to the SOAP WSDL schema definition file  
#    filePath: descriptor.xsd
#
## Parameters affecting scanner runtime.
#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)
#
## Parameters for addOns and custom scripts
#hawkAddOn: # (optional)
#  # Replacer addOn configuration
#  replacer: # (optional)
#    # List of rules for the Replacer addOn
#    rules: # (optional)
#      # Rules begin with _matchString_ key.
#      # - matchString: 'Referer.*' # (required)
#      #   replacement: 'Referer: banana.com' # (required)
#      #   replaceOnly: true
#      #   isRegex: true
#      # - matchString: 'Content-Type'
#      #   replaceOnly: false
#      #   isRegex: false
#      #   replacement: 'application/json'
#  # Custom scripts configurtation
#  scripts: # (optional)
#    # Scripts begin with the _name_ key.
#    # - name: # 'json-auth.js' (required)
#    #   type: # 'authentication' (required)
#    #   path: # ${PWD}/../zap_scripts (required)