# 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:**

```text
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:

```text
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:

```text
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:

```text
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:

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

---

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

```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
```

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