How github/gh-aw-firewall works
1. What this repo is
Agentic Workflow Firewall (AWF) is a Docker-based command runner that wraps an arbitrary user command in a network-restricted sandbox. The core architecture is a host-side CLI that assembles containers, network rules, and optional credential sidecars around the command being executed.
2. Top-level control plane
The main implementation lives in src/. It provides the awf CLI, option parsing, config loading/validation, command orchestration, and lifecycle management. This layer decides how to translate user intent (--allow-domains, --config, --ssl-bump, etc.) into a runnable sandbox definition.
3. Sandbox runtime
The sandbox is built from multiple Docker containers rather than a single process. The README’s main three-piece flow is real in the repo:
- Agent container: runs the user command.
- Squid container: enforces outbound domain allowlists.
- API proxy sidecar: optional, used to keep LLM credentials out of the agent process.
Supporting images exist for CLI proxying, build tools, Squid, and Docker-in-Docker variants.
4. Network enforcement boundary
The network boundary is enforced primarily by Squid plus host/container network setup. The host-side modules under src/host-iptables* and src/services/doh-proxy-service.ts show that AWF controls egress with iptables, DNS handling, and proxy routing, not just application-level filtering. This is the key security boundary for the whole system.
5. Proxy and traffic mediation
The containers/api-proxy service is a substantial subsystem of its own. It adapts multiple LLM provider APIs, handles authentication/token providers, rate limiting, request/response transforms, model mapping, token tracking, and observability. It sits between the agent and upstream providers so secrets and billing-related behavior can be isolated from the command being run.
6. Command execution and container lifecycle
src/container-*, src/docker-manager.ts, src/services/agent-service.ts, and related modules coordinate image selection, container start/stop, health checks, retries, and cleanup. This is the orchestration layer that turns config into a running sandbox, then tears it down safely after the command exits.
7. Configuration and policy model
Configuration is first-class. The repo contains JSON Schema files, config mappers, precedence logic, and validation code for CLI flags, YAML/JSON config files, and generated runtime config. Domain rules, URL rules, model policies, and runtime limits are compiled into the execution environment rather than interpreted ad hoc at runtime.
8. Logging, audit, and post-run analysis
Traffic and runtime telemetry are treated as artifacts. src/logs/, src/squid-log-reader.ts, and the CLI awf logs subcommands produce raw, summary, stats, and audit views. Separate schemas define audit and token-usage records, which implies a structured post-processing pipeline rather than just console logs.
9. Security hardening layers
The repo includes seccomp profiles, artifact permission handling, secret redaction, credential-hiding mounts, and shell/bootstrap scripts in containers/agent. These are not cosmetic; they form a defense-in-depth layer around the sandbox so secrets, host files, and process capabilities are tightly constrained.
10. Special execution modes
AWF supports variants such as chroot mode, DIND-related setups, host binary access, and workspace/volume mounting strategies. The src/services/* and docs/chroot-mode.md / docs/sandbox-design.md content show that the architecture is parameterized for different host capabilities and deployment environments, not just one fixed container layout.
11. Developer and release tooling
The repository is heavily automated through GitHub Actions workflows, lockfiles, and generated docs/assets. This includes build/test pipelines, security checks, smoke tests, release automation, and workflow-specific maintenance tools. For an architecture diagram, this is the “delivery/ops” boundary around the product, not part of the runtime path.
12. Documentation and schemas as part of the system
Docs are not incidental here: docs/, docs-site/, and schemas/ define the contract for config, logs, security model, and integration behavior. The architecture is therefore supported by machine-readable schemas plus human documentation, which likely keeps CLI behavior, container setup, and CI expectations aligned.
Main entry points: docker-manager.ts Docker manager · cli-workflow.ts Workflow · build-config.ts Sandbox plan · agent-service.ts Agent service
Components 20
Control plane
CLI, config, and orchestration that turn user intent into a runnable sandbox.
- AWF CLI · Top-level command interface and subcommands.
src/cli.ts - Workflow · Coordinates option validation, preflight, and command execution.
src/cli-workflow.ts - Options · Parses CLI flags and runtime options.
src/cli-options.ts - Config model · Loads, maps, merges, and validates repo configuration.
src/config-file.ts - Policy checks · Validates domain rules, runtime limits, and assembled config.
src/commands/validate-options.ts - Sandbox plan · Builds the runtime execution plan from flags and config.
src/commands/build-config.ts
Sandbox runtime
Containerized execution path and the services that surround the agent.
- Docker manager · Starts, stops, inspects, and cleans up containers.
src/docker-manager.ts - Lifecycle · Tracks startup, retries, health, stop, and cleanup behavior.
src/container-lifecycle.ts - Agent service · Assembles the command-running container and its runtime environment.
src/services/agent-service.ts - Agent env · Builds environment variables and credential exposure for the agent.
src/services/agent-environment/environment-builder.ts - Agent mounts · Constructs workspace, host, system, and secret-hiding mounts.
src/services/agent-volumes.ts - API proxy · Isolates provider credentials, routing, transforms, rate limits, and token tracking.
src/services/api-proxy-service.ts - Proxy runtime · Container-side request handling, adapters, guards, and upstream forwarding.
containers/api-proxy/server.js
Policy and network
Egress control, DNS, domain policy, and security boundaries.
- Squid service · Configures the outbound filtering proxy container.
src/services/squid-service.ts - Host firewall · Sets up host-side iptables rules for egress and host-access control.
src/host-iptables.ts - DNS proxy · Routes DNS through a controlled proxy path.
src/services/doh-proxy-service.ts
Observability
Log, audit, and telemetry processing paths.
- Logs pipeline · Discovers, parses, aggregates, and formats runtime and audit logs.
src/logs/index.ts
Docs and schemas
Contracts, docs, and release/developer automation around the product.
- Schemas · Defines audit, token usage, proxy access, and telemetry record formats.
schemas/README.md - Docs site · Human-readable architecture, usage, and security documentation.
docs/architecture.md - CI workflows · Build, test, release, and security automation for the repo.
.github/workflows/build.yml
Connections 21
- AWF CLI → Workflow: invokes · CLI entry hands off to the main workflow.
- Workflow → Options: parses · Reads flags and user-supplied runtime options.
- Workflow → Config model: loads · Pulls configuration from files and precedence layers.
- Workflow → Policy checks: checks · Validates assembled options and policy constraints.
- Policy checks → Sandbox plan: approves · Validated inputs are turned into an execution plan.
- Sandbox plan → Docker manager: assembles · Produces container definitions and orchestration inputs.
- Docker manager → Lifecycle: controls · Lifecycle manager handles startup, retry, stop, and cleanup.
- Docker manager → Agent service: starts · Creates the agent container as the primary workload.
- Agent service → Agent env: injects · Builds the agent environment with credential and proxy settings.
- Agent service → Agent mounts: mounts · Attaches workspace, system, and secret-hiding volumes.
- Docker manager → Squid service: starts · Creates the egress-filtering Squid sidecar.
- Docker manager → API proxy: optionally starts · Adds the credential-isolating API proxy when needed.
- API proxy → Proxy runtime: runs as · Service is implemented by the proxy container runtime.
- Sandbox plan → Host firewall: configures · Execution plan includes host-side firewall setup.
- Sandbox plan → DNS proxy: configures · Execution plan can route DNS through the proxy service.
- Host firewall → Squid service: funnels traffic · Firewall rules steer egress toward the proxy boundary.
- Squid service → Logs pipeline: emits · Proxy access logs feed the post-run analysis pipeline.
- Proxy runtime → Logs pipeline: emits · Proxy telemetry and access events are analyzed after execution.
- Logs pipeline → Schemas: formats · Structured log outputs follow repo schemas.
- Docs site → Schemas: describes · Docs explain the same contracts encoded in schemas.
- CI workflows → Docs site: checks · Automation validates docs, tests, and release artifacts.