Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.18.0
What's Changed
Documentation
- [docs] docs: sync version requirements with package.json by @github-actions[bot] in #848
Other Changes
- feat: proxy claude api calls to secure auth token by @claude in #849
- feat: disable codex credential sharing, enable proxied calls by @claude in #854
- chore: bump version to 0.17.1 by @claude in #853
- chore: bump version to 0.17.1 by @claude in #855
- chore: bump version to 0.17.2 by @claude in #856
- chore: bump version to 0.18.0 by @claude in #858
Full Changelog: v0.17.0...v0.18.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
--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")
--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-1771104976121")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.18.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.18.0/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.18.0/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.18.0ghcr.io/github/gh-aw-firewall/agent:0.18.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.18.0For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude
Assets 5
Release v0.17.1
What's Changed
Other Changes
Full Changelog: v0.17.0...v0.17.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
--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")
--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-1771102954753")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.17.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.17.1/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.17.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 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.17.1ghcr.io/github/gh-aw-firewall/agent:0.17.1ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.17.1For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude
Assets 5
Release v0.17.0
What's Changed
Other Changes
- perf: batch chroot integration tests to reduce container overhead by @Mossaka in #845
- feat(ci): add api-proxy image to release pipeline by @Mossaka in #846
Full Changelog: v0.16.5...v0.17.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
--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")
--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-1771029890232")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.17.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.17.0/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.17.0/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.17.0ghcr.io/github/gh-aw-firewall/agent:0.17.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.17.0For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.16.5
What's Changed
Other Changes
- fix: add roles: all to smoke-codex workflow by @Mossaka in #841
- fix: fix API proxy sidecar bugs preventing Anthropic-only usage by @Mossaka in #843
Full Changelog: v0.16.4...v0.16.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
--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")
--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-1771022638971")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.5/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.5/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.16.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
# 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.16.5ghcr.io/github/gh-aw-firewall/agent:0.16.5ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.16.5For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.16.4
What's Changed
Other Changes
- test: fix exit code validation in test runner fixture by @claude in #792
- fix: unset sensitive tokens from entrypoint environ after agent starts by @claude in #809
Full Changelog: v0.16.3...v0.16.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
--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")
--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-1770969439189")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.4/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.4/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.16.4/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.16.4ghcr.io/github/gh-aw-firewall/agent:0.16.4ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.16.4For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude
Assets 5
Release v0.16.3
What's Changed
Other Changes
Full Changelog: v0.16.2...v0.16.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
--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")
--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-1770966378413")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.3/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.3/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.16.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.16.3ghcr.io/github/gh-aw-firewall/agent:0.16.3ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.16.3For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.16.2
What's Changed
Other Changes
Full Changelog: v0.16.1...v0.16.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
--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")
--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-1770958359246")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.2/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.2/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.16.2/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.16.2ghcr.io/github/gh-aw-firewall/agent:0.16.2ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.16.2For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude
Assets 5
Release v0.16.1
What's Changed
Other Changes
Full Changelog: v0.16.0...v0.16.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
--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")
--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-1770949865570")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.1/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.16.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 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.16.1ghcr.io/github/gh-aw-firewall/agent:0.16.1ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.16.1For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude
Assets 5
Release v0.16.0
What's Changed
Other Changes
- fix: upgrade gpgv in squid container to address CVE-2025-68973 by @Mossaka in #757
- fix: upgrade packages in agent container to mitigate CVE-2023-44487 by @Mossaka in #760
- fix: use secure temp directory in volume-mounts test by @Mossaka in #765
- fix: replace unanchored regex with string assertions in tests by @Mossaka in #767
- fix(docker): hide credentials at direct home mount in chroot mode by @claude in #700
- feat: add secret-digger red team workflows by @Mossaka in #775
- feat: add API proxy sidecar for secure LLM credential management by @claude in #751
Full Changelog: v0.15.0...v0.16.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
--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")
--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-1770941449401")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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)
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.16.0/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.16.0/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.16.0ghcr.io/github/gh-aw-firewall/agent:0.16.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.16.0For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
claude and Mossaka
Assets 5
Release v0.15.0
What's Changed
Other Changes
- refactor: remove --enable-chroot flag, make chroot mode always-on by @Copilot in #714
Full Changelog: v0.14.3...v0.15.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
--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")
--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-1770934138483")
--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 (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: [])
--allow-full-filesystem-access ⚠️ SECURITY WARNING: Mount entire host filesystem with read-write access.
This DISABLES selective mounting security and exposes ALL files including:
- Docker Hub tokens (~/.docker/config.json)
- GitHub CLI tokens (~/.config/gh/hosts.yml)
- NPM, Cargo, Composer credentials
Only use if you cannot use --mount for specific directories. (default: false)
--container-workdir <dir> Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
--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/*
-h, --help display help for command
Commands:
logs [options] View and analyze Squid proxy logs from current or previous runs
Installation
One-Line Installer (Recommended)
Linux (x64) with automatic SHA verification:
curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bashThis installer:
- Downloads the latest release binary
- Verifies SHA256 checksum against
checksums.txt - Validates the file is a valid ELF executable
- Installs to
/usr/local/bin/awf
Manual Binary Installation (Alternative)
Linux (x64):
# Download binary and checksums
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.15.0/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.15.0/checksums.txt -o checksums.txt
# Verify checksum
sha256sum -c checksums.txt --ignore-missing
# Install
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.15.0/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.15.0ghcr.io/github/gh-aw-firewall/agent:0.15.0ghcr.io/github/gh-aw-firewall/squid:latestghcr.io/github/gh-aw-firewall/agent:latest
Image Verification
All container images are cryptographically signed with cosign for authenticity verification.
# Verify image signature
cosign verify \
--certificate-identity-regexp 'https://github.com/github/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/github/gh-aw-firewall/squid:0.15.0For detailed instructions including SBOM verification, see docs/image-verification.md.