sshkeyvault/docs/anleitung/README.md

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, Sicherung: ../betrieb/sicherung.md, Sicherheit: ../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
2. Übersicht
3. Einen Host aufnehmen
4. Kern-Anwendungsfall: Host A meldet sich bei Host B an
5. Deployment-Zugang für Claude Code mit dem Assistenten
6. Abgleich, Drift und Übernahme
7. Rotation und Widerruf
8. Personen, Self-Service und Zuweisungsmatrix
9. Vorlagen
10. Private Key anzeigen oder löschen
11. Audit-Log
12. Einstellungen und Benachrichtigungen

---

1. Anmelden

• Mit authentik anmelden – der Normalfall. Ihre Rolle (Leser, Operator, Admin) kommt aus den authentik-Gruppen und wird bei jeder Anmeldung neu bestimmt.
• Lokales Konto – ohne authentik oder zusätzlich dazu. Ein Admin legt das Konto an und gibt Ihnen ein Einmal-Passwort. Bei der ersten Anmeldung (Abschnitt „Lokales Konto oder Notfallzugang“) setzen Sie ein eigenes Passwort (mindestens 12 Zeichen) und richten den zweiten Faktor ein: QR-Code mit einer Authenticator-App scannen, Code bestätigen. Danach immer Anmeldename, Passwort und Code.
• Notfallzugang – nur, wenn authentik ausfällt. Gleiches Formular; der Notfall-Admin richtet bei der ersten Anmeldung ebenfalls den zweiten Faktor ein.

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

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:

ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub

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

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.

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.

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

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.

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

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.

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.

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

Deployment-Key rotieren (Einstellungen → Instanz, nur Admin): fünf Schritte – neuen Key erzeugen, per Dry-Run auf alle Hosts verteilen (er steht dann neben dem alten), die Anmeldung mit dem neuen Key prüfen, umstellen und zuletzt den alten per Dry-Run aufräumen. Scheitert die Prüfung auf einem Host, lässt er sich bewusst übergehen; sshkv erreicht ihn danach nur noch nach einem neuen Bootstrap. Solange noch nicht umgestellt ist, lässt sich die Rotation abbrechen: Der neue Key wird verworfen, ein Dry-Run nimmt ihn wieder von den Hosts.

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.

• Zuweisungen: Matrix Schlüssel × Host mit Filtern; ein Klick auf eine Zelle zeigt die Zuweisungen und erlaubt neue. Export als CSV.

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

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.

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

12. Einstellungen und Benachrichtigungen

Benutzer (Einstellungen → Instanz → „Konten verwalten“, nur Admin): lokale Konten anlegen – sshkv erzeugt das Einmal-Passwort und zeigt es genau einmal –, Rollen ändern, Konten sperren (beendet laufende Sitzungen sofort) und zurücksetzen (neues Einmal-Passwort, TOTP neu einrichten, etwa nach verlorenem Telefon). Konten aus authentik erscheinen nach ihrer ersten Anmeldung; ihre Rolle kommt aus den Gruppen, sie lassen sich hier nur sperren. Der Notfall-Admin ist unveränderlich.

Unter Einstellungen (ändern nur Admins) richten Sie Benachrichtigungen ein:

• E-Mail über SMTP – für Microsoft 365 vorbelegt (smtp.office365.com:587, STARTTLS).
• Webhook (nur https://, außer ausdrücklich für interne Ziele erlaubt) mit optionaler Signatur X-Sshkv-Signatur: sha256=… über den Inhalt.
• Anlässe einzeln schaltbar: neue Abweichungen, Schlüssel, die in 30/14/7 Tagen ablaufen, abgelaufene, aber noch ausgerollte Schlüssel, nicht erreichbare Hosts – als tägliche Zusammenfassung um 07:00 (SSHKV_MELDUNG_CRON) – und geänderte Host-Keys sofort.
• Testnachricht senden je Kanal; die letzten Zustellungen stehen darunter. Jede Meldung geht nur einmal hinaus; fehlgeschlagene werden einige Male wiederholt.

Passwörter und Geheimnisse werden verschlüsselt gespeichert und nie wieder angezeigt („gesetzt“).