Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.25.3
What's Changed
Other Changes
- fix: auto-inject GH_HOST from GITHUB_SERVER_URL when --env-all is used by @Copilot in #1453
- feat: add AWF issue auditor workflow by @lpcox in #1459
- feat: add --env-file support for injecting env vars from a file by @Copilot in #1457
- rename awf-issue-auditor → firewall-issue-dispatcher and prefix created issues with [awf] by @Copilot in #1470
- feat: add --exclude-env flag to exclude specific vars from --env-all passthrough by @Copilot in #1482
- feat(api-proxy): add WebSocket upgrade support to fix Codex /v1/responses streaming by @Copilot in #1486
Full Changelog: v0.25.2...v0.25.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
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 both squid and agent images)
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)
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 (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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)
--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 bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1774721240145")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.3/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.3/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.3/awf-linux-arm64 -o awf
curl -fL https://github.com...Contributors
lpcox
Assets 8
Release v0.25.2
What's Changed
New Feature: --allow-host-service-ports
Adds a new --allow-host-service-ports <ports> CLI flag for accessing GitHub Actions services: containers (e.g., PostgreSQL, Redis, MySQL) from within the AWF sandbox.
Why: GitHub Actions services: containers publish ports to the host via port mapping. These are typically on "dangerous" ports (5432, 6379, 3306) that AWF blocks by default. This flag allows agents to reach these specific ports on the host gateway only — traffic to the same ports on the internet remains blocked.
Usage:
# Allow PostgreSQL and Redis access to host services
sudo awf --allow-domains github.com --allow-host-service-ports 5432,6379 -- pytest
# Multiple services
sudo awf --allow-domains github.com --allow-host-service-ports 5432,6379,3306 -- npm testKey behaviors:
- Auto-enables
--enable-host-access(with explicit warning about ports 80/443 also opening) - Traffic restricted to host gateway IPs only (172.17.0.1 and 172.30.0.1) — cannot reach internet
- Port validation: single numeric ports 1-65535 (no ranges)
- Enforced at both host-level (FW_WRAPPER/DOCKER-USER) and container-level iptables
- SSH risk documented in
--helpwhen allowing port 22
Changes
Full Changelog: v0.25.1...v0.25.2
Contributors
Mossaka
Assets 8
Release v0.25.1
What's Changed
Documentation
- docs: Fix proxy env var docs and add missing CLI flags by @github-actions[bot] in #1350
Other Changes
- fix: write apiKeyHelper to ~/.claude/settings.json for Claude Code v2.1.81+ by @lpcox in #1414
- Pre-install commonly needed system packages in agent container image by @Copilot in #1432
- fix: allow host gateway traffic for localhost/Playwright by @Mossaka in #1435
Full Changelog: v0.25.0...v0.25.1
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
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 both squid and agent images)
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)
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)
-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 (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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
--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)
--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 bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1774490371167")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.1/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.1/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.1/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.1/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.1/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.1/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.1/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm in...Contributors
Mossaka and lpcox
Assets 8
Release v0.25.0
What's Changed
Other Changes
- chore(deps): update trivy-action to v0.35.0 by @lpcox in #1383
- chore: remove all trivy references by @Copilot in #1389
- feat: increase default agent memory limit to 6GB and enable swap by @Copilot in #1360
- Propagate $GITHUB_PATH into chroot PATH for setup-* action support by @Copilot in #1359
- perf: reduce CI integration test wall time by ~50% by @Copilot in #1399
- feat: add firewall audit/observability and policy logging by @Mossaka in #1405
Full Changelog: v0.24.5...v0.25.0
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
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 both squid and agent images)
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)
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)
-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 (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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
--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)
--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 bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1774294680531")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
--audit-dir <path> Directory for firewall audit artifacts (configs, policy manifest, iptables state)
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.0/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.0/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.0/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.0/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.0/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.0/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.25.0/checksums.txt -o checksums.tx...Contributors
Mossaka and lpcox
Assets 8
Release v0.24.5
What's Changed
Other Changes
- fix: update vulnerable dependencies (flatted, markdownlint-cli2) by @Copilot in #1374
- fix: eliminate 10s container shutdown delay by @Mossaka in #1373
Full Changelog: v0.24.4...v0.24.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
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 both squid and agent images)
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)
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)
-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., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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
--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)
--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 bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1773964226003")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.24.5/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
...Contributors
Mossaka
Assets 8
Release v0.24.4
What's Changed
Documentation
- docs: fix iptables logging references after simplification by @github-actions[bot] in #1292
Other Changes
- fix: skip safe dependency update PR when existing PR is open by @Copilot in #1335
- docs: update architecture docs with three-component overview by @Mossaka in #1340
- feat: support base path prefix for OpenAI and Anthropic API targets by @Copilot in #1369
Full Changelog: v0.24.3...v0.24.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
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 both squid and agent images)
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)
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)
-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., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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
--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)
--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 bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1773950551014")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.24.4/awf.tgzQuick Start
# Basic usage with domain ...Contributors
Mossaka
Assets 8
Release v0.24.3
What's Changed
Other Changes
- fix: route GHEC Copilot proxy to copilot-api subdomain by @Copilot in #1331
Full Changelog: v0.24.2...v0.24.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
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 both squid and agent images)
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)
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)
-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., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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
--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)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--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 bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1773728374988")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.24.3/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variables
sudo awf --allow-domains api.github.com -e GITHUB_TOKEN=xxx -- gh api /user
# Mount additional volumes
sudo awf --allow-domains github.com -v /my/data:/data:ro -- cat /data/file.txt
# Set working directory in container
sudo awf --allow-domains github.com --container-workdir /workspace -- pwdSee README.md for full documentation.
Container Images
Published to GitHub Container Registry:
ghcr.io/github/gh-aw-firewall/squid:0.24.3- `ghcr.io/github/gh-aw-firewall/agent...
Release v0.24.2
What's Changed
Other Changes
- feat(ci): add CI quality gates - CODEOWNERS, markdownlint, link checking by @Mossaka in #1269
- fix(squid): run Squid container as non-root proxy user by @Mossaka in #1271
- feat(ci): add weekly performance monitoring workflow by @Mossaka in #1272
- fix: speed up firewall shutdown by ~10s by @Mossaka in #1150
- fix(cli): fix secure_getenv() bypass of one-shot token protection by @Mossaka in #1244
- feat(ci): add documentation preview environment for PRs by @Mossaka in #1273
- feat(cli): add --enable-dind flag to opt-in to Docker socket access by @Mossaka in #1276
- feat(cli): add --ruleset-file for YAML domain rule configuration by @Mossaka in #1279
- feat: add DLP scanning to block credential exfiltration in URLs by @Mossaka in #1288
- feat(docker): switch seccomp profile to deny-by-default by @Mossaka in #1286
- feat(cli): add DNS-over-HTTPS support via --dns-over-https flag by @Mossaka in #1280
- feat(docker): separate iptables setup into init container by @Mossaka in #1281
- fix(docker): simplify to localhost+Squid-only iptables by @Mossaka in #1270
- feat(cli): auto-add api-target values to allowlist by @claude in #1290
- fix(cli): exclude GITHUB_API_URL when api-proxy is enabled by @claude in #1303
- feat(cli): auto-populate GHES firewall domains from engine.api-target by @claude in #1306
- feat(cli): auto-inject GH_HOST in agent container when GHES detected by @claude in #1305
- fix: auto-inject GHEC tenant domains into firewall allowlist by @Copilot in #1316
Full Changelog: v0.24.1...v0.24.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
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 both squid and agent images)
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)
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)
-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., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (default: "8.8.8.8,8.8.4.4")
--dns-over-https [resolver-url] Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)
--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
--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)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--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 bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1773555174323")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
Contributors
claude and Mossaka
Assets 8
Release v0.24.1
What's Changed
Other Changes
- ci: skip CI when only release.yml changes by @Mossaka in #1261
- docs: sync version references and add missing CLI flags by @Mossaka in #1223
- docs: document flag validation constraints by @Mossaka in #1230
- chore(deps): aggregated dependency updates by @Mossaka in #1218
- fix: use docker cp instead of file bind mounts for DinD compatibility by @Mossaka in #1079
- fix(proxy): add lowercase proxy vars and NODE_EXTRA_CA_CERTS by @Mossaka in #1234
- feat(cli): organize help text with logical option groups by @Mossaka in #1241
- test: add logger/aggregator tests for blocked domain detection by @Mossaka in #1262
- feat(cli): add --agent-timeout flag for execution time limit by @Mossaka in #1242
- feat(cli): add predownload command to pre-pull container images by @Mossaka in #1245
- feat(proxy): add GitHub Enterprise Cloud/Server support with automatic endpoint detection by @claude in #1264
Full Changelog: v0.24.0...v0.24.1
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
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)
--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 both squid and agent images)
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)
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)
-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., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
--tty Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)
Network & Security:
--dns-servers <servers> Comma-separated trusted DNS servers (default: "8.8.8.8,8.8.4.4")
--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
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)
--anthropic-api-target <host> Target hostname for Anthropic API requests (default: api.anthropic.com)
--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 bytes per minute per provider (requires --enable-api-proxy)
--no-rate-limit Disable rate limiting in the API proxy (requires --enable-api-proxy)
Logging & Debug:
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--agent-timeout <minutes> Maximum time in minutes for the agent command to run (default: no limit)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1773356466821")
--proxy-logs-dir <path> Directory to save Squid proxy access.log
-h, --help display help for command
Installation
One-Line Installer (Recommended)
Linux and macOS (x64 and ARM64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
- Downloads the correct release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/Linux (ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Apple Silicon / ARM64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/macOS (Intel / x64):
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/NPM Installation (Alternative)
# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf.tgzQuick Start
# Basic usage with domain whitelist
sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com
# Pass environment variab...Contributors
claude and Mossaka
Assets 8
Release v0.24.0
What's Changed
Other Changes
- test: add CI workflow for non-chroot integration tests by @Mossaka in #1048
- test: add DNS restriction enforcement tests by @Mossaka in #1054
- test: fix docker-warning tests and fragile timing dependencies by @Mossaka in #1049
- fix(ci): recompile ci-doctor and add missing workflows by @Copilot in #1067
- fix(deps): resolve high-severity rollup vulnerability in docs-site by @Copilot in #1069
- fix(deps): resolve minimatch ReDoS and ajv vulnerabilities by @Mossaka in #1152
- fix(squid): run Squid container as non-root user by @Mossaka in #1153
- fix(docker): disable IPv6 when ip6tables unavailable by @Mossaka in #1154
- fix(security): secure SSL Bump key wiping via tmpfs by @Mossaka in #1156
- fix(security): stop logging partial token values by @Mossaka in #1158
- fix(security): eliminate TOCTOU race conditions in ssl-bump.ts by @Mossaka in #1159
- fix(ci): resolve integration test suite failures on main by @Mossaka in #1151
- feat: combine all build-test workflows into single build-test.md by @Copilot in #1157
- fix(squid): block direct IP connections that bypass domain filtering by @Mossaka in #1160
- test: add workDir tmpfs hiding integration tests by @Mossaka in #1219
- test: add TOCTOU error path coverage for ssl-bump.ts by @Mossaka in #1161
- test: add chroot escape vector test coverage by @Mossaka in #1162
- test: add --proxy-logs-dir edge case coverage by @Mossaka in #1220
- test: add --allow-host-ports validation tests by @Mossaka in #1221
- test: add --skip-pull integration test by @Mossaka in #1222
- docs: clarify --image-tag behavior with agent-image presets by @Mossaka in #1228
- feat(cli): add short flags for frequently used options by @Mossaka in #1229
- fix(ci): update Copilot CLI version from 0.0.411 to 0.0.421 by @Mossaka in #1231
- fix(cli): clear LD_PRELOAD after one-shot-token library loads by @Mossaka in #1232
- test(docker): verify capsh execution chain after PR #715 by @Mossaka in #1240
- test: expand credential hiding tests to all 14 protected paths by @Mossaka in #1163
- feat(cli): add --memory-limit flag for configurable container memory by @Mossaka in #1243
- feat(proxy): add --openai-api-target and --anthropic-api-target flags by @claude in #1249
- fix: push only tag in release workflow to avoid branch protection violation by @Copilot in #1258
- fix: make release workflow compatible with branch protection by @Mossaka in #1260
Full Changelog: v0.23.1...v0.24.0
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
-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 containing allowed domains (one per line or comma-separated, supports # comments)
--block-domains <domains> Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
--block-domains-file <path> Path to file containing blocked domains (one per line or comma-separated, supports # comments)
--log-level <level> Log level: debug, info, warn, error (default: "info")
-k, --keep-containers Keep containers running after command exits (default: false)
--tty Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
--work-dir <dir> Working directory for temporary files (default: "/tmp/awf-1773339200015")
-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 both squid and agent images)
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 images to be pre-downloaded) (default: false)
-e, --env <KEY=VALUE> Additional environment variables to pass to container (can be specified multiple times) (default: [])
--env-all Pass all host environment variables to container (excludes system vars like PATH) (default: false)
-v, --mount <host_path:container_path[:mode]> Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--memory-limit <limit> Memory limit for the agent container (e.g., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
--dns-servers <servers> Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
--proxy-logs-dir <path> Directory to save Squid proxy logs to (writes access.log directly to this directory)
--enable-host-access Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
--allow-host-ports <ports> Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
--ssl-bump Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
--allow-urls <urls> Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
Supports wildcards: https://github.com/myorg/*
--enable-api-proxy Enable API proxy sidecar for holding authentication credentials.
Deploys a Node.js proxy that injects API keys securely.
Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
--copilot-api-target <host> Target hostname for GitHub Copilot API requests in the api-proxy sidecar.
Defaults to api.githubcopilot.com. Useful for GHES deployments.
Can also be set via COPILOT_API_TARGET env var.
--openai-api-target <host> Target hostname for OpenAI API requests in the api-proxy sidecar.
Defaults to api.openai.com. Useful for custom OpenAI-...
Contributors
claude and Mossaka