feat: add SSL Bump support for HTTPS content inspection (#131)

* Initial plan

* feat: add SSL Bump support for HTTPS content inspection

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* docs: add SSL Bump documentation

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* refactor: remove unused generateSslBumpConfig function

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* fix: address SSL Bump issues and improve documentation

Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>

* fix: resolve SSL Bump initialization and config ordering issues

- Fix SSL database initialization: security_file_certgen requires the
  directory to NOT exist, but Docker volume mounts create it. Now
  initSslDb() creates the complete DB structure (certs/, index.txt,
  size) directly on the host.

- Simplify entrypoint.sh: Since DB is pre-initialized on host, the
  entrypoint only needs to fix permissions for the proxy user.

- Fix Squid config ordering: ACL definitions must appear before
  ssl_bump rules that reference them. Moved ${aclSection} before
  ${sslBumpSection} in the config template.

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: correct URL pattern filtering for SSL Bump mode

Two issues fixed:

1. URL pattern deny rule was blocking CONNECT requests:
   - The deny rule `http_access deny allowed_domains` was evaluated
     for CONNECT requests, blocking SSL bump before the URL check
   - Added `!CONNECT` to only deny actual HTTP requests after bump
   - CONNECT requests now pass through for domain-allowed hosts

2. URL pattern regex escaping was corrupting .* wildcards:
   - Input `https://api.github.com/users/.*` was becoming
     `^https://api\.github\.com/users/\..*` (incorrect)
   - Now preserves .* patterns using placeholder before escaping
   - Output is correctly `^https://api\.github\.com/users/.*`

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

* fix: address SSL Bump security review findings

Security improvements based on review feedback:

1. URL Pattern Validation (cli.ts):
   - Reject patterns not starting with https://
   - Block overly broad patterns like https://* or .*
   - Require path component in URL patterns
   - Add helpful error messages guiding users to correct usage

2. Container Hardening (docker-manager.ts):
   - Drop unnecessary capabilities from Squid container:
     NET_RAW, SYS_ADMIN, SYS_PTRACE, SYS_MODULE, MKNOD,
     AUDIT_WRITE, SETFCAP
   - Reduces attack surface if Squid process is compromised

3. Enhanced Security Documentation (docs/ssl-bump.md):
   - Added prominent security warnings about threat model change
   - Documented when NOT to use SSL Bump:
     - Multi-tenant environments
     - Untrusted workloads
     - Multi-user systems
   - Detailed CA private key exposure risks
   - Listed all implemented mitigations

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>

---------

Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>
Co-authored-by: Mossaka <5447827+Mossaka@users.noreply.github.com>
Co-authored-by: Jiaxiao (mossaka) Zhou <duibao55328@gmail.com>
Co-authored-by: Claude Opus 4.5 <noreply@anthropic.com>

Author: 3 people

README.md

@@ -114,6 +114,7 @@ sudo awf --help
 
 - [Quick start](docs/quickstart.md) — install, verify, and run your first command
 - [Usage guide](docs/usage.md) — CLI flags, domain allowlists, Docker-in-Docker examples
+- [SSL Bump](docs/ssl-bump.md) — HTTPS content inspection for URL path filtering
 - [Logging quick reference](docs/logging_quickref.md) and [Squid log filtering](docs/squid_log_filtering.md) — view and filter traffic
 - [Security model](docs/security.md) — what the firewall protects and how
 - [Architecture](docs/architecture.md) — how Squid, Docker, and iptables fit together

containers/agent/entrypoint.sh

@@ -98,6 +98,19 @@ if [ -f /etc/resolv.conf ]; then
   echo "[entrypoint] DNS configured with Docker embedded DNS (127.0.0.11) and trusted servers: $DNS_SERVERS"
 fi
 
+# Update CA certificates if SSL Bump is enabled
+# The CA certificate is mounted at /usr/local/share/ca-certificates/awf-ca.crt
+if [ "${AWF_SSL_BUMP_ENABLED}" = "true" ]; then
+  echo "[entrypoint] SSL Bump mode detected - updating CA certificates..."
+  if [ -f /usr/local/share/ca-certificates/awf-ca.crt ]; then
+    update-ca-certificates 2>/dev/null
+    echo "[entrypoint] CA certificates updated for SSL Bump"
+    echo "[entrypoint] ⚠️  WARNING: HTTPS traffic will be intercepted for URL inspection"
+  else
+    echo "[entrypoint][WARN] SSL Bump enabled but CA certificate not found"
+  fi
+fi
+
 # Setup Docker socket permissions if Docker socket is mounted
 # This allows MCP servers that run as Docker containers to work
 # Store DOCKER_GID once to avoid redundant stat calls

containers/squid/Dockerfile

@@ -1,24 +1,27 @@
 FROM ubuntu/squid:latest
 
-# Install additional tools for debugging and healthcheck
+# Install additional tools for debugging, healthcheck, and SSL Bump
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
     curl \
     dnsutils \
     net-tools \
-    netcat-openbsd && \
+    netcat-openbsd \
+    openssl \
+    squid-openssl && \
     rm -rf /var/lib/apt/lists/*
 
-# Create log directory
+# Create log directory and SSL database directory
 RUN mkdir -p /var/log/squid && \
     chown -R proxy:proxy /var/log/squid
 
 # Copy entrypoint script
 COPY entrypoint.sh /usr/local/bin/entrypoint.sh
 RUN chmod +x /usr/local/bin/entrypoint.sh
 
-# Expose Squid port
+# Expose Squid port (3128 for HTTP, 3129 for HTTPS with SSL Bump)
 EXPOSE 3128
+EXPOSE 3129
 
 # Use entrypoint to fix permissions before starting Squid
 ENTRYPOINT ["/usr/local/bin/entrypoint.sh"]

containers/squid/entrypoint.sh

@@ -6,5 +6,18 @@ set -e
 chown -R proxy:proxy /var/log/squid
 chmod -R 755 /var/log/squid
 
+# Fix permissions on SSL certificate database if SSL Bump is enabled
+# The database is initialized on the host side by awf, but the permissions
+# need to be fixed for the proxy user inside the container.
+if [ -d "/var/spool/squid_ssl_db" ]; then
+  echo "[squid-entrypoint] SSL Bump mode detected - fixing SSL database permissions..."
+
+  # Fix ownership for Squid (runs as proxy user)
+  chown -R proxy:proxy /var/spool/squid_ssl_db
+  chmod -R 700 /var/spool/squid_ssl_db
+
+  echo "[squid-entrypoint] SSL certificate database ready"
+fi
+
 # Start Squid
 exec squid -N -d 1

docs-site/src/content/docs/index.md

@@ -15,6 +15,7 @@ When AI agents like GitHub Copilot CLI run with access to tools and MCP servers,
 
 **Key Capabilities:**
 - **Domain Allowlist & Blocklist**: Allow specific domains and block exceptions with wildcard pattern support
+- **URL Path Filtering**: Restrict access to specific URL paths with [SSL Bump](/gh-aw-firewall/reference/ssl-bump/)
 - **Docker-in-Docker Enforcement**: Spawned containers inherit firewall restrictions
 - **Host-Level Protection**: Uses iptables DOCKER-USER chain for defense-in-depth
 - **Zero Trust**: Block all traffic by default, allow only what you explicitly permit

docs-site/src/content/docs/reference/cli-reference.md

@@ -23,6 +23,8 @@ awf [options] -- <command>
 | `--allow-domains-file <path>` | string | — | Path to file containing allowed domains |
 | `--block-domains <domains>` | string | — | Comma-separated list of blocked domains (takes precedence over allowed) |
 | `--block-domains-file <path>` | string | — | Path to file containing blocked domains |
+| `--ssl-bump` | flag | `false` | Enable SSL Bump for HTTPS content inspection |
+| `--allow-urls <urls>` | string | — | Comma-separated list of allowed URL patterns (requires `--ssl-bump`) |
 | `--log-level <level>` | string | `info` | Logging verbosity: `debug`, `info`, `warn`, `error` |
 | `--keep-containers` | flag | `false` | Keep containers running after command exits |
 | `--tty` | flag | `false` | Allocate pseudo-TTY for interactive tools |
@@ -98,6 +100,47 @@ Path to file with blocked domains. Supports the same format as `--allow-domains-
 --block-domains-file ./blocked-domains.txt
 ```
 
+### `--ssl-bump`
+
+Enable SSL Bump for HTTPS content inspection. When enabled, the firewall generates a per-session CA certificate and intercepts HTTPS connections, allowing URL path filtering.
+
+```bash
+--ssl-bump --allow-urls "https://github.com/githubnext/*"
+```
+
+:::caution[HTTPS Interception]
+SSL Bump decrypts HTTPS traffic at the proxy. The proxy can see full URLs, headers, and request bodies. Applications with certificate pinning will fail to connect.
+:::
+
+**How it works:**
+1. A unique CA certificate is generated (valid for 1 day)
+2. The CA is injected into the agent container's trust store
+3. Squid intercepts HTTPS using SSL Bump (peek, stare, bump)
+4. Full URLs become visible for filtering via `--allow-urls`
+
+**See also:** [SSL Bump Reference](/gh-aw-firewall/reference/ssl-bump/) for complete documentation.
+
+### `--allow-urls <urls>`
+
+Comma-separated list of allowed URL patterns for HTTPS traffic. Requires `--ssl-bump`.
+
+```bash
+# Single pattern
+--allow-urls "https://github.com/githubnext/*"
+
+# Multiple patterns
+--allow-urls "https://github.com/org1/*,https://api.github.com/repos/*"
+```
+
+**Pattern syntax:**
+- Must include scheme (`https://`)
+- `*` matches any characters in a path segment
+- Patterns are matched against the full request URL
+
+:::note
+Without `--ssl-bump`, the firewall can only see domain names (via SNI). Enable `--ssl-bump` to filter by URL path.
+:::
+
 ### `--log-level <level>`
 
 Set logging verbosity.
@@ -397,4 +440,8 @@ awf logs summary --format pretty
 ## See Also
 
 - [Domain Filtering Guide](/gh-aw-firewall/guides/domain-filtering) - Allowlists, blocklists, and wildcards
+- [SSL Bump Reference](/gh-aw-firewall/reference/ssl-bump/) - HTTPS content inspection and URL filtering
+- [Quick Start Guide](/gh-aw-firewall/quickstart) - Getting started with examples
+- [Usage Guide](/gh-aw-firewall/usage) - Detailed usage patterns and examples
+- [Troubleshooting](/gh-aw-firewall/troubleshooting) - Common issues and solutions
 - [Security Architecture](/gh-aw-firewall/reference/security-architecture) - How the firewall works internally

docs-site/src/content/docs/reference/security-architecture.md

@@ -186,6 +186,63 @@ We considered isolating the agent in a network namespace with zero external conn
 
 mitmproxy would let us inspect HTTPS payloads, potentially catching exfiltration in POST bodies. But it requires injecting a CA certificate and breaks certificate pinning (common in security-sensitive clients). Squid's CONNECT method reads SNI without decryption—less powerful but zero client-side changes, and we maintain end-to-end encryption.
 
+:::tip[SSL Bump for URL Filtering]
+When you need URL path filtering (not just domain filtering), enable `--ssl-bump`. This uses Squid's SSL Bump feature with a per-session CA certificate, providing full URL visibility while maintaining security through short-lived, session-specific certificates.
+:::
+
+---
+
+## SSL Bump Security Model
+
+When `--ssl-bump` is enabled, the firewall intercepts HTTPS traffic for URL path filtering. This changes the security model significantly.
+
+### How SSL Bump Works
+
+1. **CA Generation**: A unique CA key pair is generated at session start
+2. **Trust Store Injection**: The CA certificate is added to the agent container's trust store
+3. **TLS Interception**: Squid terminates TLS and re-establishes encrypted connections to destinations
+4. **URL Filtering**: Full request URLs (including paths) become visible for ACL matching
+
+### Security Safeguards
+
+| Safeguard | Description |
+|-----------|-------------|
+| **Per-session CA** | Each awf execution generates a unique CA certificate |
+| **Short validity** | CA certificate valid for 1 day maximum |
+| **Ephemeral key storage** | CA private key exists only in temp directory, deleted on cleanup |
+| **Container-only trust** | CA injected only into agent container, not host system |
+
+### Trade-offs vs. SNI-Only Mode
+
+| Aspect | SNI-Only (Default) | SSL Bump |
+|--------|-------------------|----------|
+| Filtering granularity | Domain only | Full URL path |
+| End-to-end encryption | ✓ Preserved | Modified (proxy-terminated) |
+| Certificate pinning | Works | Broken |
+| Proxy visibility | Domain:port | Full request (URL, headers) |
+| Performance | Faster | Slight overhead |
+
+:::caution[When to Use SSL Bump]
+Only enable SSL Bump when you specifically need URL path filtering. For most use cases, domain-based filtering provides sufficient control with stronger encryption guarantees.
+:::
+
+### SSL Bump Threat Considerations
+
+**What SSL Bump enables:**
+- Fine-grained access control (e.g., allow only `/githubnext/*` paths)
+- Better audit logging with full URLs
+- Detection of path-based exfiltration attempts
+
+**What SSL Bump exposes:**
+- Full HTTP request/response content visible to proxy
+- Applications with certificate pinning will fail
+- Slightly increased attack surface (CA key compromise)
+
+**Mitigations:**
+- CA key never leaves the temporary work directory
+- Session isolation: each execution uses a fresh CA
+- Automatic cleanup removes all key material
+
 ---
 
 ## Failure Modes