awf-skill

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

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

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

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

# 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'

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

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

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

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"

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

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

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

# 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)"

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

- 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'

# 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

# Terminal output
awf logs stats
 
# JSON for scripting
awf logs stats --format json
 
# Markdown for GitHub Actions
awf logs summary >> $GITHUB_STEP_SUMMARY

# Using awf logs
awf logs --format json | jq 'select(.isAllowed == false)'
 
# Direct Squid log query
sudo grep "TCP_DENIED" /tmp/squid-logs-*/access.log

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

# 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'

# 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

# 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

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

sudo systemctl start docker

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