gh-aw-firewall: Secure Your Agentic Workflows with a Network Firewall

Introduction

gh-aw-firewall is an innovative network firewall tailored for agentic workflows, ensuring that all outbound HTTP/HTTPS traffic adheres to a predefined allowlist of domains. This project is a key part of GitHub's initiatives in Agentic Workflows, providing a critical layer of security and control.

The firewall operates by executing your commands inside a Docker sandbox, which includes three main components:

• Squid proxy: Filters all outbound traffic based on your domain allowlist.
• Agent: Runs your specified command, with all HTTP/HTTPS requests routed through Squid.
• API proxy sidecar (optional): Securely holds Large Language Model (LLM) API keys, preventing them from ever reaching the agent process.

Important Note: Releases v0.25.21 through v0.25.39 were retired due to a billing-related bug. Users running these versions should upgrade to the latest release immediately.

Installation

Getting started with gh-aw-firewall is straightforward. Ensure you have Docker (20.10+ with Docker Compose v2) and Node.js (20.19.0+) installed on a compatible Linux distribution (Ubuntu 22.04+).

For a quick setup, use the following command:

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

Examples

After installation, you can immediately start using awf to secure your commands. The -- separator is used to distinguish firewall options from the command you wish to run.

Run a command with a domain allowlist:

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

To inspect API proxy endpoints and models without executing an agent command, use awf --reflect:

awf --reflect

gh-aw-firewall also integrates seamlessly with GitHub Actions:

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

Why Use gh-aw-firewall?

gh-aw-firewall offers a comprehensive set of features designed to enhance the security, control, and operational efficiency of agentic workflows:

• Declarative Configuration: Supports JSON/YAML configurations with a published JSON Schema for easy management.
• Granular Domain and URL Controls: Implement allow/deny rules for domains, enable SSL Bump for HTTPS content inspection, and define URL patterns.
• Advanced Data Protection: Features include DLP scanning, DNS-over-HTTPS, and agent runtime limits to prevent data exfiltration and control execution.
• Robust API Proxy Capabilities: Supports OpenAI, Anthropic, Copilot, and Gemini targets, offering rate limits, token steering, and Anthropic auto-cache for efficient LLM interactions.
• Infrastructure Flexibility: Provides options for upstream proxy chaining, host service access, Docker-in-Docker, custom mounts, memory limits, and TTY mode.
• Operational Tooling: Includes commands to pre-download images, inspect logs (raw, pretty, JSON), view aggregate traffic statistics, generate markdown/JSON summaries, and perform audit views with policy-rule matching.

This firewall is an essential tool for developers and organizations looking to secure their automated workflows, especially those involving external API calls and sensitive data.

Links

• GitHub Repository: github/gh-aw-firewall
• Agentic Workflows Project Page: github.github.io/gh-aw/
• Quick Start Guide: docs/quickstart.md
• Usage Guide: docs/usage.md
• GitHub Actions Integration: docs/github_actions.md