Labsco
github logo

awf-skill

✓ Official★ 105

by github · part of github/gh-aw-firewall

Use the AWF (Agentic Workflow Firewall) to run commands with network isolation and domain whitelisting. Provides L7 HTTP/HTTPS egress control for AI agents.

🔥🔥🔥✓ VerifiedFreeQuick setup
#automation#git
🧰 Not standalone. This skill ships with github/gh-aw-firewall and only works together with that tool — install the tool first, then add this skill.

This is the playbook your agent receives when the skill activates — you don't need to read it to use the skill, but it's here to audit before installing.

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

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

5. Mount Custom Volumes

sudo awf --allow-domains github.com \
  -v /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:

CodeMeaning
TCP_TUNNEL:HIER_DIRECTALLOWED (HTTPS tunnel)
TCP_MISS:HIER_DIRECTALLOWED (HTTP request)
TCP_DENIED:HIER_NONEBLOCKED (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

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
  • debug-firewall - Manual Docker debugging commands for AWF
  • awf-debug-tools - Python scripts for log parsing and diagnostics