gh-aw-firewall

name	gh-aw-firewall
description	Use the AWF (Agentic Workflow Firewall) to run commands with network isolation and domain whitelisting. Provides L7 HTTP/HTTPS egress control for AI agents.
license	MIT

AWF (Agentic Workflow Firewall) Usage Skill

Use this skill when you need to run commands with network isolation, restrict network access to approved domains, or execute AI agents in a sandboxed environment with controlled network access.

What is AWF?

AWF is a network firewall for agentic workflows that provides:

• L7 Domain Whitelisting: Control HTTP/HTTPS traffic at the application layer
• Host-Level Enforcement: Uses iptables DOCKER-USER chain to enforce firewall on ALL containers
• Chroot Mode: Optional transparent access to host binaries (Python, Node.js, Go) while maintaining network isolation

WHEN TO USE AWF

Use AWF when:

• Running AI agents (Copilot CLI, Claude, etc.) that need network access but should be restricted
• Testing code that makes network requests in a controlled environment
• Enforcing network security policies for automated workflows
• Running untrusted commands with limited network access
• Testing Playwright or other tools against localhost services

WHEN NOT TO USE

• When running standard unit tests that do not require any external network requests.
• For workflows that are already running in a fully air-gapped, self-hosted runner environment where AWF is redundant.
• If the task only requires compiling YAML frontmatter (AWF is for runtime execution, not compilation).

Common Pitfalls

• Subdomain Blocking: Allowing example.com but forgetting that API calls actually go to api.example.com, causing unexpected TCP_DENIED errors in the Squid log.
• Hanging Interactive Shells: Running sudo awf with an interactive tool (like the Copilot CLI) without providing the --prompt argument, causing the firewall container to hang forever.
• Missing Cleanup: Failing to provide --keep-containers during debugging, or conversely, leaving debug containers running indefinitely and eating up host memory.

Quick Start

Basic Command

# Run a command with only github.com allowed
sudo awf --allow-domains github.com -- curl https://api.github.com

The -- separator divides firewall options from the command to run.

Test Domain Blocking

# This should FAIL (example.com not allowed)
sudo awf --allow-domains github.com -- curl -f --max-time 10 https://example.com

Enable Debug Logging

sudo awf --allow-domains github.com --log-level debug -- curl https://api.github.com

Installation

Install Script (Recommended)

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

Build from Source

git clone https://github.com/github/gh-aw-firewall.git awf
cd awf
npm install
npm run build
npm link

CLI Options Reference

sudo awf [options] -- <command>

Domain Options:
  --allow-domains <domains>       Comma-separated allowed domains
  --allow-domains-file <path>     File with allowed domains (one per line)
  --block-domains <domains>       Comma-separated blocked domains (takes precedence)
  --block-domains-file <path>     File with blocked domains

Network Options:
  --dns-servers <servers>         DNS servers (default: 8.8.8.8,8.8.4.4)
  --enable-host-access            Enable access to host via host.docker.internal
  --allow-host-ports <ports>      Ports to allow with host access (e.g., 3000,8080)

Container Options:
  --tty                           Allocate TTY for interactive tools
  --env KEY=VALUE                 Pass environment variable (repeatable)
  --env-all                       Pass all host environment variables
  --mount <host:container[:mode]> Volume mount (repeatable)
  --container-workdir <dir>       Working directory inside container
  --agent-image <value>           Agent image preset (default, act) or custom

Advanced Options:
  --ssl-bump                      Enable HTTPS content inspection
  --allow-urls <urls>             URL patterns for SSL Bump (requires --ssl-bump)

Debugging Options:
  --log-level <level>             Log level: debug, info, warn, error
  --keep-containers               Keep containers after command exits
  --proxy-logs-dir <path>         Directory to save Squid logs to

Domain Whitelisting Patterns

Subdomain Matching (Automatic)

# github.com also allows api.github.com, raw.github.com, etc.
sudo awf --allow-domains github.com -- curl https://api.github.com

Wildcard Patterns

# Match any subdomain
--allow-domains '*.github.com'

# Match prefix patterns
--allow-domains 'api-*.example.com'

# Combine multiple patterns
--allow-domains 'github.com,*.googleapis.com,api-*.example.com'

Protocol-Specific

# HTTPS only
--allow-domains 'https://secure.example.com'

# HTTP only
--allow-domains 'http://legacy.example.com'

Domain Blocklist

# Allow domain but block specific subdomain
sudo awf \
  --allow-domains example.com \
  --block-domains internal.example.com \
  -- curl https://api.example.com  # Works

Common Workflows

1. Run GitHub Copilot CLI

sudo awf \
  --allow-domains github.com,api.github.com,githubusercontent.com,anthropic.com \
  -- copilot --prompt "List my repositories"

2. Run with MCP Servers

sudo awf \
  --allow-domains github.com,arxiv.org,mcp.tavily.com \
  --log-level debug \
  -- copilot --mcp arxiv,tavily --prompt "Search arxiv for recent AI papers"

3. Playwright Testing with Localhost

# The localhost keyword auto-configures host access and dev ports
sudo awf \
  --allow-domains localhost,playwright.dev \
  -- npx playwright test

4. Pass Environment Variables

# Pass specific variables
sudo awf --allow-domains github.com \
  --env GITHUB_TOKEN="$GITHUB_TOKEN" \
  --env NODE_ENV=production \
  -- npm test

# Pass all host environment variables
sudo awf --allow-domains github.com --env-all -- npm test

5. Mount Custom Volumes

sudo awf --allow-domains github.com \
  --mount /path/to/data:/data:ro \
  -- cat /data/config.json

6. Use Host Binaries (Chroot Mode is Always On)

# Access host Python, Node, Go, etc. (chroot mode is the default)
sudo awf --allow-domains api.github.com \
  -- python3 -c "import requests; print(requests.get('https://api.github.com').status_code)"

7. SSL Bump for URL Path Filtering

sudo awf \
  --allow-domains github.com \
  --ssl-bump \
  --allow-urls "https://github.com/myorg/*" \
  -- curl https://github.com/myorg/some-repo

8. GitHub Actions Integration

- name: Setup awf
  uses: github/gh-aw-firewall@main

- name: Run with firewall
  run: |
    sudo -E awf --allow-domains github.com -- 'cd $GITHUB_WORKSPACE && npm test'

Log Analysis Commands

View Logs

# Pretty format (default)
awf logs

# Follow in real-time
awf logs -f

# JSON format for scripting
awf logs --format json

# List available log sources
awf logs --list

Get Statistics

# Terminal output
awf logs stats

# JSON for scripting
awf logs stats --format json

# Markdown for GitHub Actions
awf logs summary >> $GITHUB_STEP_SUMMARY

Find Blocked Requests

# Using awf logs
awf logs --format json | jq 'select(.isAllowed == false)'

# Direct Squid log query
sudo grep "TCP_DENIED" /tmp/squid-logs-*/access.log

Debugging Tips

Keep Containers for Inspection

sudo awf --allow-domains github.com --keep-containers -- failing-command

# Inspect containers
docker logs awf-squid
docker logs awf-agent

# View Squid config
docker exec awf-squid cat /etc/squid/squid.conf

# Manual cleanup when done
docker rm -f awf-squid awf-agent

Check Which Domains Were Blocked

# After command completes
sudo cat /tmp/squid-logs-*/access.log | grep TCP_DENIED

# Or use the logs command
awf logs --format json | jq 'select(.isAllowed == false) | .domain'

Debug Container Network

# Check iptables rules
docker exec awf-agent iptables -t nat -L OUTPUT -n -v

# Check DNS
docker exec awf-agent cat /etc/resolv.conf

# Test connectivity to Squid
docker exec awf-agent nc -zv 172.30.0.10 3128

Squid Decision Codes

When analyzing logs, these codes indicate the traffic decision:

Code	Meaning
TCP_TUNNEL:HIER_DIRECT	ALLOWED (HTTPS tunnel)
TCP_MISS:HIER_DIRECT	ALLOWED (HTTP request)
TCP_DENIED:HIER_NONE	BLOCKED (domain not in allowlist)

Agent Image Options

Presets (Pre-built, Fast)

# Default - minimal ubuntu:22.04 (~200MB)
sudo awf --agent-image default --allow-domains github.com -- command

# Act - GitHub Actions parity (~2GB)
sudo awf --agent-image act --allow-domains github.com -- command

Custom Base Images (Requires --build-local)

sudo awf \
  --build-local \
  --agent-image ghcr.io/catthehacker/ubuntu:runner-22.04 \
  --allow-domains github.com \
  -- command

Common Issues and Fixes

"Cannot connect to Docker daemon"

sudo systemctl start docker

"Port 3128 already in use"

docker stop $(docker ps -q --filter "expose=3128")

Domain Not Working

1. Check if subdomain is needed: api.example.com vs example.com
2. Enable debug logging: --log-level debug
3. Check Squid logs: awf logs --format json

Command Fails with Exit Code 28 (Timeout)

The domain is being blocked. Check:

1. Is domain in --allow-domains?
2. Is subdomain required?
3. View blocked domains: awf logs --format json | jq 'select(.isAllowed == false)'

Limitations

• No IPv6: Only IPv4 traffic is supported
• No HTTP/3: Container curl doesn't support HTTP/3
• No internationalized domains: Use punycode (e.g., xn--bcher-kva.ch)
• HTTP to HTTPS redirects: May fail; use HTTPS directly
• IP-based access: Direct IP access is blocked (no domain)

Best Practices

1. Start with minimal domains: Only add what's needed
2. Use wildcards carefully: *.example.com is safer than *
3. Enable debug logging: When troubleshooting add --log-level debug
4. Review logs: Check what was blocked with awf logs stats
5. Use blocklists: For fine-grained control when allowing broad domains
6. Quote shell commands: Use 'command $VAR' to preserve container expansion

References

• Official AWF Repo
• AWF Skill Reference

Related Skills

• gh-aw-troubleshooting - Load this skill when debugging Agentic Workflows