Files
infrastructure/docs/GNAI-005-SEC_Reverse-Proxy.md
T

315 lines
10 KiB
Markdown
Raw Blame History

This file contains ambiguous Unicode characters
This file contains Unicode characters that might be confused with other characters. If you think that this is intentional, you can safely ignore this warning. Use the Escape button to reveal them.
# Technical Architecture Specification
**Dokumenten-ID:** GNAI-006-SEC
**Titel:** Homelab / Infrastructure – Reverse Proxy & Containerized IPS Specification
**Version:** 1.0
**Status:** Aktiv
**Vorgänger / Referenzen:** GNAI-003-INFRA, GNAI-004-SEC
---
## 1. Zweck & Geltungsbereich
Dieses Dokument definiert die verbindliche System- und Sicherheitsarchitektur für den zentralen Reverse Proxy und das Intrusion Prevention System (IPS) der Ghostnet-Infrastruktur auf Proxmox LXC 103 (`reverse-proxy`).
**Umfang dieses Dokuments:**
* Betrieb von Nginx Proxy Manager (NPM) als zentraler Ingress-Controller
* Containerisiertes Fail2Ban als IPS mit nftables-Integration auf dem LXC
* Log-Parsing-Regeln und Filterdefinitionen für das NPM-spezifische Access-Log-Format
* Gehärtete Firewall-Baseline und Zugriffssteuerung
---
## 2. System- Baseline (LXC 103)
| Parameter | Wert |
| --- | --- |
| Container-ID | CT 103 |
| Hostname | `reverse-proxy`<br> |
| Betriebssystem | Debian GNU/Linux 13 (Trixie) |
| Unprivileged | Ja |
| Cores / RAM / Swap | 2 Cores / 1024 MB RAM / 512 MB Swap |
| RootFS | 8 GB |
| Netzwerkkonfiguration | IP: `10.0.0.10/24` | GW: `10.0.0.1` | Bridge: `vmbr0`<br> |
| LXC Features | `nesting=1`, `keyctl=1`<br> |
| Proxmox Host | Proxmox VE 8.4.21 (Kernel `6.8.12-23-pve`) |
*Hinweis zur Proxmox-Firewall:* Proxmox Cluster- und Node-Firewalls sind deaktiviert (`enable 0`). Die Paketfilterung erfolgt exklusiv lokal über `nftables` innerhalb des LXC.
---
## 3. Netzwerk- & Firewall-Architektur (nftables)
Die lokale Paketfilterung basiert auf `nftables` mit einer strikten `INPUT policy drop`-Doktrin.
```nftables
table inet filter {
chain input {
type filter hook input priority filter; policy drop;
iifname "lo" accept
ct state invalid drop
ct state established,related accept
ip protocol icmp accept
ip saddr 10.0.0.0/24 tcp dport { 22, 81 } accept
tcp dport { 80, 443 } accept
}
chain forward {
type filter hook forward priority filter; policy accept;
}
chain output {
type filter hook output priority filter; policy accept;
}
}
```
### Port-Matrix
| Port | Protokoll | Zweck | Erreichbarkeit |
| --- | --- | --- | --- |
| 80 | TCP | HTTP Ingress (NPM) | Öffentlich |
| 443 | TCP | HTTPS Ingress (NPM) | Öffentlich |
| 81 | TCP | NPM Web Admin Interface | Nur LAN (`10.0.0.0/24`) |
| 22 | TCP | OpenSSH Management | Nur LAN (`10.0.0.0/24`) |
| 3000 | TCP | NPM Node.js Backend | Intern / Nicht exponiert |
---
## 4. Container-Infrastruktur (Podman Quadlets)
Nginx Proxy Manager und Fail2Ban werden als rootful Podman-Container via systemd Quadlets mit `Network=host` betrieben.
### 4.1 Nginx Proxy Manager Quadlet
* **Datei:** `/etc/containers/systemd/nginx-proxy-manager.container`
* **Image:** `docker.io/jc21/nginx-proxy-manager:2.11.1` *(ausdrücklich gepinnt)*
```ini
[Unit]
Description=Nginx Proxy Manager
Wants=network-online.target
After=network-online.target
[Container]
Image=docker.io/jc21/nginx-proxy-manager:2.11.1
ContainerName=nginx-proxy-manager
Network=host
Volume=/opt/nginx-proxy-manager/data:/data:rw
Volume=/opt/nginx-proxy-manager/letsencrypt:/etc/letsencrypt:rw
Environment=DISABLE_IPV6=true
Environment=TZ=Europe/Berlin
[Service]
Restart=always
TimeoutStartSec=300
[Install]
WantedBy=multi-user.target
```
### 4.2 Fail2Ban IPS Quadlet
* **Datei:** `/etc/containers/systemd/fail2ban.container`
* **Image:** `lscr.io/linuxserver/fail2ban:latest`
* **Capabilities:** `NET_ADMIN`, `NET_RAW` *(kein `--privileged`)*
```ini
[Unit]
Description=Fail2Ban
Wants=network-online.target
After=network-online.target
[Container]
Image=lscr.io/linuxserver/fail2ban:latest
ContainerName=fail2ban
Network=host
AddCapability=NET_ADMIN
AddCapability=NET_RAW
Volume=/opt/fail2ban/config:/config:rw
Volume=/opt/nginx-proxy-manager/data/logs:/remotelogs/npm:ro
Environment=TZ=Europe/Berlin
[Service]
Restart=always
TimeoutStartSec=300
[Install]
WantedBy=multi-user.target
```
---
## 5. NPM Logformat & Parsing-Regeln
NPM nutzt ein eigenes Access-Log-Format, bei dem die eigentliche Client-IP nicht am Zeilenanfang steht.
**Beispielzeile:**
```text
[03/Sep/2026:18:35:02 +0200] - 204 204 - POST https jellyfin.ghostnet.selfhost.eu "/Sessions/Playing/Progress" [Client 93.228.100.74] [Length 0] [Gzip -] [Sent-to 10.0.0.11] "JellyfinDesktop/2.0.0" "-"
```
**Verbindliche Parser-Regeln:**
1. Die Client-IP muss zwingend aus dem Feld `[Client <HOST>]` extrahiert werden.
2. URL-Pfade oder Host-Header dürfen nicht fälschlicherweise als IP-Quelle interpretiert werden.
3. Statuscodes oder Response-Zeiten sind für automatisches Banning ungeeignet, da legitim nicht erreichbare Backends (502) False Positives auslösen würden.
---
## 6. Fail2Ban-Konfiguration & Jails
LinuxServer.io nutzt `/config/fail2ban/` als interne Konfigurationsstruktur. Sämtliche Konfigurationen liegen persistent auf dem Host unter `/opt/fail2ban/config/fail2ban/`.
### 6.1 Wichtige Erkenntnis zur Action-Syntax
Standardmäßig nutzt die Action `nftables-multiport` bei fehlenden Parametern Port 22 (SSH). **Sperrports müssen zwingend direkt in der `action`-Zeile des Jails in eckigen Klammern übergeben werden**, um Anfragen auf HTTP/HTTPS durchzusetzen:
```ini
action = nftables-multiport[port="80,443", protocol=tcp]
```
---
### 6.2 Jail 1: Exploit & Scanner Protection (`npm-scanner`)
Gezielte Blockade von Pfad-Traversal-Versuchen, Secret-Abfragen und automatisierten Framework-Scans.
* **Filter:** `/opt/fail2ban/config/fail2ban/filter.d/npm-scanner.conf`
```ini
[Definition]
failregex = ^\[.*\] - [0-9]{3} [0-9]{3} - (GET|POST|HEAD) [^ ]+ [^ ]+ "/(?:[^"]*/)?(?:\.env[^"/]*|\.git/[^" ]*|\.aws/[^" ]*|wp-config\.php[^" ]*|wp-login\.php(?:\?[^" ]*)?|wp-admin(?:/[^" ]*)?|actuator(?:/[^" ]*)?|_ignition(?:/[^" ]*)?|storage/logs(?:/[^" ]*))" \[Client <HOST>\]
ignoreregex =
```
* **Jail:** `/opt/fail2ban/config/fail2ban/jail.d/npm-scanner.local`
```ini
[npm-scanner]
enabled = true
filter = npm-scanner
backend = auto
logpath = /remotelogs/npm/proxy-host-*_access.log
findtime = 10m
maxretry = 3
bantime = 1h
ignoreip = 127.0.0.1/8 10.0.0.0/24
action = nftables-multiport[port="80,443", protocol=tcp]
```
---
### 6.3 Jail 2: Bad User-Agents (`npm-badbots`)
Blockade bekannter Angriffs-Scanner und Reconnaissance-Tools.
* **Filter:** `/opt/fail2ban/config/fail2ban/filter.d/npm-badbots.conf`
*(Wichtig: Nutzt lokale Case-Insensitivity `(?i:...)`, um Python-RegEx-Kompilierungsfehler zu vermeiden)*
```ini
[Definition]
failregex = ^\[.*\] - [0-9]{3} [0-9]{3} - (?:GET|POST|HEAD|OPTIONS) [^ ]+ [^ ]+ "[^"]*" \[Client <HOST>\] .* "[^"]*(?i:sqlmap|nikto|nmap|masscan|zgrab|nessus|openvas|dirbuster|gobuster|wpscan|python-requests|go-http-client|censys|whatweb|acunetix)[^"]*"
ignoreregex =
```
* **Jail:** `/opt/fail2ban/config/fail2ban/jail.d/npm-badbots.local`
```ini
[npm-badbots]
enabled = true
filter = npm-badbots
backend = auto
logpath = /remotelogs/npm/proxy-host-*_access.log
findtime = 10m
maxretry = 2
bantime = 24h
ignoreip = 127.0.0.1/8 10.0.0.0/24
action = nftables-multiport[port="80,443", protocol=tcp]
```
---
## 7. Aktive Proxy Hosts
Aktuell im Nginx Proxy Manager konfigurierte und aktive Routen:
| ID | Hostname | Backend-Ziel | Dienst |
| --- | --- | --- | --- |
| 1 | `jellyfin.ghostnet.selfhost.eu` | `10.0.0.11:8096` | Jellyfin Media Server |
| 3 | `nextcloud.ghostnet.selfhost.eu` | `10.0.0.12:8080` | Nextcloud Cloud Storage |
| 4 | `git.ghostnet.selfhost.eu` | `10.0.0.17:3000` | Gitea Code Hosting |
| 7 | `auth.ghostnet.selfhost.eu` | `10.0.0.4:8080` | Keycloak Identity Provider |
| 10 | `japan.ghostnet.selfhost.eu` | `10.0.0.23:80` | Japanese Web App |
| 12 | `vault.ghostnet.selfhost.eu` | `10.0.0.47:8080` | Vaultwarden Password Manager |
---
## 8. Betriebs- & Diagnosekommandos
### Fail2Ban-Status
```bash
# Gesamtstatus der aktiven Jails
podman exec fail2ban fail2ban-client status
# Spezifischen Jail prüfen
podman exec fail2ban fail2ban-client status npm-scanner
podman exec fail2ban fail2ban-client status npm-badbots
```
### Filter mit echten Logs testen
```bash
podman exec fail2ban fail2ban-regex \
/remotelogs/npm/proxy-host-10_access.log \
/config/fail2ban/filter.d/npm-scanner.conf
```
### nftables-Regeln & aktive Bans auf dem Host verifizieren
```bash
nft list ruleset | grep -A 10 "table inet f2b-table"
```
### Manuelle Sperre / Freigabe
```bash
# IP manuell sperren
podman exec fail2ban fail2ban-client set npm-scanner banip <IP>
# IP manuell freigeben
podman exec fail2ban fail2ban-client set npm-scanner unbanip <IP>
```
---
## 9. Sicherheits- & Betriebsregeln für Administrierende
1. **Kein generisches Statuscode-Banning:** Generische HTTP `4xx`- oder `5xx`-Fehler dürfen nicht als pauschales Ban-Kriterium verwendet werden.
2. **Keine verfrühten Upgrades:** Die NPM-Version ist auf `2.11.1` festgeschrieben. Upgrades müssen separat in einer Testumgebung evaluiert werden.
3. **Privilegien-Minimierung:** Der Fail2Ban-Container wird strikt ohne `--privileged` betrieben (`NET_ADMIN` und `NET_RAW` reichen aus).
4. **Whitelist-Pflicht:** Das Subnetz `10.0.0.0/24` sowie `127.0.0.1/8` müssen in allen Jails in `ignoreip` hinterlegt bleiben, um Aussperrungen zu verhindern.
5. **Syntax-Check vor Reload:** Jede Änderung an Fail2Ban-Konfigurationen ist vorab mit `podman exec fail2ban fail2ban-client -t` auf Gültigkeit zu prüfen.
---
## 10. Backup & Disaster Recovery
Es existiert ein vollständiges Proxmox LXC Snapshot-Backup von CT 103:
* **Backup-Datei:** `/var/lib/vz/dump/vzdump-lxc-103-2026_08_31-19_11_10.tar.zst`
Vor strukturellen Änderungen an `nftables` oder den Podman Quadlets ist stets ein neuer Proxmox LXC-Snapshot zu erstellen.
---
## 11. Änderungsverlauf
| Datum | Version | Geändert von | Beschreibung |
| --- | --- | --- | --- |
| 2026-08-28 | 0.1 | spektr | Erstellung der ersten Baseline-Drafts. |
| 2026-09-05 | 0.9 | spektr | Implementierung Fail2Ban Container & Test-Setup (F2B-01). |
| 2026-09-07 | 1.0 | spektr | Korrektur Action-Syntax (`port="80,443"`), Behebung RegEx-Fehler (`npm-badbots`), E2E-Validierung in nftables abgeschlossen (F2B-02). Finales SOP erstellt. |