Files

T

florian.wildeandClaude Opus 5.5 3b28f73c95 docs(betrieb): Handbuch, Bedrohungsanalyse, geprobte Sicherung (#029 )

Handbuch mit Bildern fuer alle Ablaeufe, darunter der Kern-
Anwendungsfall und der Deployment-Zugang fuer Claude Code.
Betriebsdoku zu Installation, authentik und Reverse Proxy sowie eine
Bedrohungsanalyse mit Notfallplan fuer den Fall, dass sshkv selbst
kompromittiert wird.

Sicherung und Wiederherstellung als Skripte, auf einem Wegwerf-Stapel
geprobt. Dabei fielen zwei Fehler auf: das Schema der Warteschlange
liess sich nicht zurueckspielen, und ein Abbruch ohne Transaktion
loeschte es halb. Jetzt nur Schema public, in einer Transaktion, mit
Pruefwert des Master-Keys. Der Worker startet nicht, wenn der
Master-Key nicht zur Datenbank passt.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>

2026-10-12 16:46:38 +02:00

4.7 KiB

Raw Blame History

Installation und Betrieb

SSHKeyVault läuft als Docker-Compose-Stapel aus drei Diensten plus einem einmaligen Migrationslauf:

Dienst	Aufgabe	Netz	Geheimnisse
`db`	PostgreSQL 17	nur intern (`internal: true`)	Datenbankpasswort
`migrate`	Schema einspielen, Notfall-Admin und Vorlagen anlegen (läuft bei jedem Start einmal)	intern	Notfall-Passwort beim ersten Start
`web`	Weboberfläche (Port 3400)	intern + nach außen zum OIDC-Anbieter	`SSHKV_APP_SECRET`, OIDC-Client-Secret – kein Master-Key
`worker`	SSH zu den Hosts, Ver-/Entschlüsselung, Zeitpläne	intern + zu den Hosts	Master-Key (Docker-Secret), `SSHKV_APP_SECRET`

Voraussetzungen

Linux-Host mit Docker und Docker Compose v2, im internen Netz bzw. nur per VPN erreichbar.
Der Worker muss die zu verwaltenden Hosts per SSH erreichen (Port 22 oder den jeweiligen Port).
authentik (oder ein anderer OIDC-Anbieter) für die Anmeldung.
Ein Reverse Proxy mit TLS vor der Weboberfläche.

Schritt für Schritt

sudo mkdir -p /opt/sshkv && cd /opt/sshkv
git clone <repo> .                      # oder Release entpacken
cp .env.example .env && chmod 600 .env

In .env eintragen (Kommentare in der Datei erklären jede Variable):

POSTGRES_PASSWORD – openssl rand -hex 24
SSHKV_APP_SECRET – openssl rand -base64 48
SSHKV_APP_URL – die Adresse, unter der Benutzer sshkv aufrufen, z. B. https://sshkv.intern.example.de
SSHKV_BREAKGLASS_PASSWORD – mindestens 16 Zeichen; Notfall-Admin notfall
SSHKV_OIDC_* – siehe unten

Master-Key erzeugen und nur für den Worker lesbar machen:

sudo mkdir -p geheim
sudo sh -c 'head -c 32 /dev/urandom > geheim/master.key'
sudo chown 1001:1001 geheim/master.key && sudo chmod 400 geheim/master.key

Starten:

docker compose up -d --build
docker compose logs -f worker        # „sshkv-worker … bereit“

Beim ersten Start legt migrate das Schema, den Notfall-Admin und die eingebauten Vorlagen an; der Worker erzeugt den Deployment-Key der Instanz. Danach sofort den Master-Key sichern (sicherung.md).

authentik einrichten

Provider „OAuth2/OpenID Provider“ anlegen: Client-Typ confidential, Redirect-URI https://sshkv.intern.example.de/api/auth/oidc/rueckruf, Scopes openid profile email und ein Scope-Mapping, das die Gruppen als Claim groups liefert (in authentik Standard).
Application „SSHKeyVault“ mit diesem Provider anlegen.
Gruppen sshkv-admins, sshkv-operators, sshkv-readers anlegen und Benutzer zuordnen (Namen änderbar über SSHKV_OIDC_GROUP_*). Wer in keiner Gruppe ist, kommt nicht hinein.
In .env: SSHKV_OIDC_ISSUER=https://authentik.example.de/application/o/sshkv/, SSHKV_OIDC_CLIENT_ID, SSHKV_OIDC_CLIENT_SECRET, SSHKV_OIDC_NAME=authentik.

Erneute Bestätigung vor kritischen Aktionen schickt prompt=login und max_age=0; sshkv prüft auth_time im ID-Token. authentik liefert auth_time standardmäßig.

Rolle	darf
Leser	alles ansehen, eigene Public Keys hinterlegen
Operator	zusätzlich Hosts verwalten, Host-Keys bestätigen, Schlüssel erzeugen, Public Keys ausrollen, abgleichen
Admin	zusätzlich Private Keys ausrollen/anzeigen/löschen, Zielkonten mit sudo, Massenwiderruf, Einstellungen, Vorlagen

Reverse Proxy (Beispiel Caddy)

sshkv.intern.example.de {
    tls internal                      # oder das interne Zertifikat
    @extern not remote_ip 10.0.0.0/8 192.168.0.0/16
    respond @extern 403
    reverse_proxy 127.0.0.1:3400
}

Wichtig: SSHKV_APP_URL muss die Adresse mit https:// sein – davon hängen Secure-Cookie und OIDC-Rückruf ab.

Hosts vorbereiten

Debian/Ubuntu mit openssh-server, sudo, runuser (util-linux), base64, sha256sum, visudo (bei Dienstbenutzer) – auf Standardinstallationen vorhanden.
Für den Bootstrap per Passwort einmalig ein Konto mit Passwort-Login (root oder ein Benutzer mit sudo). Danach kann Passwort-Login aus; sshkv zeigt den sshd-Befund an.

Aktualisieren

cd /opt/sshkv
sudo bash deploy/sichern.sh
git pull
docker compose up -d --build         # migrate spielt neue Migrationen ein

Variablen (Auswahl)

Variable	Bedeutung
`SSHKV_SYNC_CRON`	Zeitplan des Abgleichs (Standard `30 2 * * *`, Europe/Berlin)
`SSHKV_MELDUNG_CRON`	tägliche Zusammenfassung der Benachrichtigungen
`SSHKV_SYSLOG_HOST`/`_PORT`/`_PROTOKOLL`	Kopie des Protokolls an einen Syslog-Server
`SSHKV_WORKER_USER`	Benutzer des Worker-Containers, falls die Master-Key-Datei nicht UID 1001 gehört
`SSHKV_BIND` / `SSHKV_PORT`	Bindeadresse/Port der Weboberfläche (Standard `127.0.0.1:3400`)

4.7 KiB Raw Blame History Unescape Escape