Skip to content

CLAUDE.md

Latest commit

 

History

History
374 lines (278 loc) · 18.1 KB

CLAUDE.md

File metadata and controls

374 lines (278 loc) · 18.1 KB

AGENTS.md

This file provides guidance to coding agent when working with code in this repository.

Project Overview

awf (Agentic Workflow Firewall, package @github/awf) is a CLI that wraps any command in a sandboxed Docker network. It provides L7 (HTTP/HTTPS) egress control using Squid proxy, restricting network access to a whitelist of approved domains while giving the agent access to the host workspace and selected system paths via chroot and selective bind mounts.

Three Container Components

The system is orchestrated by src/cli.ts and managed by src/docker-manager.ts. There are three containers, two of which are always required and one optional:

1. Squid Proxy (always required) — containers/squid/, IP 172.30.0.10

  • Enforces domain ACL filtering for all HTTP/HTTPS traffic
  • Config (squid.conf) is generated by src/squid-config.ts and injected via base64 env var AWF_SQUID_CONFIG_B64 (not a file bind mount — avoids Docker-in-Docker issues)
  • Agent container depends_on Squid's healthcheck before starting

2. Agent (always required) — containers/agent/, IP 172.30.0.20

  • Runs the user's command (e.g., claude, copilot, curl)
  • An iptables-init init container (awf-iptables-init) shares the agent's network namespace and runs setup-iptables.sh to redirect all port 80/443 traffic via DNAT to Squid before the user command starts
  • entrypoint.sh handles UID/GID mapping, DNS config, chroot to /host, and capability drop (SYS_CHROOT, SYS_ADMIN dropped before user code runs)
  • Selective bind mounts (not a blanket host FS mount): system binaries (/usr, /bin, /sbin, /lib, /lib64, /opt, /sys, /dev) read-only; workspace and /tmp read-write; empty home volume with only whitelisted $HOME subdirs (.cache, .config, .local, .anthropic, .claude, .cargo, .rustup, .npm, .copilot); select /etc files (SSL certs, passwd, group, nsswitch.conf, ld.so.cache, alternatives, hosts — not /etc/shadow)
  • Sensitive API keys are NOT present in the agent environment when --enable-api-proxy is active

3. API Proxy Sidecar (optional) — containers/api-proxy/, IP 172.30.0.30

  • Enabled via --enable-api-proxy; not started otherwise
  • Injects real API credentials (OpenAI, Anthropic, Copilot) that the agent never sees
  • Agent calls the sidecar with no auth (e.g., http://172.30.0.30:10001 for Anthropic); sidecar injects the real key and forwards via Squid
  • Ports: 10000 (OpenAI), 10001 (Anthropic), 10002 (Copilot), 10004 (OpenCode) — these are discrete ports, not a contiguous range

Documentation Files

Development Workflow

Debugging GitHub Actions Failures

IMPORTANT: When GitHub Actions workflows fail, always follow this debugging workflow:

  1. Reproduce locally first - Run the same commands/scripts that failed in CI on your local machine
  2. Understand the root cause - Investigate logs, error messages, and system state to identify why it failed
  3. Test the fix locally - Verify your solution works in your local environment
  4. Then update the action - Only modify the GitHub Actions workflow after confirming the fix locally

This approach prevents trial-and-error debugging in CI (which wastes runner time and makes debugging slower) and ensures fixes address the actual root cause rather than symptoms.

Downloading CI Logs for Local Analysis:

Use scripts/download-latest-artifact.sh to download logs from GitHub Actions runs:

# Download logs from the latest integration test workflow run (default)
./scripts/download-latest-artifact.sh

# Download logs from a specific run ID
./scripts/download-latest-artifact.sh 1234567890

# Download from test-coverage workflow (latest run)
./scripts/download-latest-artifact.sh "" ".github/workflows/test-coverage.yml" "coverage-report"

Parameters:

  • RUN_ID (optional): Specific workflow run ID, or empty string for latest run
  • WORKFLOW_FILE (optional): Path to workflow file (default: .github/workflows/test-coverage.yml)
  • ARTIFACT_NAME (optional): Artifact name (default: coverage-report)

Artifact name:

  • coverage-report - test-coverage.yml

This downloads artifacts to ./artifacts-run-$RUN_ID for local examination. Requires GitHub CLI (gh) authenticated with the repository.

Example: The "Pool overlaps" Docker network error was reproduced locally, traced to orphaned networks from timeout-killed processes, fixed by adding pre-test cleanup in scripts, then verified before updating workflows.

Container Image Strategy

The firewall uses three Docker containers: Squid proxy, agent execution environment, and an optional API proxy sidecar. By default, the CLI pulls pre-built images from GitHub Container Registry (GHCR) for faster startup and easier distribution.

Default behavior (GHCR images):

  • Images are automatically pulled from ghcr.io/github/gh-aw-firewall/{squid,agent,api-proxy}:latest
  • Published during releases via .github/workflows/release.yml
  • Users don't need to build containers locally

Local build option:

  • Use --build-local flag to build containers from source
  • Useful for development or when GHCR is unavailable
  • Example: sudo awf --build-local --allow-domains github.com 'curl https://github.com'

Custom registry/tag:

  • --image-registry <registry> - Use a different registry (default: ghcr.io/github/gh-aw-firewall)
  • --image-tag <tag> - Use a specific version tag (default: latest)
  • Example: sudo awf --image-tag v0.2.0 --allow-domains github.com 'curl https://github.com'

Architecture

The codebase follows a modular architecture with clear separation of concerns:

Core Components

  1. CLI Entry Point (src/cli.ts)

    • Uses commander for argument parsing
    • Orchestrates the entire workflow: config generation → container startup → command execution → cleanup
    • Handles signal interrupts (SIGINT/SIGTERM) for graceful shutdown
    • Main flow: writeConfigs() → startContainers() → runAgentCommand() → stopContainers() → cleanup()

  2. Configuration Generation (src/squid-config.ts, src/docker-manager.ts)

    • generateSquidConfig(): Creates Squid proxy configuration with domain ACL rules
    • generateDockerCompose(): Creates Docker Compose YAML with two services (squid-proxy, agent)
    • All configs are written to a temporary work directory (default: /tmp/awf-<timestamp>)

  3. Docker Management (src/docker-manager.ts)

    • Manages container lifecycle using execa to run docker-compose commands
    • Fixed network topology: 172.30.0.0/24 subnet, Squid at 172.30.0.10, Agent at 172.30.0.20
    • Squid container uses healthcheck; Agent waits for Squid to be healthy before starting

  4. Type Definitions (src/types.ts)

    • WrapperConfig: Main configuration interface
    • SquidConfig, DockerComposeConfig: Typed configuration objects

  5. Logging (src/logger.ts)

    • Singleton logger with configurable log levels (debug, info, warn, error)
    • Uses chalk for colored output
    • All logs go to stderr (console.error) to avoid interfering with command stdout

Container Architecture

Squid Container (containers/squid/)

  • Based on ubuntu/squid:latest
  • Config passed via AWF_SQUID_CONFIG_B64 env var (base64-encoded); entrypoint decodes to /etc/squid/squid.conf
    • Why base64? Docker-in-Docker: the Docker daemon cannot access host filesystem paths, so file bind mounts don't work. See memory notes on DinD issue.
  • Exposes port 3128 as a standard forward proxy (not intercept/transparent mode)
  • HTTPS: reaches Squid via HTTPS_PROXY/https_proxy env vars → explicit CONNECT method. Tools that ignore proxy env vars will have their port 443 traffic DNAT'd to Squid, but the raw TLS ClientHello is rejected (Squid expects CONNECT), so the connection fails — still blocked, just with a TLS error instead of 403.
  • HTTP: http_proxy (lowercase) is intentionally NOT set. curl on Ubuntu 22.04 ignores uppercase HTTP_PROXY for HTTP (httpoxy mitigation), so HTTP falls through to iptables DNAT → Squid, which handles it fine. Setting http_proxy would make Squid's 403 page return exit code 0, breaking security test assertions.
  • Logs to shared volume squid-logs:/var/log/squid
  • Network: awf-net at 172.30.0.10; allowed unrestricted outbound via iptables -s 172.30.0.10 -j ACCEPT

Agent Execution Container (containers/agent/)

  • Based on ubuntu:22.04; can also use GitHub Actions parity image (act preset)
  • Selective bind mounts under /host/: system binaries /usr, /bin, /sbin, /lib, /lib64, /opt, /sys, /dev (ro); workspace and /tmp (rw); whitelisted $HOME subdirs (rw); select /etc files — NOT a blanket host FS mount; /etc/shadow, unwhitelisted home dirs, and most of /etc are excluded
  • entrypoint.sh handles: UID/GID remapping → DNS config → SSL CA import → chroot to /host → capability drop → run user command as host user
  • iptables init container (awf-iptables-init): separate container sharing agent's network namespace via network_mode: service:agent. Runs setup-iptables.sh to configure NAT rules before user command starts. Agent waits for /tmp/awf-init/ready signal file.
  • Key iptables rules (in setup-iptables.sh):
    • Allow localhost (for stdio MCP servers) and DNS
    • Allow traffic to Squid proxy itself
    • DNAT port 80 and 443 → Squid port 3128 as a defense-in-depth fallback; HTTP_PROXY and HTTPS_PROXY are always set so proxy-aware tools use the forward proxy directly
    • Block dangerous ports (SSH 22, SMTP 25, databases, Redis, MongoDB)
  • SYS_CHROOT and SYS_ADMIN dropped via capsh before user code runs; NET_ADMIN never granted to agent (only to the iptables-init init container)

API Proxy Sidecar (containers/api-proxy/) — optional, requires --enable-api-proxy

  • Node.js HTTP proxy at 172.30.0.30; listens on ports 10000, 10001, 10002, 10004
  • Agent sends unauthenticated requests; sidecar injects the real API key before forwarding
  • All upstream traffic goes through Squid (HTTP_PROXY env set inside sidecar)
  • Agent container's depends_on adds api-proxy: service_healthy when enabled

Traffic Flow

awf <flags> -- <command>
    ↓
CLI generates squid.conf (base64) + docker-compose.yml + seccomp profile in /tmp/awf-<ts>/
    ↓
Docker Compose: Squid starts (healthcheck) → [API Proxy starts (optional)] → Agent starts
                                             → iptables-init runs setup-iptables.sh (writes /ready)
    ↓
User command executes in Agent container (chrooted to /host)
    ↓
HTTPS (proxy-aware tools)  → HTTPS_PROXY env var → Squid:3128 (CONNECT) → domain ACL → allowed or blocked
HTTPS (proxy-unaware tools)→ iptables DNAT → Squid:3128 → TLS handshake rejected (connection error)
HTTP                       → iptables DNAT → Squid:3128 → domain ACL → allowed or 403
API calls (optional) → http://172.30.0.30:10001 → API Proxy injects key → Squid → upstream API
    ↓
docker compose down -v + rm /tmp/awf-<ts>/

Domain Whitelisting

  • Domains in --allow-domains are normalized (protocol/trailing slash removed)
  • Both exact matches and subdomain matches are added to Squid ACL:
    • github.com → matches github.com and .github.com (subdomains)
    • .github.com → matches all subdomains
  • Squid denies any domain not in the allowlist

DNS Configuration

DNS traffic is restricted to trusted DNS servers only to prevent DNS-based data exfiltration:

  • CLI Option: --dns-servers <servers> (comma-separated list of IP addresses)
  • Default: Google DNS (8.8.8.8,8.8.4.4)
  • IPv6 Support: Both IPv4 and IPv6 DNS servers are supported
  • Docker DNS: 127.0.0.11 is always allowed for container name resolution

Implementation:

  • Host-level iptables (src/host-iptables.ts): DNS traffic to non-whitelisted servers is blocked
  • Container NAT rules (containers/agent/setup-iptables.sh): Reads from AWF_DNS_SERVERS env var
  • Container DNS config (containers/agent/entrypoint.sh): Configures /etc/resolv.conf
  • Docker Compose (src/docker-manager.ts): Sets container dns: config and AWF_DNS_SERVERS env var

Proxy Environment Variables

AWF sets the following proxy-related environment variables in the agent container:

  • HTTP_PROXY / HTTPS_PROXY: Standard proxy variables (used by curl, wget, pip, npm, etc.)
  • SQUID_PROXY_HOST / SQUID_PROXY_PORT: Raw proxy host and port for tools that need them separately
  • JAVA_TOOL_OPTIONS: JVM system properties (-Dhttp.proxyHost, -Dhttps.proxyHost, etc.) for Java tools. Works for Gradle, SBT, and most JVM tools. Maven requires separate ~/.m2/settings.xml configuration — see docs/troubleshooting.md.

Example:

# Use Cloudflare DNS instead of Google DNS
sudo awf --allow-domains github.com --dns-servers 1.1.1.1,1.0.0.1 -- curl https://api.github.com

Exit Code Handling

The wrapper propagates the exit code from the agent container:

  1. Command runs in agent container
  2. Container exits with command's exit code
  3. Wrapper inspects container: docker inspect --format={{.State.ExitCode}}
  4. Wrapper exits with same code

Configuration Files

All temporary files are created in workDir (default: /tmp/awf-<timestamp>):

  • squid.conf: Generated Squid proxy configuration
  • docker-compose.yml: Generated Docker Compose configuration
  • agent-logs/: Directory for agent logs (automatically preserved if logs are created)
  • squid-logs/: Directory for Squid proxy logs (automatically preserved if logs are created)

Use --keep-containers to preserve containers and files after execution for debugging.

Key Dependencies

  • commander: CLI argument parsing
  • chalk: Colored terminal output
  • execa: Subprocess execution (docker-compose commands)
  • js-yaml: YAML generation for Docker Compose config
  • TypeScript 5.x, compiled to ES2020 CommonJS

Testing Notes

  • Tests use Jest (npm test)
  • Currently no test files exist (tsconfig excludes **/*.test.ts)
  • Integration testing: Run commands with --log-level debug and --keep-containers to inspect generated configs and container logs

Logging Implementation

Overview

The firewall implements comprehensive logging at two levels:

  1. Squid Proxy Logs (L7) - All HTTP/HTTPS traffic (allowed and blocked)
  2. iptables Kernel Logs (L3/L4) - Non-HTTP protocols and UDP traffic

Key Files

  • src/squid-config.ts - Generates Squid config with custom firewall_detailed logformat
  • containers/agent/setup-iptables.sh - Configures iptables LOG rules for rejected traffic
  • src/squid-config.test.ts - Tests for logging configuration

Squid Log Format

Custom format defined in src/squid-config.ts:40:

logformat firewall_detailed %ts.%03tu %>a:%>p %{Host}>h %<a:%<p %rv %rm %>Hs %Ss:%Sh %ru "%{User-Agent}>h"

Captures:

  • Timestamp with milliseconds
  • Client IP:port
  • Domain (Host header / SNI)
  • Destination IP:port
  • Protocol version
  • HTTP method
  • Status code (200=allowed, 403=blocked)
  • Decision code (TCP_TUNNEL=allowed, TCP_DENIED=blocked)
  • URL
  • User agent

iptables Logging

Two LOG rules in setup-iptables.sh:

  1. Line 80 - [FW_BLOCKED_UDP] prefix for blocked UDP traffic
  2. Line 95 - [FW_BLOCKED_OTHER] prefix for other blocked traffic

Both use --log-uid flag to capture process UID.

Testing Logging

Run tests:

npm test -- squid-config.test.ts

Manual testing:

# Test blocked traffic
awf --allow-domains example.com --keep-containers 'curl https://github.com'

# View logs
docker exec awf-squid cat /var/log/squid/access.log

Important Notes

  • Squid logs use Unix timestamps (convert with date -d @TIMESTAMP)
  • Decision codes: TCP_DENIED:HIER_NONE = blocked, TCP_TUNNEL:HIER_DIRECT = allowed
  • SNI is captured via CONNECT method for HTTPS (no SSL inspection)
  • iptables logs go to kernel buffer (view with dmesg)
  • PID not directly available (UID can be used for correlation)

Log Analysis Commands

The CLI includes built-in commands for aggregating and summarizing firewall logs.

Commands

awf logs stats - Show aggregated statistics from firewall logs

  • Default format: pretty (colorized terminal output)
  • Outputs: total requests, allowed/denied counts, unique domains, per-domain breakdown

awf logs summary - Generate summary report (optimized for GitHub Actions)

  • Default format: markdown (GitHub-flavored markdown)
  • Designed for piping directly to $GITHUB_STEP_SUMMARY

Output Formats

Both commands support --format <format>:

  • pretty - Colorized terminal output with percentages and aligned columns
  • markdown - GitHub-flavored markdown with collapsible details section
  • json - Structured JSON for programmatic consumption

Key Files

  • src/logs/log-aggregator.ts - Aggregation logic (aggregateLogs(), loadAllLogs(), loadAndAggregate())
  • src/logs/stats-formatter.ts - Format output (formatStatsJson(), formatStatsMarkdown(), formatStatsPretty())
  • src/commands/logs-stats.ts - Stats command handler
  • src/commands/logs-summary.ts - Summary command handler

Data Structures

// Per-domain statistics
interface DomainStats {
  domain: string;
  allowed: number;
  denied: number;
  total: number;
}

// Aggregated statistics
interface AggregatedStats {
  totalRequests: number;
  allowedRequests: number;
  deniedRequests: number;
  uniqueDomains: number;
  byDomain: Map<string, DomainStats>;
  timeRange: { start: number; end: number } | null;
}

GitHub Actions Usage

- name: Generate firewall summary
  if: always()
  run: awf logs summary >> $GITHUB_STEP_SUMMARY

This replaces 150+ lines of custom JavaScript parsing with a single command.