Files

T

2026-08-28 18:54:45 +02:00

8.7 KiB

Raw Blame History

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:

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:

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:

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:

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:

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:

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.

8.7 KiB Raw Blame History Unescape Escape