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

• Prerequisite: Docker is running
• Install:

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

• Run your first command:

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

  The -- separator passes 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"

For checksum verification, version pinning, and manual installation steps, see Quick start.

GitHub Action (recommended for CI/CD)

Use the setup action in your workflows:

steps:
  - name: Setup awf
    uses: githubnext/gh-aw-firewall@main
    with:
      # version: 'v1.0.0'    # Optional: defaults to latest
      # pull-images: 'true'  # Optional: pre-pull Docker images for the version

  - name: Run command with firewall
    run: sudo awf --allow-domains github.com -- curl https://api.github.com

To pin Docker images to match the installed version, use pull-images: 'true' and pass the image tag to awf:

steps:
  - name: Setup awf
    id: setup-awf
    uses: githubnext/gh-aw-firewall@main
    with:
      version: 'v0.7.0'
      pull-images: 'true'

  - name: Run with pinned images
    run: |
      sudo awf --allow-domains github.com \
        --image-tag ${{ steps.setup-awf.outputs.image-tag }} \
        -- curl https://api.github.com

Shell script

# 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

The shell 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
• SSL Bump — HTTPS content inspection for URL path filtering
• 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