Releases: github/gh-aw-firewall
Releases · github/gh-aw-firewall
Release v0.13.5
What's Changed
Documentation
- [docs] docs: add --skip-pull flag documentation by @github-actions[bot] in #521
Other Changes
- fix: eliminate host binary dependency in setup-iptables for chroot mode by @Copilot in #456
- feat: allow empty allowDomains to block all network access by @Copilot in #451
- feat: filter benign operational logs from Squid access.log by @Copilot in #432
- docs: update documentation for accuracy and consistency by @Copilot in #492
- fix: replace deprecated log_access directive with Squid 5+ syntax by @Mossaka in #506
- chore: upgrade agentic workflows to gh-aw v0.42.0 by @Mossaka in #512
- feat: add build test workflows for external test repos by @Mossaka in #507
- feat(ci): add SARIF output to npm audit workflow by @Copilot in #433
- docs: condense get started fast section by @Copilot in #504
- feat: add CLI flag consistency checker agentic workflow by @Copilot in #494
- feat: configure jest for esm dependency compatibility by @Copilot in #430
- feat: add localhost keyword for playwright testing by @Copilot in #427
- fix: restructure smoke-chroot workflow to avoid Docker-in-Docker by @Mossaka in #508
- fix: add auth and error handling to build-test workflows by @Mossaka in #514
- feat: add AWF agent skill for Claude Code agents by @Mossaka in #515
- fix: enable Squid intercept mode for NAT-redirected traffic by @Mossaka in #520
New Contributors
- @github-actions[bot] made their first contribution in #521
Full Changelog: v0.13.4...v0.13.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-1770316322446")
--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: [])
--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-chroot Enable chroot to /host for running host binaries (Python, Node, Go, etc.)
Uses selective path mounts instead of full filesystem access.
Docker socket is hidden to prevent firewall bypass. (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.13.5/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.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.13.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.13.5ghcr.io/github/gh-aw-firewall/agent:0.13.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...Contributors
Mossaka
Assets 5
Release v0.13.4
Full Changelog: v0.13.3...v0.13.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
--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-1770183121774")
--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: [])
--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-chroot Enable chroot to /host for running host binaries (Python, Node, Go, etc.)
Uses selective path mounts instead of full filesystem access.
Docker socket is hidden to prevent firewall bypass. (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.13.4/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.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.13.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.13.4ghcr.io/github/gh-aw-firewall/agent:0.13.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.13.4For detailed instructions including SBOM verification, see docs/image-verification.md.
Release v0.13.3
What's Changed
Other Changes
Full Changelog: v0.13.2...v0.13.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
--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-1770153154201")
--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: [])
--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-chroot Enable chroot to /host for running host binaries (Python, Node, Go, etc.)
Uses selective path mounts instead of full filesystem access.
Docker socket is hidden to prevent firewall bypass. (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.13.3/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.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.13.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.13.3ghcr.io/github/gh-aw-firewall/agent:0.13.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.13.3For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.13.2
What's Changed
Other Changes
- fix(cli): use GHCR images for preset agent-images in chroot mode by @Mossaka in #459
- chore: upgrade gh-aw from v0.37.26 to v0.40.0 by @Copilot in #480
Full Changelog: v0.13.1...v0.13.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
--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-1770152123468")
--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")
-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)
--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-chroot Enable chroot to /host for running host binaries (Python, Node, Go, etc.)
Uses selective path mounts instead of full filesystem access.
Docker socket is hidden to prevent firewall bypass. (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.13.2/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.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.13.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.13.2ghcr.io/github/gh-aw-firewall/agent:0.13.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.13.2For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.13.1
What's Changed
Other Changes
- fix: switch security-guard workflow to claude engine by @Copilot in #438
- chore: migrate references from githubnext to github organization by @Copilot in #474
- chore: complete migration from githubnext to github organization by @Mossaka in #476
Full Changelog: v0.13.0...v0.13.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
--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-1770083028012")
--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")
-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)
--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-chroot Enable chroot to /host for running host binaries (Python, Node, Go, etc.)
Uses selective path mounts instead of full filesystem access.
Docker socket is hidden to prevent firewall bypass. (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.13.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.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.13.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.13.1ghcr.io/github/gh-aw-firewall/agent:0.13.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.13.1For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.13.0
What's Changed
Other Changes
- chore: remove unused release workflow files by @Copilot in #423
- fix(deps): update js-yaml to 3.14.2 (CVE fix) by @Copilot in #424
- docs: add agent image tooling reference by @Copilot in #426
- feat(cli): add --enable-chroot for transparent host binary execution by @Mossaka in #448
Full Changelog: v0.11.2...v0.13.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
--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-1769804972779")
--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/githubnext/gh-aw-firewall")
--image-tag <tag> Container image tag (default: "latest")
-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)
--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/githubnext/*
--enable-chroot Enable chroot to /host for running host binaries (Python, Node, Go, etc.)
Uses selective path mounts instead of full filesystem access.
Docker socket is hidden to prevent firewall bypass. (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/githubnext/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/githubnext/gh-aw-firewall/releases/download/v0.13.0/awf-linux-x64 -o awf
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.13.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/githubnext/gh-aw-firewall/releases/download/v0.13.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/githubnext/gh-aw-firewall/squid:0.13.0ghcr.io/githubnext/gh-aw-firewall/agent:0.13.0ghcr.io/githubnext/gh-aw-firewall/squid:latestghcr.io/githubnext/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/githubnext/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/githubnext/gh-aw-firewall/squid:0.13.0For detailed instructions including SBOM verification, see docs/image-verification.md.
Contributors
Mossaka
Assets 5
Release v0.11.2
What's Changed
Other Changes
- feat(cli): replace --agent-base-image with --agent-image option by @Copilot in #397
Full Changelog: v0.11.1...v0.11.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
--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-1769210866843")
--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/githubnext/gh-aw-firewall")
--image-tag <tag> Container image tag (default: "latest")
-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)
--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/githubnext/*
-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/githubnext/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/githubnext/gh-aw-firewall/releases/download/v0.11.2/awf-linux-x64 -o awf
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.11.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/githubnext/gh-aw-firewall/releases/download/v0.11.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/githubnext/gh-aw-firewall/squid:0.11.2ghcr.io/githubnext/gh-aw-firewall/agent:0.11.2ghcr.io/githubnext/gh-aw-firewall/squid:latestghcr.io/githubnext/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/githubnext/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/githubnext/gh-aw-firewall/squid:0.11.2For detailed instructions including SBOM verification, see docs/image-verification.md.
Release v0.11.1
What's New
🚀 New: Pre-built Agent-Act Image
A new agent-act image is now published with ghcr.io/catthehacker/ubuntu:act-24.04 as the base, providing better GitHub Actions runner parity.
Usage:
# Pull and use the act-based agent image directly
docker pull ghcr.io/githubnext/gh-aw-firewall/agent-act:0.11.1Published images:
| Image | Base | Size | Use Case |
|---|---|---|---|
agent:0.11.1 |
ubuntu:22.04 |
~200MB | Default, minimal |
agent-act:0.11.1 |
catthehacker/ubuntu:act-24.04 |
~2-5GB | GitHub Actions parity |
Note: CLI support for
--agent-base-image actto automatically use this image is planned for a future release.
Full Changelog: v0.11.0...v0.11.1
Installation
curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bashContainer Images
ghcr.io/githubnext/gh-aw-firewall/squid:0.11.1ghcr.io/githubnext/gh-aw-firewall/agent:0.11.1ghcr.io/githubnext/gh-aw-firewall/agent-act:0.11.1✨ NEW
All images signed with cosign.
Release v0.11.0
Highlights
🚀 New Feature: Configurable Agent Base Image
When building containers locally from source, use --agent-base-image to achieve closer parity with GitHub Actions runner environments:
# In a GitHub Actions workflow or local development with source checkout
sudo awf --build-local --agent-base-image ghcr.io/catthehacker/ubuntu:runner-22.04 \
--allow-domains github.com -- your-commandNote:
--build-localrequires the gh-aw-firewall source code (it builds fromcontainers/agent/Dockerfile). This is primarily useful in GitHub Actions workflows that clone the repo, or for local development.
Available images:
| Image | Size | Use Case |
|---|---|---|
ubuntu:22.04 (default) |
~200MB | Fast startup, minimal footprint |
ghcr.io/catthehacker/ubuntu:runner-22.04 |
~2-5GB | Common GitHub Actions tools |
ghcr.io/catthehacker/ubuntu:full-22.04 |
~20GB | Maximum GitHub Actions parity |
SHA256 digest pinning supported for supply chain security. See docs/usage.md for details.
🔒 Security Fixes
- System UID validation (#267): Prevents privilege escalation by rejecting system UIDs (0-999) in container user mapping
- NAT blacklist for dangerous ports (#269): Defense-in-depth blocking at iptables level for SSH, databases, RDP, etc.
- ReDoS prevention (#265): Replaced unbounded
.*regex patterns with safer bounded alternatives - Supply chain hardening (#266): All GitHub Actions pinned to commit SHAs
What's Changed
Other Changes
- ci: add dedicated ESLint workflow by @Copilot in #237
- ci: add build verification workflow for PRs by @Copilot in #238
- feat: add workflow schema and upgrade agent by @Mossaka in #271
- ci: add dependabot configuration for automated dependency updates by @Copilot in #242
- feat(ci): add coverage regression detection by @Copilot in #244
- chore: delete existing firewall tests and migrate smoke tests by @Copilot in #229
- ci: pin GitHub Actions to commit SHAs for supply chain security by @Copilot in #266
- feat: port plan workflow from gh-aw repository by @Copilot in #230
- chore: remove smoke-codex workflow due to missing key by @Copilot in #291
- docs: add security scope restriction info to AGENTS.md by @Copilot in #301
- feat: port issue-monster workflow from gh-aw repository by @Copilot in #300
- chore: regenerate security-guard.lock.yml by @Copilot in #292
- feat: expand integration test coverage from 7 to 17 test files by @Copilot in #251
- feat(ci): implement test parallelization to reduce CI time by @Copilot in #255
- ci: add Node.js and Ubuntu version matrix to test workflows by @Copilot in #259
- ci: add eslint, build workflows and dependabot configuration by @Copilot in #261
- feat: expand dangerous ports database (CouchDB, Elasticsearch, InfluxDB) by @Copilot in #264
- fix: replace .* regex with safer patterns (ReDoS) by @Copilot in #265
- feat: add static analysis for execa() command injection detection by @Copilot in #268
- fix: add NAT blacklist for dangerous ports in iptables by @Copilot in #269
- feat(ci): add daily pelis agent factory advisor agentic workflow by @Copilot in #272
- feat: Add issue duplication agent using cache memory by @Copilot in #299
- fix: add system UID range validation to prevent privilege escalation by @Copilot in #267
- test: add IPv6 integration tests by @Copilot in #260
- chore: add githubnext.github.io to pelis-agent-factory-advisor domain allowlist by @Copilot in #305
- feat(ci): add TypeScript type checking to CI by @Copilot in #303
- ci: disable PR title check for dependabot PRs by @Copilot in #312
- [WIP] Regenerate pelis agent factory advisor by @Copilot in #317
- fix: add issues trigger to issue-monster workflow by @Copilot in #338
- feat: add test-coverage-improver agentic workflow by @Copilot in #344
- feat: add dependency security monitor workflow by @Copilot in #342
- feat: add doc-maintainer workflow for daily documentation sync by @Copilot in #341
- feat(ci): add CI Failure Doctor workflow by @Copilot in #340
- docs: clarify container privilege drop in security architecture by @Copilot in #385
- chore: update gh aw by @Mossaka in #387
- ci: use local awf build in smoke workflows by @Copilot in #388
- feat: add configurable agent base image for GitHub Actions runner parity by @Copilot in #214
Full Changelog: v0.10.0...v0.11.0
Installation
One-Line Installer (Recommended)
curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bashManual Installation
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.11.0/awf-linux-x64 -o awf
chmod +x awf
sudo mv awf /usr/local/bin/Container Images
ghcr.io/githubnext/gh-aw-firewall/squid:0.11.0ghcr.io/githubnext/gh-aw-firewall/agent:0.11.0
All images signed with cosign. See docs/image-verification.md for verification instructions.
Contributors
Mossaka
Assets 5
Release v0.10.0
BREAKING CHANGE: Docker-in-Docker Support Removed
Version 0.10.0 removes all Docker-in-Docker functionality from the agent container. This change improves security by eliminating the Docker socket attack surface.
Removed Components
- Docker CLI from agent container
- Docker socket mount (
/var/run/docker.sock) docker-wrapper.shinterceptor script- Docker-in-Docker examples and tests
Security Impact
This change eliminates three attack vectors:
- Container escape via Docker socket
- Unauthorized container spawning through Docker API
- Privilege escalation through docker group membership
Migration Required
If you use Docker-in-Docker features, migrate to:
Remote MCP servers - Run MCP servers outside the firewall using stdio or SSE protocols
External orchestration - Manage containers outside the agent environment
Pre-built tools - Use tools that don't spawn containers
Example of non-working code after this release:
awf --allow-domains github.com "docker run some-image" # FailsRuntime Behavior
Attempting to run docker commands now displays:
WARNING: Docker commands are not available in this environment
This firewall does not support Docker-in-Docker for security reasons
What's Changed
Other Changes
- feat: remove Docker-in-Docker support by @Copilot in #205
- docs: remove docker-in-docker references by @Copilot in #220
- ci: add docs-only path filters by @Copilot in #224
- chore: remove security fix status file by @Copilot in #215
- fix(deps): resolve docs npm audit by @Copilot in #226
- docs: update AGENTS.md for stdio-based MCP configuration by @Copilot in #221
- feat: add runtime warning for docker command attempts by @Copilot in #222
- test: add regression tests for Docker-in-Docker removal by @Copilot in #223
- feat: add release highlights generator agentic workflow by @Copilot in #197
Full Changelog: v0.9.1...v0.10.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
--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-1768525196974")
--build-local Build containers locally instead of using GHCR images (default: false)
--image-registry <registry> Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
--image-tag <tag> Container image tag (default: "latest")
-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)
--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/githubnext/*
-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/githubnext/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/githubnext/gh-aw-firewall/releases/download/v0.10.0/awf-linux-x64 -o awf
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.10.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/githubnext/gh-aw-firewall/releases/download/v0.10.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/githubnext/gh-aw-firewall/squid:0.10.0ghcr.io/githubnext/gh-aw-firewall/agent:0.10.0ghcr.io/githubnext/gh-aw-firewall/squid:latestghcr.io/githubnext/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/githubnext/gh-aw-firewall/.*' \
--certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
ghcr.io/githubnext/gh-aw-firewall/squid:0.10.0For detailed instructions including SBOM verification, see docs/image-verification.md.