# 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.