Initial commit

README.md

@@ -0,0 +1,138 @@
+# 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
+
+```text
+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**  
+   ```bash
+   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`):  
+   ```bash
+   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.
+
+```bash
+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:
+
+```bash
+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:
+
+```bash
+tail -f data/squid-logs/access.log
+```
+
+Or, inside the container:
+
+```bash
+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:
+
+```bash
+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!