Login Start Free Trial Login Start Free Trial
 

Extended Configuration

HawkScan configuration files can be overridden and scaled for multiple applications and environments. The below guide provides information on extending your HawkScan configuration using environment variable overrides and local/remote configuration overlays.

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.

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

Authentication Management with Multiple Configuration Files

Multiple configuration files can be used to manage authentication for different applications and environments. This is done by maintaining a base configuration file with settings relevant to more than one application or environment and then using an overlay configuration file to handle the authentication for the specific applications or environments.

stackhawk.yml

app:
  applicationId: ${SH_APPLICATION_ID}
  env: ${SH_ENVIRONMENT}
  host: ${SH_APP_HOST}

stackhawk-configs/auth_basic.yml

app:
  authentication:
    loggedInIndicator: "\\QLog out\\E"
    loggedOutIndicator: "\\QLog in\\E"
    external:
      type: TOKEN
      value: ${SH_AUTH_TOKEN}
    testPath:
      path: /authenticated/path
      success: '.*200.*'

Docker:

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk... -t stackhawk/hawkscan stackhawk.yml stackhawk-configs/auth_basic.yml

CLI:

hawk --api-key hawk... scan stackhawk.yml stackhawk-configs/auth_basic.yml

For more information on overlays, see HawkScan Configuration with Overlays

Remote Configuration URLs

In addition to passing YAML configuration files that live in your CI/CD environment or your local machine, HawkScan supports passing remote configuration URLs to the scanner.

Docker:

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk... -t stackhawk/hawkscan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml

CLI:

hawk --api-key hawk... scan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml

Instead of running the scan using a YAML configuration file on the file system, HawkScan will run the scan using the configuration file retrieved from the URL.

This will also work with the multiple configuration pattern described above. For example, a configuration file on the local file system can be passed after a base configuration file hosted at a remote location.

Docker:

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk... -t stackhawk/hawkscan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml stackhawk-dev.yml

CLI:

hawk --api-key hawk... scan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml stackhawk-dev.yml

Authenticated URLs are also supported. For example an authenticated GitHub URL such as https://raw.githubusercontent.com/stackhawk/JavaSpringVulny/master/stackhawk.yml?token={token} can be passed to the scanner.

Docker:

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk... -t stackhawk/hawkscan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml?token={token}

CLI:

hawk --api-key hawk... scan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml?token={token}