Agentic Workflow Firewall

A network firewall for agentic workflows with domain whitelisting. This tool provides L7 (HTTP/HTTPS) egress control using Squid proxy and Docker containers, restricting network access to a whitelist of approved domains for AI agents and their MCP servers.

Tip

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

What it does

• 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
• Docker-in-Docker Support: Spawned containers inherit firewall restrictions

Get started fast

• Requirement: Docker running on your machine
• Install:

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

  Review the script before running, or download the latest release binary and verify it with the published checksums.txt before installing.
• Run your first command:

  sudo awf --allow-domains github.com -- curl https://api.github.com

  Use the -- separator to pass the command you want to run behind the firewall.

GitHub Copilot CLI in one line

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

Installation Options

# Install latest version
curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash

# Install a specific version
curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo bash -s -- v1.0.0

# Or using environment variable
curl -sSL https://raw.githubusercontent.com/githubnext/gh-aw-firewall/main/install.sh | sudo AWF_VERSION=v1.0.0 bash

This installer automatically:

• Downloads the latest release binary (or a specified version)
• Verifies SHA256 checksum to detect corruption or tampering
• Validates the file is a valid Linux executable
• Protects against 404 error pages being saved as binaries
• Installs to /usr/local/bin/awf

Alternative: Manual installation

# Download the latest release binary
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/latest/download/awf-linux-x64 -o awf

# Download checksums for verification
curl -fL https://github.com/githubnext/gh-aw-firewall/releases/latest/download/checksums.txt -o checksums.txt

# Verify SHA256 checksum
sha256sum -c checksums.txt --ignore-missing

# Install
chmod +x awf
sudo mv awf /usr/local/bin/

# Verify installation
sudo awf --help

Docker Image Verification: All published container images are cryptographically signed with cosign. See docs/image-verification.md for verification instructions.

Explore the docs

• Quick start — install, verify, and run your first command
• Usage guide — CLI flags, domain allowlists, Docker-in-Docker examples
• 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
• 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