Dokumente vereinheitlicht.

This commit is contained in:
2026-09-19 15:55:58 +02:00
parent 35bca033a6
commit 7d1a3228ef
15 changed files with 1120 additions and 849 deletions
+54 -143
View File
@@ -2,9 +2,19 @@
**Dokumenten-ID:** GNAI-004-SEC
**Titel:** Homelab / LLM-Infrastruktur – Sicherheits-, Authentifizierungs- und Zugriffskonzept
**Version:** 1.0
**Status:** Architekturentscheidung
**Vorgänger / Referenzen:** GNAI-003-INFRA
**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. |
---
@@ -25,66 +35,27 @@ Ziel ist Least Privilege bei gleichzeitig überschaubarer Administration.
## 2. Rollenmodell
### 2.1 Full Admin
### 2.1 Familie
Vollständiger privilegierter Infrastrukturzugriff.
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.
**Netzwerkzugang:**
### 2.2 Server Admin
- WireGuard
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.
**Erlaubte Zielbereiche:**
### 2.3 LLM Admin
- Proxmox Management
- LLM Server
- weitere explizit freigegebene Managementsysteme
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.
**Zusätzliche Authentifizierung:**
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.
- 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
### 2.4 LLM User (Anwendungsrolle)
Kein privilegierter Netzwerkzugang.
**Zugang:**
```text
HTTPS → NPM → LiteLLM
```
HTTPS über NPM zur LiteLLM-API.
**Authentifizierung:**
@@ -109,20 +80,19 @@ Ein normaler LLM User erhält **keinen WireGuard-Peer**, sofern für einen konkr
## 3. Zugriffsmatrix
| Ziel | Full Admin | LLM Admin | LLM User | Öffentlich |
| Ziel | Familie | Server 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 | ❌ | ❌ |
| 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.
---
@@ -149,15 +119,9 @@ Keycloak ist die zentrale Identitätsquelle für webbasierte Benutzeranwendungen
Ziel:
```text
Benutzer
↓
Keycloak
↓ OIDC
Nextcloud / Gitea / OpenWebUI / weitere Services
```
Benutzer melden sich an der zentralen Keycloak-Identitätsquelle an. Die vorgesehenen Anwendungen binden diese per OIDC ein.
Administrative Keycloak-Funktionen bleiben auf das Managementnetz beschränkt.
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.
---
@@ -167,15 +131,7 @@ Die LLM-API ist ein anwendungsbezogener Dienst und wird deshalb nicht durch eine
Ziel:
```text
Client
↓ HTTPS
NPM
↓
LiteLLM
↓
llama.cpp
```
Der Client erreicht LiteLLM per HTTPS über NPM; LiteLLM nutzt intern llama.cpp.
Die Autorisierung erfolgt über API-Keys.
@@ -194,11 +150,7 @@ SSH wird auf dem LLM-Server schlüsselbasiert betrieben.
Zusätzliche Schutzschicht:
```text
WireGuard
+
SSH Public Key
```
WireGuard-Zielberechtigung und eigener SSH-Public-Key-Login.
Passwort- und Root-Login über SSH bleiben deaktiviert.
@@ -206,29 +158,17 @@ Passwort- und Root-Login über SSH bleiben deaktiviert.
## 5. Netzwerk-Autorisierung
WireGuard-Peers werden nicht pauschal für das gesamte LAN freigeschaltet.
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.
Zugriff ist mindestens nach folgendem Muster zu definieren:
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.
```text
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.
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. Public vs. Private Exposure
## 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
@@ -268,7 +208,7 @@ 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.
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.
---
@@ -343,47 +283,18 @@ Die Zielarchitektur soll sicherstellen, dass ein kompromittierter Bestandteil m
Beispiele:
```text
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
```
| 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. Offene Implementierungsdetails
## 11. Umsetzungsnachweise
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. |
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.