florian.wildeandClaude Opus 5.5
5d03681f3c
Eine begonnene Rotation ließ sich nicht zurücknehmen; nahm ein Host den neuen Key dauerhaft nicht an, blieb nur das Übergehen. Abbrechen verwirft jetzt den neuen Key samt Private Key, ein Dry-Run nimmt ihn wieder von den Hosts, und eine neue Rotation kann sofort starten. Nebenbei: Aktionen der Benutzerverwaltung (#035) bekommen im Audit-Log eine eigene Gruppe, statt den Filter „Anmeldung“ zu verwässern; der E2E-Test für lokale Konten hängt nicht mehr von der Reihenfolge ab. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
258 lines
13 KiB
Markdown
258 lines
13 KiB
Markdown
# 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)
|
||
12. [Einstellungen und Benachrichtigungen](#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:
|
||
|
||
```bash
|
||
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“).
|
||
|
||
|
||
|