13 KiB
Security & Access Control Specification
Dokumenten-ID: GNAI-005-SEC
Titel: Homelab / LLM-Infrastruktur – Sicherheits-, Authentifizierungs- und Zugriffskonzept
Status: Verbindliches Zielmodell; technische Durchsetzung teilweise offen
Vorgänger / Referenzen: Architektur, LXC-SSH, 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-006 geführt. |
| 2026-09-18 | 1.3 | spektr | KI-Anwendungsdienste als Zielbild und bestehende Fail2Ban-Jails als dokumentierten Ist-Stand eingeordnet. |
| 2026-09-21 | 1.4 | spektr / Codex | Zugriffsziel von einer vorentschiedenen LiteLLM-Implementierung auf eine noch festzulegende API-Policy-Schicht verallgemeinert |
| 2026-09-24 | 1.5 | Codex | Einfache serverseitige SSH-Netzbaseline festgelegt: TCP 22 aus lokalem LAN und über WireGuard erreichbar, öffentliche Netze gesperrt; Anmeldung weiterhin nur mit individuellen Public Keys. |
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 freigegebenen LLM-API-Policy-Schicht.
Authentifizierung:
- API-Key
Erlaubt:
- Nutzung der von der API-Policy 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 |
| LLM API | nach API-Policy | nach API-Policy | nach API-Policy | Soll: HTTPS + individuelles Credential |
| 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-006 dokumentiert. Laut Betreiber wird OIDC produktiv nur für Vaultwarden genutzt; Nextcloud, Gitea, OpenWebUI und weitere Dienste sind geplant.
4.3 LLM-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 die beschlossene API-Policy-Schicht per HTTPS über NPM;
diese nutzt intern llama.cpp. LiteLLM ist dafür ein Kandidat, aber bis zur
Produkt- und Policy-Entscheidung keine zwingende Komponente.
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 den Servern schlüsselbasiert betrieben. Die serverseitige Netzbaseline erlaubt TCP 22 aus dem lokalen LAN sowie für Verkehr, der über das WireGuard-Gateway zum Server gelangt. Eine zusätzliche Einschränkung auf eine einzelne Admin-Workstation oder deren dynamische DHCP-Adresse ist nicht vorgesehen. Öffentliche Netze bleiben ausgeschlossen.
Diese grobe Netzgrenze ersetzt keine Authentifizierung: Jeder tatsächliche Login benötigt einen individuell zugeordneten SSH-Public-Key. Passwort- und Root-Login über SSH bleiben deaktiviert. Die Umgebung verwendet derzeit Public-Key-Authentifizierung, keine von einer SSH-CA signierten OpenSSH-Zertifikate.
VPN-Rollen dürfen weiterhin vorgelagert am WireGuard-Gateway steuern, welche Zielserver ein Peer überhaupt erreicht. Die Zielserver führen jedoch keine zusätzliche per-Workstation- oder per-Peer-SSH-Allowlist.
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. Die LLM-API-Policy-Schicht und die Webanwendungen auf dem KI-Server werden erst nach der jeweiligen Produktentscheidung eingerichtet.
Öffentlich
- HTTP/HTTPS auf NPM
- für den VPN-Betrieb: WireGuard UDP-Port
- OIDC-Endpunkte, soweit für Web-Login erforderlich
- freigegebene LLM-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-006 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-007, der Keycloak-Adminpfad und Fail2Ban in GNAI-006. Offene Zielrechte gelten bis zu ihrer technischen Abnahme nicht als durchgesetzt.