diff --git a/.env.example b/.env.example index d39c2da..898dd7b 100644 --- a/.env.example +++ b/.env.example @@ -1 +1,8 @@ +# Host-Port fuer HTTP (Reverse Proxy -> Container Port 80) HTTP_PORT=8080 + +# Host-Port fuer HTTPS, wird erst ab Challenge 10 genutzt (-> Container Port 443). +# Hinweis: Nginx liest in der statischen Config keine Env-Variablen. Wenn du diesen +# Wert aenderst, musst du den Redirect-Zielport in proxy/nginx.conf +# (z. B. "return 301 https://$host:8443$request_uri;") manuell angleichen. +HTTPS_PORT=8443 diff --git a/README.md b/README.md index 21b6c9b..532eea5 100644 --- a/README.md +++ b/README.md @@ -122,6 +122,8 @@ curl http://localhost:8080/service/a curl http://localhost:8080/service/b ``` +> **Windows:** Diese und alle weiteren Test-Kommandos (`curl`, `openssl`, `grep`, Schleifen) im **WSL-Terminal (bash)** ausfuehren, nicht in PowerShell. In PowerShell ist `curl` ein Alias fuer `Invoke-WebRequest` und versteht die genutzten Flags (`-I`, `-k`, `--cacert`) nicht. PowerShell nur fuer den Stack-Wrapper `scripts/workshop.ps1`. + ## Fokus im Workshop Die Basis ist bewusst nur HTTP. HTTPS ist Teil der Aufgaben: diff --git a/backends/a/index.html b/backends/a/index.html index 978fd5c..85c42ed 100644 --- a/backends/a/index.html +++ b/backends/a/index.html @@ -64,6 +64,7 @@ +
Backend A

Reverse Proxy Target A

diff --git a/backends/a2/index.html b/backends/a2/index.html index 7387421..9b1dc50 100644 --- a/backends/a2/index.html +++ b/backends/a2/index.html @@ -39,6 +39,7 @@ +

Reverse Proxy Target A2

Use this page to validate load balancing between backend-a and backend-a2.

diff --git a/challenges/README.md b/challenges/README.md index f54bf4c..83111f2 100644 --- a/challenges/README.md +++ b/challenges/README.md @@ -8,13 +8,29 @@ Diese Aufgaben sind bewusst auf **manuelle Proxy-Konfiguration** ausgelegt. - Done-Check Command live ausfuehren - 2-3 Saetze erklaeren: was geaendert, warum, welche Wirkung +## Wo laufen die Kommandos? (besonders Windows) + +Die meisten Teilnehmer arbeiten unter **Windows mit Docker Desktop + WSL**. Wichtig: + +- **Stack steuern** (`make ...` oder der PowerShell-Wrapper `scripts/workshop.ps1`): geht aus PowerShell **oder** aus dem WSL-Terminal. +- **Alle Challenge-Kommandos** (`curl`, `openssl`, `grep`, `wget`, `for`-Schleifen, `./scripts/compose.sh ...`): laufen im **WSL-Terminal (bash)**, nicht in PowerShell. +- **Warnung:** In PowerShell ist `curl` ein Alias fuer `Invoke-WebRequest` und versteht die hier genutzten Flags (`-I`, `-k`, `--cacert`) **nicht**. Immer im WSL-Terminal testen. +- Das Repo liegt im WSL-Dateisystem oder unter `/mnt/c/...`; arbeite am besten aus dem WSL-Terminal im Projektordner. + ## Arbeitsmodus 1. Dateien anpassen (`proxy/nginx.conf`, `docker-compose.yml`). -2. Deployen mit `make redeploy` oder `make proxy-reload`. +2. Deployen: nach reinen `nginx.conf`-Aenderungen reicht `make proxy-reload`; nach Aenderungen an `docker-compose.yml` (z. B. neue Ports oder Services) immer `make redeploy`, da der Container neu erstellt werden muss. 3. Testen mit `curl` / `openssl` / Wireshark. 4. Bei Problemen: `./scripts/compose.sh logs reverse-proxy`. +## Arbeitsweise (wichtig) + +- Es wird **additiv in einer einzigen `proxy/nginx.conf`** gearbeitet: jede Challenge erweitert den Stand der vorherigen. Loesungen nicht wieder loeschen - die TLS-Challenges (10-12) bauen direkt aufeinander auf. +- **Ausnahme Challenge 9** (Debugging): Diese ueberschreibt die `nginx.conf` bewusst. Vorher sichern (`cp proxy/nginx.conf proxy/nginx.conf.bak`), danach wiederherstellen. +- Jede Angabe nennt einen **Ausgangszustand** (worauf baue ich auf) und einen **Zielzustand / Akzeptanz** (woran erkenne ich "fertig"). Der Done-Check ist die pruefbare Form des Zielzustands. +- Komplett zuruecksetzen geht jederzeit mit `make reset` (Container/Volumes) bzw. `make reset-hard` (zusaetzlich lokale Datei-Aenderungen verwerfen). + --- ## Easy @@ -24,45 +40,59 @@ Diese Aufgaben sind bewusst auf **manuelle Proxy-Konfiguration** ausgelegt. **Ziel** - Verstehen, wie Nginx Requests per Pfad an unterschiedliche Upstreams schickt. -**Muss** +**Datei** +- `proxy/nginx.conf` (nur lesen) + +**Schritte (Muss)** - Vor dem Test in `proxy/nginx.conf` nachsehen, welche `location` auf welchen `upstream` zeigt. - Dann erst Requests ausfuehren. - In eigenen Worten erklaeren, warum die Antworten unterschiedlich sind. -**Warum wichtig** -- Das ist die Kernkompetenz bei Reverse Proxys: Request-Fluss lesen und korrekt begruenden. +**Zielzustand / Akzeptanz** +- Du kannst fuer `/service/a` und `/service/b` jeweils Location -> Upstream -> Backend benennen und begruenden, warum die Antworten unterschiedlich sind. **Done-Check** ```bash -curl http://localhost:8080/service/a -curl http://localhost:8080/service/b +curl http://localhost:8080/service/a # -> "Reverse Proxy Target A" +curl http://localhost:8080/service/b # -> "Reverse Proxy Target B" ``` +**Warum wichtig** +- Das ist die Kernkompetenz bei Reverse Proxys: Request-Fluss lesen und korrekt begruenden. + ### 2) Drittes Backend manuell hinzufuegen **Ziel** - Setup sicher erweitern, ohne bestehende Routen kaputt zu machen. +**Ausgangszustand** +- Stack laeuft, `/service/a` und `/service/b` antworten. +- `backends/c/index.html` liegt bereits im Repo (Starterseite). + **Dateien** - `docker-compose.yml` - `proxy/nginx.conf` - `backends/c/index.html` (vorhanden, darf angepasst werden) -**Muss** +**Schritte (Muss)** - Service `backend-c` in Compose einbauen. - Upstream + Route `/service/c` in Nginx anlegen. -- A/B muessen weiterhin funktionieren. +- Deployen mit `make redeploy` (Compose-Aenderung -> Container-Neustart noetig). -**Warum wichtig** -- In realen Umgebungen kommen neue Services laufend dazu. Saubere Erweiterung ohne Regression ist entscheidend. +**Zielzustand / Akzeptanz** +- `/service/c` liefert Backend C. +- `/service/a` und `/service/b` funktionieren unveraendert weiter (keine Regression). **Done-Check** ```bash -curl http://localhost:8080/service/c -curl http://localhost:8080/service/a -curl http://localhost:8080/service/b +curl http://localhost:8080/service/c # -> enthaelt "Reverse Proxy Target C" +curl http://localhost:8080/service/a # -> weiterhin "Reverse Proxy Target A" +curl http://localhost:8080/service/b # -> weiterhin "Reverse Proxy Target B" ``` +**Warum wichtig** +- In realen Umgebungen kommen neue Services laufend dazu. Saubere Erweiterung ohne Regression ist entscheidend. + ### 3) Eigene Route mit Rewrite oder Alias-Route **Ziel** @@ -71,18 +101,22 @@ curl http://localhost:8080/service/b **Datei** - `proxy/nginx.conf` -**Muss** +**Schritte (Muss)** - Route `/demo/a` anbieten, die auf Backend A fuehrt. - Entweder per rewrite oder per eigener proxy-Route loesen. +- Deployen mit `make proxy-reload`. -**Warum wichtig** -- Der Proxy entkoppelt externe API-Pfade von internen Service-Pfaden und ermoeglicht saubere Migrationen. +**Zielzustand / Akzeptanz** +- `/demo/a` liefert dieselbe Antwort wie `/service/a` (Backend A), obwohl der externe Pfad ein anderer ist. **Done-Check** ```bash -curl http://localhost:8080/demo/a +curl http://localhost:8080/demo/a # -> "Reverse Proxy Target A" ``` +**Warum wichtig** +- Der Proxy entkoppelt externe API-Pfade von internen Service-Pfaden und ermoeglicht saubere Migrationen. + --- ## Medium @@ -95,7 +129,7 @@ curl http://localhost:8080/demo/a **Datei** - `proxy/nginx.conf` -**Muss** +**Schritte (Muss)** - Mindestens setzen: - `X-Content-Type-Options: nosniff` - `X-Frame-Options: DENY` @@ -104,15 +138,24 @@ curl http://localhost:8080/demo/a - `Cross-Origin-Opener-Policy: same-origin` - `Cross-Origin-Resource-Policy: same-origin` - Optional (Bonus): `Content-Security-Policy` fuer statische Seiten (mit Inline-Styles bewusst beruecksichtigen) +- Deployen mit `make proxy-reload`. -**Warum wichtig** -- Diese Header reduzieren typische Browser-Angriffsvektoren und gehoeren zu Security-Baselines. +**Fallstrick (`add_header`-Vererbung)** +- Header am besten **einmal im `server {}`-Block** setzen, dann gelten sie fuer alle Locations. +- Achtung: Sobald in einem `location {}`-Block **ein** `add_header` steht, verwirft Nginx in dieser Location **alle** `add_header` aus dem `server`-Block. Dann muessen sie dort wiederholt werden. Pruefen mit `curl -I` direkt auf der jeweiligen Route. + +**Zielzustand / Akzeptanz** +- `curl -I http://localhost:8080/` zeigt alle geforderten Security-Header in der Antwort. **Done-Check** ```bash curl -I http://localhost:8080/ +# -> zeigt X-Content-Type-Options, X-Frame-Options, Referrer-Policy, Permissions-Policy, COOP, CORP ``` +**Warum wichtig** +- Diese Header reduzieren typische Browser-Angriffsvektoren und gehoeren zu Security-Baselines. + ### 5) Interne Route absichern **Ziel** @@ -121,25 +164,29 @@ curl -I http://localhost:8080/ **Datei** - `proxy/nginx.conf` -**Muss** +**Schritte (Muss)** - Route `/internal/status` bauen. - Nur `127.0.0.1` erlauben, alle anderen verbieten. - -**Warum wichtig** -- Nicht jeder Endpoint soll oeffentlich sein; Zugriffskontrolle direkt am Proxy ist oft die erste Schutzschicht. +- Deployen mit `make proxy-reload`. **Wichtiger Hinweis** - Host-Request ueber `localhost:8080` kommt aus Docker-Sicht oft **nicht** von `127.0.0.1`. +**Zielzustand / Akzeptanz** +- Aufruf vom Host liefert `403`; Aufruf von innerhalb des Proxy-Containers (`127.0.0.1`) liefert die Antwort. + **Done-Check** ```bash -# Erwartet typischerweise 403 vom Host (by design) curl -i http://localhost:8080/internal/status +# -> Erwartet typischerweise 403 vom Host (by design) -# Muss innerhalb des Proxy-Containers funktionieren ./scripts/compose.sh exec -T reverse-proxy sh -lc "wget -qO- http://127.0.0.1/internal/status" +# -> "internal ok" (funktioniert nur container-intern) ``` +**Warum wichtig** +- Nicht jeder Endpoint soll oeffentlich sein; Zugriffskontrolle direkt am Proxy ist oft die erste Schutzschicht. + ### 6) Logging verbessern **Ziel** @@ -148,19 +195,27 @@ curl -i http://localhost:8080/internal/status **Datei** - `proxy/nginx.conf` -**Muss** +**Schritte (Muss)** - Eigenes `log_format` mit Upstream-Infos anlegen. - Access-Log auf das neue Format umstellen. +- Deployen mit `make proxy-reload`. -**Warum wichtig** -- Gute Logs verkuerzen Incident- und Debug-Zeit drastisch und sind zentral fuer Betrieb/Security. +**Hinweis** +- `log_format` gehoert in den `http {}`-Block (nicht in `server {}` oder `location {}`), sonst startet Nginx mit `"log_format" directive is not allowed here` nicht. `access_log` darf in `http`, `server` oder `location` stehen. + +**Zielzustand / Akzeptanz** +- Nach einem Request erscheint im Log eine Zeile im neuen Format inklusive Upstream-Infos (`upstream=...`, `urt=...`). **Done-Check** ```bash curl http://localhost:8080/service/a ./scripts/compose.sh logs reverse-proxy +# -> neue Log-Zeile mit upstream=... und urt=... ``` +**Warum wichtig** +- Gute Logs verkuerzen Incident- und Debug-Zeit drastisch und sind zentral fuer Betrieb/Security. + ### 7) Load Balancing konfigurieren **Ziel** @@ -170,20 +225,29 @@ curl http://localhost:8080/service/a - `docker-compose.yml` - `proxy/nginx.conf` -**Muss** +**Ausgangszustand** +- `/service/a` zeigt aktuell nur eine Instanz (Backend A). `backends/a2/index.html` liegt bereits im Repo. + +**Schritte (Muss)** - Zweite Instanz von Backend A (`backend-a2`) anlegen. - `upstream backend_a` auf beide Instanzen erweitern. - Mehrfach-Requests zeigen, dass beide Instanzen antworten. +- Deployen mit `make redeploy` (Compose-Aenderung). -**Warum wichtig** -- Lastverteilung ist eine der wichtigsten Funktionen eines Reverse Proxys fuer Skalierung und Verfuegbarkeit. +**Zielzustand / Akzeptanz** +- Bei mehreren Aufrufen von `/service/a` antworten **beide** Instanzen (Round-Robin), also sowohl `Target A` als auch `Target A2`. **Done-Check (Beispiel)** ```bash for i in $(seq 1 8); do - curl -s http://localhost:8080/service/a | grep -o "Target A2\|Target A" + curl -s http://localhost:8080/service/a | grep -o "INSTANCE=[A-Za-z0-9]*" done +# -> Mischung aus "INSTANCE=A" und "INSTANCE=A2" ueber die 8 Requests ``` +- Der unsichtbare Marker `` bzw. `INSTANCE=A2` steckt im HTML der Backends. `[A-Za-z0-9]*` matched das ganze Token eindeutig (kein Prefix-Problem wie bei `A` vs. `A2`). + +**Warum wichtig** +- Lastverteilung ist eine der wichtigsten Funktionen eines Reverse Proxys fuer Skalierung und Verfuegbarkeit. ### 8) Response Header Minimization @@ -193,51 +257,64 @@ done **Datei** - `proxy/nginx.conf` -**Muss** +**Schritte (Muss)** - Mit `proxy_hide_header` mindestens einen durchgereichten Backend-Header ausblenden (z. B. `ETag`, `Last-Modified`). - Kurz erklaeren, warum weniger Fingerprinting-Infos hilfreich sind. +- Deployen mit `make proxy-reload`. **Abgrenzung zu Challenge 4** - Challenge 4 setzt aktive Schutz-Header. - Challenge 8 entfernt unnoetige Header aus Upstream-Responses. -**Warum wichtig** -- Weniger Response-Metadaten bedeuten weniger Angriffsoberflaeche fuer Fingerprinting und Reconnaissance. +**Zielzustand / Akzeptanz** +- Der gewaehlte Header (z. B. `ETag`) taucht in `curl -I http://localhost:8080/service/a` **nicht mehr** auf, vorher war er sichtbar. **Done-Check** ```bash curl -I http://localhost:8080/service/a +# -> der ausgeblendete Header (z. B. ETag) fehlt jetzt in der Antwort ``` +**Warum wichtig** +- Weniger Response-Metadaten bedeuten weniger Angriffsoberflaeche fuer Fingerprinting und Reconnaissance. + ### 9) Debugging Challenge (kaputte Config reparieren) **Ziel** - Fehlerdiagnose in Nginx ueben. +**Ausgangszustand** +- Eigene `proxy/nginx.conf` ist in Betrieb. `proxy/nginx.broken.conf` enthaelt absichtlich mehrere Fehler. + **Datei** - `proxy/nginx.broken.conf` -**Muss** +**Schritte (Muss)** +- Zuerst die eigene `proxy/nginx.conf` sichern (z. B. `cp proxy/nginx.conf proxy/nginx.conf.bak`) - diese Challenge ueberschreibt sie. - Defekte Config testweise als aktive Config verwenden. - Mindestens 2-3 Fehler finden und fixen. - Symptome und Diagnoseweg erklaeren. +- Am Ende die eigene Config wiederherstellen (`cp proxy/nginx.conf.bak proxy/nginx.conf`). **Erwartete Fehlerarten (Beispiel aus `nginx.broken.conf`)** - Upstream-Name passt nicht zum referenzierten Namen in `proxy_pass`. - Falscher Upstream-Port (`8080` statt `80`). - Fehlender Trailing Slash in `proxy_pass` bei Prefix-Location. -**Warum wichtig** -- Debugging unter Druck ist Praxisalltag; diese Aufgabe trainiert systematisches Vorgehen mit Logs und Config-Tests. +**Zielzustand / Akzeptanz** +- Nach den Fixes liefern `/service/a` und `/service/b` wieder ihre Backends; Nginx startet ohne Config-Fehler. **Done-Check** ```bash -curl http://localhost:8080/service/a -curl http://localhost:8080/service/b +curl http://localhost:8080/service/a # -> "Reverse Proxy Target A" +curl http://localhost:8080/service/b # -> "Reverse Proxy Target B" ./scripts/compose.sh logs reverse-proxy ``` +**Warum wichtig** +- Debugging unter Druck ist Praxisalltag; diese Aufgabe trainiert systematisches Vorgehen mit Logs und Config-Tests. + --- ## Hard (TLS) @@ -247,23 +324,40 @@ curl http://localhost:8080/service/b **Ziel** - Eigene CA + Server-Zertifikat fuer `localhost` erstellen. +**Ausgangszustand** +- Stack laeuft auf HTTP (`8080`). Noch kein TLS, kein Port `8443`. +- `easy-rsa` und `openssl` sind installiert (siehe `challenges/easyrsa-hints.md`). + **Dateien** -- `docker-compose.yml` -- `proxy/nginx.conf` +- `docker-compose.yml` (Port `8443:443` + Cert-Volume) +- `proxy/nginx.conf` (TLS-Serverblock) +- `certs/easyrsa/*` (PKI), `certs/live/*` (Runtime-Cert + Key) -**Muss** -- Zertifikat fuer `localhost` erstellen. -- Proxy auf `443` erweitern (z. B. `8443:443`). -- Root-CA importieren und ohne `-k` testen. +**Schritte (Muss)** +- CA + Server-Zertifikat fuer `localhost` mit SAN erstellen (`--subject-alt-name="DNS:localhost,IP:127.0.0.1"`). +- Nur Runtime-Cert + Key bereitstellen (nicht die ganze PKI mounten). +- Proxy auf `443` erweitern (Mapping `8443:443`) und TLS in Nginx aktivieren. +- Mit `make redeploy` deployen (Compose-Aenderung -> Container-Neustart noetig). +- Root-CA in den System-Trust-Store importieren. -**Warum wichtig** -- TLS korrekt einzurichten ist Basis fuer Vertraulichkeit, Integritaet und Vertrauensaufbau im Netzwerk. +**Zielzustand / Akzeptanz** +- `curl https://localhost:8443/service/a` liefert Backend A **ohne** `-k` (CA wird vertraut). +- Kein SAN-/Hostname-Fehler. **Done-Check** ```bash curl https://localhost:8443/service/a +# Erwartet: HTML von Backend A, KEIN "SSL certificate problem" +# Falls CA noch nicht global importiert: +curl --cacert certs/easyrsa/pki/ca.crt https://localhost:8443/service/a ``` +**Warum wichtig** +- TLS korrekt einzurichten ist Basis fuer Vertraulichkeit, Integritaet und Vertrauensaufbau im Netzwerk. + +**Haeufigster Blocker** +- Ohne SAN scheitert curl mit `no alternative certificate subject name matches target host name` -> beim Signieren `--subject-alt-name` setzen (Details in `challenges/easyrsa-hints.md`). + ### 11) HTTP -> HTTPS Redirect **Voraussetzung** @@ -273,21 +367,29 @@ curl https://localhost:8443/service/a **Ziel** - HTTP sauber auf HTTPS umlenken. +**Ausgangszustand** +- Aus Challenge 10: HTTPS laeuft auf `8443`, HTTP auf `8080` liefert noch direkt Inhalte. + **Datei** - `proxy/nginx.conf` -**Muss** -- HTTP Requests auf HTTPS redirecten. +**Schritte (Muss)** +- HTTP Requests auf HTTPS redirecten (`return 301 https://$host:8443$request_uri;`). - `/healthz` darf optional auf HTTP bleiben. +- Deployen mit `make proxy-reload` (reine `nginx.conf`-Aenderung). -**Warum wichtig** -- Redirect erzwingt verschluesselten Zugriff und verhindert versehentliche Nutzung unsicherer HTTP-Endpunkte. +**Zielzustand / Akzeptanz** +- HTTP-Aufrufe auf `8080` antworten mit `301` und `Location: https://localhost:8443/...`. **Done-Check** ```bash curl -I http://localhost:8080/service/a +# Erwartet: HTTP/1.1 301 ... und Location: https://localhost:8443/service/a ``` +**Warum wichtig** +- Redirect erzwingt verschluesselten Zugriff und verhindert versehentliche Nutzung unsicherer HTTP-Endpunkte. + ### 12) TLS Haertung + Chain Check + HSTS **Voraussetzung** @@ -300,23 +402,39 @@ curl -I http://localhost:8080/service/a **Datei** - `proxy/nginx.conf` -**Muss** -- TLS auf 1.2/1.3 beschraenken. +**Ausgangszustand** +- Aus Challenge 10+11: HTTPS auf `8443` laeuft, HTTP wird umgeleitet. TLS ist aber noch ungehaertet (keine Protokoll-Beschraenkung, kein HSTS). + +**Schritte (Muss)** +- TLS auf 1.2/1.3 beschraenken (`ssl_protocols TLSv1.2 TLSv1.3;`). - HSTS setzen (`Strict-Transport-Security`). - Zertifikatskette pruefen und kurz erklaeren. - -**Warum wichtig** -- Reines "HTTPS an" reicht nicht: erst Haertung + HSTS reduzieren Downgrade- und Fehlkonfigurationsrisiken. +- Deployen mit `make proxy-reload`. **Hinweis** - Im HTTP-Basissetup ist HSTS absichtlich **noch nicht** aktiv. Das ist Teil der Aufgabe. +**Warnung (HSTS-Falle im Browser)** +- HSTS merkt sich der Browser **host-weit** (`localhost`), nicht pro Port. Nach einem Besuch von `https://localhost:8443` erzwingt der Browser `https` auch fuer `http://localhost:8080` -> das HTTP-Lab scheint dann "kaputt". +- Zum Pruefen daher `curl` nutzen (curl speichert HSTS nicht). +- Falls der Browser haengt: HSTS fuer `localhost` zuruecksetzen (Chrome: `chrome://net-internals/#hsts` -> "Delete domain security policies" -> `localhost`). +- `max-age` ist im Lab bewusst kurz (1h), damit der Effekt von selbst verfaellt. + +**Zielzustand / Akzeptanz** +- `curl -I` zeigt den `Strict-Transport-Security`-Header. +- `openssl s_client` verhandelt TLSv1.2 oder TLSv1.3 und endet mit `Verify return code: 0 (ok)`. + **Done-Check** ```bash curl -I https://localhost:8443/service/a +# -> enthaelt: Strict-Transport-Security: max-age=3600; includeSubDomains openssl s_client -connect localhost:8443 -servername localhost +# -> Protocol: TLSv1.3 (oder 1.2), Verify return code: 0 (ok) ``` +**Warum wichtig** +- Reines "HTTPS an" reicht nicht: erst Haertung + HSTS reduzieren Downgrade- und Fehlkonfigurationsrisiken. + --- ## Bonus Expert @@ -326,14 +444,18 @@ openssl s_client -connect localhost:8443 -servername localhost **Ziel** - Nachweisbar zeigen, was im Klartext sichtbar ist und was durch TLS geschuetzt wird. -**Muss** +**Ausgangszustand** +- HTTPS laeuft (Challenge 10), `8080` und `8443` sind erreichbar. Wireshark/tshark ist installiert (siehe `challenges/wireshark-hints.md`). + +**Schritte (Muss)** - HTTP auf `8080` mitschneiden. - HTTPS auf `8443` mitschneiden. - `ClientHello`, `ServerHello`, `Certificate` markieren. - Technisch erklaeren, warum HTTP lesbar ist und HTTPS ohne Keys nicht. -**Warum wichtig** -- Wer den Unterschied auf Paketebene gesehen hat, versteht TLS nicht nur theoretisch, sondern praktisch. +**Zielzustand / Akzeptanz** +- HTTP-Mitschnitt: Pfad und Header sind im Klartext lesbar (Follow Stream). +- HTTPS-Mitschnitt: nur der TLS-Handshake ist sichtbar, die Nutzdaten sind ohne Key nicht lesbar. **Vorgehen (empfohlen)** 1. Capture auf passendem Interface starten (lokal meist `lo`). @@ -347,6 +469,9 @@ openssl s_client -connect localhost:8443 -servername localhost **Done-Check** - 3-4 Screenshots + 3-5 Bulletpoints Auswertung. +**Warum wichtig** +- Wer den Unterschied auf Paketebene gesehen hat, versteht TLS nicht nur theoretisch, sondern praktisch. + **Typische Fehler** - falsches Interface gewaehlt - HTTPS noch nicht korrekt aktiv diff --git a/challenges/easyrsa-hints.md b/challenges/easyrsa-hints.md index 4bf9cff..7eee524 100644 --- a/challenges/easyrsa-hints.md +++ b/challenges/easyrsa-hints.md @@ -36,9 +36,11 @@ cd certs/easyrsa ```bash ./easyrsa gen-req localhost nopass -./easyrsa sign-req server localhost +./easyrsa --subject-alt-name="DNS:localhost,IP:127.0.0.1" sign-req server localhost ``` +Wichtig: Das `--subject-alt-name` ist nicht optional. Moderne Clients (curl, Browser) ignorieren den CN und pruefen ausschliesslich den SAN. Ohne SAN scheitert `curl https://localhost:8443` trotz korrekt importierter CA mit `no alternative certificate subject name matches target host name`. + ## 5) Nur Runtime-Zertifikate bereitstellen (nicht komplette PKI mounten) Nutze fuer den Container nur die benoetigten Laufzeitdateien: @@ -69,8 +71,8 @@ Danach in `proxy/nginx.conf` TLS aktivieren und in `docker-compose.yml` Port `44 services: reverse-proxy: ports: - - "8080:80" - - "8443:443" + - "${HTTP_PORT:-8080}:80" + - "${HTTPS_PORT:-8443}:443" volumes: - ./proxy/nginx.conf:/etc/nginx/nginx.conf:ro,z - ./proxy/html:/usr/share/nginx/html:ro,z @@ -101,7 +103,7 @@ server { ssl_certificate /etc/nginx/certs/localhost.crt; ssl_certificate_key /etc/nginx/certs/localhost.key; ssl_protocols TLSv1.2 TLSv1.3; - add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + add_header Strict-Transport-Security "max-age=3600; includeSubDomains" always; add_header X-Content-Type-Options "nosniff" always; add_header X-Frame-Options "DENY" always; @@ -122,6 +124,10 @@ server { ## 6) Root-CA importieren (Trust Store) +Wichtig: In den Trust-Store **der Umgebung importieren, in der du testest**. +- Test mit `curl` aus **WSL** (der Standardweg im Workshop): in den **Linux**-Trust-Store importieren -> Ubuntu/Debian-Befehle unten. +- Test im **Windows-Browser**: zusaetzlich der Windows-Import (`certutil`). + Fedora: ```bash diff --git a/challenges/wireshark-hints.md b/challenges/wireshark-hints.md index d9b01ee..95e8c51 100644 --- a/challenges/wireshark-hints.md +++ b/challenges/wireshark-hints.md @@ -22,6 +22,20 @@ sudo apt install -y wireshark tshark - Linux lokal: meist `lo` (Loopback) fuer `localhost` - Docker-Welt: ggf. `docker0` bzw. Bridge-Interface +**Windows (Docker Desktop + WSL) - empfohlener Weg:** + +- Capture **innerhalb WSL** machen, dort verhaelt sich `lo` wie unter Linux. Sowohl der `curl`-Request als auch der Mitschnitt laufen im WSL-Terminal: + +```bash +# Terminal 1 (WSL): Mitschnitt starten +sudo tshark -i lo -f "tcp port 8080" +# Terminal 2 (WSL): Request senden +curl http://localhost:8080/service/a +``` + +- Natives Windows-Wireshark kann `localhost` nur ueber den npcap-Adapter "Adapter for loopback traffic capture" mitschneiden, und Docker-Desktop-Portforwarding macht das unzuverlaessig. Fuer den Workshop daher in WSL bleiben. +- Wireshark-GUI unter WSL braucht WSLg (Windows 11) oder ein X-Server; einfacher ist `tshark` (CLI) plus spaeter `.pcap` in der Wireshark-GUI oeffnen (`tshark -w mitschnitt.pcap ...`). + ## 3) HTTP zuerst (Klartext) 1. Mitschnitt starten @@ -85,12 +99,14 @@ tls.handshake.type == 11 ## 6) Optional: TLS in Wireshark entschluesseln -1. Vor Browser-Start setzen: +1. Vor Browser-Start setzen (WSL/bash): ```bash export SSLKEYLOGFILE="$HOME/sslkeys.log" ``` +In PowerShell waere es stattdessen `$env:SSLKEYLOGFILE = "$HOME\sslkeys.log"` - der einfachste Weg ist aber, alles in WSL zu machen. + 2. Browser aus derselben Shell starten und HTTPS-Request erzeugen. 3. In Wireshark unter TLS-Preferences `sslkeys.log` als Key Log File setzen. 4. Mitschnitt erneut laden. diff --git a/proxy/html/challenges.html b/proxy/html/challenges.html index f8f3177..6a117f8 100644 --- a/proxy/html/challenges.html +++ b/proxy/html/challenges.html @@ -176,6 +176,12 @@ +
+

Wo laufen die Kommandos? (Windows)

+

Stack steuern geht aus PowerShell (scripts/workshop.ps1) oder WSL. Aber alle Test-Kommandos (curl, openssl, grep, for-Schleifen, ./scripts/compose.sh) laufen im WSL-Terminal (bash).

+

Warnung: In PowerShell ist curl ein Alias fuer Invoke-WebRequest und versteht -I/-k/--cacert nicht. Immer im WSL-Terminal testen.

+
+

Abgabe-Format

    @@ -196,8 +202,9 @@
  • Welche location matched /service/a?
  • Welcher upstream wird verwendet?
- 
curl http://localhost:8080/service/a
-curl http://localhost:8080/service/b
+

Zielzustand: Du kannst Location → Upstream → Backend benennen und begruenden, warum A und B unterschiedlich antworten.

+ 
curl http://localhost:8080/service/a   # -> "Target A"
+curl http://localhost:8080/service/b   # -> "Target B"
@@ -205,16 +212,18 @@ curl http://localhost:8080/service/b

Muss: Compose-Service + Upstream + Route /service/c.

Zusatz: backends/c/index.html ist vorhanden und darf angepasst werden.

Warum wichtig: Neue Services kommen laufend dazu; Erweiterungen ohne Seiteneffekte sind Praxisalltag.

- 
curl http://localhost:8080/service/c
-curl http://localhost:8080/service/a
-curl http://localhost:8080/service/b
+

Zielzustand: /service/c liefert Backend C; A und B laufen unveraendert weiter.

+ 
curl http://localhost:8080/service/c   # -> "Reverse Proxy Target C"
+curl http://localhost:8080/service/a   # -> weiterhin "Target A"
+curl http://localhost:8080/service/b   # -> weiterhin "Target B"
Easy 3) Eigene Route /demo/a

Muss: Alias-Route bauen, die auf Backend A fuehrt.

Warum wichtig: Der Proxy entkoppelt externe Pfade von internen Backend-Implementierungen.

- 
curl http://localhost:8080/demo/a
+

Zielzustand: /demo/a liefert dieselbe Antwort wie /service/a.

+ 
curl http://localhost:8080/demo/a   # -> "Target A"
@@ -226,7 +235,9 @@ curl http://localhost:8080/service/b

Setze mindestens nosniff, DENY, strict-origin-when-cross-origin, Permissions-Policy, COOP, CORP.

Optional: CSP fuer statische Seiten.

Warum wichtig: Diese Header reduzieren konkrete Browser-Angriffsvektoren und gehoeren zur Security-Baseline.

- 
curl -I http://localhost:8080/
+

Fallstrick: Header im server {}-Block setzen. Sobald in einem location {} ein add_header steht, verwirft Nginx dort alle Server-Header → dann erneut setzen.

+

Zielzustand: curl -I / zeigt alle geforderten Security-Header.

+ 
curl -I http://localhost:8080/   # -> nosniff, DENY, Referrer-Policy, Permissions-Policy, COOP, CORP
@@ -234,25 +245,29 @@ curl http://localhost:8080/service/b

Muss: /internal/status nur fuer 127.0.0.1.

Wichtig: Host-Request zeigt typischerweise 403 (Docker-Netzwerk).

Warum wichtig: Nicht jeder Endpoint darf oeffentlich erreichbar sein; Netzsegmentierung beginnt oft am Proxy.

- 
curl -i http://localhost:8080/internal/status
-./scripts/compose.sh exec -T reverse-proxy sh -lc "wget -qO- http://127.0.0.1/internal/status"
+

Zielzustand: Host → 403; container-intern (127.0.0.1) → Antwort.

+ 
curl -i http://localhost:8080/internal/status   # -> 403 (vom Host)
+./scripts/compose.sh exec -T reverse-proxy sh -lc "wget -qO- http://127.0.0.1/internal/status"   # -> "internal ok"
Medium 6) Logging verbessern

Eigenes log_format mit Upstream-Infos einbauen.

+

Hinweis: log_format gehoert in den http {}-Block, sonst startet Nginx nicht.

Warum wichtig: Ohne brauchbare Logs dauert Fehleranalyse deutlich laenger und Incident-Response wird unzuverlaessig.

+

Zielzustand: Log-Zeile im neuen Format mit Upstream-Infos (upstream=..., urt=...).

curl http://localhost:8080/service/a
-./scripts/compose.sh logs reverse-proxy
+./scripts/compose.sh logs reverse-proxy # -> neue Zeile mit upstream=... urt=...
Medium 7) Load Balancing

Zweite Instanz von Backend A (backend-a2) einbauen und Round-Robin zeigen.

Warum wichtig: Lastverteilung ist Kernnutzen eines Reverse Proxys fuer Skalierung und Verfuegbarkeit.

+

Zielzustand: Ueber mehrere Requests antworten beide Instanzen (Mischung aus A und A2).

for i in $(seq 1 8); do
-  curl -s http://localhost:8080/service/a | grep -o "Target A2\|Target A"
-done
+ curl -s http://localhost:8080/service/a | grep -o "INSTANCE=[A-Za-z0-9]*" +done # -> Mischung aus "INSTANCE=A" und "INSTANCE=A2"
@@ -260,16 +275,19 @@ done

Mindestens einen Backend-Response-Header per proxy_hide_header ausblenden.

Abgrenzung zu #4: #4 setzt Schutz-Header, #8 entfernt unnoetige Header aus Upstream-Responses.

Warum wichtig: Weniger preisgegebene Metadaten erschweren Fingerprinting und zielgerichtete Angriffe.

- 
curl -I http://localhost:8080/service/a
+

Zielzustand: Der ausgeblendete Header (z. B. ETag) fehlt jetzt in der Antwort.

+ 
curl -I http://localhost:8080/service/a   # -> ETag/Last-Modified nicht mehr vorhanden
Medium 9) Debugging Challenge

Mit proxy/nginx.broken.conf arbeiten, Fehler finden und reparieren.

+

Zuerst sichern: diese Challenge ueberschreibt deine nginx.conf → vorher cp proxy/nginx.conf proxy/nginx.conf.bak, am Ende zurueckkopieren.

Warum wichtig: In der Praxis geht es oft um Diagnose unter Zeitdruck, nicht nur um Greenfield-Konfiguration.

Typische Fehler in der kaputten Datei: Upstream-Name-Mismatch, falscher Port, fehlender Trailing Slash in proxy_pass.

- 
curl http://localhost:8080/service/a
-curl http://localhost:8080/service/b
+          
Zielzustand: Nach den Fixes liefern A und B wieder ihre Backends; Nginx startet fehlerfrei.

+          
curl http://localhost:8080/service/a   # -> "Target A"
+curl http://localhost:8080/service/b   # -> "Target B"
 ./scripts/compose.sh logs reverse-proxy
@@ -280,22 +298,27 @@ curl http://localhost:8080/service/b
Hard 10) HTTPS von 0 (Easy-RSA)

Zertifikat fuer localhost, Port 8443:443, Root-CA importiert.

+

Wichtig: Der neue Port ist eine Compose-Aenderung → mit make redeploy deployen, nicht nur make proxy-reload.

Warum wichtig: TLS-Grundaufbau ist Voraussetzung fuer vertrauliche und manipulationssichere Kommunikation.

- 
curl https://localhost:8443/service/a
+

Zielzustand: Aufruf liefert Backend A ohne -k (kein SAN-/Zertifikatsfehler). Zertifikat mit SAN signieren!

+ 
curl https://localhost:8443/service/a   # -> Backend A, KEIN "SSL certificate problem"
Hard 11) HTTP -> HTTPS Redirect

Voraussetzung: Challenge 10 abgeschlossen. Bestehende Config weiterverwenden.

Warum wichtig: Redirect verhindert unabsichtliche Klartext-Nutzung und erzwingt den sicheren Transport.

- 
curl -I http://localhost:8080/service/a
+

Zielzustand: HTTP auf 8080 antwortet mit 301 und Location: https://localhost:8443/....

+ 
curl -I http://localhost:8080/service/a   # -> 301, Location: https://localhost:8443/service/a
Hard 12) TLS Haertung + Chain + HSTS

Voraussetzung: Challenge 10 und 11 abgeschlossen. Gleiche Config weiter erweitern.

Warum wichtig: Erst Haertung + HSTS reduzieren Downgrade-Risiken und sorgen fuer dauerhaft sichere Clients.

- 
curl -I https://localhost:8443/service/a
+          
Warnung (HSTS-Falle): Der Browser merkt sich HSTS host-weit fuer localhost (nicht pro Port). Nach https://localhost:8443 wird auch http://localhost:8080 auf https erzwungen. Zum Testen curl nutzen; Browser-HSTS ggf. unter chrome://net-internals/#hsts fuer localhost loeschen. max-age ist im Lab bewusst kurz (1h).

+          
Zielzustand: curl -I zeigt Strict-Transport-Security; s_client verhandelt TLSv1.2/1.3 mit Verify return code: 0 (ok).

+          
curl -I https://localhost:8443/service/a   # -> enthaelt Strict-Transport-Security
 openssl s_client -connect localhost:8443 -servername localhost
@@ -313,6 +336,7 @@ openssl s_client -connect localhost:8443 -servername localhost
  • 3-5 Bulletpoints: was ist sichtbar, was ist geschuetzt?

    • Optional: TLS Decrypt mit SSLKEYLOGFILE.

    +

    Zielzustand: HTTP-Mitschnitt zeigt Pfad/Header im Klartext; HTTPS zeigt nur den Handshake, Nutzdaten ohne Key nicht lesbar.

    Abgabe: mind. 3 Screenshots + technische Interpretation.

    diff --git a/proxy/html/hints.html b/proxy/html/hints.html index c4aebcd..ff9a486 100644 --- a/proxy/html/hints.html +++ b/proxy/html/hints.html @@ -173,7 +173,7 @@ cd certs/easyrsa ./easyrsa init-pki ./easyrsa build-ca nopass ./easyrsa gen-req localhost nopass -./easyrsa sign-req server localhost     +./easyrsa --subject-alt-name="DNS:localhost,IP:127.0.0.1" sign-req server localhost

    Nur Runtime-Certs mounten (z. B. certs/live), nicht die komplette PKI.

    diff --git a/proxy/html/index.html b/proxy/html/index.html index 9b63ab0..fbd30bd 100644 --- a/proxy/html/index.html +++ b/proxy/html/index.html @@ -104,7 +104,7 @@

    HTL Reverse Proxy & TLS Lab

    - Basis läuft mit HTTP. Ziel im Workshop: Reverse Proxy verstehen und HTTPS/TLS manuell + Basis laeuft mit HTTP. Ziel im Workshop: Reverse Proxy verstehen und HTTPS/TLS manuell aufbauen.

    @@ -125,6 +125,10 @@
  • curl http://localhost:8080/service/b
  • ./scripts/compose.sh ps
    • +

    + Windows: Diese Kommandos im WSL-Terminal (bash) ausfuehren, nicht in PowerShell + (dort ist curl ein Alias fuer Invoke-WebRequest). +

    diff --git a/proxy/html/solutions.html b/proxy/html/solutions.html index 6c2da08..58816ef 100644 --- a/proxy/html/solutions.html +++ b/proxy/html/solutions.html @@ -215,7 +215,7 @@ location /service/c {
    - Easy 3) Rewrite Route + Easy 3) Alias-Route /demo/a

    Dateien: proxy/nginx.conf

    Commands noetig: ja

    location = /demo/a {
@@ -238,6 +238,7 @@ add_header Referrer-Policy "strict-origin-when-cross-origin" always;
 add_header Permissions-Policy "camera=(), microphone=(), geolocation=()" always;
 add_header Cross-Origin-Opener-Policy "same-origin" always;
 add_header Cross-Origin-Resource-Policy "same-origin" always;
    +

    Platzierung: in den server {}-Block, damit alle Locations sie erben. Sobald eine Location ein eigenes add_header hat, verwirft Nginx dort die Server-Header und sie muessen wiederholt werden.

    Optional CSP (statisch, inline styles erlaubt):

    add_header Content-Security-Policy "default-src 'self'; style-src 'self' 'unsafe-inline'; img-src 'self' data:; object-src 'none'; base-uri 'none'; frame-ancestors 'none'" always;

    Check: curl -I http://localhost:8080/

    @@ -262,6 +263,7 @@ add_header Cross-Origin-Resource-Policy "same-origin" always; Medium 6) Logging verbessern

    Dateien: proxy/nginx.conf

    Commands noetig: ja

    +

    Platzierung: log_format muss in den http {}-Block (sonst startet Nginx nicht). access_log darf in http, server oder location.

    log_format workshop '$remote_addr - $request '
                    'status=$status upstream=$upstream_addr '
                    'rt=$request_time urt=$upstream_response_time';
@@ -289,8 +291,9 @@ access_log /var/log/nginx/access.log workshop;
    }

    Check:

    for i in $(seq 1 8); do
-  curl -s http://localhost:8080/service/a | grep -o "Target A2\|Target A"
+  curl -s http://localhost:8080/service/a | grep -o "INSTANCE=[A-Za-z0-9]*"
 done
    +

    Marker: Backend A/A2 enthalten unsichtbar <!-- INSTANCE=A --> bzw. INSTANCE=A2. [A-Za-z0-9]* matched das ganze Token (kein Prefix-Problem A vs. A2).

    @@ -298,6 +301,7 @@ done

    Dateien: proxy/nginx.conf

    Commands noetig: ja

    Abgrenzung zu #4: #4 fuegt Schutz-Header hinzu, #8 entfernt unnoetige Upstream-Metadaten.

    +

    Gut zu wissen: proxy_hide_header ist kein add_header → es loest die Vererbungsfalle aus #4 nicht aus. Die Server-Header bleiben in dieser Location erhalten.

    location /service/a {
   proxy_pass http://backend_a/;
   proxy_hide_header ETag;
@@ -310,10 +314,14 @@ done
    Medium 9) Debugging Challenge

    Dateien: proxy/nginx.broken.conf, proxy/nginx.conf

    Commands noetig: ja

    -

    Ablauf: Kopiere testweise proxy/nginx.broken.conf auf proxy/nginx.conf, behebe die Fehler und stelle danach die funktionierende Konfiguration wieder her.

    - 
    cp proxy/nginx.broken.conf proxy/nginx.conf
+          
    Ablauf: Zuerst die eigene Config sichern (diese Challenge ueberschreibt sie!), dann die kaputte aktivieren, Fehler beheben und am Ende die eigene Config wiederherstellen.
    
+          
    cp proxy/nginx.conf proxy/nginx.conf.bak      # 1. eigene Config sichern
+cp proxy/nginx.broken.conf proxy/nginx.conf   # 2. kaputte aktivieren
 make proxy-reload
-./scripts/compose.sh logs reverse-proxy
    
+./scripts/compose.sh logs reverse-proxy        # 3. Fehler finden + fixen
    +

    Am Ende eigene Config zurueck:

    + 
    cp proxy/nginx.conf.bak proxy/nginx.conf
+make proxy-reload

    Konkrete Fehler und Fixes:

    1. Upstream-Mismatch: backend_a_typo ist definiert, aber backend_a wird referenziert -> Namen angleichen.
      2. @@ -340,15 +348,16 @@ cd certs/easyrsa ./easyrsa init-pki ./easyrsa build-ca nopass ./easyrsa gen-req localhost nopass -./easyrsa sign-req server localhost +./easyrsa --subject-alt-name="DNS:localhost,IP:127.0.0.1" sign-req server localhost

      Compose:

      reverse-proxy:
   ports:
-    - "8080:80"
-    - "8443:443"
+    - "${HTTP_PORT:-8080}:80"
+    - "${HTTPS_PORT:-8443}:443"
   volumes:
     - ./certs/live:/etc/nginx/certs:ro,z

      Wichtig: Nicht die komplette PKI in den Container mounten. Nur Runtime-Zertifikat + Key bereitstellen.

      +

      Deploy: Port- und Volume-Aenderungen sind Compose-Aenderungen → make redeploy (nicht make proxy-reload), sonst greift der neue Port nicht.

      Nginx TLS-Pfade: ssl_certificate /etc/nginx/certs/localhost.crt; und ssl_certificate_key /etc/nginx/certs/localhost.key;

      Check: curl https://localhost:8443/service/a (ohne -k nach CA-Import)

    @@ -381,7 +390,7 @@ cd certs/easyrsa

    Commands noetig: ja

    ssl_protocols TLSv1.2 TLSv1.3;
 ssl_prefer_server_ciphers on;
-add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always;
    +add_header Strict-Transport-Security "max-age=3600; includeSubDomains" always;

    Check:

    curl -I https://localhost:8443/service/a
 openssl s_client -connect localhost:8443 -servername localhost
    diff --git a/proxy/nginx.tls.example.conf b/proxy/nginx.tls.example.conf index 50bccda..1caca2e 100644 --- a/proxy/nginx.tls.example.conf +++ b/proxy/nginx.tls.example.conf @@ -39,7 +39,10 @@ http { ssl_protocols TLSv1.2 TLSv1.3; ssl_prefer_server_ciphers on; - add_header Strict-Transport-Security "max-age=31536000; includeSubDomains" always; + # max-age im Lab bewusst kurz (1h). In Produktion eher 1 Jahr (31536000). + # includeSubDomains weitet HSTS auf alle Subdomains aus (Produktions-Best-Practice). + # Achtung: HSTS bleibt im Browser host-weit haengen -> siehe Warnhinweis in Challenge 12. + add_header Strict-Transport-Security "max-age=3600; includeSubDomains" always; add_header X-Content-Type-Options "nosniff" always; add_header X-Frame-Options "DENY" always; add_header Referrer-Policy "strict-origin-when-cross-origin" always;