feat: JSON/YAML config file as alternative to CLI flags

[lpcox]

Problem

AWF currently has 53+ CLI flags across 70 .option() calls in src/cli.ts. A typical invocation with non-trivial configuration looks like:

sudo awf \
  --allow-domains github.com,api.github.com,objects.githubusercontent.com \
  --block-domains evil.com \
  --dns-servers 1.1.1.1,1.0.0.1 \
  --enable-api-proxy \
  --anthropic-api-target api.anthropic.com \
  --openai-api-target api.openai.com \
  --copilot-api-target api.githubcopilot.com \
  --log-level debug \
  --memory-limit 8g \
  --agent-timeout 600 \
  --rate-limit-rpm 60 \
  --rate-limit-rph 1000 \
  --upstream-proxy http://corp-proxy:3128 \
  --env-file .env \
  --exclude-env SECRET_KEY,INTERNAL_TOKEN \
  --diagnostic-logs \
  --audit-dir /var/log/awf-audit \
  --session-state-dir /tmp/session \
  -- claude --prompt "do the thing"

This is unwieldy, hard to version-control, and error-prone. The flag surface area will only grow as features like DLP, DIFC proxy, ssl-bump, DinD, and rate limiting mature.

Proposal

Support reading configuration from a JSON or YAML file as an alternative to CLI flags:

# Read config from file
sudo awf --config awf.json -- claude --prompt "do the thing"

# Read config from stdin (for piping / programmatic use)
cat awf.json | sudo awf --config - -- claude --prompt "do the thing"

Example config file

{
  "$schema": "https://raw.githubusercontent.com/github/gh-aw-firewall/main/docs/awf-config.schema.json",
  "network": {
    "allowDomains": ["github.com", "api.github.com", "*.githubusercontent.com"],
    "blockDomains": ["evil.com"],
    "dnsServers": ["1.1.1.1", "1.0.0.1"],
    "upstreamProxy": "http://corp-proxy:3128"
  },
  "apiProxy": {
    "enabled": true,
    "targets": {
      "anthropic": { "host": "api.anthropic.com" },
      "openai": { "host": "api.openai.com" },
      "copilot": { "host": "api.githubcopilot.com" }
    }
  },
  "security": {
    "sslBump": false,
    "enableDlp": false,
    "difcProxy": { "host": "localhost:18443" }
  },
  "container": {
    "memoryLimit": "8g",
    "agentTimeout": 600,
    "enableDind": false,
    "workDir": "/tmp/awf-work",
    "imageRegistry": "ghcr.io/github/gh-aw-firewall",
    "imageTag": "latest"
  },
  "environment": {
    "envFile": ".env",
    "envAll": false,
    "excludeEnv": ["SECRET_KEY", "INTERNAL_TOKEN"]
  },
  "logging": {
    "logLevel": "debug",
    "diagnosticLogs": true,
    "auditDir": "/var/log/awf-audit",
    "proxyLogsDir": "/tmp/squid-logs"
  },
  "rateLimiting": {
    "enabled": true,
    "requestsPerMinute": 60,
    "requestsPerHour": 1000,
    "bytesPerMinute": 10485760
  }
}

Deliverables

1. JSON Schema (docs/awf-config.schema.json) — machine-readable schema for validation and IDE autocomplete
2. Config file loading — --config <path> flag that reads JSON/YAML, validates against schema, and merges with any CLI flag overrides
3. CLI flag precedence — explicit CLI flags override config file values (like how git config works: file < CLI)
4. Stdin support — --config - reads from stdin for programmatic/pipeline use
5. Schema validation — validate config at load time with clear error messages

Benefits

• Version-controllable — teams can check in awf.json alongside their project
• IDE support — JSON Schema enables autocomplete and validation in VS Code, etc.
• Composable — base config + CLI overrides for environment-specific tweaks
• Self-documenting — schema describes every option with types, defaults, and constraints
• Programmatic — stdin support enables config generation from scripts or CI systems

Current flag inventory (53 flags across 8 categories)

Category	Flags	Count
Network	--allow-domains, --allow-domains-file, --allow-urls, --block-domains, --block-domains-file, --dns-servers, --dns-over-https, --upstream-proxy	8
API Proxy	--enable-api-proxy, --anthropic-api-target, --openai-api-target, --copilot-api-target, --gemini-api-target, --*-api-base-path (×4)	9
Security	--ssl-bump, --enable-dlp, --difc-proxy, --difc-proxy-host, --difc-proxy-ca-cert, --allow-host-ports, --allow-host-service-ports, --enable-host-access	8
Container	--memory-limit, --agent-timeout, --enable-dind, --docker-host, --agent-image, --container-workdir, --image-registry, --image-tag, --skip-pull, --tty, --work-dir	11
Environment	--env-file, --env-all, --exclude-env	3
Logging	--log-level, --diagnostic-logs, --audit-dir, --proxy-logs-dir, --session-state-dir	5
Rate Limiting	--no-rate-limit, --rate-limit-rpm, --rate-limit-rph, --rate-limit-bytes-pm	4
Other	--with-pid, --ruleset-file, --format	3
Subcommands	logs stats, logs summary, audit (each with own flags)	2+

Open questions

1. YAML support? — JSON is sufficient for schema validation; YAML adds human-friendliness but another dependency
2. Config discovery — should AWF auto-discover awf.json / .awf.json in the working directory?
3. Config merging — should multiple --config flags be supported for layered configs (base + override)?
4. Env var interpolation — should config files support ${ENV_VAR} syntax for secrets?

References

• src/cli.ts — all 70 .option() calls
• src/types.ts — WrapperConfig interface (the internal config representation)
• action.yml — GitHub Action inputs (subset of CLI flags)