gh-aw-firewall: Restrict Network Access for Agentic Workflows

Overview

gh-aw-firewall runs commands in a Docker sandbox and filters outbound HTTP/HTTPS traffic through a domain allowlist. Its API proxy sidecar keeps supported LLM API credentials away from the agent process, addressing two risks when automated agents run code or access external services: unrestricted network access and direct exposure of model credentials.

It is intended for developers and teams running agentic workflows who need to constrain network access, inspect traffic, or integrate firewalling into GitHub Actions. It adds infrastructure and configuration overhead, so it is most useful when those controls matter more than the simplicity of running a command directly.

Key Features

• Runs commands in a Docker sandbox with outbound traffic filtered by domain rules.
• Uses an API proxy sidecar to hold LLM API keys outside the agent process.
• Supports declarative JSON or YAML configuration, with a published schema.
• Offers URL-pattern filtering with SSL Bump, which must be enabled for URL rules.
• Provides DLP scanning, DNS-over-HTTPS, and agent runtime limits.
• Includes log, statistics, summary, and audit commands for reviewing traffic.
• Integrates with GitHub Actions through a setup action.
• Documents preview microVM backends that require explicit opt-in and have platform constraints.

Use Cases

• Agent workflow maintainers can restrict an agent's network access to the services it needs while running commands in CI.
• Security teams can use traffic logs and audit views to review whether network policy matches observed requests.
• Teams using LLM APIs can route supported provider requests through the sidecar to reduce credential exposure to agent processes.
• Developers debugging integrations can inspect allowed traffic and adjust domain rules when a workflow needs access to an external service.

Getting Started

The README provides a quick install and test command:

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

See the repository README for configuration, GitHub Actions setup, and detailed usage.

Alternatives

• agent-sandbox: Agent Sandbox isolates coding agents’ workspace and network access, while gh-aw-firewall focuses on outbound domain filtering and credential isolation in a sidecar.

Considerations

• Requires Docker 20.10 or later with Docker Compose v2. Building from source requires Node.js 20.19.0 or later; the documented supported systems are Ubuntu 22.04 or compatible Linux distributions on x86_64 and arm64.
• The quick-start installation and execution commands use sudo.
• URL-path filtering depends on SSL Bump, which requires HTTPS inspection configuration.
• Releases v0.25.21 through v0.25.39 were retired because of a billing-impacting bug. Users on those versions should upgrade to a current release.
• Cloud Hypervisor and NVX integrations are described as previews with explicit opt-in and platform restrictions.