Configuration

The complete stackhawk.yml config guide

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:
host: http://localhost:3000

The stackhawk.yml configuration is split into two 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

This is a list of all available configuration options and their default values:

Option

Default

Description

hawk

...

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

hawk.

spider

...

Configuration block for the application web crawler / spider.

hawk.spider.

base

true

Enable the basic web crawler for discovering your application's routes. This spider is appropriate for most traditional web applications.

hawk.spider.

ajax

false

Enable the ajax web crawler for discovering your application's routes. This spider is appropriate for single-page web applications.

hawk.spider.

maxDurationMinutes

2

Maximum allowed time for enabled spiders to crawl your web application.

hawk.

startupTimeoutMinutes

5

Maximum time to allow for the scanner application to start up.

app

...

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

app.

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.

app.

contactEmail

""

A string field for HawkScan alpha customers to provide a voluntary email contact we can reach out to if we identify any bugs in HawkScan or in your application scan. If we notice a bug, we'll use this email to reach out and learn more or provide a fix. We will never use this contact for marketing purposes.

app.

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).

app.

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.

app.

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.

app.

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).

app.

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.

app.

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.

app.

formAuth

...

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. For more information, see the Authenticated Scanning section.

app.formAuth.

loginPath

(required)

The route to your login form and its POST action to authenticate a user in the application, provided as a string (ex./login). An http POST request using as the content-typeapplication/x-www-form-urlencoded will be made to this path. Any returned cookies matching those found in app.sessionTokens will be included in http requests made by the scanner ensuring authorized access to protected paths.

app.formAuth.

logoutPath

(required)

The route to logout an authenticated user from the application, provided as a string (ex /logout).

app.formAuth.

usernameField

(required)

The username field used in your application form, provided as a string.

app.formAuth.

passwordField

(required)

The password field used in your application form, provided as a string.

app.formAuth.

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").

app.formAuth.

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").

app.formAuth.

otherParams

[]

Other request parameters required by your login form, 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 in the form authentication request. 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.

app.formAuth.

scanUsername

(required)

The username credentials provided to the form 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 ).

app.formAuth.

scanPassword

(required)

The password credentials provided to the form 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.

jsonAuth

(optional)

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. For more information, see the Authenticated Scanning section.

app.jsonAuth.

loginPath

(required)

The route your login form POSTs to, to authenticate a user in the application, provided as a string (ex./login). An http POST request using application/json as the content type will be made to this path. This path should return a JSON payload containing the authorization token located at payloadTokenPath . The returned token will used as the authorization header value in the format of a bearer token for all request made by the scanner. ie: Authorization: Bearer <token>

app.jsonAuth.

usernameField

(required)

The username field name used in your JSON payload, provided as a string.

app.jsonAuth.

passwordField

(required)

The password field name used in your JSON payload, provided as a string.

app.jsonAuth

payloadTokenPath

(required)

The path to the field in the returned JSON payload that will contain the authentication token passed as an Authorization header on requests.

app.jsonAuth.

scanUsername

(required)

The username credentials provided to the form 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 ).

app.jsonAuth.

scanPassword

(required)

The password credentials provided to the form 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.jsonAuth.

authTokenName

Bearer

The name of the token in the Authorization header. ie: Authorization: Bearer <token>

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 --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 -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 -it stackhawk/hawkscan stackhawk-prod.yml

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)
# Application specific configuration
app:
# The url of your application to scan
host: http://localhost:3000 # (required)
# Our scanner's capability is still in Alpha; If we notice a bug we'll use this email to reach out or provide a fix.
# We will never use this contact for marketing purposes.
contactEmail: your_email@company.com # (optional)
# 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)
# Form POST based authentication configuration for scanning as a user.
# Enabling will force the scanner to scan as an
# authenticated user of your app.
# Autenticated requests will pass cookies received from the form POST
# to maintain authentication.
formAuth: # (optional)
# The route to a form POST to authenticate a user
loginPath: /login # (required)
# The route to logout a user
logoutPath: /logout # (required)
# The username field name in your authentication form
usernameField: session[email] # (required)
# The password field name in your authentication form.
passwordField: session[password] # (required)
# The username to authenticate as when scanning
scanUsername: ${SCAN_USERNAME} # (required)
# The password of the scanUsername
scanPassword: ${SCAN_PASSWORD} # (required)
# 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)
# Other request parameters that may be required by your log in form
otherParams: # (optional)
- name: utf8
val: "&#x2713;"
- name: "session[remember_me]"
val: "0"
# JSON POST based authentication configuration for scanning as a user.
# Enabling will force the scanner to scan as an
# authenticated user of your app.
# Authenticated requests will use the token returned from the POST
# request to loginPath, and identifed by payloadTokenPath,
# as the Authorization header to requests.
# The Authorization header is in the form of a Bearer token ie:
# Authorization: Bearer <token>
jsonAuth: # (optional)
# The route to a form POST to authenticate a user
loginPath: /login # (required)
# The username field name in your authentication form
usernameField: email # (required)
# The password field name in your authentication form.
passwordField: password # (required)
# The username to authenticate as when scanning
scanUsername: ${SCAN_USERNAME} # (required)
# The password of the scanUsername
scanPassword: ${SCAN_PASSWORD} # (required)
# The path to the field in the returned JSON payload that
# will contain the authentication token passed as an Authorization
# header on requests.
payloadTokenPath: "authentication.token" # (required)
# The name of the token in the Authorization header.
# ie: Authorization: Bearer <token>
# Bearer is the default if not supplied.
authTokenName: Bearer # (optional)
# Other parameters that are required to be present in the JSON
# payload when POSTing to the loginPath
otherParams: # (optional)
- name: "rememberMe"
val: "true"
# Path to openapi 2 spec file or inline openapi 2 spec yaml
api: "app.openapi.json" # (optional)