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
stackhawk.yml
contains the following sections.
Section | Description |
---|---|
hawk |
Parameters for scanner runtime and how it should look for vulnerabilities. |
app |
Parameters for the target application and specifics for how it should be scanned. |
hawkAddOn |
Parameters for additional HawkScan add-ons. |
tags |
A list of name value pairs for tagging scans with contextual metadata. |
Below is a description of optional and default parameters within each section.
hawk
Configuration block for the scanner, independent of the scanned application.
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. Accepted values: high, medium, or low |
.scan |
{} |
Read more |
.config |
[] |
Read more – Scanner configuration overrides |
.outboundProxy |
{} |
Read more – Configuration for an outbound proxy |
hawk.spider
Configuration block for the application web crawler / scan discovery. See the Scan Discovery page for more details.
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. Note: This parameter is not currently supported with Docker on aarch64/arm64. Please use the HawkScan CLI instead. |
.maxDurationMinutes |
2 |
Maximum allowed time for enabled spiders to crawl your web application. |
.ajaxBrowser |
FIREFOX_HEADLESS |
The browser type and style to use. This has no effect when running the stackhawk/hawkscan Docker container and is only for usage via the StackHawk CLI. The options are FIREFOX_HEADLESS , FIREFOX , CHROME_HEADLESS , and CHROME . |
.seedPaths |
[] |
List of paths to supplement the spider. These paths will be used as additional starting points for crawling your application. Useful for paths that are not crawlable from the root of your application. For example, /admin . Note: this configuration is NOT a replacement for an API spec and provides no benefit to pure REST API’s. |
.custom |
{} |
Discover paths in your application with the assistance of a complimentary developer tool or software command. This is appropriate if your team already implements other application testing tools in their CI/CD pipeline, for a more thorough and repeatable scan. |
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.
Parameter | Default | Description |
---|---|---|
.command |
'' |
a space-delimitated command to invoke a developer tool with HTTP_PROXY support eg. "curl -x $HTTP_PROXY http://localhost:3000/admin" |
.arguments |
[] |
a list of strings that can be provided to the command or used instead of. Ideal for specifying commands sensitive to whitespace. |
.environment |
{} |
key-value map of environment variables present at command execution |
.credentials |
{} |
additional environment variables present at command execution and redacted from the logs. |
.workingDir |
"" |
The absolute path working directory these commands are run from. Otherwise will use the base directory HawkScan is run from. |
hawk.scan
Configuration block for HawkScan runtime.
Parameter | Default | Description |
---|---|---|
.maxDurationMinutes |
0 |
Max duration that a scan will run. |
.maxRuleDurationMinutes |
0 |
Max duration that a scan will spend on a rule. |
.requestDelayMillis |
0 |
Delay time between sending requests. |
.concurrentRequests |
20 |
Number of request threads. You know, if you need that little extra push. |
.policyName |
'' |
Name of the scan policy to use. This field is optional and defaults will be selected if omitted. Note: This parameter is only available in the HawkScan 2.2.0 version and later. Read more |
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:
Override | Default | Description |
---|---|---|
spider.processform |
true |
Whether the spider should process forms and request discovered URLs from forms. |
spider.postform |
true |
Whether to use the POST method when requesting URLs discovered in forms. |
spider.handleParameters |
USE_ALL |
Whether to use parameters for requests sent to forms. USE_ALL to use the name and value of the parameter. IGNORE_VALUE to use only the name of the parameter. IGNORE_COMPLETELY to ignore parameters completely. |
hawk.outboundProxy
Configuration block for an outbound proxy including
Parameter | Default | Description |
---|---|---|
.host |
'' |
Host of outbound proxy including port (e.g. ‘https://localhost:8888’) |
.credentials |
{} |
Read more – Configuration for an outbound proxy |
hawk.outboundProxy.credentials
Configuration block for an outbound proxy including
Parameter | Default | Description |
---|---|---|
.username |
'' |
Username for outbound proxy authentication |
.password |
'' |
Password for outbound proxy authentication |
.scheme |
'' |
Scheme for outbound proxy authentication (e.g. BASIC) |
hawkAddOn
Configuration block for HawkScan add-ons and custom scripts.
Parameter | Default | Description |
---|---|---|
.scripts |
[] |
List of configurations for custom scripts. Read more |
.replacer |
{} |
Configuration for the replacer addOn. Read more |
hawkAddOn.scripts
Configuration block for custom scripts.
Parameter | Default | Description |
---|---|---|
.name |
'' |
File name for the custom script. |
.type |
'' |
One of the following script types : active , authentication , session , httpsender , passive , proxy , standalone , or targeted |
.path |
'' |
Path to the file location for the custom script. |
.language |
'' |
Required. The language of the script. Either KOTLIN or JAVASCRIPT |
hawkAddOn.replacer
Configuration block for the Replacer add-on.
Parameter | Default | Description |
---|---|---|
.rules |
[] |
List of regex match and replace rules for request headers. Read more |
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.
Parameter | Default | Description |
---|---|---|
.matchString |
'' |
If replaceOnly is false, only match the header name. If replaceOnly is true , matches the exact string on the header line. |
.replacement |
'' |
Injection or replacement string. If replaceOnly is false , replace the existing header value or add the new header. If replaceOnly is true , replace the entire matched portion. |
.replaceOnly |
false |
If false , replace existing header value or add the missing header using replacement as the value. If true , only replace the matchString of an existing header line. |
.isRegex |
false |
Enable regex search for matchString . Useful when replaceOnly is true (e.g. Referer:.* will replace the entire Referer: header line) |
app
Scanned application parameters, independent of the scanner.
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. Notes:
|
.sessionTokens |
[] |
The names of any session tokens used by your application, provided as an array of strings. Notes:
|
.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 CSR Defense Recommendations. |
.appDataType |
'' |
Deprecated. Indicates to HawkScan the type of data sensitivity of the application, provided as a string. Possible values include:
|
.riskLevel |
MEDIUM |
Deprecated. How important is this application to the business? This should be set to either CRITICAL , HIGH , MEDIUM , or LOW (ex. Critical application that the business runs on = HIGH, Internal employee phone directory = LOW). |
.api |
'' |
Deprecated. Use app.openApiConf instead. – Either a string relative path to an OpenAPI v2 specification file (JSON or YAML) or the specification block itself (YAML). Prefix the path with / to pull from the target host. 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. example: /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. |
.includePaths |
[] |
An array of strings, used as regexes to constrain the application routes HawkScan will specifically visit. example: /api/v1 will specifically include this one route, while /api/v1/.* will only include routes starting with /api/v1/ . This field is useful for constraining the reach of the HawkScan scanner and spider. |
.authentication |
{} |
Configuration block for application authentication to enable scanning as the provided user of your application. Read more |
.graphQLConf |
'' |
GraphQL scanner parameters. Read more |
.openApiConf |
'' |
OpenApi (Swagger) configuration parameters. Read more |
.soapConf |
'' |
SOAP API scanner parameters. Read more |
.autoPolicy |
false |
Set to true to enable an optimized policy when scanning only API’s like GraphQL and OpenAPI. |
.autoInputVectors |
false |
Set to true to automatically enabled the correct input data types when scanning API’s like GraphQL and OpenAPI. This can increase scan accuracy and reduce false positives. |
.waitForAppTarget |
'' |
Wait for an application to start up before starting HawkScan. Read more |
.redact |
{} |
Specification for additional redaction of words in the scan logs. Read more |
app.graphqlConf
GraphQL scanner parameters.
Parameter | Default | Type | Description |
---|---|---|---|
.enabled |
false |
bool |
Enable GraphQL scan support. HawkScan will enumerate all possible field types and input values for GraphQL Queries and Mutations. Provide relative path to the API endpoint. |
.schemaPath |
'' |
string |
Path to the GraphQL introspection endpoint, relative to the target URI (default: /graphql). Note: HawkScan requires either schemaPath OR filePath to be configured in order to acquire the introspection endpoint (do not configure both). |
.filePath |
'' |
string |
Relative path to a JSON formatted GraphQL schema (default: None). Note: HawkScan requires either schemaPath OR filePath to be configured in order to acquire the introspection endpoint (do not configure both). |
.operation |
ALL |
enum |
GraphQL operation to enumerate and scan. Defaults to find all Query and Mutation operations. Types: ALL, QUERY, MUTATION |
.excludeOperations |
[] |
array |
GraphQL operations that should be excluded from the scan by operation name and type. Types: ALL, QUERY, MUTATION |
.requestMethod |
POST |
enum |
Request method to use for queries. Will generate GraphQL queries as either POST payloads or GET uri strings. Types: POST, GET |
.uriMaxLength |
4000 |
int |
Max length of URIs when generation queries for GET requests. |
.introspection |
{} |
introspection | Optional configuration for schema introspection. This can be used to assist in enumerating endpoints for applications that have throttling measures in place. Read more |
.maxDepth |
5 |
int |
Maximum depth for generated query graphs. Value must be between 0 and 50. |
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.
Parameter | Default | Type | Description |
---|---|---|---|
.requestsPerCycle |
10 |
int |
Number of requests to make per cycle during GraphQL introspection and discovery. |
.requestDelay |
1000 |
int |
Delay between each request cycle in milliseconds. |
app.openApiConf
OpenApi (Swagger) configuration parameters.
Use methods (path, filePath, inline
) to specify the application’s OpenAPI specification.
Parameter | Default | Type | Description |
---|---|---|---|
.path |
'' |
string |
A string relative path to an OpenAPI v2 or OpenAPI v3 specification file (JSON or YAML) on the app.host specifed. |
.filePath |
'' |
string |
Relative path to a specification file(s) (JSON or YAML). The path is relative to /hawk the mount point specified by the -v docker run argument. ie: docker run -v $(pwd):/hawk . |
.inline |
'' |
string |
Define your openapi specification yaml inline as a string. |
.strict |
false |
bool |
Enable strict parsing of the openapi. |
.customVariables |
[] |
array |
Array of parameters that exist in the OpenAPI definition and a corresponding list of values to inject for each of them. Read More |
.includeAllMethods |
false |
boolean |
Include all HTTP methods in custom variable injection. By default, set to false and DELETE’s will not inject provided custom variables in an effort to protect data from being deleted. |
.includedMethods |
[] |
array |
All the HTTP methods to include for custom variable injection. If includeAllMethods is set to true, this list is ignored. |
.fakerEnabled |
false |
bool |
Enable generating random realistic values when format information is provided on the OpenAPI definition. Read More |
.maxAliasesForCollections |
100 |
int |
Maximum number of aliases for a collection when parsing a YAML version of the openapi specification. Increase this value if you see the error Number of aliases for non-scalar nodes exceeds the specified max=100 . |
app.soapConf
SOAP API scanner parameters.
Parameter | Default | Type | Description |
---|---|---|---|
.path |
'' |
string |
Host path to the SOAP WSDL, prefixed with a / |
.filePath |
'' |
string |
Relative path to the SOAP WSDL schema definition file |
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.
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 |
{} |
Optional configuration specifying a username and password based authentication configuration. Do not configure if using external or script . Read more |
.external |
{} |
Optional configuration block for specifying an externally supplied authorization token. Do not configure if using usernamePassword or script . Read more |
.script |
{} |
Optional configuration block for specifying an authentication script. Do not configure if using usernamePassword or external . Read more |
.tokenExtraction |
{} |
Optional configuration block for extracting the authorization token from the authentication response. Read more |
.cookieAuthorization |
{} |
Optional configuration specifying if authorization is maintained via a cookie session. Do not configure if using tokenAuthorization or sessionScript . Read more |
.tokenAuthorization |
{} |
Optional configuration telling HawkScan how to pass the authorization token to your application on each request to maintain authorized access. Do not configure if using cookieAuthorization or sessionScript . Read more |
.sessionScript |
{} |
Optional configuration block for specifying a session management script. Do not configure if using cookieAuthorization or tokenAuthorization . Read more |
.testPath |
{} |
A configuration block specifying how to verify authentication/authorization is working. 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 POST credentials 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 |
'' |
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. |
.passwordField |
'' |
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: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 andpassword 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 with 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. Note: If COOKIE is specified, set .external.value as a cookie name and value combination separated by = (for instance, <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 assigned type . |
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.
Parameter | Default | Description |
---|---|---|
.name |
'' |
Required The name of the authentication script defined in hawkAddons.scripts . The script type must be authentication . |
.parameters |
{} |
A map of key/value pairs that will be passed to your authentication script as the paramsValues: Map<String, String> . |
.credentials |
{} |
A map of key/value pairs that will be passed to your authentication script as the credentials: GenericAuthenticationCredentials . Unlike parameters , credentials will be redacted throughout the StackHawk platform. |
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.
Parameter | Default | Description |
---|---|---|
.type |
TOKEN_PATH |
An enum value representing the method of extraction. TOKEN_PATH or HEADER_NAME 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 |
'' |
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.sessionScript
Optional configuration block for specifying a session management script. To learn more about session scripts, reference the HawkScan Examples repository.
Parameter | Default | Description |
---|---|---|
.name |
'' |
Required The name of the session script defined in hawkAddons.scripts . The script type must be session . |
.parameters |
{} |
A map of key/value pairs that will be passed to your session script, which can be accessed via sessionWrapper.getParam() function. |
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.
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 |
'' |
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.HawkScan requires that either success OR fail be configured (do not configure both) |
.fail |
'' |
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.HawkScan requires that either success OR fail be configured (do not configure both) |
.requestMethod |
GET |
The request method to use for authentication verification. If using POST or PUT methods, a value must also be provided to the requestBody .Supported types: GET , POST , PUT |
.requestBody |
'' |
The request content to send along with POST or PUT requests for authentication verification. |
.requestHeaders |
{} |
A map of key/value pairs to be included as headers in the request to the path . Headers that match the following pattern are unable to be added or modified '^(Host|Origin|Proxy-.*|Sec-.*|Content-Length)' . Example header entry: - Content-Type: "application/json" |
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.
Parameter | Default | Type | Description |
---|---|---|---|
.path |
'' |
string |
The path to a public accessible route in your application, prefixed with a / |
.requestMethod |
GET |
string |
The request method to use for app readiness verification. If using POST or PUT methods, a value must also be provided to the requestBody .Supported types: GET , POST , PUT |
.requestBody |
'' |
string |
The request content to send along with POST or PUT requests for application readiness |
.waitTimeoutMillis |
'' |
int |
Time in milleseconds that HawkScan should wait for application to start before exiting |
.pollDelay |
'' |
int |
Time in milleseconds between requests to check for application readiness |
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.
Parameter | Default | Description |
---|---|---|
.headers |
[] |
List of string header names: the values of HTTP headers matching these names will be redacted from alerts and logs. |
.values |
[] |
List of string static values: the values here will be added to the redacted token list. This is best used with ${ENV_VAR:default} interpolation. |
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 Variable | Description |
---|---|
NO_COLOR |
Disables colored terminal output from the scanner |
SHAWK_DEBUG |
Run the scanner with verbose logging |
HAWK_MEM |
Allocate this much RAM to HawkScan, e.g. 2024m or 2g |
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 tofalse
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
- In this example,
replacement
is the replacement formatchString
- The replacement string should include both the replacement header’s key and value if an entire header pair is to be replaced
replaceOnly
set totrue
to avoid injecting a new headerisRegex
set tofalse
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.
- Note: partial matches of a header line will occur if, for example, only the header key is provided in
...
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 withUser-Agent
- In this example,
replacement
is the replacement formatchString
- The replacement string will replace everything found within the regex match group
replaceOnly
set to true to avoid injecting a new headerisRegex
sets thematchString
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 thereplacement
text.
- Note: partial matches of a header line will occur if only part of the header value or the header key is provided in
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)