301 lines
12 KiB
Markdown
301 lines
12 KiB
Markdown
# Security & Access Control Specification
|
||
|
||
**Dokumenten-ID:** GNAI-004-SEC
|
||
**Titel:** Homelab / LLM-Infrastruktur – Sicherheits-, Authentifizierungs- und Zugriffskonzept
|
||
**Status:** Verbindliches Zielmodell; technische Durchsetzung teilweise offen
|
||
**Vorgänger / Referenzen:** [Architektur](GNAI-003-INFRA_Architecture.md), [Gateway](GNAI-006-SEC_VPN.md), [GUI-SOP](GNAI-006-SEC_VPN_Client-Management.md), [Reverse Proxy](GNAI-005-SEC_Reverse-Proxy.md)
|
||
|
||
---
|
||
|
||
## Änderungsverlauf
|
||
|
||
| Datum | Version | Autor | Beschreibung |
|
||
| --- | --- | --- | --- |
|
||
| 2026-08-28 | 1.0 | spektr | Erstellung des Sicherheits- und Zugriffskonzepts. |
|
||
| 2026-09-15 | 1.1 | spektr | Familie, Server Admin und LLM Admin getrennt; serverseitige Zielrechte, NAT und Umsetzungsdefizite dokumentiert; OIDC-Ist präzisiert. |
|
||
| 2026-09-16 | 1.2 | spektr | Fail2Ban-Pin `1.1.0-r2-ls43` und wieder laufenden Container als Ist-Stand übernommen; technische Abnahme bleibt in GNAI-005 geführt. |
|
||
| 2026-09-18 | 1.3 | spektr | KI-Anwendungsdienste als Zielbild und bestehende Fail2Ban-Jails als dokumentierten Ist-Stand eingeordnet. |
|
||
|
||
---
|
||
|
||
## 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 Familie
|
||
|
||
Familienmitglieder (Betreiber und Bruder) dürfen das gesamte Heimnetz `10.0.0.0/24` einschließlich gewöhnlicher PCs und Clients erreichen. Das ist eine bewusste Vollzugriffsentscheidung für die Netzwerkebene. Proxmox, SSH und andere Anwendungen behalten eigene Authentifizierung und Autorisierung. Zugriff auf wg-easy und NPM-Administration ist vorgesehen.
|
||
|
||
### 2.2 Server Admin
|
||
|
||
Server Admins dürfen Proxmox `10.0.0.2`, aktuelle Service-LXCs und KI-Server `10.0.0.90` erreichen. NPM und wg-easy zählen zu den Service-LXCs. Allgemeine Heimnetz-PCs/Clients gehören nicht zu dieser Freigabe. Serverseitig eine Liste bestätigter Hosts pflegen; der statische Adressbereich bis `.99` ist keine pauschale Zugriffsfreigabe.
|
||
|
||
### 2.3 LLM Admin
|
||
|
||
LLM Admins dürfen ausschließlich KI-Server `10.0.0.90` erreichen. Proxmox, andere Service-LXCs, wg-easy/NPM und gewöhnliche Heimnetz-PCs sind gesperrt. Netzwerkzugriff auf den Host ersetzt keine SSH-/Anwendungsrechte. SSH bleibt schlüsselbasiert, ohne Passwort- oder Root-Login.
|
||
|
||
Die drei Gruppen sind VPN-Netzwerkrollen. Alte Full-Admin-Peers müssen ausdrücklich Familie oder Server Admin zugeordnet werden. Jeder Peer gehört zu einem einzelnen Gerät und einer dokumentierten Rolle.
|
||
|
||
### 2.4 LLM User (Anwendungsrolle)
|
||
|
||
Kein privilegierter Netzwerkzugang.
|
||
|
||
**Zugang:**
|
||
|
||
HTTPS über NPM zur LiteLLM-API.
|
||
|
||
**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 | Familie | Server Admin | LLM Admin | LLM User / öffentlich |
|
||
| --- | --- | --- | --- | --- |
|
||
| Heimnetz-PCs / DHCP-Clients | erlaubt | gesperrt | gesperrt | gesperrt |
|
||
| Proxmox UI/SSH | erlaubt + Dienstauthentifizierung | erlaubt + Dienstauthentifizierung | gesperrt | gesperrt |
|
||
| Service-LXCs / NPM / wg-easy | erlaubt + Dienstauthentifizierung | erlaubt + Dienstauthentifizierung | gesperrt | nur veröffentlichte Anwendungen |
|
||
| KI-Server SSH/Management | erlaubt + Dienstauthentifizierung | erlaubt + Dienstauthentifizierung | erlaubt + Dienstauthentifizierung | gesperrt |
|
||
| Keycloak Administration | intern, nach Dienstberechtigung | intern, nach Dienstberechtigung | gesperrt | Soll: gesperrt; Ist: öffentlich erreichbar |
|
||
| benötigte OIDC-Endpunkte | anwendungsbezogen | anwendungsbezogen | anwendungsbezogen | öffentlich für Login |
|
||
| LiteLLM API | nach API-Policy | nach API-Policy | nach API-Policy | Soll: HTTPS + individueller API-Key |
|
||
| OpenWebUI / weitere Webanwendungen | nach Anwendungsrechten | nach Anwendungsrechten | nach Anwendungsrechten | Soll: HTTPS und geeignete Anmeldung |
|
||
| llama.cpp / Datenbanken | nur nach Backend-/Dienstpolicy | nur nach Backend-/Dienstpolicy | nur KI-Server-bezogen nach Bedarf | nicht direkt öffentlich |
|
||
|
||
Das ist die Sollmatrix. Per-Client Firewall ist aktuell deaktiviert; Keycloak-Admin-Exposure ist durch einen externen Betreiber-Test bestätigt. Keine Sollfreigabe wird damit als bereits sicher implementiert behauptet.
|
||
|
||
---
|
||
|
||
## 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:
|
||
|
||
Benutzer melden sich an der zentralen Keycloak-Identitätsquelle an. Die vorgesehenen Anwendungen binden diese per OIDC ein.
|
||
|
||
Administrative Keycloak-Funktionen müssen auf interne berechtigte Zugriffe beschränkt werden. Ist: externe Admin-Anmeldung möglich, Korrektur in GNAI-005 dokumentiert. Laut Betreiber wird OIDC produktiv nur für Vaultwarden genutzt; Nextcloud, Gitea, OpenWebUI und weitere Dienste sind geplant.
|
||
|
||
---
|
||
|
||
### 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:
|
||
|
||
Der Client erreicht LiteLLM per HTTPS über NPM; LiteLLM nutzt intern 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:
|
||
|
||
WireGuard-Zielberechtigung und eigener SSH-Public-Key-Login.
|
||
|
||
Passwort- und Root-Login über SSH bleiben deaktiviert.
|
||
|
||
---
|
||
|
||
## 5. Netzwerk-Autorisierung
|
||
|
||
Familie erhält ausdrücklich Heimnetz-Vollzugriff. Server Admins und LLM Admins erhalten nur die beschlossenen Zielhosts. Die **serverseitigen Firewall Allowed IPs** in wg-easy sollen diese Rechte durchsetzen, während clientseitige Allowed IPs nur Routing festlegen. Ein Benutzer darf die Serverbeschränkung nicht durch Änderungen an seinem lokalen Profil umgehen können. Für Gateway-eigene Dienste wird die INPUT-Chain separat geprüft und anhand zugeordneter VPN-Quellen begrenzt.
|
||
|
||
Aktuell fehlt die Per-Client-Durchsetzung. Negative Tests müssen mit absichtlich erweitertem Client-Routing und aktivem Zielservice stattfinden. Normale LLM-Anwendungsnutzer erhalten keinen Managementpeer. Geräteprofile werden durch Administratoren erstellt und geschützt verteilt. Die GUI ist für Familie und Server Admins vorgesehen.
|
||
|
||
MASQUERADE wird mangels Rückroute verwendet; es verbirgt gegenüber LAN-Diensten die ursprüngliche Peer-IP. Zielkontrolle muss daher am VPN-Gateway vor NAT erfolgen. Lokale LAN-Quellen lassen sich nicht allein durch die VPN-Rolle gruppengenau zuordnen; hierfür sind zusätzliche Regeln/Identitäten nötig.
|
||
|
||
---
|
||
|
||
## 6. Vorgesehene öffentliche und private Erreichbarkeit
|
||
|
||
Die folgende Einordnung ist das Zielmodell. LiteLLM und die Webanwendungen auf dem KI-Server werden erst im späteren Ansible-Sprint eingerichtet.
|
||
|
||
### Ö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 vorhandenen NPM-Jails sind in [GNAI-005](GNAI-005-SEC_Reverse-Proxy.md) dokumentiert. Ihre Funktion nach dem Image-Pin sowie Neustart und Wiederanlauf müssen noch abgenommen werden.
|
||
|
||
---
|
||
|
||
## 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:
|
||
|
||
| Ereignis / Berechtigung | darf keinen automatischen Zugriff geben auf |
|
||
| --- | --- |
|
||
| kompromittiertes Webkonto | Proxmox |
|
||
| gestohlener API-Key | SSH |
|
||
| kompromittierter LLM-Container | WireGuard-Administration |
|
||
| LLM-Admin-Peer | Proxmox-Netzwerkzugang |
|
||
| öffentliche NPM-Verbindung | direkte interne Backendports |
|
||
|
||
Das Sicherheitsmodell basiert damit nicht auf einem einzelnen „Security-Programm“, sondern auf der Kombination mehrerer voneinander unabhängiger Kontrollen.
|
||
|
||
---
|
||
|
||
## 11. Umsetzungsnachweise
|
||
|
||
Dieses Dokument definiert die Zugriffsziele. Der [Dokumentationsindex](GNAI-000-DOC_Index.md) bündelt den aktuellen Projektstand. Konkrete Gateway-Regeln und Rollentests stehen in [GNAI-006](GNAI-006-SEC_VPN.md), der Keycloak-Adminpfad und Fail2Ban in [GNAI-005](GNAI-005-SEC_Reverse-Proxy.md). Offene Zielrechte gelten bis zu ihrer technischen Abnahme nicht als durchgesetzt.
|