Skip to main content
skill CX Codex official · GitHub

awf-skill — Claude Code skill: what it does, how to install

Constrains AI agent network access via AWF. Enforces L7 domain whitelisting and blocks unauthorized outbound HTTP and HTTPS traffic.

MIT 21 installs ★ 165 updated 2026-10-29

Install into Claude Code · Skills CLI (Vercel) All methods and platforms ↓
npx skills add github/gh-aw-firewall --skill awf-skill -a claude-code
Open on GitHub

What awf-skill does

The skill provides workflow rules for running commands under the Agentic Workflow Firewall (awf). It controls egress HTTP and HTTPS traffic at the application layer, allowing connections only to specified domains. Enforcement happens directly on the host using the iptables DOCKER-USER chain across all containers.

Chroot mode is active by default. It allows transparent execution of host binaries such as Python, Node.js, and Go while keeping network traffic strictly confined. The tool also supports wildcard subdomain matching, Squid proxy log analysis via awf logs, and URL path inspection using --ssl-bump.

Executing commands with awf requires an active Docker installation and sudo permissions. Without root access, the firewall cannot write iptables rules or route traffic through its proxy containers.

What it helps with

  • Restrict agent egress traffic to approved domain lists
  • Run Playwright tests isolated to localhost and target staging servers
  • Execute untrusted scripts without unauthorized network requests
  • Audit blocked egress calls using local Squid proxy logs

Example prompts for the agent

  • Run npm test using awf with network access restricted to github.com
  • Execute Copilot CLI through awf allowing only api.github.com and arxiv.org
  • Run npx playwright test inside awf with localhost access enabled

How to install awf-skill

1Skills CLI (Vercel)

npx skills add github/gh-aw-firewall --skill awf-skill -a claude-code

2Manually: put the files in place

~/.claude/skills/awf-skill/SKILL.md

Copy the whole skill folder; for one project use .claude/skills/awf-skill/

Step by step, with commands for each platform: How to install skills in Claude Code: five ways

Questions about awf-skill

What does awf-skill do?

It gives the AI agent instructions to sandbox commands with AWF, restricting outbound network traffic using L7 domain whitelists.

How to install awf-skill in Claude Code?

Run npx skills add github/gh-aw-firewall --skill awf-skill -a claude-code in your terminal.

What are the requirements to run AWF commands?

The host system needs Docker installed and sudo rights to configure iptables chains and run firewall containers.

Source text

SKILL.md · MIT
---
name: awf-skill
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.
allowed-tools: Bash(sudo:*), Bash(awf:*), Bash(docker:*), Read
user-invocable: false
---

# 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

## Quick Start

### Basic Command

```bash
# 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

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

### Enable Debug Logging

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

## Installation

### Install Script (Recommended)

```bash
gh auth status
export GH_TOKEN="$(gh auth token)"
sudo --preserve-env=GH_TOKEN bash ./install.sh
unset GH_TOKEN
sudo awf --version
```

Obtain and review `install.sh` through an independently authenticated channel
before running it. Do not pipe an unauthenticated download into `sudo bash`.

### Build from Source

```bash
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)

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

### Wildcard Patterns

```bash
# 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

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

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

### Domain Blocklist

```bash
# 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

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

### 2. Run with MCP Servers

```bash
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

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

### 4. Pass Environment Variables

```bash
# 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

```bash
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)

```bash
# 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

```bash
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

```yaml
- name: Setup awf
  uses: github/gh-aw-firewall@<reviewed-commit-SHA>

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

## Log Analysis Commands

### View Logs

```bash
# 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

```bash
# 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

```bash
# 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

```bash
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

```bash
# 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

```bash
# 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)

```bash
# 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)

```bash
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"

```bash
sudo systemctl start docker
```

### "Port 3128 already in use"

```bash
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

## Related Skills

- `debug-firewall` - Manual Docker debugging commands for AWF
- `awf-debug-tools` - Python scripts for log parsing and diagnostics

© github · MIT · github/gh-aw-firewall

Similar skills

All skills for Security →

Project sponsors

Companies that keep this analytics open