Skip to content

Release v0.27.8

Choose a tag to compare

View all tags
@github-actions github-actions released this 22 Jun 21:28
· 50 commits to main since this release
v0.27.8
2b14e40

What's Changed

Other Changes

  • chore: upgrade gh-aw to v0.80.6 and recompile workflows by @lpcox in #5294
  • [Test Coverage] Add coverage for parsers, services, host-identity by @github-actions[bot] in #5240
  • docs: sync schemas and specs with source changes by @github-actions[bot] in #5250
  • fix: propagate config fields to all layers by @github-actions[bot] in #5279
  • docs: sync schemas and specs with source changes by @github-actions[bot] in #5283
  • [WIP] Refactor entrypoint.sh by extracting initialization phases into functions by @lpcox with @Copilot in #5285
  • Refactor workdir setup tests and guard fixture cleanup by @lpcox with @Copilot in #5303
  • [WIP] Refactor Docker startup retry tests to reduce code duplication by @lpcox with @Copilot in #5304
  • [WIP] Refactor API proxy secret-isolation tests to reduce duplicate code by @lpcox with @Copilot in #5305
  • [WIP] Fix security guard workflow failure due to authentication issues by @lpcox with @Copilot in #5306
  • fix(ci): prevent empty safeoutputs schema probes in smoke-claude workflow by @lpcox with @Copilot in #5307
  • [WIP] Fix missing data in contribution check workflow by @lpcox with @Copilot in #5308
  • [WIP] Refactor to extract rule-setup phases into named bash functions by @lpcox with @Copilot in #5309
  • [WIP] Refactor extract functions in token-parsers file by @lpcox with @Copilot in #5310
  • fix(smoke-claude): raise turn budget to 8 and fix add_comment usage by @lpcox in #5328
  • perf(security-guard): prioritize security-relevant files in PR diff by @lpcox in #5329
  • [Test Coverage] Cover regex rules in policy-manifest and signals in log-streamer by @github-actions[bot] in #5317
  • Split api-proxy token parser tests by JSON, SSE, and normalization concerns by @lpcox with @Copilot in #5356
  • Split config-assembly validator tests by concern group by @lpcox with @Copilot in #5348
  • refactor: split docker-manager-lifecycle.test.ts into focused modules by @lpcox with @Copilot in #5347
  • Increase Documentation Maintainer LLM invocation budget to prevent false Copilot auth failures by @lpcox with @Copilot in #5349
  • Refactor duplicated invalid host-service port assertions in host-access firewall tests by @lpcox with @Copilot in #5350
  • Deduplicate runMainWorkflow test scaffolding by @lpcox with @Copilot in #5351
  • Split docker-manager utility tests into focused concern-based modules by @lpcox with @Copilot in #5354
  • Split docker-manager cleanup tests by concern by @lpcox with @Copilot in #5357
  • Split api-proxy auth tests into focused provider-aligned modules by @lpcox with @Copilot in #5353
  • [Test Coverage] deduplicate docker-manager.ts re-export tests by @github-actions[bot] in #5341
  • Refactor writeConfigs cleanup tests to remove duplicated config + tolerant-failure scaffolding by @lpcox with @Copilot in #5352
  • Refactor host iptables setup into validation, chain, and rule modules by @lpcox with @Copilot in #5355
  • refactor(tests): deduplicate COPILOT_MODEL detection test scaffolding by @lpcox with @Copilot in #5369
  • [WIP] Refactor audit enricher tests to remove duplicate policy fixture builders by @lpcox with @Copilot in #5370
  • fix: propagate config fields to all layers by @github-actions[bot] in #5387
  • [Test Coverage] squid-log-reader.ts: 100% coverage by @github-actions[bot] in #5378
  • Refactor duplicated firewall topology assertions in ensureFirewallNetwork tests by @lpcox with @Copilot in #5371
  • refactor: move agent-service testHelpers to dedicated test-utils file by @lpcox with @Copilot in #5394
  • Remove unused DomainProtocol export from domain-patterns.ts by @lpcox with @Copilot in #5395
  • Remove unused export from resolveAgentImageConfig by @lpcox with @Copilot in #5396
  • Remove unused ParsedDomain from domain-patterns by @lpcox with @Copilot in #5397
  • Remove unused ParsedDomainList export from domain-matchers by @lpcox with @Copilot in #5398

Full Changelog: v0.27.7...v0.27.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

  Configuration:
    --config <path>                                Path to AWF JSON/YAML config file (use "-" to read from stdin)

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

  Image Management:
    -b, --build-local                              Build containers locally instead of using GHCR images (default: false)
    --agent-image <value>                          Agent container image (default: "default")
                                       Presets (pre-built, fast):
                                         default  - Minimal ubuntu:22.04 (~200MB)
                                         act      - GitHub Actions parity (~2GB)
                                       Custom base images (requires --build-local):
                                         ubuntu:XX.XX
                                         ghcr.io/catthehacker/ubuntu:runner-XX.XX
                                         ghcr.io/catthehacker/ubuntu:full-XX.XX
    --image-registry <registry>                    Container image registry (default: "ghcr.io/github/gh-aw-firewall")
    --image-tag <tag>                              Container image tag (applies to squid, agent/agent-act, api-proxy, and cli-proxy when enabled)
                                       Optional digest metadata format:
                                         <tag>,squid=sha256:...,agent=sha256:...,agent-act=sha256:...,api-proxy=sha256:...,cli-proxy=sha256:...
                                       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)
    --docker-host <socket>                         Docker socket for AWF's own containers (default: auto-detect from DOCKER_HOST env).
                                       Use when Docker is at a non-standard path.
                                       Example: unix:///run/user/1000/docker.sock
    --docker-host-path-prefix <prefix>             Prefix bind-mount source paths so Docker daemon can resolve runner filesystem paths.
                                       Useful for split runner/daemon filesystems (e.g. ARC DinD).
                                       Example: /host

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

  Network & Security:
    --dns-servers <servers>                        Comma-separated trusted DNS servers (auto-detected from host if omitted)
    --dns-over-https [resolver-url]                Enable DNS-over-HTTPS via sidecar proxy (default: https://dns.google/dns-query)

  Network & Security:
    --upstream-proxy <url>                         Upstream (corporate) proxy URL for Squid to chain through.
                                       Auto-detected from host https_proxy/http_proxy if not set.
                                       Example: http://proxy.corp.com:3128
    --enable-host-access                           Enable access to host services via host.docker.internal (default: false)
    --allow-host-ports <ports>                     Ports/ranges to allow with --enable-host-access (default: 80,443).
                                       Example: 3000,8080 or 3000-3010,8000-8090
    --allow-host-service-ports <ports>             Ports to allow ONLY to host gateway (for GitHub Actions services).
                                       Bypasses dangerous port restrictions. Auto-enables host access.
                                       WARNING: Allowing port 22 grants SSH access to the host.
                                       Example: 5432,6379
    --enable-dind                                  Enable Docker-in-Docker by exposing host Docker socket.
                                       WARNING: allows firewall bypass via docker run (default: false)
    --enable-dlp                                   Enable DLP (Data Loss Prevention) scanning to block credential
                                       exfiltration in outbound request URLs. (default: false)

  API Proxy:
    --enable-api-proxy                             Enable API proxy sidecar for secure credential injection.
                                       Supports OpenAI (Codex) and Anthropic (Claude) APIs. (default: false)
    --copilot-api-target <host>                    Target hostname for Copilot API requests (default: api.githubcopilot.com)
    --openai-api-target <host>                     Target hostname for OpenAI API requests (default: api.openai.com)
    --openai-api-base-path <path>                  Base path prefix for OpenAI API requests (e.g. /serving-endpoints for Databricks)
    --anthropic-api-target <host>                  Target hostname for Anthropic API requests (default: api.anthropic.com)
    --anthropic-api-base-path <path>               Base path prefix for Anthropic API requests (e.g. /anthropic)
    --openai-api-auth-header <name>                Custom auth header name for OpenAI requests (default: Authorization with Bearer prefix)
    --anthropic-api-auth-header <name>             Custom auth header name for Anthropic requests (default: x-api-key)
    --gemini-api-target <host>                     Target hostname for Gemini API requests (default: generativelanguage.googleapis.com)
    --gemini-api-base-path <path>                  Base path prefix for Gemini API requests
    --anthropic-auto-cache                         Enable Anthropic prompt-cache optimizations in the API proxy (requires --enable-api-proxy).
                                       Injects cache breakpoints on tools/system/messages, upgrades TTL to 1h,
                                       and strips ANSI codes — typically saves ~90% on Anthropic API input costs. (default: false)
    --anthropic-cache-tail-ttl <5m|1h>             TTL for the rolling-tail cache breakpoint when --anthropic-auto-cache is enabled.
                                       Use "5m" (default) for fast interactive sessions, "1h" for long agentic tasks.
    --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)
    --max-model-multiplier <model:multiplier,...>
                                                   Per-model cost multipliers for effective token accounting (requires --enable-api-proxy).
                                       Format: comma-separated model:multiplier pairs, e.g.
                                       claude-opus-4-5-1m:10,claude-opus-4-5-200k:2.5
                                       Multipliers must be positive numbers. Models without
                                       a multiplier default to 1×.
    --max-model-multiplier-cap <number>            Maximum allowed model cost multiplier (requires --enable-api-proxy).
                                       Requests for models whose resolved multiplier exceeds this cap
                                       are rejected with HTTP 400 and error type model_multiplier_cap_exceeded.
                                       Must be a positive number.
    --max-permission-denied <number>               Maximum number of upstream 401/403 responses allowed per run (requires --enable-api-proxy).
                                       When reached, the API proxy rejects all subsequent requests with HTTP 403
                                       and error type permission_denied_limit_exceeded, stopping the run to avoid
                                       wasting tokens on misconfigured credentials.
                                       Must be a positive integer.
    --max-cache-misses <number>                    Maximum consecutive cache misses allowed per run (requires --enable-api-proxy).
                                       A miss counts only when input_tokens > 0 and cache_read_tokens === 0.
                                       Responses with cache_read_tokens > 0 reset the miss streak.
                                       Must be a positive integer.
    --enable-token-steering                        Enable effective token budget steering in the API proxy (requires --enable-api-proxy).
                                       Injects budget-warning system messages at 80%, 90%, 95%, and 99%
                                       usage to nudge the agent to wrap up before hitting the hard limit. (default: false)
    --difc-proxy-host <host:port>                  Connect to an external DIFC proxy (mcpg) at host:port.
                                       Enables the CLI proxy sidecar that routes gh commands through the DIFC proxy.
                                       The DIFC proxy must be started externally (e.g., by the gh-aw compiler).
    --difc-proxy-ca-cert <path>                    Path to TLS CA cert written by the external DIFC proxy.
                                       Recommended when --difc-proxy-host is set for TLS verification.

  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-1782163708619")
    --proxy-logs-dir <path>                        Directory to save Squid proxy access.log
    --audit-dir <path>                             Directory for firewall audit artifacts (configs, policy manifest, iptables state)
    --session-state-dir <path>                     Directory to save Copilot CLI session state (events.jsonl, session data)
    --diagnostic-logs                              Collect container logs, exit state, and sanitized config on non-zero exit.
                                       Useful for debugging container startup failures (e.g. Squid crashes in DinD).
                                       Written to <workDir>/diagnostics/ (or <audit-dir>/diagnostics/ when set). (default: false)
    -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.27.8/awf-linux-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.27.8/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.27.8/awf-linux-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.27.8/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.27.8/awf-darwin-arm64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.27.8/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.27.8/awf-darwin-x64 -o awf
curl -fL https://github.com/github/gh-aw-firewall/releases/download/v0.27.8/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.27.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.27.8
  • ghcr.io/github/gh-aw-firewall/agent:0.27.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.27.8

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

Contributors

lpcox
Assets 14
Loading