Configuration

HawkScan Configuration

HawkScan depends on the stackhawk.yml configuration file. See YAML configuration for more information.

Write the base stackhawk.yml configuration to the current directory.

stackhawk.yml

app:
  applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW
  env: Test
  host: http://localhost:port

Configuration Options

The HawkScan configuration. The stackhawk.yml file follows this structure. A run of HawkScan will use this configuration to inform the scanner how to operate.

The minimum stackhawk.yml required will require the following:

app:
applicationId: kkAAAKAW-kAWW-kkAA-WWwW-kAAkkAAAAwWW
env: Test
host: http://localhost:1337

Signup for a StackHawk account and Get Started.

hawk

Configuration preferences for HawkScan, independent of the scanned application.

hawk.spider

Configuration block for the application crawling and Discovery Phase aka Spider. See the Scan Discovery page for more details.

hawk.spider.custom

Configuration for custom scan discovery. See the Custom Scan Discovery section for more details.

hawk.spider.har

Configuration for using a HAR file as the discovery for a scan. HAR files often contain requests including urls from many hosts, but only URLs matching the app.host or replaceHost will be included in the scan.

hawk.spider.har.file

Paths to .har HTTP Archive formatted files, for use with HARImportConfig.

hawk.spider.har.dir

Paths to directories, for use with HARImportConfig.

hawk.scan

Configuration block for HawkScan runtime.

hawk.outboundProxy

Configuration block for a proxy. This enables HawkScan to traffic scanner requests through an outbound network proxy.

hawk.outboundProxy.credentials

Credential details for the outbound proxy behavior.

app

Configuration parameters for the scanned application, independent of the scanner.

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.

app.authentication.usernamePassword.otherParams

General name / value parameter.

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.external.values

Configuration for Token Authentication.

app.authentication.external.values.value

General name / value parameter.

app.authentication.script

Configuration for a custom authentication script. HawkScan will run the provided authentication script until a request matches the loggedInIndicator, or if the loggedOutIndicator is tripped on a request. The authentication script name should also be included in the hawkAddOn.scripts.name

app.authentication.externalCommand

Optional configuration block allowing HawkScan to run a specified command line process. HawkScan will attempt to access a protected path in your web application with the supplied headers or cookies before scanning. For more information, see the Authenticated Scanning section.

app.authentication.oauth

Optional configuration block allowing HawkScan to authorize requests with a 3rd party OAuth 2.0 auth provider.

app.authentication.oauth.credentials

app.authentication.oauth.parameters

app.authentication.tokenExtraction

Token extraction is optional unless you’re using the tokenAuthorization in combination with usernamePassword authentication. This 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 custom session management script. To learn more about session scripts, reference the HawkScan Examples repository.

app.authentication.testPath

A configuration specifying how to verify if Scan authentication and authorization is working before running a scan.

An example configuration of app.authentication.testPath:

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

This uses either success or fail criteria to determine if authorized access is working correctly.

app.graphqlConf

GraphQL scanner parameters. See the StackHawk graphQL configuration docs for more details.

app.graphqlConf.excludeOperations

A GraphQL operation to exclude from the spider by name and type.

app.graphqlConf.customVariables

Custom variable data specific to OpenAPI schemas.

app.openApiConf

OpenApi scanner parameters. See the StackHawk OpenAPI configuration docs for more details.

app.openApiConf.deprecatedCustomVariables

Generic custom variable for different API types.

app.openApiConf.customVariables

Custom variable data specific to OpenAPI schemas.

app.soapConf

SOAP API scanner parameters. See the StackHawk SOAP configuration docs for more details.

app.grpcConf

gRPC API scanner parameters. See the gRPC configuration docs for more details.

app.grpcConf.customVariables

Generic custom variable for different API types.

app.inputVectors

Fine-grained configuration of HawkScan input vectors. This configuration is how and where testable inputs are applied on http requests.

app.inputVectors.injectableParam

Advanced Configuration* The specific parts of an http request that can be modified by HawkScan.

Different http protocols like REST (OpenAPI) graphQL gRPC and SOAP use different parts of http requests to function. This setting is configured dynamically depending on the scan protocol used, and should only be modified for advanced scan configuration.

Enabling additional injectable params will increase scan time. Do not set these values unless instructed to by StackHawk Support.

app.inputVectors.enabledRpcParam

Advanced Configuration* The specific input shapes for http request bodies made by HawkScan. Enabling additional RPC params will increase scan time. Do not set these values unless instructed to by StackHawk Support.

app.waitForAppTarget

A configuration specifying how to determine if app is up and ready or scanning.

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.

app.scanPolicy

hawkAddOn

Configuration block for HawkScan add-ons and custom scripts.

hawkAddOn.replacer

Configuration block for header value replacement. These rules support manipulating request headers, useful for modifying requests to web applications running behind a proxy.

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.

hawkAddOn.scripts

Configuration block for custom scripts.

hawkAddOn.scripts.vars

General name / value parameter.

tags

Scan tags are name value pairs that represent metadata of the scan, capturing additional state or context around a scan.

Examples could include adding 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}

hawkAddon.replacerRules.initiators

ReplacerRule Initiators.

hawkAddon.scripts.type

One of the following custom script types : active, authentication, httpsender, passive, proxy, standalone, targeted, session.

hawkAddon.scripts.language

A supported scripting language interpreter for custom scripts.

nameValParam

General name / value parameter.

hawk.config

The hawk.config setting accepts strings that can be accepted and used by the HSTE as advanced configuration. Because HSTE may accept and define its own configuration, this list is not exhaustive.

This list may improve or change over time.

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

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