Release v0.13.12

What's Changed

Other Changes

• fix: resolve host.docker.internal DNS in chroot mode for MCP servers by @Mossaka in #555

Full Changelog: v0.13.11...v0.13.12

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-1770401456393")
  --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 bash

This 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.12/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.12/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.12/awf.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.12
• ghcr.io/github/gh-aw-firewall/agent:0.13.12
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.12

For detailed instructions including SBOM verification, see docs/image-verification.md.

Release v0.13.11

What's Changed

Other Changes

• fix: set NO_PROXY for host gateway to bypass Squid for MCP by @Mossaka in #554

Full Changelog: v0.13.10...v0.13.11

CLI Options

Usage: awf [options] [command] [args...]

Network firewall for agentic workflows with domain whitelisting

Arguments:
  args                                           Command and arguments to execute (use -- to separate from options)

Options:
  -V, --version                                  output the version number
  --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-1770369468320")
  --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 bash

This 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.11/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.11/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.11/awf.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.11
• ghcr.io/github/gh-aw-firewall/agent:0.13.11
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.11

For detailed instructions including SBOM verification, see docs/image-verification.md.

Release v0.13.10

What's Changed

Documentation

• [docs] add awf logs command documentation by @github-actions[bot] in #551

Other Changes

• fix: ensure .copilot directory permissions before Copilot CLI install by @Mossaka in #547
• chore: upgrade gh-aw workflows to v0.42.0 by @Mossaka in #552
• fix: bypass Squid for network gateway to fix MCP SSE crash by @Mossaka in #553

Full Changelog: v0.13.9...v0.13.10

CLI Options

Usage: awf [options] [command] [args...]

Network firewall for agentic workflows with domain whitelisting

Arguments:
  args                                           Command and arguments to execute (use -- to separate from options)

Options:
  -V, --version                                  output the version number
  --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-1770367206603")
  --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 bash

This 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.10/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.10/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.10/awf.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.10
• ghcr.io/github/gh-aw-firewall/agent:0.13.10
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.10

For detailed instructions including SBOM verification, see docs/image-verification.md.

Release v0.13.9

What's Changed

Other Changes

• fix: remove leftover SQUID_INTERCEPT_PORT references by @Mossaka in #548
• fix: create resolv.conf in chroot when not mounted by @Mossaka in #549

Full Changelog: v0.13.8...v0.13.9

CLI Options

Usage: awf [options] [command] [args...]

Network firewall for agentic workflows with domain whitelisting

Arguments:
  args                                           Command and arguments to execute (use -- to separate from options)

Options:
  -V, --version                                  output the version number
  --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-1770344682005")
  --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 bash

This 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.9/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.9/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.9/awf.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.9
• ghcr.io/github/gh-aw-firewall/agent:0.13.9
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.9

For detailed instructions including SBOM verification, see docs/image-verification.md.

Release v0.13.8

What's Changed

Other Changes

• fix: mount /etc/hosts in chroot mode for localhost resolution by @Mossaka in #545
• fix: pass BUN_INSTALL to chroot to prevent Bun core dump by @Mossaka in #546
• fix: bypass Squid for host.docker.internal MCP gateway traffic by @Mossaka in #543

Full Changelog: v0.13.7...v0.13.8

CLI Options

Usage: awf [options] [command] [args...]

Network firewall for agentic workflows with domain whitelisting

Arguments:
  args                                           Command and arguments to execute (use -- to separate from options)

Options:
  -V, --version                                  output the version number
  --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-1770340839925")
  --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 bash

This 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.8/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.8/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.8/awf.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.8
• ghcr.io/github/gh-aw-firewall/agent:0.13.8
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.8

For detailed instructions including SBOM verification, see docs/image-verification.md.

Release v0.13.7

What's Changed

Other Changes

• revert: remove Squid intercept mode and all cascading fixes by @Mossaka in #541
• ci: add write permissions for issue monster agent assignment by @Copilot in #537

Full Changelog: v0.13.6...v0.13.7

CLI Options

Usage: awf [options] [command] [args...]

Network firewall for agentic workflows with domain whitelisting

Arguments:
  args                                           Command and arguments to execute (use -- to separate from options)

Options:
  -V, --version                                  output the version number
  --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-1770338704020")
  --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 bash

This 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.7/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.7/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.7/awf.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.7
• ghcr.io/github/gh-aw-firewall/agent:0.13.7
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.7

For detailed instructions including SBOM verification, see docs/image-verification.md.

Release v0.13.6

What's Changed

Other Changes

• fix: remove HTTP_PROXY/HTTPS_PROXY env vars from agent container by @Mossaka in #524
• chore: recompile workflow lock files for AWF v0.13.5 by @Mossaka in #526
• fix: recompile lock files with release action mode by @Mossaka in #527
• fix: mount /etc/hosts in chroot mode and handle missing resolv.conf by @Mossaka in #522
• fix: restore HTTPS_PROXY and fix smoke-chroot checkout by @Mossaka in #530

Full Changelog: v0.13.5...v0.13.6

CLI Options

Usage: awf [options] [command] [args...]

Network firewall for agentic workflows with domain whitelisting

Arguments:
  args                                           Command and arguments to execute (use -- to separate from options)

Options:
  -V, --version                                  output the version number
  --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-1770333499895")
  --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 bash

This 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.6/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.13.6/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.6/awf.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.6
• ghcr.io/github/gh-aw-firewall/agent:0.13.6
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.6

For detailed instructions including SBOM verification, see docs/image-verification.md.

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 bash

This 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.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.5
• ghcr.io/github/gh-aw-firewall/agent:0.13.5
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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...

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 bash

This 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.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.4
• ghcr.io/github/gh-aw-firewall/agent:0.13.4
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.4

For detailed instructions including SBOM verification, see docs/image-verification.md.

Release v0.13.3

What's Changed

Other Changes

• feat(cli): add --skip-pull flag to use pre-downloaded images by @Mossaka in #493

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 bash

This 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.tgz

Quick 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 -- pwd

See README.md for full documentation.

Container Images

Published to GitHub Container Registry:

• ghcr.io/github/gh-aw-firewall/squid:0.13.3
• ghcr.io/github/gh-aw-firewall/agent:0.13.3
• ghcr.io/github/gh-aw-firewall/squid:latest
• ghcr.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.3

For detailed instructions including SBOM verification, see docs/image-verification.md.