390 lines
8.7 KiB
Markdown
390 lines
8.7 KiB
Markdown
# Security & Access Control Specification
|
||
|
||
**Dokumenten-ID:** GNAI-004-SEC
|
||
**Titel:** Homelab / LLM-Infrastruktur – Sicherheits-, Authentifizierungs- und Zugriffskonzept
|
||
**Version:** 1.0
|
||
**Status:** Architekturentscheidung
|
||
**Vorgänger / Referenzen:** GNAI-INFRA-003
|
||
|
||
---
|
||
|
||
## 1. Zweck
|
||
|
||
Dieses Dokument definiert das verbindliche Zugriffs- und Authentifizierungsmodell für die öffentlich und intern erreichbaren Komponenten der Ghostnet-Infrastruktur.
|
||
|
||
Das Modell trennt bewusst:
|
||
|
||
- **Netzwerkzugang** über WireGuard,
|
||
- **Benutzeridentität** über Keycloak/OIDC,
|
||
- **Maschinen-/API-Zugriff** über API-Keys bzw. anwendungsbezogene Credentials,
|
||
- **SSH-Administration** über SSH Public Keys.
|
||
|
||
Ziel ist Least Privilege bei gleichzeitig überschaubarer Administration.
|
||
|
||
---
|
||
|
||
## 2. Rollenmodell
|
||
|
||
### 2.1 Full Admin
|
||
|
||
Vollständiger privilegierter Infrastrukturzugriff.
|
||
|
||
**Netzwerkzugang:**
|
||
|
||
- WireGuard
|
||
|
||
**Erlaubte Zielbereiche:**
|
||
|
||
- Proxmox Management
|
||
- LLM Server
|
||
- weitere explizit freigegebene Managementsysteme
|
||
|
||
**Zusätzliche Authentifizierung:**
|
||
|
||
- Proxmox-eigene Authentifizierung und 2FA, sofern konfiguriert
|
||
- SSH Public Keys für SSH
|
||
- Anwendungsspezifische Credentials bei Web-UIs
|
||
|
||
WireGuard ersetzt die eigentliche Dienstauthentifizierung nicht.
|
||
|
||
---
|
||
|
||
### 2.2 LLM Admin
|
||
|
||
Administration des LLM-Servers ohne allgemeine Proxmox-/LAN-Administration.
|
||
|
||
**Netzwerkzugang:**
|
||
|
||
- WireGuard
|
||
|
||
**Erlaubte Zielbereiche:**
|
||
|
||
- LLM-Server
|
||
- SSH
|
||
- weitere ausdrücklich für den LLM-Betrieb freigegebene Managementschnittstellen
|
||
|
||
**Nicht erlaubt:**
|
||
|
||
- Proxmox Management
|
||
- allgemeiner Zugriff auf andere Service-LXCs
|
||
- allgemeiner Zugriff auf das LAN
|
||
|
||
**SSH:**
|
||
|
||
- Public-Key-Authentifizierung
|
||
- kein Passwort-Login
|
||
|
||
---
|
||
|
||
### 2.3 LLM User
|
||
|
||
Kein privilegierter Netzwerkzugang.
|
||
|
||
**Zugang:**
|
||
|
||
```text
|
||
HTTPS → NPM → LiteLLM
|
||
```
|
||
|
||
**Authentifizierung:**
|
||
|
||
- API-Key
|
||
|
||
**Erlaubt:**
|
||
|
||
- Nutzung der von LiteLLM freigegebenen Modelle / Endpunkte
|
||
- Nutzung nach den für den Benutzer gesetzten Quoten und Policies
|
||
|
||
**Nicht erlaubt:**
|
||
|
||
- SSH
|
||
- Zugriff auf den LLM-Server allgemein
|
||
- Zugriff auf `llama.cpp` direkt
|
||
- Zugriff auf Proxmox
|
||
- Zugriff auf andere interne Services
|
||
|
||
Ein normaler LLM User erhält **keinen WireGuard-Peer**, sofern für einen konkreten Anwendungsfall kein zusätzlicher privilegierter Zugriff erforderlich ist.
|
||
|
||
---
|
||
|
||
## 3. Zugriffsmatrix
|
||
|
||
| Ziel | Full Admin | LLM Admin | LLM User | Öffentlich |
|
||
| --- | --- | --- | --- | --- |
|
||
| Proxmox Web UI | ✅ WireGuard | ❌ | ❌ | ❌ |
|
||
| Proxmox SSH | ✅ WireGuard + SSH-Key | ❌ | ❌ | ❌ |
|
||
| LLM Server SSH | ✅ WireGuard + SSH-Key | ✅ WireGuard + SSH-Key | ❌ | ❌ |
|
||
| `llama.cpp` direkt | intern/admin nach Bedarf | intern/admin nach Bedarf | ❌ | ❌ |
|
||
| LiteLLM API | ✅ | ✅ | ✅ HTTPS + API-Key | ✅ HTTPS |
|
||
| OpenWebUI | ✅ | ✅ optional | ✅ HTTPS + OIDC | ✅ HTTPS |
|
||
| Nextcloud | ✅ | ✅ optional | ✅ HTTPS + OIDC | ✅ HTTPS |
|
||
| Gitea | ✅ | ✅ optional | ✅ HTTPS + OIDC | ✅ HTTPS |
|
||
| Keycloak OIDC-Endpunkte | ✅ | ✅ | ✅ für Login | ✅ nur erforderliche Endpunkte |
|
||
| Keycloak Admin | ✅ WireGuard | ❌ | ❌ | ❌ |
|
||
| NPM Admin | ✅ WireGuard | ❌ | ❌ | ❌ |
|
||
| Fail2Ban Management | ✅ intern/admin | ggf. LLM-intern falls separat erforderlich | ❌ | ❌ |
|
||
|
||
---
|
||
|
||
## 4. Authentifizierungsmodell
|
||
|
||
### 4.1 WireGuard
|
||
|
||
WireGuard authentifiziert Peers kryptografisch über Public-/Private-Key-Paare.
|
||
|
||
Es besteht keine Kopplung zwischen WireGuard-Peer-Authentifizierung und Keycloak.
|
||
|
||
Grund:
|
||
|
||
- WireGuard kontrolliert **Netzwerkzugang**
|
||
- Keycloak kontrolliert **Benutzer-/Anwendungsidentität**
|
||
|
||
Diese Trennung ist beabsichtigt.
|
||
|
||
---
|
||
|
||
### 4.2 Keycloak / OIDC
|
||
|
||
Keycloak ist die zentrale Identitätsquelle für webbasierte Benutzeranwendungen.
|
||
|
||
Ziel:
|
||
|
||
```text
|
||
Benutzer
|
||
↓
|
||
Keycloak
|
||
↓ OIDC
|
||
Nextcloud / Gitea / OpenWebUI / weitere Services
|
||
```
|
||
|
||
Administrative Keycloak-Funktionen bleiben auf das Managementnetz beschränkt.
|
||
|
||
---
|
||
|
||
### 4.3 LiteLLM API
|
||
|
||
Die LLM-API ist ein anwendungsbezogener Dienst und wird deshalb nicht durch einen allgemeinen LAN-/VPN-Zugang für normale Benutzer bereitgestellt.
|
||
|
||
Ziel:
|
||
|
||
```text
|
||
Client
|
||
↓ HTTPS
|
||
NPM
|
||
↓
|
||
LiteLLM
|
||
↓
|
||
llama.cpp
|
||
```
|
||
|
||
Die Autorisierung erfolgt über API-Keys.
|
||
|
||
API-Keys sollen:
|
||
|
||
- individuell pro Benutzer bzw. Anwendung vergeben werden,
|
||
- widerrufbar sein,
|
||
- nach Möglichkeit mit Quoten / Rate Limits verbunden werden,
|
||
- nicht als Ersatz für privilegierten Netzwerkzugriff dienen.
|
||
|
||
---
|
||
|
||
### 4.4 SSH
|
||
|
||
SSH wird auf dem LLM-Server schlüsselbasiert betrieben.
|
||
|
||
Zusätzliche Schutzschicht:
|
||
|
||
```text
|
||
WireGuard
|
||
+
|
||
SSH Public Key
|
||
```
|
||
|
||
Passwort- und Root-Login über SSH bleiben deaktiviert.
|
||
|
||
---
|
||
|
||
## 5. Netzwerk-Autorisierung
|
||
|
||
WireGuard-Peers werden nicht pauschal für das gesamte LAN freigeschaltet.
|
||
|
||
Zugriff ist mindestens nach folgendem Muster zu definieren:
|
||
|
||
```text
|
||
Full Admin
|
||
→ Proxmox
|
||
→ LLM Server
|
||
→ explizit freigegebene Managementziele
|
||
|
||
LLM Admin
|
||
→ LLM Server
|
||
→ explizit freigegebene Managementziele
|
||
|
||
LLM User
|
||
→ kein Management-VPN
|
||
```
|
||
|
||
`AllowedIPs` und Firewall-Regeln bilden gemeinsam die technische Durchsetzung.
|
||
|
||
---
|
||
|
||
## 6. Public vs. Private Exposure
|
||
|
||
### Öffentlich
|
||
|
||
- HTTP/HTTPS auf NPM
|
||
- für den VPN-Betrieb: WireGuard UDP-Port
|
||
- OIDC-Endpunkte, soweit für Web-Login erforderlich
|
||
- LiteLLM API über HTTPS
|
||
- öffentliche Webanwendungen
|
||
|
||
### Privat
|
||
|
||
- Proxmox Management
|
||
- SSH
|
||
- NPM Admin
|
||
- Keycloak Admin
|
||
- `llama.cpp`
|
||
- interne Datenbanken
|
||
- interne Serviceports
|
||
- Podman-/Container-Management
|
||
- sonstige Infrastruktur-Interfaces
|
||
|
||
---
|
||
|
||
## 7. Fail2Ban-Rolle
|
||
|
||
Fail2Ban ist ein ergänzender Schutzmechanismus für die öffentliche NPM-Schicht.
|
||
|
||
Es soll insbesondere:
|
||
|
||
- eindeutige Scanner-/Exploit-Muster,
|
||
- wiederholte Missbrauchsmuster,
|
||
- geeignete Authentifizierungsangriffe
|
||
|
||
erkennen und dynamisch blockieren.
|
||
|
||
Nicht vorgesehen ist ein pauschales Blocking aller HTTP-Fehlercodes.
|
||
|
||
Insbesondere soll ein allgemeiner `404` nicht automatisch als Angriff gewertet werden.
|
||
|
||
Die finalen Jails werden serviceorientiert entworfen und getrennt validiert.
|
||
|
||
---
|
||
|
||
## 8. Weitere Schutzmaßnahmen
|
||
|
||
Das Zugriffskonzept setzt zusätzlich voraus:
|
||
|
||
### Perimeter
|
||
|
||
- keine unnötigen Portweiterleitungen
|
||
- IPv4-/IPv6-Exposure gleichwertig prüfen
|
||
- keine direkte Veröffentlichung von Managementports
|
||
|
||
### Identität
|
||
|
||
- MFA für privilegierte Accounts
|
||
- vorzugsweise WebAuthn/FIDO2, wo sinnvoll
|
||
- individuelle Accounts statt gemeinsam genutzter Konten
|
||
|
||
### Systeme
|
||
|
||
- zeitnahes Patchmanagement
|
||
- minimale installierte Dienste
|
||
- minimale Container-/LXC-Capabilities
|
||
- unprivileged LXCs, wo technisch möglich
|
||
|
||
### Recovery
|
||
|
||
- getrennte Backups
|
||
- Schutz gegen versehentliches oder böswilliges Löschen
|
||
- regelmäßige Restore-Tests
|
||
|
||
### Monitoring
|
||
|
||
- Uptime-/Health-Monitoring
|
||
- regelmäßige Überprüfung der extern sichtbaren Ports und Dienste
|
||
- Überwachung sicherheitsrelevanter Logs
|
||
|
||
---
|
||
|
||
## 9. Grundprinzip für zukünftige Services
|
||
|
||
Neue Services sind nach folgendem Entscheidungsmodell einzuordnen:
|
||
|
||
### Ist es ein öffentlicher Benutzer-/Anwendungsdienst?
|
||
|
||
→ HTTPS über NPM
|
||
→ OIDC/Keycloak oder anwendungsspezifische Authentifizierung
|
||
|
||
### Ist es ein privilegierter Managementdienst?
|
||
|
||
→ nicht öffentlich
|
||
→ Zugriff über WireGuard
|
||
→ zusätzliche Dienstauthentifizierung
|
||
|
||
### Ist es ein Backend?
|
||
|
||
→ keine Internet-Exposure
|
||
→ Zugriff ausschließlich von den benötigten internen Komponenten
|
||
|
||
### Ist es eine Maschinen-API?
|
||
|
||
→ HTTPS über NPM, wenn extern erforderlich
|
||
→ API-Key oder geeignetes OAuth2-/Client-Credentials-Modell
|
||
→ Rate Limits / Quotas
|
||
|
||
---
|
||
|
||
## 10. Sicherheitsziel
|
||
|
||
Die Zielarchitektur soll sicherstellen, dass ein kompromittierter Bestandteil möglichst nicht automatisch zu einem vollständigen Infrastrukturzugriff führt.
|
||
|
||
Beispiele:
|
||
|
||
```text
|
||
Kompromittiertes Webkonto
|
||
≠ Proxmox-Zugriff
|
||
|
||
Gestohlener LLM-API-Key
|
||
≠ SSH-Zugriff
|
||
|
||
Kompromittierter LLM-Container
|
||
≠ WireGuard-Admin
|
||
|
||
LLM-Admin-WireGuard-Peer
|
||
≠ Proxmox-Admin
|
||
|
||
Öffentlicher NPM-Dienst
|
||
≠ direkter Zugriff auf interne Backendports
|
||
```
|
||
|
||
Das Sicherheitsmodell basiert damit nicht auf einem einzelnen „Security-Programm“, sondern auf der Kombination mehrerer voneinander unabhängiger Kontrollen.
|
||
|
||
---
|
||
|
||
## 11. Offene Implementierungsdetails
|
||
|
||
Die folgenden Punkte werden erst in den jeweiligen Umsetzungs-SOPs festgelegt:
|
||
|
||
- WireGuard-VPN-Adressraum
|
||
- Peer-IP-Zuweisungen
|
||
- Firewall-Regeln für Full Admin / LLM Admin
|
||
- konkrete `wg-easy`-Containerkonfiguration
|
||
- NPM- und Fail2Ban-Netzwerke
|
||
- konkrete Fail2Ban-Filter/Jails
|
||
- LiteLLM-Key-/Quota-Modell
|
||
- Keycloak-Realm-/Client-/Role-Struktur
|
||
- DNS-Namen
|
||
- IPv6-Regelsatz
|
||
- Logging-/Alerting-Strategie
|
||
|
||
---
|
||
|
||
## 12. Änderungsverlauf
|
||
|
||
| Datum | Version | Geändert von | Beschreibung |
|
||
| --- | --- | --- | --- |
|
||
| 2026-08-28 | 1.0 | spektr | Erstellung des Sicherheits- und Zugriffskonzepts. |
|