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.

Parameter Default Description
hawk {} Parameters for scanner runtime and how it should look for vulnerabilities. Read More.
app {} Required. Parameters for the target application and specifics for how it should be scanned. Read More.
hawkAddOn {} Parameters for additional HawkScan add-ons and custom scripts. Read More.
tags [] Searchable keywords to associate with this scan. Read More.

hawk

Configuration preferences for HawkScan, independent of the scanned application.

Parameter Default Description
spider {} Configuration for the application web crawler & scan discovery. Read More.
startupTimeoutMinutes 5 Maximum time in minutes to wait for the scanner process to start.
failureThreshold "" The lowest alert level that returns a failed scan status. Accepted values: high, medium, or low.
scan {} Configuration for the HawkScan runtime. Read More.
config [] Scanner configuration overrides, provided as a list of key=value strings. A list of strings in the form of key=value pairs passed to the scanner as scanner configuration overrides. This is an advanced feature to configure HawkScan plugins and override their default behavior. Read More.
outboundProxy {} Configuration for an outbound proxy. Read More.

hawk.spider

Configuration block for the application crawling and Discovery Phase aka Spider. 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.
maxDurationMinutes 2 Maximum allowed time for enabled spiders to crawl your web application.
ajaxBrowser "FIREFOX_HEADLESS" The browser type and style to use when running the AjaxSpider. When running the stackhawk/hawkscan docker container, this setting is ignored and will uses the default FIREFOX_HEADLESS. 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. Read More.
har {} Import a HAR file as the API discovery method for the scan. Read More.

hawk.spider.custom

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

Parameter Default Description
command "" Provide a command to run as part of the scan discovery phase. This command will be split from its arguments and execute on its own thread in a context with additional environment variables set with the proxy configuration for HawkScan to intercept http traffic.
environment [] Environment variables to pass along into the execution of the command.
workingDir "" The absolute path working directory these commands are run from.
credentials [] Additional environment variables or secrets to pass along into the execution of the command. These values will be redacted from the logs.
arguments [] Command arguments provided as an array of strings. These arguments can be used in addition to or instead of the command. This should be used if the command is sufficiently complex or is exceptionally whitespace sensitive.
excludeParentEnvironment false Only provide the environment variables and credentials as configured. By default also includes the environment from the parent process environment for convenience.
logOutputToForeground false This command prints the stdout and stderr of the command to the foreground.

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.

Parameter Default Description
replaceHost "" The hostname of URLs in the HAR file that will be replaced with the host defined in app.host. Leave blank if the app.host is then same hostname in the HAR file.
file {} Use individual HAR files. Read More.
dir {} Use a directory of HAR files. Read More.

hawk.spider.har.file

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

Parameter Default Description
paths [] Paths to HAR files to import. Files will be loaded in order provided.

hawk.spider.har.dir

Paths to directories, for use with HARImportConfig.

Parameter Default Description
path "" Path to directory containing .har files. Only files with the .har extension will be loaded in alphanumeric order.

hawk.scan

Configuration block for HawkScan runtime.

Parameter Default Description
maxDurationMinutes 0 Maximum duration that a scan will run.
maxRuleDurationMinutes 0 Maximum duration that a scan will spend on a rule.
requestDelayMillis 0 Delay time between sending requests.
concurrentRequests 20 Number of request threads. If you need that little extra push. defaults to 20.
throttlePassiveBacklog 10000 Pause active scan when passive backlog is greater than this value, resumes once backlog is empty. defaults to 50.
throttleIntervalSeconds 600 How often the throttle check is run, in seconds.
throttleTempRecordMax 100000 The max number of temp records allowed before pruning of temp records begins.
throttleTempRecordDeleteQuota 50 The percentage of throttleTempRecordMax records to delete on each throttleIntervalSeconds.
policyName "" Name of a specific named scan policy to use. This field is optional, and an applicable scan policy will be selected if omitted.

hawk.outboundProxy

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

Parameter Default Description
host "" The host of the outbound explicit proxy, including port (e.g. https://localhost:8888).
credentials {} Credentials for logging into the outbound explicit proxy. Read More.
rootCACertPath "" Path to root CA Certificate for transparent outbound proxies. This can be used without specifying host or credentials.

hawk.outboundProxy.credentials

Credential details for the outbound proxy behavior.

Parameter Default Description
username "" Required. The username for proxy credentials.
password "" Required. The password for proxy credentials.
realm "" Realm for proxy credentials.
scheme "" Scheme of proxy authentication. Currently BASIC, NTLM are supported.

app

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

Parameter Default Description
host "" Required. The base url of the application to scan ex: http://localhost:8000. If the url cannot be reached, the scan will not proceed.
sessionTokens [] The names of any session tokens used by your application, provided as an array of strings (Hint: these are the names of session cookies used by your application).
antiCsrfParam "" The name of your CSRF security parameter used in any application form inputs. Globally set, HawkScan will parse this parameter value from form responses to use in subsequent requests.
authentication {} Authenticated scan configuration. This informs HawkScan how to authenticate as a user to the scanned application. Read More.
excludePaths [] An array of strings, used as regexes to match against routes that should be ignored entirely by HawkScan. If populated, paths that match any supplied regex will be excluded from the scan. This field is useful for prohibiting asset directories or other resources that don’t require vulnerability scanning.
applicationId "" Required. The applicationId of an application from the StackHawk platform.
env "" Required. The env environment name to organize Scan Results.
graphqlConf {} GraphQL API scanner parameters. Read More.
includePaths [] An array of strings, used as regexes to limit which application routes HawkScan will specifically visit. If populated, paths must match at least one supplied regex to be included as part of the scan. This field is useful for constraining the reach of the HawkScan scanner and spider.
autoPolicy false Set to true to enable an optimized policy when scanning specific APIs like GraphQL and OpenAPI. Defaults to True.
autoInputVectors false Set to true to automatically enabled the correct input data types when scanning APIs like GraphQL and OpenAPI. This can increase scan accuracy and reduce false positives. Defaults to True.
openApiConf {} OpenApi scanner parameters. Read More.
soapConf {} SOAP API scanner parameters. Read More.
grpcConf {} gRPC scanner parameters. Read More.
inputVectors {} Fine grained control of injectable input vectors. Input vectors are managed automatically and should only be set for advanced use cases.
waitForAppTarget {} Optional configuration for waiting for the host to be up and ready for scanning. Read More.
redact {} Specification for additional redaction of words in the scan logs. Read More.

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
usernamePassword {} Optional configuration specifying a username and password based authentication configuration. Do not configure if using external.
external {} Optional configuration block for specifying an externally supplied authorization token. Do not configure if using usernamePassword.
script {} Optional configuration block for using an authentication script.
externalCommand {} Optional configuration block for running an external command process.
oauth {} Optional configuration block for 3rd Party/OAuth.
tokenExtraction {} Optional configuration block for extracting the authorization token from the authentication response.
cookieAuthorization {} Optional configuration specifying if authorization is maintained via a cookie session. Do not configure if using tokenAuthorization.
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.
sessionScript {} Optional configuration for using a session management script.
loggedInIndicator "" 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. ".*signed in as.*"). Required if authorization token is not a JWT.
loggedOutIndicator "" 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. Required if authorization token is not a JWT.
testPath {} A configuration block specifying how to verify authentication/authorization is working.
overrideJWTAutoRenew false If set to true HawkScan will not try to autorenew a JWT.

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
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.
loginPath "" Required. login route to POST credentials for a user in the application (ex. /login). An http POST request using the type specified will be made to this path.
usernameField "" Required. the username html field used in your application form or json, provided as a string.
passwordField "" Required. The password html field used in your application form or json, provided as a string.
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).
type "FORM" An enum value describing the type of POST data expected by the loginPath
otherParams [] Other request parameters required by your login payload, provided as an array of objects with name and value string keys. 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. Read More.
realm "" Realm for NTLM authentication

app.authentication.usernamePassword.otherParams

General name / value parameter.

Parameter Default Description
name "" Param name.
val "" Param value.

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" Specifies the type of token being supplied. If COOKIE is specified the .external.value should be in the form of a cookie value = . Defaults to `TOKEN`.
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. Use value or values but not both. The value containing the token that will authorize requests. How the token is passed to your application is determined by the assigned type.
values [] The value pairs containing the token that will authorize requests. How the token is passed to your application is determined by the assigned type.

app.authentication.external.values

Configuration for Token Authentication.

Parameter Default Description
type "TOKEN" Specifies the type of token being supplied, either TOKEN or COOKIE. Defaults to TOKEN.
tokenType "" If specified tokenType will be prepended the header value e.g. tokenType: Bearer -> “Bearer xxxxxxxxx”
value {} Name and value of token. If token is specified it will be appended Name: Val. Read More.

app.authentication.external.values.value

General name / value parameter.

Parameter Default Description
name "" Param name.
val "" Param value.

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

Parameter Default Description
name "" The name of the authentication script, as specified in the hawkAddOn.scripts.name.
parameters [] The parameters required for the authentication script.
credentials [] The credentials required for the authentication script. These values will be redacted.

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.

Parameter Default Description
command "" The command to start the process e.g. bash, python
parameters [] Parameters required to run the script e.g. -c, --verbose

app.authentication.oauth

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

Parameter Default Description
credentials {} Credentials needed to authenticate with an OAuth/3rd party provider e.g. password, clientSecret, etc. Read More.
parameters {} Non sensitive parameters to use with an OAuth/3rd party provider e.g. tokenEndpoint, scope, etc. Read More.

app.authentication.oauth.credentials

Parameter Default Description
username "" Username which will be posted in the request body to the token endpoint with the field name of username.
password "" Password which will be posted in the request body to the token endpoint with the field name of password.
clientId "" The client id of your application registered with your OAuth provider which will be posted n the request body to the token endpoint with the field name of client_id.
clientSecret "" The client secret of your application registered with your OAuth provider which will be posted n the request body to the token endpoint with the field name of client_secret.
additionalCreds [] A list of name/value pairs of any additional fields or credentials that need to be posted to the OAuth provider token endpoint.

app.authentication.oauth.parameters

Parameter Default Description
tokenEndpoint "" URL of the endpoint to get a token
grantType "" Grant type of token request, this will be passed to the request body of the token endpoint as grant_type.
scope "" Scope type of token request, this will be passed to the request body of the token endpoint as scope.
additionalQueryParams [] A list of optional additional name/value pairs to be passed to the query string.
additionalBodyParams [] A list of optional additional name/value pairs to be included in the request body of the post. NOTE: These values are not redacted, if you need additional sensitive values please use outhCredentials.additionalCreds
requestMethod "POST" Http method for accessing the token endpoint. The default is POST.
requestHeaders {"Content-Type":"application/x-www-form-urlencoded","Accept":"application/json","Cache-control":"no-cache"} Additional headers to be sent along with the request to the token endpoint

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.

Parameter Default Description
type "TOKEN_PATH" 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. defaults to TOKEN_PATH.
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 cookies 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 indicates that each request should have the authorization token header added 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 "Bearer" TokenType will be prepended the header value e.g. tokenType: TOKEN -> “TOKEN xxxxxxxxx”
isJWT false If the token is a JWT, mark this field as true
renewMillis 1500 If isJWT is set to true, this field will determine the time in milliseconds before expiration to auto renew the JWT.

app.authentication.sessionScript

Optional configuration block for specifying a custom 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, and match the hawkAddOn.scripts.name field.
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 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.

Parameter Default Description
type "HEADER" An enum value representing what to match against in the response from issuing a 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 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 scanning should halt and enter an error state. HawkScan requires that either success OR fail be configured (do not configure both).
requestMethod "GET" Request method to use for queries. Will generate GraphQL queries as either POST payloads or GET uri strings.
requestBody "" The request content to send along with POST or PUT requests for authentication verification.
requestHeaders [] List 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)'.

app.graphqlConf

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

Parameter Default Description
schemaPath "" Path to the GraphQL introspection endpoint, relative to the target URI.
requestMethod "POST" Request method to use for queries. Will generate GraphQL queries as either POST payloads or GET uri strings.
uriMaxLength 0 Max length of URIs when generation queries for GET requests.
maxDepth 0 Maximum depth for generated query graphs.
enabled false 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.
operation "ALL" GraphQL operation to enumerate and scan. Defaults to find all Query and Mutation operations. Options are All, QUERY and MUTATION.
filePath "" Relative path to a JSON formatted GraphQL schema (default: None).
excludeOperations [] GraphQL operations to exclude from the spider.
fakerEnabled false Enables faker for a GraphQL scan to generate more realistic values when format is provided on the API spec or custom variables.
customVariables [] Define custom variables and values for use in GraphQL scanning.

app.graphqlConf.excludeOperations

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

Parameter Default Description
name "" GraphQL operation name.
type "ALL" Graphql operation type. Options are All, QUERY and MUTATION.

app.graphqlConf.customVariables

Custom variable data specific to OpenAPI schemas.

Parameter Default Description
field "" The field name of the param to inject values into.
values [] A list of possible values to be randomly selected for the given field.
operationName "" An optional operationName that will only inject custom values if the name of the operation on the request matches.
operationType "ALL" An optional GraphQL operation type (MUTATION or QUERY) that will inject custom values only when the request matches the operation type.

app.openApiConf

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

Parameter Default Description
path "" A string relative path to an OpenAPI specification file (JSON or YAML) from the scanned host.
filePath "" Relative path to specification file(s) (JSON or YAML). The path is relative to the /hawk mount point specified by the -v docker run argument. ie: docker run -v $(pwd):/hawk.
inline "" Define your openapi specification yaml inlined as a string.
strict false Whether to enable strict parsing of the OpenAPI.
deprecatedCustomVariables [] Define custom variables and values for use in REST API scanning.
customVariables [] Define custom variables and values for use in REST API scanning.
includeAllMethods false When custom variables are provided, DELETE’s are skipped for injection. Set this to true to override this default and include all methods in variable injection.
includedMethods [] List of methods to include in custom variable injection. Note: if ‘includeAllMethods’ is set to true, this list is ignored and all methods will be used for custom variable injection.
fakerEnabled false Enables faker for a REST API scan to generate more realistic values when format is provided on the API spec or custom variables.
maxAliasesForCollections 0 Maximum number of aliases for a collection when parsing YAML. Increase this value if you see the “Number of aliases for non-scalar nodes exceeds the specified max=100” error.
filePaths [] A list of relative path to specification file(s) (JSON or YAML) for the open api generation for specs with multiple open api files.

app.openApiConf.deprecatedCustomVariables

Generic custom variable for different API types.

Parameter Default Description
field "" The field name of the param to inject values into.
values [] A list of possible values to be randomly selected for the given field.

app.openApiConf.customVariables

Custom variable data specific to OpenAPI schemas.

Parameter Default Description
field "" The field name of the param to inject values into.
values [] A list of possible values to be randomly selected for the given field.
path "" An optional path regex that will only inject custom values if the path of the request matches.
requestMethods [] A list of optional HTTP request methods that will inject custom values only when the request matches one of those methods.

app.soapConf

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

Parameter Default Description
path "" Host path to the SOAP WSDL, prefixed with a / .
filePath "" Relative path to the SOAP WSDL schema definition file.

app.grpcConf

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

Parameter Default Description
path "" Host path for the grpc reflection endpoint.
filePath "" Relative path to the grpc protobuf descriptor_set file.
customVariables [] Define custom variables and values for use in gRPC scanning.
maxDepth 0 Maximum depth for resolving nested protobuf.
filePaths [] A list of paths to the grpc protobuf descriptor_set file.

app.grpcConf.customVariables

Generic custom variable for different API types.

Parameter Default Description
field "" The field name of the param to inject values into.
values [] A list of possible values to be randomly selected for the given field.

app.inputVectors

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

Parameter Default Description
injectableParam {} Configuration of where params are injectable in the request.
enabledRpcParam {} Configuration of what RPC parts are injectable by configuration.

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.

Parameter Default Description
urlQueryParam false Allow injection of testable inputs url query parameter values.
urlQuery false Allow injections of testable inputs url query parameter names.
postData false Allow injection of testable inputs request body inputs on POST requests.
urlPath false Allow injection of testable inputs url paths.
httpHeaders false Allow injection of testable inputs for http headers.
cookieData false Allow injection of testable inputs for cookie data.

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.

Parameter Default Description
multipartFormData false Support for multipart/form-data request bodies.
xmlTag false Support for xml request bodies.
json false Support for json request bodies.
googleWebToolkit false Support for GWT request bodies. Deprecated.
odataId false Support for Odata request bodies. Deprecated.
directWebRemoting false Support for direct web remoting request bodies. Deprecated.

app.waitForAppTarget

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

Parameter Default Description
path "" The path to a public reachable route in your application. For example /index. A GET request will be made to this path to confirm the host is up and ready to receive traffic.
requestMethod "GET" Request method to use for queries. Will generate GraphQL queries as either POST payloads or GET uri strings.
requestBody "" The request content to send along with POST or PUT requests for target verification.
waitTimeoutMillis 0 The maximum amount of time in milliseconds that HawkScan will wait for your app to be available before it starts scanning
pollDelay 0 The maximum amount of time in milliseconds in between requests to your application to see if it’s running

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.

hawkAddOn

Configuration block for HawkScan add-ons and custom scripts.

Parameter Default Description
replacer {} Configuration for the replacer addOn. Read More.
scripts [] List of configurations for custom scripts. Read More.

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.

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 "" 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.
initiators [] Replacer rule initiators. Read More.
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).

hawkAddOn.scripts

Configuration block for custom scripts.

Parameter Default Description
name "" The name of this custom script.
type "active" The type of this script. One of active, authentication, httpsender, passive, proxy, standalone, targeted, session. Read More.
path "" Path to the file location for the custom script.
vars [] Named variables to expose to the script. Read More.
language "KOTLIN" Required. The language of this script. Either KOTLIN or JAVASCRIPT. Read More.
id 0 Plugin Id for script.

hawkAddOn.scripts.vars

General name / value parameter.

Parameter Default Description
name "" Param name.
val "" Param value.

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}

Parameter Default Description
name "" The keyword name.
value "" An arbitrary value to associate with the keyword.

hawkAddon.replacerRules.initiators

ReplacerRule Initiators.

Enum Description
PROXY

Proxy.

ACTIVE_SCANNER

Active Scanner.

SPIDER

Spider.

FUZZER

Fuzzer.

AUTHENTICATION

Authentication.

MANUAL_REQUEST

Manual request.

CHECK_FOR_UPDATES

Check for updates.

BEAN_SHELL

Bean Shell.

ACCESS_CONTROL_SCANNER

Access Control Scanner.

AJAX_SPIDER

Ajax Spider.

FORCED_BROWSE

Forced Browse.

TOKEN_GENERATOR

Token Generator.

WEB_SOCKET

Web Socket.

AUTHENTICATION_HELPER

Authentication help.

hawkAddon.scripts.type

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

Enum Description
active

Active scripts are executed as part of the active scanner. They can be used to generate and send attack requests, to extract information from responses, and to report vulnerabilities.

authentication

Authentication scripts are executed when authentication is performed for a context. They can be used to intercept and modify authentication requests and responses, or to perform other actions related to authentication.

httpsender

HttpSender scripts are executed against every request/response sent through the scanner proxy. They can be used to modify requests and responses, to inject custom headers, or to perform other actions related to HTTP traffic.

passive

Passive scripts are executed as part of the passive scanner. They can be used to extract information from requests and responses, to report vulnerabilities, or to perform other actions related to passive scanning.

proxy

Proxy scripts are executed ‘inline’, can change every request and response and can be individually enabled. They can be used to modify requests and responses, to inject custom headers, or to perform other actions related to proxying traffic.

session

Session scripts are executed when a new session is created or when a session is loaded. They can be used to initialize the session or to perform some other action when a new session is created.

hawkAddon.scripts.language

A supported scripting language interpreter for custom scripts.

Enum Description
KOTLIN

Kotlin Engine.

JAVASCRIPT

Javascript Engine.

nameValParam

General name / value parameter.

Parameter Default Description
name "" Param name.
val "" Param value.

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.

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.

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

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