12 KiB
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, Gateway, GUI-SOP, Reverse Proxy
Ä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.cppdirekt - 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 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 bündelt den aktuellen Projektstand. Konkrete Gateway-Regeln und Rollentests stehen in GNAI-006, der Keycloak-Adminpfad und Fail2Ban in GNAI-005. Offene Zielrechte gelten bis zu ihrer technischen Abnahme nicht als durchgesetzt.