Skip to content

Release v0.24.1

Latest
Latest

Choose a tag to compare

View all tags
@github-actions github-actions released this 12 Mar 23:01
· 17 commits to main since this release
v0.24.1
7dce4a8

What's Changed

Other Changes

  • ci: skip CI when only release.yml changes by @Mossaka in #1261
  • docs: sync version references and add missing CLI flags by @Mossaka in #1223
  • docs: document flag validation constraints by @Mossaka in #1230
  • chore(deps): aggregated dependency updates by @Mossaka in #1218
  • fix: use docker cp instead of file bind mounts for DinD compatibility by @Mossaka in #1079
  • fix(proxy): add lowercase proxy vars and NODE_EXTRA_CA_CERTS by @Mossaka in #1234
  • feat(cli): organize help text with logical option groups by @Mossaka in #1241
  • test: add logger/aggregator tests for blocked domain detection by @Mossaka in #1262
  • feat(cli): add --agent-timeout flag for execution time limit by @Mossaka in #1242
  • feat(cli): add predownload command to pre-pull container images by @Mossaka in #1245
  • feat(proxy): add GitHub Enterprise Cloud/Server support with automatic endpoint detection by @claude in #1264

Full Changelog: v0.24.0...v0.24.1

CLI Options

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

Network firewall for agentic workflows with domain whitelisting

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

Options:
    -V, --version                                  output the version number

  Domain Filtering:
    -d, --allow-domains <domains>                  Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
                                       github.com         - exact domain + subdomains (HTTP & HTTPS)
                                       *.github.com       - any subdomain of github.com
                                       api-*.example.com  - api-* subdomains
                                       https://secure.com - HTTPS only
                                       http://legacy.com  - HTTP only
                                       localhost          - auto-configure for local testing (Playwright, etc.)
    --allow-domains-file <path>                    Path to file with allowed domains (one per line, supports # comments)
    --block-domains <domains>                      Comma-separated blocked domains (overrides allow list). Supports wildcards.
    --block-domains-file <path>                    Path to file with blocked domains (one per line, supports # comments)
    --ssl-bump                                     Enable SSL Bump for HTTPS content inspection (allows URL path filtering) (default: false)
    --allow-urls <urls>                            Comma-separated allowed URL patterns for HTTPS (requires --ssl-bump).
                                       Supports wildcards: https://github.com/myorg/*

  Image Management:
    -b, --build-local                              Build containers locally instead of using GHCR images (default: false)
    --agent-image <value>                          Agent container image (default: "default")
                                       Presets (pre-built, fast):
                                         default  - Minimal ubuntu:22.04 (~200MB)
                                         act      - GitHub Actions parity (~2GB)
                                       Custom base images (requires --build-local):
                                         ubuntu:XX.XX
                                         ghcr.io/catthehacker/ubuntu:runner-XX.XX
                                         ghcr.io/catthehacker/ubuntu:full-XX.XX
    --image-registry <registry>                    Container image registry (default: "ghcr.io/github/gh-aw-firewall")
    --image-tag <tag>                              Container image tag (applies to both squid and agent images)
                                       Image name varies by --agent-image preset:
                                         default → agent:<tag>
                                         act     → agent-act:<tag> (default: "latest")
    --skip-pull                                    Use local images without pulling from registry (requires pre-downloaded images) (default: false)

  Container Configuration:
    -e, --env <KEY=VALUE>                          Environment variable for the container (repeatable) (default: [])
    --env-all                                      Pass all host environment variables to container (excludes system vars like PATH) (default: false)
    -v, --mount <host_path:container_path[:mode]>
                                                   Volume mount (repeatable). Format: host_path:container_path[:ro|rw] (default: [])
    --container-workdir <dir>                      Working directory inside the container
    --memory-limit <limit>                         Memory limit for the agent container (e.g., 1g, 2g, 4g, 512m). Default: 2g (default: "2g")
    --tty                                          Allocate a pseudo-TTY (required for interactive tools like Claude Code) (default: false)

  Network & Security:
    --dns-servers <servers>                        Comma-separated trusted DNS servers (default: "8.8.8.8,8.8.4.4")
    --enable-host-access                           Enable access to host services via host.docker.internal (default: false)
    --allow-host-ports <ports>                     Ports/ranges to allow with --enable-host-access (default: 80,443).
                                       Example: 3000,8080 or 3000-3010,8000-8090

  API Proxy:
    --enable-api-proxy                             Enable API proxy sidecar for secure credential injection.
                                       Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
    --copilot-api-target <host>                    Target hostname for Copilot API requests (default: api.githubcopilot.com)
    --openai-api-target <host>                     Target hostname for OpenAI API requests (default: api.openai.com)
    --anthropic-api-target <host>                  Target hostname for Anthropic API requests (default: api.anthropic.com)
    --rate-limit-rpm <n>                           Max requests per minute per provider (requires --enable-api-proxy)
    --rate-limit-rph <n>                           Max requests per hour per provider (requires --enable-api-proxy)
    --rate-limit-bytes-pm <n>                      Max request bytes per minute per provider (requires --enable-api-proxy)
    --no-rate-limit                                Disable rate limiting in the API proxy (requires --enable-api-proxy)

  Logging & Debug:
    --log-level <level>                            Log level: debug, info, warn, error (default: "info")
    -k, --keep-containers                          Keep containers running after command exits (default: false)
    --agent-timeout <minutes>                      Maximum time in minutes for the agent command to run (default: no limit)
    --work-dir <dir>                               Working directory for temporary files (default: "/tmp/awf-1773356466821")
    --proxy-logs-dir <path>                        Directory to save Squid proxy access.log
    -h, --help                                     display help for command

Installation

One-Line Installer (Recommended)

Linux and macOS (x64 and ARM64) with automatic SHA verification:

curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bash

This installer:

  • Automatically detects your OS (Linux or macOS) and architecture (x86_64/aarch64/arm64)
  • Downloads the correct release binary
  • Verifies SHA256 checksum against checksums.txt
  • Validates the file is a valid executable (ELF on Linux, Mach-O on macOS)
  • Installs to /usr/local/bin/awf

Manual Binary Installation (Alternative)

Linux (x64):

curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/

Linux (ARM64):

curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
sha256sum -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/

macOS (Apple Silicon / ARM64):

curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/

macOS (Intel / x64):

curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/checksums.txt -o checksums.txt
shasum -a 256 -c checksums.txt --ignore-missing
chmod +x awf
sudo mv awf /usr/local/bin/

NPM Installation (Alternative)

# Install from tarball
npm install -g https://github.com/github/gh-aw-firewall/releases/download/v0.24.1/awf.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.24.1
  • ghcr.io/github/gh-aw-firewall/agent:0.24.1
  • 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.24.1

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

Contributors

claude and Mossaka
Assets 8
Loading