---
title: "Extended Configuration"
description: "Override and scale HawkScan configuration for multiple applications and environments"
url: https://docs.stackhawk.com/hawkscan/configuration/extended-configuration/
---

# 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:**

```yaml
app:
  applicationId: ${APP_ID}
  env: ${ENV_NAME:staging}
  formAuth:
    scanUsername: ${SCAN_USERNAME:admin}
    scanPassword: ${SCAN_PASSWORD}
```

Variables can also be embedded within a larger string:

```yaml
app:
  env: preprod-${REGION}
  host: https://${HOST_DOMAIN}/api
```

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:

```bash
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:

```bash
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](#environment-variable-runtime-overrides).

```bash
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:

```bash
docker run --rm -v $(pwd):/hawk:rw -e API_KEY=hawk.xxx...xxx -t stackhawk/hawkscan stackhawk.yml stackhawk-test.yml docker-test.yml
```

```yaml
# stackhawk.yml
app:
  applicationId: xxXXXXXX-xXXX-xxXX-XXxX-xXXxxXXXXxXX
  env: Development
  host: http://localhost:3000
```

```yaml
# stackhawk-test.yml
app:
  env: Test
  host: https://myapp.test.example.com:3000
```

```yaml
# docker-test.yml
app:
  host: http://myapp:3000
```

The result after merging all three files:

```yaml
# 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.

```yaml
# stackhawk.yml
app:
  applicationId: ${SH_APPLICATION_ID}
  env: ${SH_ENVIRONMENT}
  host: ${SH_APP_HOST}
```

```yaml
# 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.*'
```

> **Note:** The `\Q...\E` syntax is regex literal quoting—it treats the text between `\Q` and `\E` as a literal string rather than a regex pattern.

Docker:

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

CLI:

```bash
hawk --api-key hawk.xxx...xxx scan stackhawk.yml stackhawk-configs/auth_basic.yml
```

## 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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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