🔥 GitHub Agentic Workflows - Firewall Skill

📋 Purpose

Master the Agentic Workflow Firewall (AWF) - a network firewall for agentic workflows providing L7 (HTTP/HTTPS) egress control using Squid proxy and Docker containers. This skill provides comprehensive expertise in restricting network access to a whitelist of approved domains for AI agents and their MCP servers.

🎯 Core Concepts

What is AWF?

AWF (Agentic Workflow Firewall) is a network security layer that restricts AI agent network access to explicitly approved domains, preventing data exfiltration and unauthorized external communication.

Key Features:

• 🌐 L7 Domain Whitelisting: HTTP/HTTPS traffic control at application layer

• 🔒 Host-Level Enforcement: iptables DOCKER-USER chain for all containers

• 📦 Chroot Mode: Host binaries with network isolation

• 🔑 API Proxy Sidecar: Secure LLM credential management

• ✅ Transparent: Works with existing containers

Security Model

┌────────────────────────────────────────────────┐ │ AI Agent Container │ │ ┌──────────────────────────────────────┐ │ │ │ Application Code │ │ │ │ (Read-only filesystem) │ │ │ └───────────────┬──────────────────────┘ │ │ │ Network Request │ │ ▼ │ │ ┌──────────────────────────────────────┐ │ │ │ iptables DOCKER-USER Chain │ │ │ │ (Force all traffic through Squid) │ │ │ └───────────────┬──────────────────────┘ │ └──────────────────┼──────────────────────────────┘ │ ▼ ┌───────────────────────────────┐ │ Squid Proxy │ │ ┌─────────────────────────┐ │ │ │ Domain Whitelist │ │ │ │ - github.com ✅ │ │ │ │ - api.github.com ✅ │ │ │ │ - evil.com ❌ │ │ │ └─────────────────────────┘ │ │ │ │ ┌─────────────────────────┐ │ │ │ SSL Bump (HTTPS) │ │ │ │ (Content Inspection) │ │ │ └─────────────────────────┘ │ └────────────┬──────────────────┘ │ ▼ External Network (Allowed domains only)

🏗️ Architecture

Three Operating Modes

1. Standard Mode (Default)

awf --allow-domains github.com,api.github.com -- docker run myapp

How it works:

• Launches Squid proxy with domain whitelist

• Creates iptables rules in DOCKER-USER chain

• Runs command in Docker container

• All HTTP/HTTPS traffic forced through Squid

• Unauthorized domains blocked

2. Chroot Mode

awf --chroot --allow-domains github.com -- python3 script.py

How it works:

• Uses host binaries (Python, Node.js, Go)

• Transparent network isolation

• No Docker container overhead

• Squid proxy still enforces whitelist

Use Cases:

• Faster startup (no container pull)

• Access to host tools

• Still network-isolated

3. API Proxy Sidecar

awf --api-proxy --allow-domains api.openai.com,api.anthropic.com -- node agent.js

How it works:

• Node.js proxy for LLM API calls

• Credentials injected securely

• Tokens never exposed to AI agent

• All calls routed through Squid

🔧 Configuration

CLI Usage

Basic Command Structure:

awf [firewall-options] -- [command-to-run]

The -- separator divides firewall configuration from the command to execute.

Domain Allowlisting

Single Domain:

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

Multiple Domains:

awf --allow-domains github.com,api.openai.com,anthropic.com -- python agent.py

Wildcard Subdomains:

awf --allow-domains '*.github.com' -- npm install

Domain File:

domains.txt

github.com api.github.com *.githubusercontent.com

awf --allow-domains-file domains.txt -- git clone https://github.com/repo

Environment Variables

Passing Variables to Container:

awf --env API_KEY --env DEBUG -- node app.js

With Values:

awf --env API_KEY=secret123 -- python script.py

From File:

.env file

API_KEY=secret123 DEBUG=true

awf --env-file .env -- npm start

Installation

Quick Install:

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

Manual Install:

npm install -g gh-aw-firewall

Verify:

awf --version awf --help

🔐 API Proxy Sidecar

Secure Credential Management

The API proxy sidecar provides secure credential management for LLM APIs (OpenAI, Anthropic) without exposing tokens to AI agents.

Architecture:

┌──────────────────────────────────────┐ │ AI Agent Container │ │ ┌────────────────────────────┐ │ │ │ Code makes API call │ │ │ │ http://localhost:8080/v1 │ │ │ │ (No API key in code) │ │ │ └──────────────┬─────────────┘ │ └─────────────────┼────────────────────┘ │ ▼ ┌─────────────────────────────┐ │ API Proxy Sidecar │ │ ┌──────────────────────┐ │ │ │ Inject Credentials │ │ │ │ Authorization: sk-xx │ │ │ └──────────────────────┘ │ │ │ │ │ ▼ │ │ ┌──────────────────────┐ │ │ │ Route via Squid │ │ │ └──────────────────────┘ │ └───────────┬─────────────────┘ │ ▼ ┌─────────────┐ │ Squid Proxy │ │ (Whitelist) │ └──────┬──────┘ │ ▼ External API (api.openai.com)

Configuration:

Export credentials (not visible to agent)

export OPENAI_API_KEY=sk-xxx export ANTHROPIC_API_KEY=sk-ant-xxx

Start with API proxy

awf --api-proxy
--allow-domains api.openai.com,api.anthropic.com
-- node agent.js

Agent Code:

// Agent makes calls without credentials fetch('http://localhost:8080/v1/chat/completions', { method: 'POST', headers: { 'Content-Type': 'application/json' }, body: JSON.stringify({ model: 'gpt-4', messages: [...] }) });

// API proxy automatically injects: // Authorization: Bearer sk-xxx

Benefits:

• ✅ Credentials never in agent code

• ✅ Tokens isolated in proxy

• ✅ All traffic still goes through Squid

• ✅ Domain whitelist enforced

• ✅ Logging and monitoring

Implementation Example

Go Proxy Server:

package main

import ( "net/http" "net/http/httputil" "net/url" "os" )

func main() { // Read credentials from environment openaiKey := os.Getenv("OPENAI_API_KEY") anthropicKey := os.Getenv("ANTHROPIC_API_KEY")

// Squid proxy URL
squidURL, _ := url.Parse("http://squid:3128")

// Create reverse proxy
proxy := httputil.NewSingleHostReverseProxy(squidURL)

// Modify request to inject credentials
director := proxy.Director
proxy.Director = func(req *http.Request) {
    director(req)
    
    // Inject appropriate credential
    if req.Host == "api.openai.com" {
        req.Header.Set("Authorization", "Bearer "+openaiKey)
    } else if req.Host == "api.anthropic.com" {
        req.Header.Set("x-api-key", anthropicKey)
    }
    
    // Route through Squid
    req.URL.Host = req.Host
    req.URL.Scheme = "https"
}

http.ListenAndServe(":8080", proxy)

}

🌐 SSL Bump (HTTPS Inspection)

Content Inspection

SSL Bump allows Squid to inspect HTTPS traffic for URL path filtering and content validation.

Configuration:

Enable SSL Bump

http_port 3128 ssl-bump
cert=/etc/squid/certs/squid-ca-cert.pem
key=/etc/squid/certs/squid-ca-key.pem

SSL Bump rules

acl step1 at_step SslBump1 ssl_bump peek step1 ssl_bump bump all

URL path filtering

acl allowed_paths url_regex ^https://api\.github\.com/repos/ http_access allow allowed_paths http_access deny all

Use Cases:

• ✅ Block specific URL paths

• ✅ Content validation

• ✅ Deep packet inspection

• ✅ Logging HTTPS requests

Security Considerations:

• ⚠️ Requires CA certificate in agent

• ⚠️ Man-in-the-middle by design

• ✅ Transparent to agent code

• ✅ Logs include HTTPS details

🔄 GitHub Actions Integration

Basic Workflow

name: Agentic Workflow with Firewall

on: pull_request

jobs: agent: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4

  - name: Install AWF
    run: |
      curl -sSL https://raw.githubusercontent.com/github/gh-aw-firewall/main/install.sh | sudo bash
  
  - name: Run Agent with Firewall
    run: |
      awf --allow-domains github.com,api.github.com \
          -- node agent.js
    env:
      GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

MCP Server Configuration

• name: Run MCP Server with Firewall run: | awf --allow-domains github.com,api.githubcopilot.com
  --env GITHUB_TOKEN
  -- docker run -i
  -e GITHUB_TOKEN
  ghcr.io/github/github-mcp-server:latest env: GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}

Multi-Stage Pipeline

jobs: build: runs-on: ubuntu-latest steps: - name: Build with NPM Registry run: | awf --allow-domains registry.npmjs.org
-- npm install

  - name: Test with External APIs
    run: |
      awf --allow-domains api.github.com,api.openai.com \
          --api-proxy \
          -- npm test
    env:
      OPENAI_API_KEY: ${{ secrets.OPENAI_API_KEY }}
  
  - name: Deploy (No Network)
    run: |
      awf --allow-domains '' \
          -- npm run build

📊 Logging & Monitoring

Log Files

Squid Access Log:

Location

/var/log/squid/access.log

Format

timestamp ip method url status bytes

View recent

tail -f /var/log/squid/access.log

Filter blocked requests

grep "TCP_DENIED" /var/log/squid/access.log

Squid Cache Log:

Location

/var/log/squid/cache.log

Contains

• Squid startup/shutdown
• Configuration errors
• Domain whitelist violations

Monitor

tail -f /var/log/squid/cache.log

Quick Reference

View All Traffic:

awf --log-level debug --allow-domains github.com -- curl https://api.github.com

Filter by Domain:

grep "github.com" /var/log/squid/access.log

Count Requests:

awk '{print $7}' /var/log/squid/access.log | sort | uniq -c | sort -rn

Blocked Requests:

grep "TCP_DENIED" /var/log/squid/access.log | awk '{print $7}' | sort | uniq

Monitoring Metrics

Prometheus Exporter:

docker-compose.yml

services: squid-exporter: image: boynux/squid-exporter ports: - "9301:9301" environment: - SQUID_HOSTNAME=squid - SQUID_PORT=3128

Grafana Dashboard:

• Total requests

• Allowed vs denied

• Top domains

• Response times

• Cache hit rate

🔧 Troubleshooting

Common Issues

1. Connection Refused

Symptom:

Error: connect ECONNREFUSED 127.0.0.1:3128

Diagnosis:

Check Squid is running

ps aux | grep squid

Check Squid port

netstat -tlnp | grep 3128

Check Squid logs

tail /var/log/squid/cache.log

Solutions:

• Ensure Squid container is running

• Verify iptables rules are applied

• Check Squid configuration syntax

2. Domain Not Whitelisted

Symptom:

HTTP 403 Forbidden TCP_DENIED/403

Diagnosis:

Check domain in whitelist

grep "example.com" /etc/squid/allowed-domains.txt

View denied requests

grep "TCP_DENIED" /var/log/squid/access.log | tail -20

Solutions:

• Add domain to whitelist

• Use wildcard: *.example.com

• Check for typos in domain name

3. SSL Certificate Issues

Symptom:

Error: certificate verify failed

Diagnosis:

Check CA certificate

ls -la /etc/squid/certs/

Test SSL connection

openssl s_client -connect api.github.com:443 -proxy localhost:3128

Solutions:

• Install Squid CA certificate in container

• Disable SSL Bump if not needed

• Use --insecure flag for testing (not production)

4. Performance Issues

Symptom:

• Slow response times

• High latency

Diagnosis:

Check Squid CPU/memory

docker stats squid

Monitor request timing

tail -f /var/log/squid/access.log | grep -o "TCP_[A-Z_]*"

Solutions:

• Increase Squid cache size

• Add more Squid workers

• Use connection pooling

• Enable HTTP/2

5. Docker Networking

Symptom:

Error: network unreachable

Diagnosis:

Check Docker network

docker network ls docker network inspect awf-network

Check iptables

sudo iptables -L DOCKER-USER -n -v

Solutions:

• Verify Docker network exists

• Check iptables rules are applied

• Restart Docker daemon

⚙️ Advanced Configuration

Custom Squid Configuration

squid.conf:

Basic ACLs

acl localnet src 172.16.0.0/12 acl SSL_ports port 443 acl Safe_ports port 80 acl CONNECT method CONNECT

Allowed domains from file

acl allowed_domains dstdomain "/etc/squid/allowed-domains.txt"

Deny CONNECT to other than SSL ports

http_access deny CONNECT !SSL_ports

Allow only safe ports

http_access deny !Safe_ports

Allow localhost

http_access allow localnet

Allow only whitelisted domains

http_access allow allowed_domains

Deny everything else

http_access deny all

Logging

access_log /var/log/squid/access.log squid cache_log /var/log/squid/cache.log

Performance

cache_mem 256 MB maximum_object_size 50 MB cache_dir ufs /var/spool/squid 1000 16 256

DNS

dns_nameservers 8.8.8.8 8.8.4.4

Docker Compose Setup

version: '3.8'

services: squid: image: ubuntu/squid:latest container_name: awf-squid ports: - "3128:3128" volumes: - ./squid.conf:/etc/squid/squid.conf:ro - ./allowed-domains.txt:/etc/squid/allowed-domains.txt:ro - squid-cache:/var/spool/squid - squid-logs:/var/log/squid networks: - awf-network restart: unless-stopped

agent: image: myagent:latest depends_on: - squid environment: - HTTP_PROXY=http://squid:3128 - HTTPS_PROXY=http://squid:3128 networks: - awf-network

networks: awf-network: driver: bridge

volumes: squid-cache: squid-logs:

iptables Rules

Automatic (via AWF):

awf --allow-domains github.com -- docker run myapp

iptables rules applied automatically

Manual:

Force all container traffic to Squid

sudo iptables -I DOCKER-USER -p tcp --dport 80 -j REDIRECT --to-port 3128 sudo iptables -I DOCKER-USER -p tcp --dport 443 -j REDIRECT --to-port 3128

Verify rules

sudo iptables -L DOCKER-USER -n -v

🎯 Best Practices

1. Principle of Least Privilege

❌ DON'T: Allow all subdomains

awf --allow-domains '*' -- node agent.js

✅ DO: Specific domains only

awf --allow-domains api.github.com,api.openai.com -- node agent.js

2. Use API Proxy for Credentials

❌ DON'T: Expose tokens to agent

const token = process.env.OPENAI_API_KEY; // Visible to agent

✅ DO: Use API proxy

awf --api-proxy -- node agent.js # Tokens in proxy only

3. Monitor and Audit

Enable comprehensive logging:

awf --log-level debug
--audit-log /var/log/awf/audit.log
--allow-domains github.com
-- python agent.py

Review logs regularly:

Daily review

grep "TCP_DENIED" /var/log/squid/access.log | wc -l

Alert on suspicious patterns

grep "evil.com" /var/log/squid/access.log && notify-admin

4. Test Firewall Rules

Verify blocking:

Should succeed

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

Should fail

awf --allow-domains github.com -- curl https://evil.com

5. Performance Optimization

Enable caching:

cache_mem 512 MB maximum_object_size 100 MB cache_dir ufs /var/spool/squid 10000 16 256

Use connection pooling:

persistent_connection_timeout 60 seconds client_persistent_connections on server_persistent_connections on

6. Security Hardening

Disable unnecessary features:

No FTP

acl FTP proto FTP http_access deny FTP

No HTTPS without SSL Bump

acl SSL_ports port 443 http_access deny CONNECT !SSL_ports

Regular updates:

Update Squid

docker pull ubuntu/squid:latest

Update AWF

npm update -g gh-aw-firewall

🔗 Related Skills

• gh-aw-safe-outputs - Controlled write operations

• gh-aw-mcp-gateway - MCP server routing

• gh-aw-security-architecture - Overall security model

• gh-aw-containerization - Docker patterns

• gh-aw-authentication-credentials - Credential management

📚 References

• AWF Repository

• Quickstart Guide

• Chroot Mode

• API Proxy Sidecar

• GitHub Actions Integration

• Squid Documentation

✅ Remember

• ✅ AWF provides L7 domain whitelisting

• ✅ iptables enforces rules at host level

• ✅ Three modes: Standard, Chroot, API Proxy

• ✅ Use API proxy for credential isolation

• ✅ SSL Bump enables HTTPS inspection

• ✅ Monitor logs for security events

• ✅ Test firewall rules before production

• ✅ Principle of least privilege (minimal domains)

• ✅ Regular security updates

• ✅ Works transparently with containers

Version: 1.0.0

Last Updated: 2026-02-17

Maintained by: Hack23 AB