Release v0.11.0

Highlights

🚀 New Feature: Configurable Agent Base Image

When building containers locally from source, use --agent-base-image to achieve closer parity with GitHub Actions runner environments:

# In a GitHub Actions workflow or local development with source checkout
sudo awf --build-local --agent-base-image ghcr.io/catthehacker/ubuntu:runner-22.04 \
  --allow-domains github.com -- your-command

Note: --build-local requires the gh-aw-firewall source code (it builds from containers/agent/Dockerfile). This is primarily useful in GitHub Actions workflows that clone the repo, or for local development.

Available images:

Image	Size	Use Case
ubuntu:22.04 (default)	~200MB	Fast startup, minimal footprint
ghcr.io/catthehacker/ubuntu:runner-22.04	~2-5GB	Common GitHub Actions tools
ghcr.io/catthehacker/ubuntu:full-22.04	~20GB	Maximum GitHub Actions parity

SHA256 digest pinning supported for supply chain security. See docs/usage.md for details.

🔒 Security Fixes

• System UID validation (#267): Prevents privilege escalation by rejecting system UIDs (0-999) in container user mapping
• NAT blacklist for dangerous ports (#269): Defense-in-depth blocking at iptables level for SSH, databases, RDP, etc.
• ReDoS prevention (#265): Replaced unbounded .* regex patterns with safer bounded alternatives
• Supply chain hardening (#266): All GitHub Actions pinned to commit SHAs

---

What's Changed

Other Changes

• ci: add dedicated ESLint workflow by @Copilot in #237
• ci: add build verification workflow for PRs by @Copilot in #238
• feat: add workflow schema and upgrade agent by @Mossaka in #271
• ci: add dependabot configuration for automated dependency updates by @Copilot in #242
• feat(ci): add coverage regression detection by @Copilot in #244
• chore: delete existing firewall tests and migrate smoke tests by @Copilot in #229
• ci: pin GitHub Actions to commit SHAs for supply chain security by @Copilot in #266
• feat: port plan workflow from gh-aw repository by @Copilot in #230
• chore: remove smoke-codex workflow due to missing key by @Copilot in #291
• docs: add security scope restriction info to AGENTS.md by @Copilot in #301
• feat: port issue-monster workflow from gh-aw repository by @Copilot in #300
• chore: regenerate security-guard.lock.yml by @Copilot in #292
• feat: expand integration test coverage from 7 to 17 test files by @Copilot in #251
• feat(ci): implement test parallelization to reduce CI time by @Copilot in #255
• ci: add Node.js and Ubuntu version matrix to test workflows by @Copilot in #259
• ci: add eslint, build workflows and dependabot configuration by @Copilot in #261
• feat: expand dangerous ports database (CouchDB, Elasticsearch, InfluxDB) by @Copilot in #264
• fix: replace .* regex with safer patterns (ReDoS) by @Copilot in #265
• feat: add static analysis for execa() command injection detection by @Copilot in #268
• fix: add NAT blacklist for dangerous ports in iptables by @Copilot in #269
• feat(ci): add daily pelis agent factory advisor agentic workflow by @Copilot in #272
• feat: Add issue duplication agent using cache memory by @Copilot in #299
• fix: add system UID range validation to prevent privilege escalation by @Copilot in #267
• test: add IPv6 integration tests by @Copilot in #260
• chore: add githubnext.github.io to pelis-agent-factory-advisor domain allowlist by @Copilot in #305
• feat(ci): add TypeScript type checking to CI by @Copilot in #303
• ci: disable PR title check for dependabot PRs by @Copilot in #312
• [WIP] Regenerate pelis agent factory advisor by @Copilot in #317
• fix: add issues trigger to issue-monster workflow by @Copilot in #338
• feat: add test-coverage-improver agentic workflow by @Copilot in #344
• feat: add dependency security monitor workflow by @Copilot in #342
• feat: add doc-maintainer workflow for daily documentation sync by @Copilot in #341
• feat(ci): add CI Failure Doctor workflow by @Copilot in #340
• docs: clarify container privilege drop in security architecture by @Copilot in #385
• chore: update gh aw by @Mossaka in #387
• ci: use local awf build in smoke workflows by @Copilot in #388
• feat: add configurable agent base image for GitHub Actions runner parity by @Copilot in #214

Full Changelog: v0.10.0...v0.11.0

Installation

One-Line Installer (Recommended)

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

Manual Installation

curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.11.0/awf-linux-x64 -o awf
chmod +x awf
sudo mv awf /usr/local/bin/

Container Images

• ghcr.io/githubnext/gh-aw-firewall/squid:0.11.0
• ghcr.io/githubnext/gh-aw-firewall/agent:0.11.0

All images signed with cosign. See docs/image-verification.md for verification instructions.

Release v0.10.0

BREAKING CHANGE: Docker-in-Docker Support Removed

Version 0.10.0 removes all Docker-in-Docker functionality from the agent container. This change improves security by eliminating the Docker socket attack surface.

Removed Components

• Docker CLI from agent container
• Docker socket mount (/var/run/docker.sock)
• docker-wrapper.sh interceptor script
• Docker-in-Docker examples and tests

Security Impact

This change eliminates three attack vectors:

• Container escape via Docker socket
• Unauthorized container spawning through Docker API
• Privilege escalation through docker group membership

Migration Required

If you use Docker-in-Docker features, migrate to:

Remote MCP servers - Run MCP servers outside the firewall using stdio or SSE protocols

External orchestration - Manage containers outside the agent environment

Pre-built tools - Use tools that don't spawn containers

Example of non-working code after this release:

awf --allow-domains github.com "docker run some-image"  # Fails

Runtime Behavior

Attempting to run docker commands now displays:

WARNING: Docker commands are not available in this environment
This firewall does not support Docker-in-Docker for security reasons

---

What's Changed

Other Changes

• feat: remove Docker-in-Docker support by @Copilot in #205
• docs: remove docker-in-docker references by @Copilot in #220
• ci: add docs-only path filters by @Copilot in #224
• chore: remove security fix status file by @Copilot in #215
• fix(deps): resolve docs npm audit by @Copilot in #226
• docs: update AGENTS.md for stdio-based MCP configuration by @Copilot in #221
• feat: add runtime warning for docker command attempts by @Copilot in #222
• test: add regression tests for Docker-in-Docker removal by @Copilot in #223
• feat: add release highlights generator agentic workflow by @Copilot in #197

Full Changelog: v0.9.1...v0.10.0

CLI Options

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

Network firewall for agentic workflows with domain whitelisting

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

Options:
  -V, --version                                  output the version number
  --allow-domains <domains>                      Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
                                     github.com         - exact domain + subdomains (HTTP & HTTPS)
                                     *.github.com       - any subdomain of github.com
                                     api-*.example.com  - api-* subdomains
                                     https://secure.com - HTTPS only
                                     http://legacy.com  - HTTP only
  --allow-domains-file <path>                    Path to file containing allowed domains (one per line or comma-separated, supports # comments)
  --block-domains <domains>                      Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
  --block-domains-file <path>                    Path to file containing blocked domains (one per line or comma-separated, supports # comments)
  --log-level <level>                            Log level: debug, info, warn, error (default: "info")
  --keep-containers                              Keep containers running after command exits (default: false)
  --tty                                          Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
  --work-dir <dir>                               Working directory for temporary files (default: "/tmp/awf-1768525196974")
  --build-local                                  Build containers locally instead of using GHCR images (default: false)
  --image-registry <registry>                    Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
  --image-tag <tag>                              Container image tag (default: "latest")
  -e, --env <KEY=VALUE>                          Additional environment variables to pass to container (can be specified multiple times) (default: [])
  --env-all                                      Pass all host environment variables to container (excludes system vars like PATH) (default: false)
  -v, --mount <host_path:container_path[:mode]>  Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
  --container-workdir <dir>                      Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
  --dns-servers <servers>                        Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
  --proxy-logs-dir <path>                        Directory to save Squid proxy logs to (writes access.log directly to this directory)
  --enable-host-access                           Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
  --allow-host-ports <ports>                     Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
  --ssl-bump                                     Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
  --allow-urls <urls>                            Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
                                     Supports wildcards: https://github.com/githubnext/*
  -h, --help                                     display help for command

Commands:
  logs [options]                                 View and analyze Squid proxy logs from current or previous runs

Installation

One-Line Installer (Recommended)

Linux (x64) with automatic SHA verification:

curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo 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/githubnext/gh-aw-firewall/releases/download/v0.10.0/awf-linux-x64 -o awf
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.10.0/checksums.txt -o checksums.txt

# Verify checksum
sha256sum -c checksums.txt --ignore-missing

# Install
chmod +x awf
sudo mv awf /usr/local/bin/

NPM Installation (Alternative)

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

Image Verification

All container images are cryptographically signed with cosign for authenticity verification.

# Verify image signature
cosign verify \
  --certificate-identity-regexp 'https://github.com/githubnext/gh-aw-firewall/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/githubnext/gh-aw-firewall/squid:0.10.0

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

Release v0.9.1

🔒 Security Patch: Critical Firewall Bypass Fix (CVSS 8.2)

This release fixes a critical security vulnerability where agents could bypass domain filtering by accessing host services on non-standard ports.

Migration Guide

✅ No action required for most users - this release is 100% backward compatible.

What Changed:

• Before v0.9.1: --enable-host-access allowed access to ALL ports on the host (security vulnerability)
• After v0.9.1: --enable-host-access restricts access to ports 80 and 443 only (secure by default)

If you need non-standard ports (e.g., MCP Gateway on port 3000):

# New flag: --allow-host-ports
sudo awf --enable-host-access --allow-host-ports 3000 \
  --allow-domains host.docker.internal -- \
  curl http://host.docker.internal:3000/

# Multiple ports and ranges supported
sudo awf --enable-host-access --allow-host-ports 3000,8080,9000 \
  --allow-domains host.docker.internal -- command

sudo awf --enable-host-access --allow-host-ports 8000-8090 \
  --allow-domains host.docker.internal -- command

Security improvements:

• Defense-in-depth architecture (iptables + Squid filtering)
• Dangerous ports (SSH:22, MySQL:3306, PostgreSQL:5432, etc.) are permanently blocked
• Explicit port allowlist with default deny policy

For details, see SECURITY-FIX-STATUS.md and PR #213.

---

What's Changed

Other Changes

• feat: make firewall activity collapsible like other report sections by @Copilot in #204
• fix(cli): enable all shell commands for firewall escape test workflow by @Copilot in #212
• feat: add daily security review and threat modeling workflow by @Copilot in #211
• fix: critical firewall bypass via non-standard ports (CVSS 8.2) by @Mossaka in #213

Full Changelog: v0.9.0...v0.9.1

CLI Options

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

Network firewall for agentic workflows with domain whitelisting

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

Options:
  -V, --version                                  output the version number
  --allow-domains <domains>                      Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
                                     github.com         - exact domain + subdomains (HTTP & HTTPS)
                                     *.github.com       - any subdomain of github.com
                                     api-*.example.com  - api-* subdomains
                                     https://secure.com - HTTPS only
                                     http://legacy.com  - HTTP only
  --allow-domains-file <path>                    Path to file containing allowed domains (one per line or comma-separated, supports # comments)
  --block-domains <domains>                      Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
  --block-domains-file <path>                    Path to file containing blocked domains (one per line or comma-separated, supports # comments)
  --log-level <level>                            Log level: debug, info, warn, error (default: "info")
  --keep-containers                              Keep containers running after command exits (default: false)
  --tty                                          Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
  --work-dir <dir>                               Working directory for temporary files (default: "/tmp/awf-1768451321453")
  --build-local                                  Build containers locally instead of using GHCR images (default: false)
  --image-registry <registry>                    Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
  --image-tag <tag>                              Container image tag (default: "latest")
  -e, --env <KEY=VALUE>                          Additional environment variables to pass to container (can be specified multiple times) (default: [])
  --env-all                                      Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST) (default: false)
  -v, --mount <host_path:container_path[:mode]>  Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw] (default: [])
  --container-workdir <dir>                      Working directory inside the container (should match GITHUB_WORKSPACE for path consistency)
  --dns-servers <servers>                        Comma-separated list of trusted DNS servers. DNS traffic is ONLY allowed to these servers (default: 8.8.8.8,8.8.4.4) (default: "8.8.8.8,8.8.4.4")
  --proxy-logs-dir <path>                        Directory to save Squid proxy logs to (writes access.log directly to this directory)
  --enable-host-access                           Enable access to host services via host.docker.internal. Security warning: When combined with --allow-domains host.docker.internal, containers can access ANY service on the host machine. (default: false)
  --allow-host-ports <ports>                     Comma-separated list of ports or port ranges to allow when using --enable-host-access. By default, only ports 80 and 443 are allowed. Example: --allow-host-ports 3000 or --allow-host-ports 3000,8080 or --allow-host-ports 3000-3010,8000-8090
  --ssl-bump                                     Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
  --allow-urls <urls>                            Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
                                     Supports wildcards: https://github.com/githubnext/*
  -h, --help                                     display help for command

Commands:
  logs [options]                                 View and analyze Squid proxy logs from current or previous runs

Installation

One-Line Installer (Recommended)

Linux (x64) with automatic SHA verification:

curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo 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/githubnext/gh-aw-firewall/releases/download/v0.9.1/awf-linux-x64 -o awf
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.9.1/checksums.txt -o checksums.txt

# Verify checksum
sha256sum -c checksums.txt --ignore-missing

# Install
chmod +x awf
sudo mv awf /usr/local/bin/

NPM Installation (Alternative)

# Install from tarball
npm install -g https://github.com/githubnext/gh-aw-firewall/releases/download/v0.9.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/githubnext/gh-aw-firewall/squid:0.9.1
• ghcr.io/githubnext/gh-aw-firewall/agent:0.9.1
• ghcr.io/githubnext/gh-aw-firewall/squid:latest
• ghcr.io/githubnext/gh-aw-firewall/agent:latest

Image Verification

All container images are cryptographically signed with cosign for authenticity verification.

# Verify image signature
cosign verify \
  --certificate-identity-regexp 'https://github.com/githubnext/gh-aw-firewall/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/githubnext/gh-aw-firewall/squid:0.9.1

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

Release v0.9.0

What's Changed

Highlights:

• SSL Bump support enables HTTPS content inspection and URL path filtering
• Enhanced container security with no-new-privileges and ptrace syscall blocking
• Comprehensive egress filtering documentation explaining port vs domain security models

New Features:

• SSL Bump Mode (--ssl-bump): Intercept HTTPS traffic for URL path filtering instead of domain-only filtering
  • Generate per-session CA certificates (1-day validity)
  • Filter traffic by URL patterns with wildcard support via --allow-urls
  • View complete URLs in Squid access logs for debugging
  • Automatic trust store injection in agent containers
• URL Pattern Filtering: Restrict access to specific HTTPS paths (e.g., https://github.com/githubnext/*)
  • Input validation prevents overly broad patterns
  • Wildcard support for flexible path matching
  • Requires explicit https:// scheme for security

Security Enhancements:

• Container hardening: Dropped unnecessary capabilities from Squid container (NET_RAW, SYS_ADMIN, SYS_PTRACE, SYS_MODULE, MKNOD, AUDIT_WRITE, SETFCAP)
• Enabled no-new-privileges flag preventing privilege escalation
• Seccomp profile blocks ptrace syscall to prevent process injection attacks
• SSL Bump CA private keys isolated per-session with restrictive permissions (0600)
• Extensive security documentation for SSL Bump threat model and safe usage

Other Changes

• feat: add no-new-privileges and ptrace syscall blocking by @Copilot in #139
• feat: add SSL Bump support for HTTPS content inspection by @Copilot in #131
• docs: add egress filtering documentation by @Mossaka in #202

Full Changelog: v0.8.2...v0.9.0

CLI Options

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

Network firewall for agentic workflows with domain whitelisting

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

Options:
  -V, --version                                  output the version number
  --allow-domains <domains>                      Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
                                     github.com         - exact domain + subdomains (HTTP & HTTPS)
                                     *.github.com       - any subdomain of github.com
                                     api-*.example.com  - api-* subdomains
                                     https://secure.com - HTTPS only
                                     http://legacy.com  - HTTP only
  --allow-domains-file <path>                    Path to file containing allowed domains (one per line or comma-separated, supports # comments)
  --block-domains <domains>                      Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
  --block-domains-file <path>                    Path to file containing blocked domains (one per line or comma-separated, supports # comments)
  --log-level <level>                            Log level: debug, info, warn, error (default: "info")
  --keep-containers                              Keep containers running after command exits (default: false)
  --tty                                          Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
  --work-dir <dir>                               Working directory for temporary files (default: "/tmp/awf-1768414155449")
  --build-local                                  Build containers locally instead of using GHCR images (default: false)
  --image-registry <registry>                    Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
  --image-tag <tag>                              Container image tag (default: "latest")
  -e, --env <KEY=VALUE>                          Additional environment variables to pass to container (can be specified multiple times) (default: [])
  --env-all                                      Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST) (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)
  --ssl-bump                                     Enable SSL Bump for HTTPS content inspection (allows URL path filtering for HTTPS) (default: false)
  --allow-urls <urls>                            Comma-separated list of allowed URL patterns for HTTPS (requires --ssl-bump).
                                     Supports wildcards: https://github.com/githubnext/*
  -h, --help                                     display help for command

Commands:
  logs [options]                                 View and analyze Squid proxy logs from current or previous runs

Installation

One-Line Installer (Recommended)

Linux (x64) with automatic SHA verification:

curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo 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/githubnext/gh-aw-firewall/releases/download/v0.9.0/awf-linux-x64 -o awf
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/do...

Release v0.8.2

Highlights

New: --enable-host-access Flag

Access host services (e.g., MCP gateways) from within the firewall via host.docker.internal:

sudo awf --enable-host-access --allow-domains host.docker.internal -- curl http://host.docker.internal:8080

⚠️ Security: Host access is opt-in. When enabled with host.docker.internal in allowed domains, containers can reach any service on the host.

Fix: CONNECT to Port 80

Fixed issue where Node.js fetch failed for HTTP URLs through the proxy. The firewall now allows CONNECT to both ports 80 and 443 (Safe_ports).

New: GitHub Action for Installing AWF

- uses: githubnext/gh-aw-firewall@v0.8.2

New: Debugging Skills

Added /debugging-workflows skill for troubleshooting GitHub Actions failures.

---

What's Changed

• docs: streamline README quickstart section (#185)
• docs: add server connectivity guide for HTTP, HTTPS, and gRPC (#179)
• feat: add GitHub Action for installing awf (#184)
• feat: add debugging-workflows skill (#181)
• feat: add agentic workflow to update release notes (#186)
• feat: add --enable-host-access flag and fix CONNECT to port 80 (#190)

Full Changelog: v0.8.1...v0.8.2

---

Installation

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

Container Images

• ghcr.io/githubnext/gh-aw-firewall/squid:0.8.2
• ghcr.io/githubnext/gh-aw-firewall/agent:0.8.2

Release v0.8.1

Bug Fix

Fixed: Seccomp profile missing from binary - The v0.8.0 binary failed with "Seccomp profile not found" error because the seccomp profile wasn't bundled in the pkg assets.

---

What's Changed

• fix: bundle seccomp profile in pkg binary

Full Changelog: v0.8.0...v0.8.1

Installation

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

Or use --image-tag 0.8.1 with the CLI.

Release v0.8.0

Highlights

🔒 Security Enhancements

NET_ADMIN Capability Dropped After Setup (#133)

• The agent container now irrevocably drops NET_ADMIN capability after iptables rules are configured
• Prevents malicious code from flushing firewall rules to bypass the proxy
• Uses capsh --drop=cap_net_admin to remove the capability from the bounding set

Container Hardening (#96)

• Drops dangerous capabilities: NET_RAW, SYS_PTRACE, SYS_MODULE, SYS_RAWIO, MKNOD
• Seccomp profile blocks dangerous syscalls: kexec_*, *_module, mount, reboot, pivot_root
• Resource limits: 4GB memory, 1000 PID limit, swap disabled
• DNS audit logging with [FW_DNS_QUERY] prefix

✨ New Features

Domain Blocklist Support (#114)

• New --block-domains and --block-domains-file options
• Block specific domains while allowing everything else

Protocol-Specific Domain Filtering (#115)

• Restrict domains to HTTP-only or HTTPS-only: --allow-domains 'https://secure.example.com'

Log Analysis Commands (#118)

• awf logs stats - aggregated firewall statistics
• awf logs summary - markdown report for GitHub Actions
• Supports --format json|markdown|pretty

PID/Process Tracking (#132)

• Track which process made each network request
• New --with-pid flag for awf logs -f

host.docker.internal Support (#168)

• Enables container-to-host communication on Linux
• Useful for connecting to MCP servers on the host

---

What's Changed

Other Changes

• feat: add install script with sha256 validation by @Copilot in #108
• feat(cli): add container hardening measures by @Copilot in #96
• docs: streamline README for first-time visitors by @Copilot in #111
• feat: add blocklist support for domain filtering by @Copilot in #114
• feat: add version pinning support to install.sh by @Copilot in #123
• feat: add protocol-specific domain allowlisting (http/https) by @Copilot in #115
• feat: add awf logs stats and awf logs summary commands by @Mossaka in #118
• feat: initialize repository for github agentic workflows by @Copilot in #151
• chore: enable smoke workflows to run on all PRs by @Copilot in #144
• fix(docker): drop NET_ADMIN capability after iptables setup by @Copilot in #133
• feat: add PID/process tracking for network request attribution by @Copilot in #132
• test: improve docker-manager.ts coverage to 80%+ by @Copilot in #140
• docs: add documentation for awf logs stats and summary commands by @Copilot in #148
• docs: add protocol-specific domain filtering documentation by @Copilot in #149
• docs: add blocklist documentation to docs-site by @Copilot in #150
• feat: add daily CI/CD gaps assessment agentic workflow by @Copilot in #156
• feat: add weekly firewall escape test agentic workflow by @Copilot in #157
• ci: add container scanning workflow using trivy by @Copilot in #153
• docs: add PID tracking documentation for awf logs command by @Copilot in #159
• feat: add security guard agentic workflow for PR review by @Copilot in #152
• ci: add dependency vulnerability audit workflow by @Copilot in #154
• feat(ci): add smoke test for binary in release workflow by @Copilot in #155
• test: add NET_ADMIN capability verification tests by @Copilot in #158
• docs: add common awf usage examples by @Copilot in #160
• feat: add host.docker.internal support by @Mossaka in #168
• feat: add firewall debugging skill to agents by @Mossaka in #180

Full Changelog: v0.7.0...v0.8.0

CLI Options

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

Network firewall for agentic workflows with domain whitelisting

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

Options:
  -V, --version                                  output the version number
  --allow-domains <domains>                      Comma-separated list of allowed domains. Supports wildcards and protocol prefixes:
                                     github.com         - exact domain + subdomains (HTTP & HTTPS)
                                     *.github.com       - any subdomain of github.com
                                     api-*.example.com  - api-* subdomains
                                     https://secure.com - HTTPS only
                                     http://legacy.com  - HTTP only
  --allow-domains-file <path>                    Path to file containing allowed domains (one per line or comma-separated, supports # comments)
  --block-domains <domains>                      Comma-separated list of blocked domains (takes precedence over allowed domains). Supports wildcards.
  --block-domains-file <path>                    Path to file containing blocked domains (one per line or comma-separated, supports # comments)
  --log-level <level>                            Log level: debug, info, warn, error (default: "info")
  --keep-containers                              Keep containers running after command exits (default: false)
  --tty                                          Allocate a pseudo-TTY for the container (required for interactive tools like Claude Code) (default: false)
  --work-dir <dir>                               Working directory for temporary files (default: "/tmp/awf-...")
  --build-local                                  Build containers locally instead of using GHCR images (default: false)
  --image-registry <registry>                    Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
  --image-tag <tag>                              Container image tag (default: "latest")
  -e, --env <KEY=VALUE>                          Additional environment variables to pass to container (can be specified multiple times)
  --env-all                                      Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST)
  -v, --mount <host_path:container_path[:mode]>  Volume mount (can be specified multiple times). Format: host_path:container_path[:ro|rw]
  --container-workdir <dir>                      Working directory inside the container
  --dns-servers <servers>                        Comma-separated list of trusted DNS servers (default: "8.8.8.8,8.8.4.4")
  --proxy-logs-dir <path>                        Directory to save Squid proxy logs to
  -h, --help                                     display help for command

Commands:
  logs [options]                                 View and analyze Squid proxy logs from current or previous runs

Installation

One-Line Installer (Recommended)

Linux (x64) with automatic SHA verification:

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

Manual Binary Installation

# Download binary and checksums
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.8.0/awf-linux-x64 -o awf
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/download/v0.8.0/checksums.txt -o checksums.txt

# Verify checksum
sha256sum -c checksums.txt --ignore-missing

# Install
chmod +x awf
sudo mv awf /usr/local/bin/

NPM Installation

npm install -g https://github.com/githubnext/gh-aw-firewall/releases/download/v0.8.0/awf.tgz

Container Images

Published to GitHub Container Registry:

• ghcr.io/githubnext/gh-aw-firewall/squid:0.8.0
• ghcr.io/githubnext/gh-aw-firewall/agent:0.8.0
• ghcr.io/githubnext/gh-aw-firewall/squid:latest
• ghcr.io/githubnext/gh-aw-firewall/agent:latest

Image Verification

All container images are cryptographically signed with cosign:

cosign verify \
  --certificate-identity-regexp 'https://github.com/githubnext/gh-aw-firewall/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/githubnext/gh-aw-firewall/squid:0.8.0

See docs/image-verification.md for details.

Release v0.7.0

What's Changed

Other Changes

• docs: add pr description length guidance to agents.md by @Copilot in #93
• feat: write exit code to stderr on process termination by @Copilot in #95
• feat: add cosign signing for docker images in release pipeline by @Copilot in #89
• feat: run agent container processes as non-root user by @Copilot in #90
• fix: use version from package.json in cli by @Copilot in #91
• test: add smoke testing by @Mossaka in #97

Full Changelog: v0.6.0...v0.7.0

CLI Options

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

Network firewall for agentic workflows with domain whitelisting

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

Options:
  -V, --version                                  output the version number
  --allow-domains <domains>                      Comma-separated list of allowed domains. Supports wildcards:
                                     github.com        - exact domain + subdomains
                                     *.github.com      - any subdomain of github.com
                                     api-*.example.com - api-* subdomains
  --allow-domains-file <path>                    Path to file containing allowed 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-1766100732533")
  --build-local                                  Build containers locally instead of using GHCR images (default: false)
  --image-registry <registry>                    Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
  --image-tag <tag>                              Container image tag (default: "latest")
  -e, --env <KEY=VALUE>                          Additional environment variables to pass to container (can be specified multiple times) (default: [])
  --env-all                                      Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST) (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)
  -h, --help                                     display help for command

Commands:
  logs [options]                                 View Squid proxy logs from current or previous runs

Installation

Binary Installation (Recommended)

Linux (x64):

curl -L https://github.com/githubnext/gh-aw-firewall/releases/download/v0.7.0/awf-linux-x64 -o awf
chmod +x awf
sudo mv awf /usr/local/bin/

NPM Installation (Alternative)

# Install from tarball
npm install -g https://github.com/githubnext/gh-aw-firewall/releases/download/v0.7.0/awf.tgz

Requirements

• Docker and Docker Compose must be installed
• For iptables manipulation, run with sudo: sudo awf ...
• Container images will be pulled automatically from GHCR on first run

Verification

Verify checksums after download:

sha256sum -c checksums.txt

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

Image Verification

All container images are cryptographically signed with cosign for authenticity verification.

# Verify image signature
cosign verify \
  --certificate-identity-regexp 'https://github.com/githubnext/gh-aw-firewall/.*' \
  --certificate-oidc-issuer 'https://token.actions.githubusercontent.com' \
  ghcr.io/githubnext/gh-aw-firewall/squid:0.7.0

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

Release v0.6.0

What's Changed

Other Changes

• feat(cli): restrict dns traffic to trusted servers only by @Mossaka in #68
• feat: add wildcard domain support by @Mossaka in #70
• feat: add log management commands and utilities for squid proxy logs by @Mossaka in #72

Full Changelog: v0.5.1...v0.6.0

CLI Options

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

Network firewall for agentic workflows with domain whitelisting

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

Options:
  -V, --version                                  output the version number
  --allow-domains <domains>                      Comma-separated list of allowed domains. Supports wildcards:
                                     github.com        - exact domain + subdomains
                                     *.github.com      - any subdomain of github.com
                                     api-*.example.com - api-* subdomains
  --allow-domains-file <path>                    Path to file containing allowed 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-1764723166070")
  --build-local                                  Build containers locally instead of using GHCR images (default: false)
  --image-registry <registry>                    Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
  --image-tag <tag>                              Container image tag (default: "latest")
  -e, --env <KEY=VALUE>                          Additional environment variables to pass to container (can be specified multiple times) (default: [])
  --env-all                                      Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST) (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)
  -h, --help                                     display help for command

Commands:
  logs [options]                                 View Squid proxy logs from current or previous runs

Installation

Binary Installation (Recommended)

Linux (x64):

curl -L https://github.com/githubnext/gh-aw-firewall/releases/download/v0.6.0/awf-linux-x64 -o awf
chmod +x awf
sudo mv awf /usr/local/bin/

NPM Installation (Alternative)

# Install from tarball
npm install -g https://github.com/githubnext/gh-aw-firewall/releases/download/v0.6.0/awf.tgz

Requirements

• Docker and Docker Compose must be installed
• For iptables manipulation, run with sudo: sudo awf ...
• Container images will be pulled automatically from GHCR on first run

Verification

Verify checksums after download:

sha256sum -c checksums.txt

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

Release v0.5.1

This is a patch release to fix the following problem and root cause:

Problem

Copilot CLI running inside AWF container had ~2x larger system prompt (522KB vs 275KB), with instructions being
loaded twice.

Root Cause

Git's "safe directory" security feature rejected the bind-mounted repository directory because:

• Container runs as root (UID 0)
• Mounted directory owned by host user (UID 1000)
• Git refuses to operate on directories with mismatched ownership

Impact

When git root detection failed, Copilot CLI fell back to scanning for .github/instructions/ from multiple
starting points (both CWD and HOME), finding the same directory twice since CWD is nested inside HOME.

Fix

Added to containers/agent/entrypoint.sh:
git config --global --add safe.directory '*'

What's Changed

Other Changes

• fix(docs): remove duplicate h1 titles from starlight documentation by @Copilot in #60
• docs: condense CLI reference page to true reference format by @Copilot in #61
• docs: add mermaid diagram rendering for Astro Starlight site by @Copilot in #62
• docs: remove duplicate security architecture documentation by @Copilot in #64
• fix(docs): add missing base path to security-architecture links by @Copilot in #67
• fix(cli): add git safe.directory to fix duplicate instruction loading by @Mossaka in #84

Full Changelog: v0.5.0...v0.5.1

CLI Options

Usage: awf [options] [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 (e.g., github.com,api.github.com)
  --allow-domains-file <path>                    Path to file containing allowed 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-1764715360907")
  --build-local                                  Build containers locally instead of using GHCR images (default: false)
  --image-registry <registry>                    Container image registry (default: "ghcr.io/githubnext/gh-aw-firewall")
  --image-tag <tag>                              Container image tag (default: "latest")
  -e, --env <KEY=VALUE>                          Additional environment variables to pass to container (can be specified multiple times) (default: [])
  --env-all                                      Pass all host environment variables to container (excludes system vars like PATH, DOCKER_HOST) (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)
  -h, --help                                     display help for command

Installation

Binary Installation (Recommended)

Linux (x64):

curl -L https://github.com/githubnext/gh-aw-firewall/releases/download/v0.5.1/awf-linux-x64 -o awf
chmod +x awf
sudo mv awf /usr/local/bin/

NPM Installation (Alternative)

# Install from tarball
npm install -g https://github.com/githubnext/gh-aw-firewall/releases/download/v0.5.1/awf.tgz

Requirements

• Docker and Docker Compose must be installed
• For iptables manipulation, run with sudo: sudo awf ...
• Container images will be pulled automatically from GHCR on first run

Verification

Verify checksums after download:

sha256sum -c checksums.txt

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