github / gh-aw-firewall
✓ Official★ 104A skill package that teaches your agent 5 capabilities — every one documented and browsable below, no GitHub required · by github.
Each skill below is one capability this package teaches your agent. Install the whole package, or open a skill to install just that one.
Practical Python scripts for debugging awf - parse logs, diagnose issues, inspect containers, test domains
8 files — installable on its own
Use the AWF (Agentic Workflow Firewall) to run commands with network isolation and domain whitelisting. Provides L7 HTTP/HTTPS egress control for AI agents.
3 files — installable on its own
Debug the AWF firewall by inspecting Docker containers (awf-squid, awf-agent), analyzing Squid access logs, checking iptables rules, and troubleshooting…
1 file — installable on its own
Debug GitHub Actions workflows by downloading logs, analyzing summaries, and understanding how agentic workflows and the AWF firewall work together.
3 files — installable on its own
Regenerate and post-process all agentic workflows. Use when gh-aw is updated, workflow .md files change, or when asked to recompile/regenerate workflows.
1 file — installable on its own
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.comThe -- 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 environmentsawf logs— inspect firewall logs in raw/pretty/jsonawf logs stats— aggregate traffic statisticsawf logs summary— markdown/json summaries (great for GitHub Actions step summaries)awf logs audit— audit view with policy-rule matching (requirespolicy-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.comSee 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 (glibc-based daemon hosts)
- 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
- Diagnosing AWF failures — use the Self-Hosted Runner Doctor agent to triage self-hosted/ARC/GHES/GHEC failures
- 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
Install the whole package (5 skills):
npx skills add https://github.com/github/gh-aw-firewallOr install a single skill:
npx skills add https://github.com/github/gh-aw-firewall --skill <name>Pick the skill name from the Skills tab — each entry there installs independently.