Merge branch 'phase/029-handbuch'

# Conflicts: # src/worker/index.ts
2026-10-12 16:56:22 +02:00
parent b99d19ec8c 7721a9f764
commit ca05d6a58e
13 changed files with 701 additions and 3 deletions
@@ -0,0 +1,216 @@
+# SSHKeyVault – Handbuch
+
+SSHKeyVault (`sshkv`) verwaltet SSH-Schlüssel zentral: Schlüsselpaare erzeugen, Public Keys in
+`authorized_keys` verteilen, Private Keys gezielt auf andere Hosts legen, Ist und Soll abgleichen –
+alles protokolliert. Installation und Betrieb: [../betrieb/installation.md](../betrieb/installation.md),
+Sicherung: [../betrieb/sicherung.md](../betrieb/sicherung.md), Sicherheit:
+[../betrieb/sicherheit.md](../betrieb/sicherheit.md).
+
+**Grundsatz:** Auf einem Host ändert sich nur etwas, nachdem Sie einen **Dry-Run** gesehen und
+„Änderung anwenden“ geklickt haben. Alles, was sshkv in `authorized_keys`, `~/.ssh/config` und
+`known_hosts` schreibt, steht in einem verwalteten Block:
+
+```
+# BEGIN SSHKV MANAGED – nicht manuell bearbeiten
+…
+# END SSHKV MANAGED
+```
+
+Zeilen außerhalb dieses Blocks bleiben unverändert – außer Sie übernehmen einen Schlüssel ausdrücklich
+in die Verwaltung.
+
+1. [Anmelden](#1-anmelden)
+2. [Übersicht](#2-übersicht)
+3. [Einen Host aufnehmen](#3-einen-host-aufnehmen)
+4. [Kern-Anwendungsfall: Host A meldet sich bei Host B an](#4-kern-anwendungsfall-host-a-meldet-sich-bei-host-b-an)
+5. [Deployment-Zugang für Claude Code mit dem Assistenten](#5-deployment-zugang-für-claude-code-mit-dem-assistenten)
+6. [Abgleich, Drift und Übernahme](#6-abgleich-drift-und-übernahme)
+7. [Rotation und Widerruf](#7-rotation-und-widerruf)
+8. [Personen, Self-Service und Zuweisungsmatrix](#8-personen-self-service-und-zuweisungsmatrix)
+9. [Vorlagen](#9-vorlagen)
+10. [Private Key anzeigen oder löschen](#10-private-key-anzeigen-oder-löschen)
+11. [Audit-Log](#11-audit-log)
+
+---
+
+## 1. Anmelden
+
+![Anmeldeseite](bilder/anmelden-desktop.png)
+
+- **Mit authentik anmelden** – der Normalfall. Ihre Rolle (Leser, Operator, Admin) kommt aus den
+  authentik-Gruppen und wird bei jeder Anmeldung neu bestimmt.
+- **Notfallzugang** – nur, wenn authentik ausfällt. Anmeldename, Passwort und ein Code aus einer
+  Authenticator-App. Bei der ersten Anmeldung richtet der Notfall-Admin den zweiten Faktor ein
+  (QR-Code scannen, Code bestätigen).
+
+Kritische Aktionen (Private Key anzeigen, Benutzer mit sudo anlegen, Massenwiderruf, Host-Key
+ersetzen) verlangen eine **erneute Bestätigung**; sie gilt fünf Minuten.
+
+## 2. Übersicht
+
+![Übersicht](bilder/uebersicht-desktop.png)
+
+Kennzahlen, Hosts mit Abweichung, bald ablaufende Schlüssel und die letzten Aktionen. Von hier aus:
+**Jetzt abgleichen** (alle Hosts), **Host-zu-Host-Assistent**, **Neuer Schlüssel**.
+
+## 3. Einen Host aufnehmen
+
+**Hosts → + Host anlegen:** Name (z. B. `srv-pve01`), Adresse, Port, Gruppen, Tags. Bei
+**Anmeldung** ist „Dienstbenutzer `sshkv` mit sudo“ empfohlen – im auth.log des Hosts ist dann
+eindeutig zu sehen, was von sshkv kam, und root-Login kann aus bleiben.
+
+**Host-Key bestätigen.** „Host-Key abrufen“ holt den Fingerprint, ohne sich anzumelden. Vergleichen
+Sie ihn direkt am Host:
+
+```bash
+ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub
+```
+
+![Host-Key bestätigen](bilder/hostkey-bestaetigen-desktop.png)
+
+Erst nach „Fingerprint stimmt – vertrauen“ verbindet sich sshkv. Ändert sich der Host-Key später,
+bricht jede Verbindung ab und die Hostseite warnt deutlich – annehmen nur, wenn der Host wirklich neu
+installiert wurde.
+
+**Bootstrap.** Zwei Wege, den Deployment-Key von sshkv auf den Host zu bringen:
+
+- **Einmalig per Passwort** (root oder ein Benutzer mit sudo). Das Passwort wird nicht gespeichert.
+- **Per Befehl:** den angezeigten Befehl auf dem Host einfügen, danach „Einrichtung prüfen“.
+
+![Eingerichteter Host](bilder/host-eingerichtet-desktop.png)
+
+Danach zeigt die Hostseite den **sshd-Befund**. Steht dort „root darf sich per Passwort anmelden“,
+empfiehlt sich `PermitRootLogin prohibit-password` in `/etc/ssh/sshd_config` – sshkv ändert das nicht
+von sich aus.
+
+## 4. Kern-Anwendungsfall: Host A meldet sich bei Host B an
+
+Beispiel: Der Backup-Server `srv-backup01` soll sich als `root` per SSH auf `srv-pve01` anmelden.
+Beide Hosts sind aufgenommen (Kapitel 3).
+
+**1. Schlüssel erzeugen.** *Schlüssel → + Schlüssel anlegen → Erzeugen*: Zweck „Backup srv-backup01 →
+srv-pve01“, Typ ed25519, optional Ablaufdatum. Keine Passphrase – ein Cronjob kann sie nicht eingeben.
+
+![Schlüssel anlegen](bilder/schluessel-neu-desktop.png)
+
+**2a. Private Key auf A.** In der Karte *Private Key ausgerollt auf* → **+ Ausrollen**: Quell-Host
+`srv-backup01`, Benutzer `root`, Pfad `~/.ssh/id_ed25519_…`. Mit **Eintrag in ~/.ssh/config** und
+Ziel-Host `srv-pve01` legt sshkv einen Alias an und trägt den (bereits bestätigten) Host-Key von B in
+`known_hosts` von A ein. *HostName* ist die Adresse, unter der **A** den Host B erreicht.
+
+**2b. Public Key auf B.** In der Karte *Public Key ausgerollt auf* → **+ Ausrollen**: Ziel
+`srv-pve01`, Benutzer `root`, optional Einschränkungen wie `from="10.0.0.12",no-pty`.
+
+2a und 2b sind unabhängig und jederzeit nachholbar.
+
+**3. Dry-Run und anwenden.** *Dry-Run starten* zeigt je Host, was sich ändert – beim Private Key nur
+„wird angelegt“, nie den Inhalt.
+
+![Dry-Run](bilder/kern-dry-run-desktop.png)
+
+„Änderung anwenden“ schreibt genau das, was Sie gesehen haben (mit Sicherung der Dateien). Hat sich
+in der Zwischenzeit etwas auf dem Host geändert, bricht sshkv ab – dann den Dry-Run neu starten.
+
+**4. Verbindung testen.** In der Private-Karte „Verbindung testen“ ruft auf A
+`ssh -o BatchMode=yes <alias> true` auf – genau das, was später der Cronjob braucht.
+
+![Ausgerollt und getestet](bilder/kern-ausgerollt-desktop.png)
+
+## 5. Deployment-Zugang für Claude Code mit dem Assistenten
+
+Szenario: Claude Code auf `srv-rz-claude-linux` soll eine Anwendung per SSH auf `srv-app01`
+ausrollen. **Übersicht → Host-zu-Host-Assistent** (nur Admins):
+
+1. **Vorlage „Deployment-Zugang“** wählen, Zweck „Claude Code Deployment → srv-app01“. Die Vorlage
+   setzt Benutzer `deploy`, 90 Tage Laufzeit, `from="<IP von A>"` und den Alias `deploy-<Ziel>`.
+2. **Quelle:** `srv-rz-claude-linux`, Benutzer, unter dem Claude Code läuft.
+3. **Ziel:** `srv-app01`, Benutzer `deploy` – „Benutzer anlegen“ ist vorgewählt; sudo nach Bedarf
+   (keine, bestimmte Befehle mit Vorschau der sudoers-Datei, oder voll). Fingerprint von B bestätigen.
+
+![Assistent – Ziel](bilder/assistent-ziel-desktop.png)
+
+4. **Prüfen** und „Vorbereiten“: sshkv erzeugt den Schlüssel, legt `deploy` an (frische Bestätigung
+   nötig – sie öffnet sich in einem neuen Tab, Ihre Eingaben bleiben stehen) und legt die
+   Zuweisungen an.
+5. **Ausrollen:** Dry-Run, anwenden, „Verbindung von A nach B testen“.
+
+![Assistent – fertig](bilder/assistent-fertig-desktop.png)
+
+Claude Code kann danach einfach `ssh deploy-srv-app01` benutzen. Wählen Sie `root` als Ziel, warnt
+der Assistent: Ein KI-Agent hätte dann uneingeschränkten Zugriff.
+
+**Nach Projektende** (oder Ablaufdatum): auf der Schlüsselseite **Widerrufen** – entfernt Public und
+Private Key, config- und known_hosts-Eintrag und auf Wunsch den Benutzer `deploy` samt sudoers-Datei.
+
+## 6. Abgleich, Drift und Übernahme
+
+Nachts um 02:30 (einstellbar) und auf Knopfdruck vergleicht sshkv jeden Host mit dem Soll. Gefunden
+werden fehlende Schlüssel, von Hand geänderte Blöcke, **unbekannte Schlüssel** außerhalb des Blocks,
+falsche Rechte von `~/.ssh` und veränderte Private Keys. Der Abgleich ändert auf dem Host nichts.
+
+![Abgleich](bilder/abgleich-desktop.png)
+
+Ein unbekannter Schlüssel lässt sich **übernehmen**: nur als bekannt aufnehmen (der Befund
+verschwindet) oder „in den verwalteten Block holen“ – dann wandert die Zeile beim nächsten Ausrollen
+(mit Dry-Run) in den Block.
+
+## 7. Rotation und Widerruf
+
+**Rotieren** (Schlüsselseite): Ein neuer Schlüssel kommt an alle Stellen des alten, der Alias in
+`~/.ssh/config` zeigt auf die neue Datei, die Verbindungen werden getestet – **erst dann** wird der
+alte entfernt. Die Rotation lässt sich jederzeit fortsetzen.
+
+![Rotation](bilder/rotation-desktop.png)
+
+**Widerrufen** (Schlüsselseite, Gefahr-Knopf): Der Dialog zeigt, was entfernt wird; danach Dry-Run
+und anwenden. Ist ein Host nicht erreichbar, bleibt der Schlüssel als „Widerruf unvollständig“
+markiert, bis auch dort alles entfernt ist. **Massenwiderruf:** in der Schlüsselliste mehrere
+auswählen (nur Admin).
+
+![Widerruf](bilder/widerruf-desktop.png)
+
+## 8. Personen, Self-Service und Zuweisungsmatrix
+
+- **Personen:** Admins, Mitarbeiter, Dienstleister mit ihren Schlüsseln. Private Keys von Personen
+  speichert sshkv nie.
+- **Meine Schlüssel:** Jede angemeldete Person kann eigene Public Keys hinterlegen. Wirksam werden
+  sie erst, wenn ein Operator oder Admin sie einem Host zuweist.
+
+![Meine Schlüssel](bilder/meine-schluessel-desktop.png)
+
+- **Zuweisungen:** Matrix Schlüssel × Host mit Filtern; ein Klick auf eine Zelle zeigt die
+  Zuweisungen und erlaubt neue. Export als CSV.
+
+![Zuweisungen](bilder/zuweisungen-desktop.png)
+
+## 9. Vorlagen
+
+Vorlagen legen Schlüsseltyp, Laufzeit, Zielbenutzer (samt Anlegen und sudo), `authorized_keys`-
+Optionen und das Alias-Muster vor. Platzhalter: `{{quellHost}}`, `{{quellHostIp}}`, `{{zielHost}}`,
+`{{zielHostIp}}`. Eingebaut: „Deployment-Zugang“, „Backup-Zugang“, „Admin-Zugang Person“.
+
+![Vorlage bearbeiten](bilder/vorlage-bearbeiten-desktop.png)
+
+## 10. Private Key anzeigen oder löschen
+
+Nur Admins, nur nach erneuter Bestätigung: „anzeigen (Re-Auth)“ in der Info-Leiste eines Schlüssels.
+Der Key wird genau einmal ausgeliefert und nirgends zwischengespeichert; jede Anzeige steht im
+Protokoll. **Private Key löschen** entfernt ihn endgültig aus sshkv – auf den Hosts bleibt er; neu
+ausrollen geht danach nicht mehr.
+
+## 11. Audit-Log
+
+Jede Aktion steht im **Audit-Log**: Zeitpunkt, Benutzer, Host, Zielbenutzer, Fingerprint, das Diff
+der geänderten Datei und das Ergebnis – nie ein Private Key oder Passwort. Einträge lassen sich
+weder ändern noch löschen; jeder Eintrag ist per Hash mit seinem Vorgänger verkettet.
+
+![Audit-Log](bilder/protokoll-desktop.png)
+
+- **Filter** nach Zeitraum, Aktionsgruppe, Benutzer, Host, Ergebnis und Freitext; eine Zeile
+  aufklappen zeigt Diff, Details und Hashes.
+- **Kette prüfen** rechnet alle Hashes nach. Wurde eine Zeile an sshkv vorbei in der Datenbank
+  verändert, zeigt die Seite die erste betroffene Zeile.
+- **CSV-Export** mit denselben Filtern (der Export selbst wird protokolliert).
+- **Syslog:** Mit `SSHKV_SYSLOG_HOST` geht jeder Eintrag zusätzlich an einen zentralen Syslog-Server
+  (z. B. für Zabbix) – eine Kopie außerhalb von sshkv.
+