README.md

Agentic Workflow Firewall

Warning

Releases v0.25.21 through v0.25.39 were retired due to a bug that impacted billing. If you are running one of these versions, please upgrade to the latest release as soon as possible.

A network firewall for agentic workflows that restricts outbound HTTP/HTTPS to an allowlist of domains.

Tip

This project is a part of GitHub's explorations of Agentic Workflows. For more background, check out the project page! ✨

How it works

awf runs your command inside a Docker sandbox with three containers:

• Squid proxy — filters outbound traffic by domain allowlist
• Agent — runs your command; all HTTP/HTTPS is routed through Squid
• API proxy sidecar (optional) — holds LLM API keys so they never reach the agent process

Requirements

• Docker: 20.10+ with Docker Compose v2
• Node.js: 20.19.0+ (for building from source)
• OS: Ubuntu 22.04+ or compatible Linux distribution (x86_64 and arm64)

See Compatibility for full details on supported versions and tested configurations.

Get started fast

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

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

Feature highlights

• Declarative config support: --config <path> with JSON/YAML + published JSON Schema
• Domain and URL controls: allow/deny domain rules, SSL Bump (--ssl-bump), and URL patterns (--allow-urls, requires --ssl-bump)
• Data protection controls: DLP scanning (--enable-dlp), DNS-over-HTTPS, and agent runtime limits (--agent-timeout)
• API proxy capabilities: OpenAI, Anthropic, Copilot, and Gemini targets with rate limits, token steering, and Anthropic auto-cache
• Infrastructure flexibility: upstream proxy chaining, host service access, Docker-in-Docker, custom mounts, memory limits, and TTY mode
• Operational tooling: pre-download images and inspect logs/stats/summaries/audits from live or saved runs

CLI subcommands

• awf predownload — pre-pull runtime images for faster startup or offline environments
• awf logs — inspect firewall logs in raw/pretty/json
  • awf logs stats — aggregate traffic statistics
  • awf logs summary — markdown/json summaries (great for GitHub Actions step summaries)
  • awf logs audit — audit view with policy-rule matching (requires policy-manifest.json, typically from --audit-dir)

For the complete CLI surface area, run awf --help.

GitHub Action quick start

steps:
  - uses: actions/checkout@v4
  - name: Setup AWF
    uses: github/gh-aw-firewall@v1
  - name: Run command through firewall
    run: sudo awf --allow-domains github.com,api.github.com -- curl https://api.github.com

See GitHub Actions for advanced setup and awf logs summary examples.

Explore the docs

• Quick start — install, verify, and run your first command
• Usage guide — CLI flags, domain allowlists, examples
• AWF config schema — machine-readable JSON Schema for JSON/YAML configs (also published as a versioned release asset for IDE autocomplete)
• AWF config spec — normative processing and precedence rules for tooling/compiler integration
• Audit log schema — JSON Schema for L7 traffic audit records (audit.jsonl)
• Token usage schema — JSON Schema for per-call token usage records (token-usage.jsonl)
• Schemas README — versioning policy, record identification, and validation examples
• Enterprise configuration — GitHub Enterprise Cloud and Server setup
• Chroot mode — use host binaries with network isolation
• API proxy sidecar — secure credential management for LLM APIs
• Authentication architecture — deep dive into token handling and credential isolation
• SSL Bump — HTTPS content inspection for URL path filtering
• GitHub Actions — CI/CD integration and MCP server setup
• Environment variables — passing environment variables to containers
• Logging quick reference and Squid log filtering — view and filter traffic
• Security model — what the firewall protects and how
• Architecture — how Squid, Docker, and iptables fit together
• Compatibility — supported Node.js, OS, and Docker versions
• Troubleshooting — common issues and fixes
• Image verification — cosign signature verification

Development

• Install dependencies: npm install
• Run tests: npm test
• Build: npm run build

Contributing

Contributions welcome! Please see CONTRIBUTING.md for guidelines.

License

MIT