squid-ssl-bumping-lab/README.md

Squid SSL Bumping Lab

This project demonstrates how to deploy a Squid proxy that performs SSL bumping (man‐in‐the‐middle) to inspect HTTPS traffic, and how to collect and export its logs with Fluent Bit (OTLP) or read them locally. It’s packaged with Docker and Docker Compose for easy lab deployment.

---

Features

• SSL Bumping
  Intercept and decrypt HTTPS traffic using a custom CA certificate.
• Logging
  • Export logs in real time to an OpenTelemetry/HTTP endpoint (e.g. SigNoz).
  • Or retain logs locally in plain text files.
• Reproducible
  Dockerfile + docker-compose.yml spin up everything (Squid, Fluent Bit).

---

Repository Layout

squid-ssl-bumping-lab/
├── ssl/                       # Your custom CA cert + key (ignored by Git)
│   ├── squid-ca-cert.pem
│   └── squid-ca-key.pem
├── data/                      # Runtime data (ignored by Git)
│   ├── fluent-bit-db/         # Fluent Bit position database
│   ├── squid-cache/           # Squid cache directory
│   └── squid-logs/            # Squid logs (access.log, cache.log)
├── fluent-bit/
│   └── conf/
│       ├── fluent-bit.conf    # Fluent Bit main configuration
│       ├── parsers.conf       # Log parsing rules for Squid
│       └── transform.lua      # Lua filter to reshape records
├── squid.conf                 # Squid configuration (SSL bump, logformat)
├── init-ssl.sh                # Initialize Squid SSL DB on startup
├── entrypoint.sh              # Container entrypoint (dirs, permissions, init)
├── Dockerfile                 # Build Squid with SSL bump support
├── docker-compose.yml         # Compose for Squid + optional Fluent Bit
└── .gitignore                 # data/ and ssl/ are not committed

---

Prerequisites

• Docker >= 20.x
• Docker Compose >= 2.x
• A custom CA certificate (.pem) and private key in ssl/

---

Initial Setup

1. Clone the repo

   git clone <repo-url> squid-ssl-bumping-lab && cd squid-ssl-bumping-lab
   

2. Generate or copy your CA into the ssl/ directory:
   • ssl/squid-ca-cert.pem
   • ssl/squid-ca-key.pem
3. Create runtime directories (they are in .gitignore):

   mkdir -p data/squid-cache data/squid-logs data/fluent-bit-db
   

---

Deployment

1. With Log Export (Fluent Bit → OTLP)

This will start both Squid and Fluent Bit and forward each request to your OTLP endpoint.

docker-compose --profile logging up --build -d

• squid service listens on port 3128 (host).
• fluent-bit reads /var/log/squid/access.log, transforms and ships to OTLP at port 4318.

2. Without Log Export

Run only the Squid proxy and keep logs locally:

docker-compose up --build -d

Under the hood, docker-compose will skip the fluent-bit service because it’s attached to the logging profile.

---

Reading Logs Locally

If you did not enable Fluent Bit, Squid will write logs into:

• data/squid-logs/access.log
• data/squid-logs/cache.log

To tail the access log:

tail -f data/squid-logs/access.log

Or, inside the container:

docker-compose exec squid tail -f /var/log/squid/access.log

Use your favorite tools (less, grep, awk) to analyze stored logs.

---

SSL Bump & Certificates

1. The entrypoint script runs init-ssl.sh to build a Squid SSL DB under /var/cache/squid/ssl_db.
2. Squid’s squid.conf points at your ssl/squid-ca-cert.pem and ssl/squid-ca-key.pem.
3. Clients must trust your CA (import the squid-ca-cert.pem into their browser/system).

---

Cleanup

To stop and remove containers, networks, volumes:

docker-compose down
rm -rf data/*

---

License & Credits

This lab is provided “as is” for educational purposes. Feel free to adapt it to your security-lab environment!