feat: configure AWF via JSON/YAML config instead of CLI flags
- Dominant language
- Go
- Stars
- 5.1k
- Forks
- 541
- Avg merge
- 5h 46m
- Merged PRs (30d)
- 760
Description
## Summary
AWF now supports a formal JSON/YAML configuration model as an alternative to its 53+ CLI flags. The `gh-aw` compiler should adopt this config file to configure AWF, replacing the growing list of `--flag` arguments on the `awf` command line.
## Background
The AWF command line has become unwieldy — over 53 flags covering domains, DNS, proxy settings, container options, API proxy configuration, logging, and more. To address this, AWF now supports `--config ` which accepts a JSON or YAML configuration document.
The full specification and schema are published in the AWF repository:
- **W3C-style spec**: [`docs/awf-config-spec.md`](https://github.com/github/gh-aw-firewall/blob/main/docs/awf-config-spec.md)
- **JSON Schema**: [`docs/awf-config.schema.json`](https://github.com/github/gh-aw-firewall/blob/main/docs/awf-config.schema.json)
- **Implementation PR**: https://github.com/github/gh-aw-firewall/pull/2018
- **Original issue**: https://github.com/github/gh-aw-firewall/issues/2017
## Proposal
When `gh-aw` compiles a workflow lock file, it should:
1. **Generate an AWF config file** (JSON) containing all firewall settings (allowed domains, DNS servers, proxy config, logging options, container settings, etc.)
2. **Write the config to a temp file** in the workflow workspace (e.g., `/tmp/gh-aw/awf-config.json`)
3. **Invoke AWF with `--config`** instead of individual flags:
```bash
awf --config /tmp/gh-aw/awf-config.json --
```
instead of the current:
```bash
awf --allow-domains "dom1,dom2,..." --dns-servers "8.8.8.8" --log-level info --proxy-logs-dir ... --audit-dir ... --session-state-dir ... --enable-host-access --build-local --enable-api-proxy --difc-proxy-host ... --difc-proxy-ca-cert ... --
```
## Benefits
- **Readability**: Config is structured and self-documenting vs. a 500+ character command line
- **Validation**: JSON Schema provides static validation before AWF runs
- **Maintainability**: Adding new AWF options requires only schema + config changes, not flag parsing
- **Debuggability**: Config file can be inspected, diffed, and version-controlled
- **Processing model**: CLI flags still override config values, so per-invocation tweaks work
## Config Structure Example
```json
{
"allowDomains": ["github.com", "api.github.com", "registry.npmjs.org"],
"dnsServers": ["8.8.8.8", "8.8.4.4"],
"logLevel": "info",
"proxyLogsDir": "/tmp/gh-aw/sandbox/firewall/logs",
"auditDir": "/tmp/gh-aw/sandbox/firewall/audit",
"sessionStateDir": "/tmp/gh-aw/sandbox/agent/session-state",
"enableHostAccess": true,
"buildLocal": true,
"enableApiProxy": true,
"difcProxyHost": "host.docker.internal:18443",
"difcProxyCaCert": "/tmp/gh-aw/difc-proxy-tls/ca.crt",
"containerWorkdir": "/home/runner/work/repo/repo"
}
```
## Migration Path
This could be adopted incrementally:
1. Start by generating the config file alongside the existing flags
2. Validate that AWF produces identical behavior with `--config` vs. flags
3. Switch the compiled lock files to use `--config`
4. Eventually deprecate the long flag invocations in lock files
Contributor guide
Assessment
This issue has not been assessed yet.