From 4c0cc90734d8551facb7f74a11e8b88ebef44740 Mon Sep 17 00:00:00 2001
From: duffyduck <info@hacker-net.de>
Date: Sat, 16 May 2026 13:33:54 +0200
Subject: [PATCH] =?UTF-8?q?docs:=20README=20=E2=80=93=20BREACH-Schutz=20vi?=
 =?UTF-8?q?a=20gzip=20off=20f=C3=BCr=20/api/*=20am=20Reverse-Proxy?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

Pentest mit testssl markiert die Prod-Instanz wegen aktivierter gzip-
Komprimierung als BREACH-anfällig (CVE-2013-3587, "Ausnutzbar: Ja").
Die JWT-SPA-Architektur hält das Risiko praktisch klein, der Audit-
Marker bleibt aber medium.

README-Sektion „Production-Deployment" um expliziten Hinweis ergänzt:
gzip nur für statische Assets erlauben, für /api/* deaktivieren. Mit
Setup-Schritten für Nginx Proxy Manager (Custom Locations) und Plain
Nginx + Verifikationsbefehl.

Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com>
---
 README.md | 44 ++++++++++++++++++++++++++++++++++++++++++++
 1 file changed, 44 insertions(+)

diff --git a/README.md b/README.md
index eb7e2919..fcc084b9 100644
--- a/README.md
+++ b/README.md
@@ -215,6 +215,50 @@ Plus:
 - Vollständige Hardening-Story + restliche Trade-offs:
   [docs/SECURITY-HARDENING.md](docs/SECURITY-HARDENING.md)
 
+### ⚠️ Wichtig: gzip für `/api/*` am Reverse-Proxy deaktivieren (BREACH-Schutz)
+
+Wenn ein TLS-Reverse-Proxy (Nginx Proxy Manager, Caddy, eigener Nginx, …) HTTPS
+terminiert und Antworten gzip-komprimiert, ist die **BREACH-Attacke** (CVE-2013-3587)
+theoretisch möglich: aus der gzip-komprimierten Response-Größe könnten unter
+ungünstigen Umständen Secrets erraten werden. Auch wenn unsere JWT-basierte SPA
+das Risiko praktisch klein hält (keine reflektierten Secrets im Response-Body),
+geht ein Penetration-Test mit testssl trotzdem auf „medium – Ausnutzbar: Ja".
+
+**Lösung:** gzip-Komprimierung nur für statische Frontend-Assets erlauben, für
+`/api/*` deaktivieren. Statische Bundles bleiben damit performant ausgeliefert,
+JSON-API-Responses werden ohne Kompression gesendet → BREACH ist dort kein
+Einfallstor mehr.
+
+**Nginx Proxy Manager (NPM):**
+1. Proxy-Hosts → den CRM-Host → **Edit**
+2. Tab **Custom Locations** → **„Add location"**
+3. **Define location:** `/api/`
+4. **Scheme:** `http`, **Forward Hostname/IP:** wie im Haupt-Host
+   (z.B. `172.0.2.39`), **Forward Port:** `3010`
+5. Zahnrad rechts an der Location → erweiterte Config eintragen:
+   ```nginx
+   gzip off;
+   proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+   proxy_set_header X-Real-IP $remote_addr;
+   ```
+6. **Save** (Location), **Save** (Proxy-Host)
+
+**Plain Nginx** (falls eigener Nginx statt NPM):
+```nginx
+location /api/ {
+    gzip off;
+    proxy_pass http://backend:3010;
+    proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
+    proxy_set_header X-Real-IP $remote_addr;
+}
+```
+
+**Verifikation** (sollte leer sein, kein `content-encoding: gzip` mehr):
+```bash
+curl -sI -H 'Accept-Encoding: gzip' https://kundencenter.deine-domain.de/api/health \
+  | grep -i content-encoding
+```
+
 ## Developer-Tools aktivieren
 
 Die Developer-Tools (Datenbankstruktur, ER-Diagramm) sind standardmäßig für Admins verfügbar. Falls der Menüpunkt nicht erscheint: