Extended Configuration

HawkScan configuration can be extended for multiple applications and environments. This guide covers:

• Environment variable overrides — Inject values at runtime
• Multiple configuration files — Layer configs for different environments
• Remote configuration URLs — Load configs from external sources

Environment Variable Runtime Overrides

Use ${VAR} or ${VAR:default} syntax to inject environment variables into your configuration at runtime:

Syntax	Behavior
${VAR}	Replaced with the value of VAR, or empty string if unset
${VAR:default}	Replaced with VAR value, or default if unset

Example:

app:
  formAuth:
    scanUsername: ${SCAN_USERNAME:admin}
    scanPassword: ${SCAN_PASSWORD}

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.xxx...xxx -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.xxx...xxx -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.xxx...xxx -t stackhawk/hawkscan stackhawk.yml stackhawk-dev.yml

Each configuration file is merged on top of the prior—later files override earlier ones. If the same key appears in multiple files, the last value wins. For example:

docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk.xxx...xxx -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

The result after merging all three files:

# Merged Result
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.xxx...xxx -t stackhawk/hawkscan stackhawk.yml stackhawk-configs/auth_basic.yml

CLI:

hawk --api-key hawk.xxx...xxx 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.xxx...xxx -t stackhawk/hawkscan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml

CLI:

hawk --api-key hawk.xxx...xxx 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.xxx...xxx -t stackhawk/hawkscan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml stackhawk-dev.yml

CLI:

hawk --api-key hawk.xxx...xxx 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=<YOUR_TOKEN> can be passed to the scanner.

Docker:

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

CLI:

hawk --api-key hawk.xxx...xxx scan https://raw.githubusercontent.com/kaakaww/javaspringvulny/main/stackhawk.yml?token=<YOUR_TOKEN>