feat: add https payload interception via ssl bumping

IMPLEMENTATION_SUMMARY.md

@@ -0,0 +1,70 @@
+# HTTPS Payload Interception - Implementation Summary
+
+## Question Investigated
+**Can the Squid proxy container intercept the HTTPS payload as a logging/debugging mechanism?**
+
+## Answer
+**YES** - Implemented as the `--ssl-bump` feature.
+
+## What It Does
+
+Enables man-in-the-middle SSL/TLS interception to decrypt and log HTTPS traffic for debugging purposes.
+
+### Before (Default)
+```
+# Log shows only domain name
+172.30.0.20:39748 api.github.com:443 ... CONNECT 200 TCP_TUNNEL api.github.com:443
+```
+
+### After (With `--ssl-bump`)
+```
+# Log shows full URL and HTTP details
+172.30.0.20:39748 api.github.com ... GET 200 TCP_MISS https://api.github.com/zen
+```
+
+## Usage
+
+```bash
+sudo awf --allow-domains github.com --ssl-bump -- curl -k https://api.github.com/zen
+```
+
+⚠️ **WARNING**: Use only for debugging. Performs active MITM interception of encrypted traffic.
+
+## Implementation
+
+- **CLI Flag**: `--ssl-bump` (disabled by default)
+- **Certificate**: Ephemeral CA certificate auto-generated on startup
+- **Configuration**: Squid ssl_bump directives dynamically generated
+- **Tests**: 11 new test cases, all passing
+- **Documentation**: Comprehensive security warnings and usage guide
+
+## Security Safeguards
+
+1. ✅ Opt-in only (disabled by default)
+2. ✅ Prominent warnings when enabled
+3. ✅ Ephemeral certificates (not persisted)
+4. ✅ Comprehensive security documentation
+5. ✅ Clear "debugging only" guidance
+
+## Files Changed
+
+- `src/types.ts` - Added sslBump configuration option
+- `src/squid-config.ts` - SSL bumping config generation
+- `src/cli.ts` - CLI flag and warnings
+- `containers/squid/Dockerfile` - OpenSSL installation
+- `containers/squid/generate-cert.sh` - Certificate generation script
+- `src/squid-config.test.ts` - 11 new test cases
+- Documentation: README, investigation results, manual testing guide
+
+## Testing
+
+- ✅ 359 automated tests passing (348 existing + 11 new)
+- ✅ Build successful
+- ✅ TypeScript compilation clean
+- 📋 Manual testing guide provided for integration testing
+
+## Recommendation
+
+**Use sparingly and only in controlled debugging environments.**
+
+The feature provides valuable debugging capability while maintaining security through opt-in behavior, clear warnings, and comprehensive documentation of risks.

README.md

@@ -181,6 +181,36 @@ sudo awf \
   -- curl https://api.github.com
 ```
 
+## Advanced Features
+
+### HTTPS Payload Interception (SSL Bumping)
+
+For debugging purposes, awf can intercept and decrypt HTTPS traffic to log full request/response details.
+
+⚠️ **WARNING**: SSL bumping performs man-in-the-middle interception and should **ONLY** be used for debugging.
+
+```bash
+# Enable SSL bumping to see full HTTPS payloads
+sudo awf \
+  --allow-domains github.com \
+  --ssl-bump \
+  -- curl https://api.github.com/zen
+```
+
+**With SSL bumping enabled, you can see:**
+- Complete URLs inside HTTPS requests (not just domain names)
+- HTTP headers (User-Agent, Authorization, etc.)
+- Request/response bodies (requires additional Squid config)
+
+**Security implications:**
+- Generates ephemeral CA certificate
+- Performs active man-in-the-middle interception
+- Breaks certificate pinning
+- May expose sensitive data in logs
+- Should NOT be used in production
+
+See [docs/ssl-bumping-investigation.md](docs/ssl-bumping-investigation.md) for detailed information.
+
 ## Development & Testing
 
 ### Running Tests

containers/squid/Dockerfile

@@ -1,21 +1,27 @@
 FROM ubuntu/squid:latest
 
-# Install additional tools for debugging and healthcheck
+# Install additional tools for debugging, healthcheck, and SSL certificate generation
 RUN apt-get update && \
     apt-get install -y --no-install-recommends \
     curl \
     dnsutils \
     net-tools \
-    netcat-openbsd && \
+    netcat-openbsd \
+    openssl && \
     rm -rf /var/lib/apt/lists/*
 
 # Create log directory
 RUN mkdir -p /var/log/squid && \
     chown -R proxy:proxy /var/log/squid
 
-# Copy entrypoint script
+# Create SSL certificate directory
+RUN mkdir -p /etc/squid/ssl_cert && \
+    chown -R proxy:proxy /etc/squid/ssl_cert
+
+# Copy scripts
+COPY generate-cert.sh /usr/local/bin/generate-cert.sh
 COPY entrypoint.sh /usr/local/bin/entrypoint.sh
-RUN chmod +x /usr/local/bin/entrypoint.sh
+RUN chmod +x /usr/local/bin/generate-cert.sh /usr/local/bin/entrypoint.sh
 
 # Expose Squid port
 EXPOSE 3128

containers/squid/entrypoint.sh

@@ -6,5 +6,11 @@ set -e
 chown -R proxy:proxy /var/log/squid
 chmod -R 755 /var/log/squid
 
+# Check if SSL bumping is enabled by looking for ssl_bump directive in config
+if grep -q "ssl_bump" /etc/squid/squid.conf 2>/dev/null; then
+    echo "SSL bumping enabled - generating certificate..."
+    /usr/local/bin/generate-cert.sh
+fi
+
 # Start Squid
 exec squid -N -d 1

containers/squid/generate-cert.sh

@@ -0,0 +1,43 @@
+#!/bin/bash
+# Script to generate ephemeral CA certificate for Squid SSL bumping
+# This certificate is used for man-in-the-middle interception of HTTPS traffic
+# for debugging/investigation purposes only.
+
+set -e
+
+CERT_DIR="/etc/squid/ssl_cert"
+CERT_FILE="$CERT_DIR/squid.pem"
+DB_DIR="/var/lib/squid/ssl_db"
+
+# Create directories if they don't exist
+mkdir -p "$CERT_DIR"
+mkdir -p "$DB_DIR"
+
+# Check if certificate already exists
+if [ -f "$CERT_FILE" ]; then
+    echo "SSL certificate already exists at $CERT_FILE"
+    exit 0
+fi
+
+echo "Generating ephemeral CA certificate for SSL bumping..."
+
+# Generate private key and self-signed certificate
+# Valid for 365 days, 2048-bit RSA key
+openssl req -new -newkey rsa:2048 -sha256 -days 365 -nodes -x509 \
+    -keyout "$CERT_FILE" \
+    -out "$CERT_FILE" \
+    -subj "/C=US/ST=State/L=City/O=AWF/OU=Proxy/CN=AWF Squid Proxy CA"
+
+# Set proper permissions
+chmod 600 "$CERT_FILE"
+chown proxy:proxy "$CERT_FILE"
+chown -R proxy:proxy "$CERT_DIR"
+
+echo "Certificate generated successfully at $CERT_FILE"
+
+# Initialize SSL database for certificate caching
+echo "Initializing SSL certificate database..."
+/usr/lib/squid/security_file_certgen -c -s "$DB_DIR" -M 4MB
+chown -R proxy:proxy "$DB_DIR"
+
+echo "SSL bumping setup complete"