commit 8c581330b37a40ae5c643d7a4f27a52cca149e8e Author: spektr Date: Fri Aug 28 18:54:45 2026 +0200 Initial commit diff --git a/docs/GNAI-001-INFRA_BaseSystem.md b/docs/GNAI-001-INFRA_BaseSystem.md new file mode 100644 index 0000000..461da2d --- /dev/null +++ b/docs/GNAI-001-INFRA_BaseSystem.md @@ -0,0 +1,203 @@ +# Standard Operating Procedure + +**Dokumenten-ID:** GNAI-001-INFRA +**Titel:** Initialisierung und OS-Installation: LLM-Server (Phase 1) +**Version:** 1.1 +**Status:** Architekturentscheidung +**Vorgänger / Referenzen:** - + +--- + +## 1. Zweck und Geltungsbereich + +Dieses Dokument beschreibt den standardisierten Prozess für die Hardware-Konfiguration, BIOS-Einstellung, Betriebssystem-Installation und Basis-Härtung von LLM-Servern (Large Language Model). Ziel ist die Gewährleistung einer reproduzierbaren, fehlerfreien und performanten Basis für die spätere KI-Anwendungssoftware. + +--- + +## 2. Spezifikationen (Hardware-Konfiguration) + +| Komponente | Spezifikation | Bemerkung | +| --- | --- | --- | +| **Gehäuse** | Silverstone SST-RM42-502 | Rackmount / Server-Chassis | +| **Mainboard** | ASRock Z790 PG Lightning | Socket LGA1700 | +| **CPU** | Intel Core i5-13600K | 14 Kerne (6P + 8E) | +| **CPU-Kühler** | Thermalright Peerless Assassin 120 Mini | - | +| **RAM** | Crucial Pro DDR5 RAM 64GB Kit (2x32GB) | Dimm Slot A2 & B2 | +| **PSU** | Corsair RM1200e | 1200W ATX 3.0 | +| **SSD** | 2 TB Samsung 970 EVO Plus | Primäre NVMe (Slot M2_1) | +| **GPU 1** | Sapphire Nitro+ AMD Radeon RX 6900 XT OC 16GB | PCIe Slot 1 (x16) | +| **GPU 2** | Sapphire Nitro+ AMD Radeon RX 6900 XT OC 16GB | PCIe Slot 2 (x8/x4 via PCH) | + +### 2.1 BIOS-Konfiguration + +Vor der Betriebssystem-Installation sind folgende Schritte im BIOS (Aufrufen via `DEL` oder `F2` beim Booten) durchzuführen: + +1. **Firmware-Update (Instant Flash):** +* BIOS-Datei auf einen FAT32-formatierten USB-Stick entpacken. +* Im BIOS navigieren zu: `Tool` -> `Instant Flash`. +* BIOS-Version auf **`19.02`** (oder neuer) aktualisieren. + + +2. **RAM-Performance:** +* Navigieren zu: `OC Tweaker` -> `DRAM Configuration`. +* **Load XMP Setting:** auf **XMP Profile 1** stellen. + + +3. **Virtualisierung & PCI-Einstellungen (Wichtig für GPU/ROCm):** +* Navigieren zu: `Advanced` -> `CPU Configuration` -> **Intel Virtualization Technology** -> `Enabled`. +* Navigieren zu: `Advanced` -> `PCI Configuration`: + * **Above 4G Decoding:** `Enabled` + * **Re-Size BAR Support:** `Enabled` *(Kritisch für AMD ROCm Multi-GPU-Performance!)* + +--- + +## 3. Installation des Betriebssystems + +### 3.1 Vorbereitung des Installationsmediums (am Admin-PC) + +1. **Debian ISO herunterladen:** + ```bash + curl -L -O https://cdimage.debian.org/debian-cd/current-minimal/amd64/iso-cd/debian-netinst.iso + ``` + +2. **Checksum verifizieren:** + ```bash + curl -O https://cdimage.debian.org/debian-cd/current/amd64/iso-cd/SHA512SUMS + sha512sum --ignore-missing -c SHA512SUMS + ``` + *Erwartete Ausgabe:* `debian-netinst.iso: OK` (Treffen Fehler auf, Download wiederholen). + +3. **Bootfähigen USB-Stick erstellen:** +* [Ventoy](https://www.ventoy.net) auf dem USB-Stick installieren. +* Die heruntergeladene ISO-Datei direkt per Dateimanager auf die Ventoy-Partition kopieren. + +--- + +### 3.2 Schritt-für-Schritt Installationsanleitung (Debian Netinst) + +1. **Booten:** +* USB-Stick einstecken, System starten und per `F11` das Boot-Menü öffnen. +* USB-Stick auswählen -> Im Ventoy-Menü `debian-netinst.iso` wählen -> **Graphical Install** auswählen. + +2. **Lokalisierung:** +* **Language:** `German - Deutsch` +* **Land/Territorium:** `Deutschland` +* **Tastaturlayout:** `Deutsch` + +3. **Netzwerk & Hostname:** +* **Hostname:** `ghostnet-ai-node-01` (oder entsprechend Vorgabe des IP-Plans). +* **Domain-Name:** `ghost.net` +* **Netzwerk:** Per DHCP konfigurieren lassen. *(Feste IP wird nach der Installation vergeben).* + +4. **Benutzerverwaltung:** +* **Root-Passwort:** Starkes Passwort aus dem Passwort-Manager eintragen. +* **Neuer Benutzer:** + * Vollständiger Name: `Admin` + * Benutzername: `gnaiadmin` + * Passwort: Sicheres Kennwort vergeben. + +5. **Partitionierung (Manuell / Geführt):** +* Methode: `Geführt - gesamte Festplatte verwenden`. +* Disk auswählen: `Samsung SSD 970 EVO Plus 2TB`. +* Schema: `Alle Dateien auf eine Partition (für Anfänger empfohlen)`. +* **Wichtig:** Änderungen auf die Festplatte schreiben -> `Ja`. + +6. **Paketmanager-Konfiguration:** +* Spiegelserver-Land: `Deutschland` +* `deb.debian.org` wählen. +* HTTP-Proxy: Leer lassen. + +7. **Software-Auswahl (Software selection):** +* [_] Debian desktop environment *(ABWÄHLEN)* +* [_] GNOME / KDE / etc. *(ABWÄHLEN)* +* [x] **SSH server** *(AUSWÄHLEN)* +* [x] **standard system utilities** *(AUSWÄHLEN)* + +8. **Bootloader (GRUB):** +* GRUB-Bootloader in den primären Laufwerksbereich installieren: `Ja` +* Gerät wählen: `/dev/nvme0n1` (Samsung SSD). + +9. **Abschluss:** +* USB-Stick entfernen und auf `Weiter` klicken, um das System neu zu starten. + +--- + +### 3.3 Post-Installation & Basis-Härtung (Erst-Setup via CLI) + +Nach dem Neustart als `root` am Terminal anmelden und folgende Schritte ausführen: + +#### 1. Sudo-Rechte für den Admin-User einrichten + +```bash +apt update && apt install -y sudo +usermod -aG sudo gnaiadmin +``` + +#### 2. Netzwerk auf Statische IP umstellen + +Datei `/etc/network/interfaces` anpassen (Beispiel-IP an den lokalen Netzwerkplan anpassen): + +```bash +nano /etc/network/interfaces +``` + +Inhalt anpassen/ergänzen: + +```text +auto enp8s0 +iface enp8s0 inet static + address 10.0.0.90/24 + gateway 10.0.0.1 + dns-nameservers 10.0.0.1 1.1.1.1 +``` + +Netzwerk neustarten: `systemctl restart networking` + +#### 3. Grundlegende Admin-Tools & Firmware installieren + +Da AMD RX 6900 XT GPUs verwendet werden, müssen die Unfree-Firmware-Pakete vorbereitet werden: + +```bash +# Non-free Repository aktivieren +apt install -y software-properties-common +apt-add-repository non-free-firmware -y +apt update + +# Grundlegende Tools und GPU-Firmware installieren +apt install -y curl wget git htop tmux pciutils firmware-amd-graphics firmware-linux-nonfree + +``` + +#### 4. SSH-Schlüssel hinterlegen (Remote-Zugriff) + +Wechsle zum Admin-User: + +```bash +su - gnaiadmin +mkdir -p ~/.ssh +chmod 700 ~/.ssh +nano ~/.ssh/authorized_keys # Public-Key des Admin-PCs einfügen +chmod 600 ~/.ssh/authorized_keys + +``` + +--- + +## 4. Abnahmekriterien + +Vor der Übergabe an das KI-Team (Phase 2) muss das System folgende Punkte bestehen: + +* **RAM-Check:** `free -h` zeigt mindestens ~62 GB RAM an. +* **GPU-Erkennung:** `lspci | grep -i vga` listet **beide** AMD RX 6900 XT Grafikkarten auf. +* **Netzwerk:** Der Server ist via SSH (`ssh gnaiadmin@`) vom Admin-PC erreichbar. +* **Storage:** `df -h /` zeigt die vollständige ~2 TB Partition an. +* **Re-Size BAR:** Prüfen mit `dmesg | grep -i BAR`. Es sollten Einträge vorhanden sein, die auf erfolgreiche Zuordnung hinweisen (ReBAR active). + +--- + +## 5. Dokumentation der Änderungen + +| Datum | Version | Geändert von | Beschreibung der Änderung | +| --- | --- | --- | --- | +| 2026-08-24 | 1.0 | spektr | Erstellung des Initial-Dokuments (Hardware & OS) | +| 2026-08-24 | 1.1 | spektr / Assistant | Detaillierung der BIOS-ReBAR-Settings, Netinst-CLI-Schritte, Post-Installation & Abnahmekriterien hinzugefügt. | \ No newline at end of file diff --git a/docs/GNAI-002-INFRA_Users.md b/docs/GNAI-002-INFRA_Users.md new file mode 100644 index 0000000..db4a12a --- /dev/null +++ b/docs/GNAI-002-INFRA_Users.md @@ -0,0 +1,245 @@ +# Standard Operating Procedure (SOP) + +**Dokumenten-ID:** GNAI-INFRA-002 + +**Titel:** Benutzerverwaltung, SSH-Härtung & Netzwerkkonfiguration (Phase 2) + +**Version:** 1.0 + +--- + +## 1. Zweck und Geltungsbereich + +Dieses Dokument beschreibt die Erstellung von Systembenutzern mit Berechtigungen, die Härtung des SSH-Dienstes (Abschaltung von Root-Login und Passwort-Authentifizierung), die Umstellung auf eine statische IP-Adresse sowie die Konfiguration des SSH-Zugriffs von Admin-Workstations auf LLM-Servern. + +--- + +## 2. Voraussetzungen & Berechtigungen + +* Bereits installiertes Debian-Grundsystem gemäß **GNAI-INFRA-001**. +* Root-Zugriff oder Benutzer mit `sudo`-Rechten. +* Admin-Workstation mit lokal installierter SSH-Suite (`ssh-keygen`, `ssh-copy-id`). + +--- + +## 3. Prozessbeschreibung + +### 3.1 Benutzerverwaltung & Sudo-Berechtigungen (Server-Seite) + +#### 1. Sudo-Paket installieren & prüfen (falls noch nicht geschehen) + +Als `root` am Server anmelden: + +```bash +su - +apt update && apt install -y sudo + +``` + +#### 2. Benutzer anlegen & Berechtigungen vergeben + +> **Wichtig:** Beim Anlegen von Benutzern immer `adduser` verwenden (interaktive Eingabe von Passwort und Benutzerdaten). Falls versehentlich `userdel` benötigt wird, zwingend die Option `-r` nutzen, um das Home-Verzeichnis mit aufzuräumen (`sudo userdel -r `). + +Neuen Benutzer anlegen und zur `sudo`-Gruppe hinzufügen: + +```bash +# Beispiel für Benutzer 'ghost' oder 'debugofen' +sudo adduser debugofen +sudo usermod -aG sudo debugofen + +``` + +--- + +### 3.2 Statische Netzwerkkonfiguration (Server-Seite) + +#### 1. Netzschnittstelle ermitteln & anpassen + +Lass dir die primäre Netzwerkschnittstelle anzeigen (z. B. `enp8s0`): + +```bash +ip addr show + +``` + +Bearbeite die Datei `/etc/network/interfaces`: + +```bash +sudo nano /etc/network/interfaces + +``` + +Netzwerkkonfiguration für statische IP eintragen: + +```text +# Loopback Interface +auto lo +iface lo inet loopback + +# Primary Network Interface +allow-hotplug enp8s0 +iface enp8s0 inet static + address 10.0.0.90/24 + gateway 10.0.0.1 + dns-nameservers 10.0.0.1 1.1.1.1 + +``` + +#### 2. DNS-Resolver prüfen/anpassen + +Prüfe die Datei `/etc/resolv.conf`: + +```bash +sudo nano /etc/resolv.conf + +``` + +Sicherstellen, dass folgende Nameserver eingetragen sind: + +```text +nameserver 10.0.0.1 +nameserver 1.1.1.1 + +``` + +#### 3. Netzwerkdienst neustarten & Funktion prüfen + +```bash +sudo systemctl restart networking +ip -4 addr +ping -c 4 google.com + +``` + +*(Tritt ein Konfigurationskonflikt auf, das System einmal per `sudo reboot` neustarten).* + +--- + +### 3.3 SSH-Key-Generierung & Übertragung (Workstation-Seite) + +Führe diese Schritte auf der **lokalen Workstation** aus. + +#### 1. Ed25519 SSH-Schlüsselpaar erzeugen + +```bash +ssh-keygen -t ed25519 -C "ghost@ghostnet-ki" -f ~/.ssh/id_ed25519_ghost +ssh-keygen -t ed25519 -C "debugofen@ghostnet-ki" -f ~/.ssh/id_ed25519_debugofen + +``` + +#### 2. Public Keys auf den Server übertragen + +Verwende `ssh-copy-id`, um die öffentlichen Schlüssel auf den Server zu kopieren (vorläufig noch mit Passwort-Authentifizierung): + +```bash +ssh-copy-id -i ~/.ssh/id_ed25519_ghost.pub ghost@10.0.0.90 +ssh-copy-id -i ~/.ssh/id_ed25519_debugofen.pub debugofen@10.0.0.90 + +``` + +#### 3. Schlüsselbasierten Login testen + +```bash +ssh -i ~/.ssh/id_ed25519_ghost ghost@10.0.0.90 +ssh -i ~/.ssh/id_ed25519_debugofen debugofen@10.0.0.90 + +``` + +#### 4. Workstation Client-Config einrichten (`~/.ssh/config`) + +Erstelle/bearbeite die Datei `~/.ssh/config` auf der Workstation, um Kurznamen für Verbindungen zu nutzen: + +```bash +nano ~/.ssh/config + +``` + +Inhalt eintragen: + +```text +Host * + AddKeysToAgent yes + IdentitiesOnly yes + +Host ghostnet.ki + Hostname 10.0.0.90 + User ghost + IdentityFile ~/.ssh/id_ed25519_ghost + +``` + +Berechtigungen auf der Workstation korrigieren: + +```bash +chmod 600 ~/.ssh/config + +``` + +Verbindung über den Alias testen: + +```bash +ssh ghostnet.ki + +``` + +--- + +### 3.4 SSH-Dienst härten (Server-Seite) + +Sobald der SSH-Key-Login erfolgreich getestet wurde, wird die Passwort-Authentifizierung aus Sicherheitsgründen serverseitig komplett deaktiviert. + +#### 1. Drop-in-Konfiguration für SSH erstellen + +```bash +sudo nano /etc/ssh/sshd_config.d/99-security.conf + +``` + +Füge folgenden Inhalt ein: + +```text +# Root-Login über SSH komplett verbieten +PermitRootLogin no + +# Passwort-Authentifizierung deaktivieren (nur SSH-Keys erlauben) +PasswordAuthentication no +KbdInteractiveAuthentication no + +# Leere Passwörter verbieten +PermitEmptyPasswords no + +# Nur explizite SSH-Key Methoden erlauben +PubkeyAuthentication yes + +``` + +#### 2. SSH-Konfiguration prüfen und Dienst neustarten + +> **Achtung:** Die bestehende SSH-Sitzung **nicht** schließen, bevor der Login in einem zweiten Terminalfenster erfolgreich verifiziert wurde! + +```bash +# Syntaktische Prüfung der Konfiguration +sudo sshd -t + +# Wenn sshd -t keine Fehler ausgibt, Dienst neustarten +sudo systemctl restart sshd + +``` + +--- + +## 4. Abnahmekriterien (Checkliste für den Junior-Admin) + +* [ ] **Benutzerprüfung:** Der Benutzer kann sich mit `sudo` administrative Rechte verschaffen (`whoami` nach `sudo` ergibt `root`). +* [ ] **Netzwerk:** Server ist unter der statischen IP `10.0.0.90` erreichbar. Ausgehender Datenverkehr funktioniert (`ping google.com`). +* [ ] **SSH-Alias:** Der Login von der Workstation über `ssh ghostnet.ki` funktioniert ohne Passworteingabe. +* [ ] **Root-Sperre:** Direct-Login als Root per SSH wird abgelehnt (`ssh root@10.0.0.90` -> *Permission denied*). +* [ ] **Passwort-Sperre:** Login-Versuch ohne hinterlegten SSH-Key wird direkt abgelehnt (keine Passwort-Aufforderung mehr). + +--- + +## 5. Dokumentation der Änderungen + +| Datum | Version | Geändert von | Beschreibung der Änderung | +| --- | --- | --- | --- | +| 2026-08-26 | 1.0 | spektr | Erstellung des Dokuments (Benutzer, Netzwerkkonfiguration, SSH-Härtung) | diff --git a/docs/GNAI-003-INFRA_Architecture.md b/docs/GNAI-003-INFRA_Architecture.md new file mode 100644 index 0000000..f7aa988 --- /dev/null +++ b/docs/GNAI-003-INFRA_Architecture.md @@ -0,0 +1,338 @@ +# Technical Architecture Specification + +**Dokumenten-ID:** GNAI-003-INFRA +**Titel:** Homelab / LLM-Infrastruktur – Zielarchitektur +**Version:** 1.0 +**Status:** Architekturentscheidung +**Vorgänger / Referenzen:** GNAI-001-INFRA, GNAI-002-INFRA + +--- + +## 1. Zweck und Geltungsbereich + +Dieses Dokument beschreibt die festgelegte Zielarchitektur für die sichere Bereitstellung des LLM-Servers und der öffentlich erreichbaren Webservices innerhalb der Ghostnet-Infrastruktur. + +Es handelt sich ausdrücklich um eine **technische Spezifikation und kein Installationshandbuch**. Konkrete Implementierungsanweisungen, Konfigurationsdateien und Abnahmetests werden in nachgelagerten SOPs dokumentiert. + +Die Architektur baut auf dem in **GNAI-001-INFRA** beschriebenen Debian-basierten LLM-Server und der in **GNAI-002-INFRA** beschriebenen SSH-/Benutzer-Härtung auf. + +--- + +## 2. Architekturprinzipien + +Die Infrastruktur folgt diesen Grundsätzen: + +1. **Minimale Internet-Exposure:** Aus dem Internet werden ausschließlich die tatsächlich benötigten öffentlichen Dienste freigegeben. +2. **Dedizierter Reverse Proxy:** Sämtliche öffentlichen HTTP(S)-Dienste werden über einen zentralen Nginx Proxy Manager (NPM) veröffentlicht. +3. **Managementnetz getrennt von Applikationszugriff:** Privilegierter Netzwerkzugriff erfolgt über WireGuard. +4. **Anwendungsidentität über Keycloak:** Webanwendungen verwenden OIDC zur zentralen Authentifizierung. +5. **LLM-API als dedizierte Applikationsschnittstelle:** Direkter Zugriff auf `llama.cpp` aus dem Internet ist nicht vorgesehen; die öffentliche LLM-Schnittstelle wird durch LiteLLM bereitgestellt. +6. **Defense in Depth:** Reverse Proxy, Fail2Ban, Firewall-Regeln, MFA, Patchmanagement, Monitoring und Backups ergänzen sich. +7. **Least Privilege:** Zugriffe werden pro Rolle, Peer, Host und Dienst eingeschränkt. +8. **Isolation:** Öffentlich exponierte Infrastruktur und einzelne Backend-Dienste bleiben logisch bzw. durch eigene LXCs getrennt. + +--- + +## 3. Netzwerk- und Hoststruktur + +### 3.1 Bestehende Proxmox-Struktur + +Der Proxmox-Server bildet die Virtualisierungs- und Isolationsschicht. + +| Komponente | Adresse | Rolle | +| --- | --- | --- | +| Proxmox VE | `10.0.0.2` | Virtualisierungs-/Managementhost | +| Reverse Proxy LXC | `10.0.0.10` | einziger öffentlicher HTTP(S)-Entry-Point | +| WireGuard LXC | `10.0.0.15` | VPN-/Managementzugang | +| LLM Server | gemäß IP-Plan, aktuell `10.0.0.90` | KI-Inferenz und LLM-Dienste | + +Die Service-LXCs (z. B. Nextcloud, Gitea, Vaultwarden, Keycloak etc.) verbleiben jeweils in eigenen LXCs und werden nicht in den Reverse-Proxy-LXC zusammengelegt. + +### 3.2 Perimeter + +Die Fritzbox 7530 bildet den Internet-Perimeter. + +Aus dem Internet sollen grundsätzlich nur die für den öffentlichen Betrieb erforderlichen Weiterleitungen existieren: + +- TCP 80 → Reverse Proxy LXC +- TCP 443 → Reverse Proxy LXC +- UDP auf dem festgelegten WireGuard-Port → WireGuard LXC + +Managementdienste wie Proxmox Web UI oder SSH werden **nicht direkt aus dem Internet veröffentlicht**. + +IPv4- und IPv6-Exposure sind gleichwertig zu betrachten und müssen bei der Implementierung separat verifiziert werden. + +--- + +## 4. Reverse-Proxy-LXC + +Der Reverse-Proxy-LXC (`10.0.0.10`) ist eine dedizierte Infrastrukturzone für öffentlich exponierte HTTP(S)-Komponenten. + +### 4.1 Containerisierung + +Innerhalb des LXCs wird Podman verwendet. + +Vorgesehene Container: + +- **Nginx Proxy Manager** +- **Fail2Ban** + +NPM und Fail2Ban befinden sich absichtlich im selben LXC. Dadurch kann Fail2Ban die Logdaten von NPM auswerten und – unter minimal erforderlichen Capabilities – die Netzwerk-/Firewallebene des eigenen LXCs absichern, ohne Zugriff auf die Firewall eines anderen LXCs zu benötigen. + +### 4.2 Verantwortlichkeiten + +**NPM** + +- TLS-Terminierung +- Reverse Proxy +- Routing zu internen Services +- HTTP(S)-Security-Header und weitere Proxy-Policies +- optionales Rate Limiting, soweit sinnvoll + +**Fail2Ban** + +- Erkennung wiederholter bzw. eindeutiger Missbrauchsmuster +- temporäre Sperrung auffälliger Quelladressen +- Auswertung gezielter NPM-/Applikationslogs + +Fail2Ban ist eine **zusätzliche Abuse-Protection-Schicht**, kein Ersatz für Patchmanagement, sichere Authentifizierung oder Netzwerksegmentierung. + +--- + +## 5. Öffentliche Webservices + +Alle öffentlich vorgesehenen Webservices werden hinter NPM veröffentlicht. + +Beispiele: + +### Services auf separaten Proxmox-LXCs + +- Nextcloud +- Gitea +- Vaultwarden +- Keycloak + +### Services auf dem LLM-Server + +- OpenWebUI +- GPT Researcher +- LiteLLM API + +Direkter Internetzugriff auf die internen Backend-Ports der Services ist nicht vorgesehen. + +--- + +## 6. LLM-Server-Architektur + +Der LLM-Server basiert auf der in **GNAI-001-INFRA** dokumentierten Debian-Basis mit AMD-Multi-GPU-Konfiguration und der in **GNAI-002-INFRA** vorgesehenen SSH-Key-basierten Absicherung. + +### 6.1 LLM-Inferenz + +`llama.cpp` stellt die eigentliche lokale Modell-Inferenz bereit. + +Grundsatz: + +> `llama.cpp` wird nicht direkt aus dem Internet exponiert. + +Der Zugriff erfolgt intern über die dafür vorgesehene API-Schicht. + +### 6.2 LiteLLM + +LiteLLM bildet die standardisierte OpenAI-kompatible API- und Policy-Schicht vor `llama.cpp`. + +Verantwortlichkeiten: + +- öffentliche API-Schnittstelle +- API-Key-Authentifizierung +- Routing zu laufenden Modellen +- ggf. Modell-/Benutzer-Policies +- Rate-/Quota-Steuerung +- Trennung der öffentlichen API von der eigentlichen Inferenz-Engine + +Zielpfad: + +```text +Internet Client + ↓ HTTPS +NPM + ↓ +LiteLLM + ↓ internes Container-/Host-Netz +llama.cpp + ↓ +GPU(s) +``` + +--- + +## 7. WireGuard-Managementnetz + +WireGuard ist die dedizierte Zugangsschicht für privilegierte Netzwerkzugriffe. + +### 7.1 Implementierung + +- eigener WireGuard-LXC auf Proxmox +- `wg-easy` als Podman-Container +- WireGuard-Peer-Authentifizierung ausschließlich über kryptografische Schlüssel +- kein OIDC für die eigentliche WireGuard-Peer-Authentifizierung + +### 7.2 Rollen + +**Full Admin** + +- Proxmox Management +- LLM-Server Management +- weitere ausdrücklich freigegebene Managementziele + +**LLM Admin** + +- ausschließlich LLM-Server Management +- insbesondere SSH und ggf. ausgewählte Managementschnittstellen + +Die WireGuard-Konfiguration ist peer-basiert. `AllowedIPs` und zusätzliche Firewall-Regeln werden gemeinsam verwendet; ein VPN-Peer erhält nicht automatisch vollständigen Zugriff auf das LAN. + +--- + +## 8. Keycloak / OIDC + +Keycloak ist die zentrale Identitäts- und Authentifizierungsplattform für die Webanwendungen. + +Vorgesehenes Modell: + +```text +Browser + ↓ HTTPS +NPM + ↓ +Web Service + ↓ OIDC +Keycloak +``` + +Die Webservices nutzen OIDC zur Benutzeridentifikation und Authentifizierung. + +Die Keycloak-Administrationsoberfläche und administrative Managementschnittstellen sollen nicht öffentlich zugänglich sein und werden über das Managementnetz bereitgestellt. + +Öffentlich erforderlich bleiben ausschließlich die für OIDC tatsächlich benötigten Endpunkte des jeweiligen Realms. + +--- + +## 9. SSH + +SSH auf dem LLM-Server wird ausschließlich schlüsselbasiert betrieben. + +Aus **GNAI-INFRA-002** übernimmt die Zielkonfiguration insbesondere: + +- `PermitRootLogin no` +- `PasswordAuthentication no` +- `KbdInteractiveAuthentication no` +- `PubkeyAuthentication yes` + +Der LLM-Server-SSH-Port wird nicht aus dem Internet veröffentlicht. + +Zulässige Herkunft: + +- lokales vertrauenswürdiges Netzwerk +- WireGuard-Managementnetz + +--- + +## 10. Sicherheitszonen und Vertrauensmodell + +Die Infrastruktur unterscheidet mindestens drei Vertrauensklassen: + +### Public Application Access + +Zugang über: + +```text +HTTPS → NPM +``` + +Authentifizierung erfolgt je nach Anwendung über: + +- OIDC / Keycloak +- API-Key bei der LLM-API + +### Management Access + +Zugang über: + +```text +WireGuard → Zielsystem +``` + +Zusätzliche Dienstauthentifizierung bleibt erhalten, z. B. SSH Public Keys oder Proxmox-Authentifizierung. + +### Backend Access + +Nicht öffentlich. + +Beispiele: + +- `llama.cpp` +- interne Datenbankports +- interne Container-/Serviceports +- sonstige administrative Backend-Schnittstellen + +--- + +## 11. Geplante Defense-in-Depth-Schichten + +Die Zielarchitektur sieht folgende komplementäre Schutzschichten vor: + +1. Fritzbox als Perimeter +2. keine unnötigen Portweiterleitungen +3. Proxmox-/LXC-Netzwerk- und Firewallregeln +4. dedizierter Reverse Proxy +5. Fail2Ban für erkannte Missbrauchsmuster +6. TLS/HTTPS +7. zentrale Authentifizierung mit Keycloak/OIDC +8. MFA/WebAuthn für privilegierte Benutzer, wo unterstützt +9. API-Keys bzw. OAuth-/Anwendungscredentials für Maschinenzugriffe +10. SSH ausschließlich über Schlüssel +11. regelmäßige Updates / Patchmanagement +12. Backup- und Restore-Strategie +13. externes Monitoring und regelmäßige Prüfung der öffentlichen Exposure + +--- + +## 12. Nicht Teil dieser Spezifikation + +Folgende Punkte sind Architekturentscheidungen vorbehalten und werden in Implementierungsdokumenten konkretisiert: + +- konkrete WireGuard-Subnetze und Peer-Adressen +- konkrete Firewall-Regelsätze +- genaue `wg-easy`-Version und Containerparameter +- genaue NPM-Container-/Storage-Konfiguration +- konkrete Fail2Ban-Jails und Filter +- konkrete LiteLLM-Modell- und Key-Policies +- konkrete Keycloak-Realm-/Client-Struktur +- konkrete DNS-/Domainnamen +- konkrete Backup- und Monitoring-Implementierung + +--- + +## 13. Architektur-Abnahmekriterien + +Die Architektur gilt als korrekt umgesetzt, wenn mindestens folgende Eigenschaften nachweisbar sind: + +- Nur vorgesehene öffentliche Ports sind aus dem Internet erreichbar. +- Proxmox ist nicht direkt aus dem Internet erreichbar. +- SSH des LLM-Servers ist nicht direkt aus dem Internet erreichbar. +- `llama.cpp` ist nicht direkt aus dem Internet erreichbar. +- Öffentliche Webservices terminieren an NPM. +- Fail2Ban befindet sich zusammen mit NPM im Reverse-Proxy-LXC. +- Full-Admin- und LLM-Admin-WireGuard-Peers besitzen unterschiedliche, restriktive Zugriffsprofile. +- Webanwendungen authentifizieren Benutzer über Keycloak/OIDC. +- Die LLM-API wird über LiteLLM bereitgestellt und über API-Key geschützt. +- Administrative Weboberflächen von Keycloak sind nicht öffentlich. +- Service-LXCs bleiben voneinander isoliert und erlauben nur erforderliche Kommunikationsbeziehungen. + +--- + +## 14. Änderungsverlauf + +| Datum | Version | Geändert von | Beschreibung | +| --- | --- | --- | --- | +| 2026-08-28 | 1.0 | spektr | Erstellung der Zielarchitektur | diff --git a/docs/GNAI-004-SEC_Access-Control.md b/docs/GNAI-004-SEC_Access-Control.md new file mode 100644 index 0000000..495cdd5 --- /dev/null +++ b/docs/GNAI-004-SEC_Access-Control.md @@ -0,0 +1,389 @@ +# 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. |