stackhawk-hawkscan-config

HawkScan Config Patterns Reference

Looking for per-field syntax? Use hawk config show <field-path> --text for the canonical reference (e.g. hawk config show hawk.spider --text). This file documents patterns — env var interpolation, multi-env composition, common config-time gotchas — not individual field reference.

For authentication, follow Phase 1c in SKILL.md (uses hawk config show <section> --text).

Table of Contents

1. Env Var Interpolation
2. Multi-Environment Config
3. Common Config-Time Gotchas

---

Env Var Interpolation

Always use env var interpolation (${VAR:default}) for sensitive values and anything that varies across environments.

Syntax: HawkScan uses ${VAR:default} — single colon, no dash. The bash form ${VAR:-default} is NOT supported.

Whole-value rule: The entire YAML value must be the variable. Mid-string interpolation does NOT work:

# WRONG — will NOT interpolate
host: "https://${HOST}/api"

# RIGHT — interpolate the entire value
host: ${FULL_HOST_URL}

If you need a composed value, compose it in the shell first and export a single env var:

export FULL_HOST_URL="https://${HOST}/api"
hawk scan

---

Multi-Environment Config

Preferred: Host interpolation (one file, works everywhere)

Use ${VAR:default} interpolation for host-only differences. Never create a second YAML file just to change the host.

# stackhawk.yml — one file, works everywhere
app:
  applicationId: ${APP_ID}
  env: ${APP_ENV:Development}
  host: ${APP_HOST:https://your-default-host.com}

Override the host at runtime without touching the file:

# Scan locally
APP_HOST=http://localhost:3000 hawk scan

# Scan staging
APP_HOST=https://staging.example.com hawk scan

Multi-file layering (for structurally different scan settings)

Use file layering only when environments need meaningfully different settings — different env name, different failureThreshold, or CI-only tags. Not for host-only differences.