Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.27.11
What's Changed
Other Changes
- [Test Coverage] container-startup-diagnostics coverage by @github-actions[bot] in #5474
- docs: sync schemas and specs with source changes by @github-actions[bot] in #5480
- fix: eliminate catastrophic regex backtracking in postprocess script by @lpcox in #5491
- test: add manual network-isolation smoke workflow by @lpcox in #5492
- Add portable self-hosted runner doctor agent by @lpcox in #5504
- fix: pin network-isolation-test to concrete release tags by @lpcox in #5495
- docs: add AWF failure diagnosis guide (Self-Hosted Runner Doctor) by @lpcox in #5513
- docs: fix broken raw URL placeholder in AWF failure diagnosis guide by @lpcox in #5514
- perf: optimize duplicate-code-detector to reduce AIC by ~50% by @lpcox with @Copilot in #5517
- [Test Coverage] Add branch coverage for etc-mounts, system-mounts, api/doh-proxy, iptables-chain by @github-actions[bot] in #5509
- docs(runner-doctor): add A12 — binariesSourcePath / docker-host-path-prefix path collision on ARC/DinD by @lpcox with @Copilot in #5515
- refactor(api-proxy): extract sliding-window data structure into rate-limiter-window.js by @lpcox with @Copilot in #5523
- refactor: split
writeConfigsinto focused setup phases by @lpcox with @Copilot in #5521 - refactor: split agent-volumes-mounts.test.ts by feature area by @lpcox with @Copilot in #5522
- refactor: extract allow_host_access_to_gateway to deduplicate gateway iptables logic by @lpcox with @Copilot in #5516
- test: shared port-spec fixture to keep TypeScript and shell validators in sync by @lpcox with @Copilot in #5519
- refactor(copilot): extract buildCopilotModelsRequest to deduplicate /models auth headers by @lpcox with @Copilot in #5518
- refactor(api-proxy): extract guard enforcement into proxy-guards.js by @lpcox with @Copilot in #5520
- fix(network-isolation): break topology-attach ordering deadlock starving cli-proxy health gate by @lpcox with @Copilot in #5544
- Fix rootless firewall artifact permissions to prevent EACCES on upload by @lpcox with @Copilot in #5546
- test: fix stale assertions breaking npm test on main by @lpcox in #5549
Full Changelog: v0.27.10...v0.27.11
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--network-isolation Experimental: enforce egress via Docker network topology (internal network +
dual-homed proxy) instead of iptables. Requires no sudo/NET_ADMIN.
Not yet supported with --dns-over-https or --enable-host-access. (default: false)
--topology-attach <name> With --network-isolation, attach an externally-launched trusted container
(by name) to the internal network so the agent can reach it.
Repeatable. Example: --topology-attach m...
Contributors
lpcox
Assets 14
- 2.28 KB
2026-06-26T00:00:03Z - 639 KB
2026-06-26T00:00:03Z - 36.4 KB
2026-06-26T00:00:03Z - 36.4 KB
2026-06-26T00:00:03Z - 50.5 MB
2026-06-26T00:00:03Z - 57.5 MB
2026-06-26T00:00:03Z - 49.2 MB
2026-06-26T00:00:03Z - 52.8 MB
2026-06-26T00:00:03Z - 2.73 MB
2026-06-26T00:00:03Z - 916 Bytes
2026-06-26T00:00:03Z -
2026-06-25T23:51:17Z -
2026-06-25T23:51:17Z - Loading
Release v0.27.10
What's Changed
Other Changes
- fix(chroot): mount binaries overlay at /host/tmp/awf-runner-bin to avoid read-only /host/usr collision on ARC/DinD by @lpcox with @Copilot in #5482
Full Changelog: v0.27.9...v0.27.10
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--network-isolation Experimental: enforce egress via Docker network topology (internal network +
dual-homed proxy) instead of iptables. Requires no sudo/NET_ADMIN.
Not yet supported with --dns-over-https or --enable-host-access. (default: false)
--topology-attach <name> With --network-isolation, attach an externally-launched trusted container
(by name) to the internal network so the agent can reach it.
Repeatable. Example: --topology-attach mcp-gateway --topology-attach difc-proxy (default: [])
--allow-host-ports <ports> Ports/ranges to allow with --enable-host-access (default: 80,443).
Example: 3000,8080 or 3000-3010,8000-8090
--allow-host-service-ports <ports> Ports to allow ONLY to host gateway (for GitHub Actions services).
Bypasses dangerous port restrictions. Auto-enables host access.
WARNING: Allowing port 22 grants SSH access to the host.
Example: 5432,6379
--enable-dind Enable Docker-in-Docker by exposing host Docker socket.
WARNING: allows firewall bypass via docker run (default: false)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--copilot-api-target <host> Target hostname for Copilot API requests (default: api.githubcopilot.com)
--openai-api-target <host> Target hostname for OpenAI API requests (default: api.openai.com)
--openai-api-base-path <path> Base path prefix for OpenAI API requests (e.g. /serving-endpoints for Databricks)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--anthropic-api-base-path <path> Base path prefix for Anthropic API requests (e.g. /anthropic)
--openai-api-auth-header <name> Custom auth header name for OpenAI requests (default: Authorization with Bearer prefix)
--anthropic-api-auth-header <name> Custom auth header name for Anthropic requests (default: x-api-key)
--gemini-api-target <host> Target hostname for Gemini API requests (default: generativelanguage.googleapis.com)
--gemini-api-base-path <path> Base path prefix for Gemini API requests
--anthropic-auto-cache Enable Anthropic prompt-cache optimizations in the API proxy (requires --enable-api-proxy).
Injects cache breakpoints on tools/system/messages, upgrades TTL to 1h,
and strips ANSI codes — typically saves ~90% on Anthropic API input costs. (default: false)
--anthropic-cache-tail-ttl <5m|1h> TTL for the rolling-tail cache breakpoint...
Contributors
lpcox
Assets 14
Release v0.27.9
What's Changed
Other Changes
- fix(api-proxy): use 'token' auth prefix for Copilot Business endpoint by @lpcox in #5415
- refactor: extract shared helper to eliminate duplicate test scaffold in docker-host-env tests by @lpcox with @Copilot in #5419
- refactor: extract shared helpers for duplicate Gemini secret-isolation tests by @lpcox with @Copilot in #5420
- refactor(api-proxy): decompose handleUpstreamResponse into focused helpers by @lpcox with @Copilot in #5421
- refactor: extract buildAgentSecurityConfig from buildAgentService by @lpcox with @Copilot in #5422
- Fix gVisor workflow: Add proper health checks for Squid and Envoy by @lpcox in #5237
- chore: upgrade gh-aw to v0.81.0 and recompile workflows by @lpcox in #5447
- test: fix failing npm test after gh-aw v0.81.0 recompile by @lpcox in #5450
- Refactor
generatePolicyManifestinto composable policy section builders by @lpcox with @Copilot in #5446 - Refactor api-proxy upstream response factory into focused modules by @lpcox with @Copilot in #5445
- Refactor WebSocket proxy by extracting guard and tunnel modules by @lpcox with @Copilot in #5444
- Refactor api-proxy service config into env and lifecycle builders by @lpcox with @Copilot in #5443
- Refactor api-proxy credential isolation into per-provider env builders by @lpcox with @Copilot in #5442
- Add Self-Hosted Runner Doctor workflow for ARC/DinD and enterprise AWF triage by @lpcox with @Copilot in #5460
- Refactor host-access validation tests to remove duplicated exit/assert scaffolding by @lpcox with @Copilot in #5462
- refactor(test): extract runAuditFilter helper to deduplicate audit filter tests by @lpcox with @Copilot in #5461
- fix: de-flake docker-host staging tests (parallel-worker race on /tmp/gh-aw) by @lpcox in #5467
Full Changelog: v0.27.8...v0.27.9
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--network-isolation Experimental: enforce egress via Docker network topology (internal network +
dual-homed proxy) instead of iptables. Requires no sudo/NET_ADMIN.
Not yet supported with --dns-over-https or --enable-host-access. (default: false)
--topology-attach <name> With --network-isolation, attach an externally-launched trusted container
(by name) to the internal network so the agent can reach it.
Repeatable. Example: --topology-attach mcp-gateway --topology-attach difc-proxy (default: [])
--allow-host-ports <ports> Ports/ranges to allow with --enable-host-access (default: 80,443).
Example: 3000,8080 or 3000-3010,8000-8090
--allow-host-service-ports <ports> Ports to allow ONLY to host gateway (for GitHub Actions services).
Bypasses dangerous port restrictions. Auto-enables host access.
WARNING: Allowing port 22 g...
Contributors
lpcox
Assets 14
Release v0.27.8
What's Changed
Other Changes
- chore: upgrade gh-aw to v0.80.6 and recompile workflows by @lpcox in #5294
- [Test Coverage] Add coverage for parsers, services, host-identity by @github-actions[bot] in #5240
- docs: sync schemas and specs with source changes by @github-actions[bot] in #5250
- fix: propagate config fields to all layers by @github-actions[bot] in #5279
- docs: sync schemas and specs with source changes by @github-actions[bot] in #5283
- [WIP] Refactor entrypoint.sh by extracting initialization phases into functions by @lpcox with @Copilot in #5285
- Refactor workdir setup tests and guard fixture cleanup by @lpcox with @Copilot in #5303
- [WIP] Refactor Docker startup retry tests to reduce code duplication by @lpcox with @Copilot in #5304
- [WIP] Refactor API proxy secret-isolation tests to reduce duplicate code by @lpcox with @Copilot in #5305
- [WIP] Fix security guard workflow failure due to authentication issues by @lpcox with @Copilot in #5306
- fix(ci): prevent empty safeoutputs schema probes in smoke-claude workflow by @lpcox with @Copilot in #5307
- [WIP] Fix missing data in contribution check workflow by @lpcox with @Copilot in #5308
- [WIP] Refactor to extract rule-setup phases into named bash functions by @lpcox with @Copilot in #5309
- [WIP] Refactor extract functions in token-parsers file by @lpcox with @Copilot in #5310
- fix(smoke-claude): raise turn budget to 8 and fix add_comment usage by @lpcox in #5328
- perf(security-guard): prioritize security-relevant files in PR diff by @lpcox in #5329
- [Test Coverage] Cover regex rules in policy-manifest and signals in log-streamer by @github-actions[bot] in #5317
- Split api-proxy token parser tests by JSON, SSE, and normalization concerns by @lpcox with @Copilot in #5356
- Split config-assembly validator tests by concern group by @lpcox with @Copilot in #5348
- refactor: split docker-manager-lifecycle.test.ts into focused modules by @lpcox with @Copilot in #5347
- Increase Documentation Maintainer LLM invocation budget to prevent false Copilot auth failures by @lpcox with @Copilot in #5349
- Refactor duplicated invalid host-service port assertions in host-access firewall tests by @lpcox with @Copilot in #5350
- Deduplicate
runMainWorkflowtest scaffolding by @lpcox with @Copilot in #5351 - Split docker-manager utility tests into focused concern-based modules by @lpcox with @Copilot in #5354
- Split docker-manager cleanup tests by concern by @lpcox with @Copilot in #5357
- Split api-proxy auth tests into focused provider-aligned modules by @lpcox with @Copilot in #5353
- [Test Coverage] deduplicate docker-manager.ts re-export tests by @github-actions[bot] in #5341
- Refactor
writeConfigscleanup tests to remove duplicated config + tolerant-failure scaffolding by @lpcox with @Copilot in #5352 - Refactor host iptables setup into validation, chain, and rule modules by @lpcox with @Copilot in #5355
- refactor(tests): deduplicate COPILOT_MODEL detection test scaffolding by @lpcox with @Copilot in #5369
- [WIP] Refactor audit enricher tests to remove duplicate policy fixture builders by @lpcox with @Copilot in #5370
- fix: propagate config fields to all layers by @github-actions[bot] in #5387
- [Test Coverage] squid-log-reader.ts: 100% coverage by @github-actions[bot] in #5378
- Refactor duplicated firewall topology assertions in
ensureFirewallNetworktests by @lpcox with @Copilot in #5371 - refactor: move agent-service testHelpers to dedicated test-utils file by @lpcox with @Copilot in #5394
- Remove unused
DomainProtocolexport from domain-patterns.ts by @lpcox with @Copilot in #5395 - Remove unused export from
resolveAgentImageConfigby @lpcox with @Copilot in #5396 - Remove unused
ParsedDomainfrom domain-patterns by @lpcox with @Copilot in #5397 - Remove unused
ParsedDomainListexport from domain-matchers by @lpcox with @Copilot in #5398
Full Changelog: v0.27.7...v0.27.8
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemo...
Contributors
lpcox
Assets 14
Release v0.27.7
What's Changed
Other Changes
- fix: check iptables availability before host firewall setup by @zarenner with @Copilot in #5136
- fix(api-proxy): map OpenAI Responses API cached tokens to cache_read by @lpcox in #5262
- ci(smoke): add token-usage sanity checks to smoke workflows by @lpcox in #5264
- fix(containers): apt install fallback to archive.ubuntu.com by @lpcox in #5266
- fix(api-proxy): 403 for terminal caps; fix Anthropic/Copilot input credits by @lpcox in #5271
Full Changelog: v0.27.6...v0.27.7
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--allow-host-ports <ports> Ports/ranges to allow with --enable-host-access (default: 80,443).
Example: 3000,8080 or 3000-3010,8000-8090
--allow-host-service-ports <ports> Ports to allow ONLY to host gateway (for GitHub Actions services).
Bypasses dangerous port restrictions. Auto-enables host access.
WARNING: Allowing port 22 grants SSH access to the host.
Example: 5432,6379
--enable-dind Enable Docker-in-Docker by exposing host Docker socket.
WARNING: allows firewall bypass via docker run (default: false)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--copilot-api-target <host> Target hostname for Copilot API requests (default: api.githubcopilot.com)
--openai-api-target <host> Target hostname for OpenAI API requests (default: api.openai.com)
--openai-api-base-path <path> Base path prefix for OpenAI API requests (e.g. /serving-endpoints for Databricks)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--anthropic-api-base-path <path> Base path prefix for Anthropic API requests (e.g. /anthropic)
--openai-api-auth-header <name> Custom auth header name for OpenAI requests (default: Authorization with Bearer prefix)
--anthropic-api-auth-header <name> Custom auth header name for Anthropic requests (default: x-api-key)
--gemini-api-target <host> Target hostname for Gemini API requests (default: generativelanguage.googleapis.com)
--gemini-api-base-path <path> Base path prefix for Gemini API requests
--anthropic-auto-cache Enable Anthropic prompt-cache optimizations in the API proxy (requires --enable-api-proxy).
Injects cache breakpoints on tools/system/messages, upgrades TTL to 1h,
and strips ANSI codes — typically saves ~90% on Anthropic API input costs. (default: false)
--anthropic-cache-tail-ttl <5m|1h> TTL for the rolling-tail cache breakpoint when --anthropic-auto-cache is enabled.
Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
--rate-limit-rpm <n> Max requests per minute per p...
Contributors
zarenner and lpcox
Assets 14
Release v0.27.6
What's Changed
Other Changes
- fix(contribution-check): pre-fetch steps skipped on workflow_dispatch triggers by @lpcox with @Copilot in #5193
- fix: normalizeUsage maps OpenAI prompt_tokens_details.cached_tokens to cache_read_tokens by @lpcox with @Copilot in #5204
- docs: comprehensive auth matrix documentation and tests by @lpcox in #4794
- Add max-cache-misses guardrail for API proxy token budget enforcement by @lpcox with @Copilot in #5202
- Centralize provider adapter assembly with
buildProviderAdapterand enforceisEnabledcontract by @lpcox with @Copilot in #5205 - Refactor: extract
createProviderOidcAuthto unify OIDC setup across provider adapters by @lpcox with @Copilot in #5206 - fix: allow node preflight to use explicit binary by @zarenner in #5145
- refactor: extract provider env var constants to a shared module by @lpcox with @Copilot in #5207
- Add comprehensive gVisor firewall comparison workflow by @lpcox in #5236
- fix(api-proxy): copy token-tracker-shared + otel modules into image (fixes AIC=0) by @lpcox in #5254
- fix(api-proxy): use copilot_usage token_details for accurate cache split by @lpcox in #5253
Full Changelog: v0.27.5...v0.27.6
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--allow-host-ports <ports> Ports/ranges to allow with --enable-host-access (default: 80,443).
Example: 3000,8080 or 3000-3010,8000-8090
--allow-host-service-ports <ports> Ports to allow ONLY to host gateway (for GitHub Actions services).
Bypasses dangerous port restrictions. Auto-enables host access.
WARNING: Allowing port 22 grants SSH access to the host.
Example: 5432,6379
--enable-dind Enable Docker-in-Docker by exposing host Docker socket.
WARNING: allows firewall bypass via docker run (default: false)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--copilot-api-target <host> Target hostname for Copilot API requests (default: api.githubcopilot.com)
--openai-api-target <host> Target hostname for OpenAI API requests (default: api.openai.com)
--openai-api-base-path <path> Base path prefix for OpenAI API requests (e.g. /serving-endpoints for Databricks)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--anthropic-api-base-path <path> Base path prefix for Anthropic API requests (e.g. /anthropic)
--openai-api-auth-header <name> Custom auth header name for OpenAI requests (default: Authorization with Bearer prefix)
--anthropic-api-auth-header <name> Custom auth header name for Anthropic requests (default: x-api-key)
...
Contributors
zarenner and lpcox
Assets 14
Release v0.27.5
What's Changed
Other Changes
- feat: allowedModels / disallowedModels policy enforcement in api-proxy by @Copilot in #5095
- fix: propagate platform.type config field to spec CLI mapping by @github-actions[bot] in #5110
- fix(ci-gate): tag PR owner with instructions by @lpcox in #5116
- [Test Coverage] Improve test coverage for network-options, environment-builder, log-parser, workspace-mounts by @github-actions[bot] in #5104
- docs: sync schemas and specs with source changes by @github-actions[bot] in #5114
- fix: add bare API proxy targets as https:// only to prevent over-broad allowlisting by @Copilot in #5130
- fix: make GitHub MCP tool optional in AOAI Copilot smoke workflows by @Copilot in #5124
- Reduce Refactoring Scanner AI-credit burn from duplicate-issue lookups by @Copilot in #5125
- refactor(cli-proxy): decompose handleExec into buildExecEnv and runGhCommand by @Copilot in #5126
- refactor: decompose
prepareWorkDirectoriesinto two focused sub-functions by @Copilot in #5128 - refactor: split api-proxy-config.ts into focused validation, warnings, and domains modules by @Copilot in #5127
- refactor(agent-service): extract resolveAgentImageConfig from buildAgentService by @Copilot in #5129
- Fix duplicate-code-detector: Add missing GH_TOKEN for gh CLI authentication by @Copilot in #5146
- feat(api-proxy): forward COPILOT_INTEGRATION_ID from host env by @lpcox in #5147
- [Test Coverage] Add branch coverage for audit-enricher, log-and-limits, docker-host-staging by @github-actions[bot] in #5152
- Reduce Pelis Advisor AI credit burn with fixed low-cost model + turn cap by @Copilot in #5166
- fix(ci-cd-gaps-assessment): resolve AI credits rate limit with DataOps refactor by @Copilot in #5165
- feat(workflow): optimize test-coverage-reporter token usage (~26% avg, ~60% worst-case) by @Copilot in #5160
- fix(security-guard): switch model to claude-haiku-4-5 to avoid rate limiting by @Copilot in #5164
- fix(smoke-claude): raise max-turns to 2 to eliminate 96% failure rate by @Copilot in #5162
- fix(contribution-check): switch to gpt-5.4-mini and add cancel-in-progress concurrency by @Copilot in #5163
Full Changelog: v0.27.4...v0.27.5
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--allow-host-ports <ports> Ports/ranges to allow with --enable-host-access (default: 80,443).
Example: 3000,8080 or 3000-3010,8000-8090
--allow-host-service-ports <ports> Ports to allow ONLY to host gateway (for GitHub Actions services).
Bypasses dangerous port restrictions. Auto-enables host access.
WARNING: Allowing port 22 grants SSH access to the host.
Example: 5432,6379
--enable-dind Enable Docker-in-Docker b...
Contributors
lpcox
Assets 14
Release v0.27.4
What's Changed
Other Changes
- Reduce test-coverage-reporter prompt surface and coverage payload size by @Copilot in #4871
- fix: add noop fallback to smoke-copilot workflows on non-PR triggers by @Copilot in #4872
- fix(dispatcher): eliminate AI credits overrun with DataOps pre-fetch and hard guardrails by @Copilot in #4870
- fix(workflow): use gpt-5.4-mini and raise max-ai-credits for copilot-token-usage-analyzer by @Copilot in #4877
- Honor workflow-level COPILOT_MODEL in Copilot BYOK smoke workflows by @Copilot in #4876
- test: add docker-manager barrel and cleanup branch coverage by @github-actions[bot] in #4861
- Clarify non-PR behavior in AOAI Entra smoke workflow to prevent missing_data failures by @Copilot in #4875
- refactor: decompose 287-line
assembleAndValidateConfiginto named helpers by @Copilot in #4894 - refactor: extract adapter-factory.js from proxy-utils.js by @Copilot in #4895
- refactor: decompose
writeConfigsintoworkdir-setup.ts+ focused orchestrator by @Copilot in #4896 - chore: recompile all workflows with gh-aw v0.79.6 by @lpcox in #4890
- fix: normalize model name separators in AWF CLI validation by @Copilot in #4908
- Add interactive workflow designer agent by @lpcox in #4910
- [Test Coverage] artifact-preservation.ts error paths by @github-actions[bot] in #4925
- refactor(token-tracker-http): decompose 238-line trackTokenUsage into testable top-level functions by @Copilot in #4937
- refactor(model-resolver): decompose resolveModel into focused sub-functions; move version utils tests by @Copilot in #4938
- Refactor OpenAI BYOK base URL parsing to reuse shared proxy URL normalization by @Copilot in #4949
- refactor(api-proxy): split proxy-request.js into http-client.js and body-handler.js by @Copilot in #4939
- Refactor shared OIDC runtime auth flow for OpenAI and Copilot adapters by @Copilot in #4948
- Reduce CI/CD gaps assessment run cost to avoid AI-credit guardrail trips by @Copilot in #4943
- Deduplicate shared fs/host-home Jest mock setup in config-writer and workdir-setup tests by @Copilot in #4940
- Deduplicate Copilot bearer-prefix stripping in api-proxy by @Copilot in #4951
- refactor(api-proxy): deduplicate guard enforcement between HTTP and WebSocket paths, fix 3 missing WebSocket guards by @Copilot in #4950
- Centralize AWF container IP topology constants and remove duplicated literals by @Copilot in #4947
- refactor: extract
parseUrlPatternsfromssl-bump.tsintodomain-patterns.tsby @Copilot in #4946 - feat(test-coverage-reporter): token optimization — ~57% reduction per run by @Copilot in #4945
- Reduce Copilot token analyzer prompt verbosity to avoid max-ai-credits trips by @Copilot in #4944
- Pin Duplicate Code Detector to priced Copilot model to avoid unknown-model AI credit failures by @Copilot in #4942
- Refactor OTEL test module-reload helper into shared utility by @Copilot in #4941
- fix(api-proxy): add embedding model pricing to resolve unknown model rejection by @Copilot in #4936
- Remove unused export: CopilotModelValidationResult by @Copilot in #5029
- refactor(api-proxy): eliminate duplicate Copilot auth-error diagnostic test scaffolding by @Copilot in #5027
- Remove unused export:
isContainerStartupFailureErrorby @Copilot in #5023 - refactor(logs): remove unused
aggregateLogsexport by @Copilot in #5022 - Remove unused export: SquidLogCheckResult by @Copilot in #5021
- refactor(api-proxy tests): extract shared upstream mock cycle helpers by @Copilot in #5028
- refactor(tests): deduplicate WebSocket frame builder across token-tracker schema tests by @Copilot in #5026
- smoke-claude: token optimization — precompute result, restrict bash tools, minimize prompt by @Copilot in #5024
- [Test Coverage] squid ACL security modules (acl-generator, access-rules, domain-acl) by @github-actions[bot] in #5012
- feat: optimize duplicate-code-detector workflow token usage (~50% reduction) by @Copilot in #5025
- fix: correct acl-generator test assertions to match formatDomainForSquid output by @lpcox in #5049
- feat: gate agentic CI behind ready-for-ci label by @lpcox in #5054
- Refactor
ApiProxyOptionsinto composed, domain-focused option interfaces by @Copilot in #5060 - test: add manual gVisor compatibility test workflow by @lpcox in #5064
- refactor: decompose validateDomainOrPattern and split domain-patterns.ts by concern by @Copilot in #5063
- fix: recognize copilot-pull-request-reviewer in ci-gate by @lpcox in #5068
- refactor: decompose
finalizeHttpTrackinginto focused helper functions by @Copilot in #5072 - fix: broaden GHES detection for Copilot auth prefix by @lpcox in #5076
Full Changelog: v0.27.3...v0.27.4
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/ag...
Contributors
lpcox
Assets 14
Release v0.27.3
What's Changed
Other Changes
- [Test Coverage] host-iptables branch coverage by @github-actions[bot] in #4738
- docs: sync schemas and specs with source changes by @github-actions[bot] in #4752
- fix: chroot runner tool cache mountpoints by @zarenner in #4733
- perf(doc-maintainer): reduce per-run token usage by @Copilot in #4765
- perf(test-coverage-reporter): reduce token usage ~7-10% per run by @Copilot in #4764
- fix: propagate apiProxy.diagnostics config fields to all layers by @github-actions[bot] in #4743
- refactor: extract assignImageSource to deduplicate service builders by @lpcox in #4777
- refactor: extract shared token-tracker budget helpers by @lpcox in #4780
- refactor: extract validateAuthHeaderEnv and isValidHeaderName helpers by @lpcox in #4783
- refactor: extract makeUnconfiguredHealthResponse helper by @lpcox in #4781
- refactor: extract createCounterGuard factory for guard modules by @lpcox in #4784
- fix: skip symlink assertion for pre-existing path segments by @lpcox in #4786
- chore: upgrade all agentic workflows by @lpcox in #4819
- test: regression tests for Copilot SDK model-missing AI credits bug by @lpcox in #4797
- [Test Coverage] container-lifecycle.ts retry/timeout/kill branches by @github-actions[bot] in #4809
- fix(docker-host): pass through loopback TCP DOCKER_HOST for ARC/DinD orchestration by @Copilot in #4832
- feat(api-proxy): implement OTLP fan-out to multiple endpoints by @lpcox in #4845
- fix(entrypoint): bind-mount passwd/group synthesis fallback for read-only /host/etc (ARC/DinD) by @Copilot in #4831
Full Changelog: v0.27.2...v0.27.3
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--allow-host-ports <ports> Ports/ranges to allow with --enable-host-access (default: 80,443).
Example: 3000,8080 or 3000-3010,8000-8090
--allow-host-service-ports <ports> Ports to allow ONLY to host gateway (for GitHub Actions services).
Bypasses dangerous port restrictions. Auto-enables host access.
WARNING: Allowing port 22 grants SSH access to the host.
Example: 5432,6379
--enable-dind Enable Docker-in-Docker by exposing host Docker socket.
WARNING: allows firewall bypass via docker run (default: false)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--copilot-api-target <host> Target hostname for Copilot API requests (default: api.githubcopilot.com)
--op...
Contributors
zarenner and lpcox
Assets 14
Release v0.27.2
What's Changed
Other Changes
- fix(api-proxy): use 'token' auth prefix for GHES enterprise Copilot API by @lpcox in #4755
- fix(api-proxy): stop double-counting cached tokens in AI credits by @lpcox in #4760
- fix: WIF/OIDC Anthropic auth regression — Squid blocks api-proxy OIDC exchange + ANTHROPIC_API_KEY leaks to agent by @Copilot in #4748
Full Changelog: v0.27.1...v0.27.2
CLI Options
Usage: awf [options] [command] [args...]
Network firewall for agentic workflows with domain whitelisting
Arguments:
args Command and arguments to execute (use -- to separate from options)
Options:
-V, --version output the version number
Configuration:
--config <path> Path to AWF JSON/YAML config file (use "-" to read from stdin)
Domain Filtering:
-d, --allow-domains <domains> Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
github.com - exact domain + subdomains (HTTP & HTTPS)
*.github.com - any subdomain of github.com
api-*.example.com - api-* subdomains
https://secure.com - HTTPS only
http://legacy.com - HTTP only
localhost - auto-configure for local testing (Playwright, etc.)
--allow-domains-file <path> Path to file with allowed domains (one per line, supports # comments)
--ruleset-file <path> YAML rule file for domain allowlisting (repeatable). Schema: version: 1, rules: [{domain, subdomains}] (default: [])
--block-domains <domains> Comma-separated blocked domains (overrides allow list). Supports wildcards.
--block-domains-file <path> Path to file with blocked domains (one per line, supports # comments)
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
--allow-urls <urls> Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
Image Management:
-b, --build-local Build containers locally instead of using GHCR images (default: false)
--agent-image <value> Agent container image (default: "default")
Presets (pre-built, fast):
default - Minimal ubuntu:22.04 (~200MB)
act - GitHub Actions parity (~2GB)
Custom base images (requires --build-local):
ubuntu:XX.XX
ghcr.io/catthehacker/ubuntu:runner-XX.XX
ghcr.io/catthehacker/ubuntu:full-XX.XX
--image-registry <registry> Container image registry (default: "ghcr.io/github/gh-aw-firewall")
--image-tag <tag> Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
Optional digest metadata format:
<tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
Image name varies by --agent-image preset:
default → agent:<tag>
act → agent-act:<tag> (default: "latest")
--skip-pull Use local images without pulling from registry (requires pre-downloaded images) (default: false)
--docker-host <socket> Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
Use when Docker is at a non-standard path.
Example: unix:///run/user/1000/docker.sock
--docker-host-path-prefix <prefix> Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
Useful for split runner/daemon filesystems (e.g. ARC DinD).
Example: /host
Container Configuration:
-e, --env <KEY=VALUE> Environment variable for the container (repeatable) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
--exclude-env <name> Exclude a specific environment variable from --env-all passthrough (repeatable) (default: [])
--env-file <path> Read environment variables from a file (KEY=VALUE format, one per line)
-v, --mount <host_path:container_path[:mode]>
Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container
--memory-limit <limit> Memory limit for the agent container (e.g., 4g, 6g, 8g, 512m). Default: 6g (default: "6g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (auto-detected from host if omitted)
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
Network & Security:
--upstream-proxy <url> Upstream (corporate) proxy URL for Squid to chain through.
Auto-detected from host https_proxy/http_proxy if not set.
Example: http://proxy.corp.com:3128
--enable-host-access Enable access to host services via host.docker.internal (default: false)
--allow-host-ports <ports> Ports/ranges to allow with --enable-host-access (default: 80,443).
Example: 3000,8080 or 3000-3010,8000-8090
--allow-host-service-ports <ports> Ports to allow ONLY to host gateway (for GitHub Actions services).
Bypasses dangerous port restrictions. Auto-enables host access.
WARNING: Allowing port 22 grants SSH access to the host.
Example: 5432,6379
--enable-dind Enable Docker-in-Docker by exposing host Docker socket.
WARNING: allows firewall bypass via docker run (default: false)
--enable-dlp Enable DLP (Data Loss Prevention) scanning to block credential
exfiltration in outbound request URLs. (default: false)
API Proxy:
--enable-api-proxy Enable API proxy sidecar for secure credential injection.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--copilot-api-target <host> Target hostname for Copilot API requests (default: api.githubcopilot.com)
--openai-api-target <host> Target hostname for OpenAI API requests (default: api.openai.com)
--openai-api-base-path <path> Base path prefix for OpenAI API requests (e.g. /serving-endpoints for Databricks)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--anthropic-api-base-path <path> Base path prefix for Anthropic API requests (e.g. /anthropic)
--openai-api-auth-header <name> Custom auth header name for OpenAI requests (default: Authorization with Bearer prefix)
--anthropic-api-auth-header <name> Custom auth header name for Anthropic requests (default: x-api-key)
--gemini-api-target <host> Target hostname for Gemini API requests (default: generativelanguage.googleapis.com)
--gemini-api-base-path <path> Base path prefix for Gemini API requests
--anthropic-auto-cache Enable Anthropic prompt-cache optimizations in the API proxy (requires --enable-api-proxy).
Injects cache breakpoints on tools/system/messages, upgrades TTL to 1h,
and strips ANSI codes — typically saves ~90% on Anthropic API input costs. (default: false)
--anthropic-cache-tail-ttl <5m|1h> TTL for the rolling-tail cache breakpoint when --anthropic-auto-cache is enabled.
Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
--rate-limit-rpm <n> Max requests per minute per provider (requires --enable-api-proxy)
--rate-limit-rph <n> Max requests per hour per provider (requires --enable-api-proxy)
--rate-limit-bytes-pm <n> Max request byt...
Contributors
lpcox