florian.wildeandClaude Opus 5.5
3b28f73c95
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>
69 lines
3.2 KiB
Markdown
69 lines
3.2 KiB
Markdown
# SSHKeyVault (`sshkv`)
|
||
|
||
Selbst gehostete Weboberfläche zur zentralen Verwaltung von SSH-Schlüsseln: Schlüsselpaare
|
||
erzeugen und verwalten, Public Keys in `authorized_keys` verteilen, Private Keys gezielt auf
|
||
andere Hosts ausrollen, Ist- und Soll-Zustand abgleichen – alles revisionssicher protokolliert.
|
||
|
||
> **Stand 0.1.0 (Phase 1):** Grundgerüst, Anmeldung (OIDC + Notfall-Admin mit TOTP), Hosts und
|
||
> Hostgruppen, Host-Key-Prüfung (TOFU) und Bootstrap neuer Hosts. Schlüsselverwaltung und
|
||
> Ausrollen folgen in Phase 2 und 3 – siehe [`docs/PLAN.md`](docs/PLAN.md).
|
||
|
||
## Sicherheit vorab
|
||
|
||
SSHKeyVault hat **root-Zugriff auf alle verwalteten Hosts**. Deshalb:
|
||
|
||
- nur im internen Netz bzw. VPN betreiben, mit Reverse Proxy und TLS davor;
|
||
- den **Master-Key** (`SSHKV_MASTER_KEY_FILE`) getrennt von der Datenbank sichern – ohne ihn
|
||
ist ein Datenbank-Backup wertlos, und mit ihm zusammen gibt es alle Private Keys preis;
|
||
- Private Keys liegen nur verschlüsselt in der Datenbank (AES-256-GCM, Envelope Encryption);
|
||
entschlüsseln kann ausschließlich der Worker, der Webprozess hat den Master-Key nicht.
|
||
|
||
Mehr dazu in [`docs/betrieb/sicherheit.md`](docs/betrieb/sicherheit.md) (mit Bedrohungsanalyse und
|
||
Notfallplan) und [`docs/betrieb/sicherung.md`](docs/betrieb/sicherung.md).
|
||
|
||
## Dokumentation
|
||
|
||
- [Handbuch](docs/anleitung/README.md) – Bedienung Schritt für Schritt mit Bildern
|
||
- [Installation und Betrieb](docs/betrieb/installation.md) – Docker Compose, authentik, Reverse Proxy
|
||
- [Sicherung und Wiederherstellung](docs/betrieb/sicherung.md) – `deploy/sichern.sh`, `deploy/wiederherstellen.sh`
|
||
- [Sicherheit](docs/betrieb/sicherheit.md) – Aufbau, Bedrohungsanalyse, Notfallplan
|
||
|
||
## Installation (Docker Compose)
|
||
|
||
```bash
|
||
cp .env.example .env # Werte eintragen, siehe Kommentare
|
||
openssl rand -base64 48 # → SSHKV_APP_SECRET
|
||
mkdir -p geheim && head -c 32 /dev/urandom > geheim/master.key
|
||
sudo chown 1001:1001 geheim/master.key && sudo chmod 400 geheim/master.key
|
||
docker compose up -d
|
||
```
|
||
|
||
Die Oberfläche lauscht auf `127.0.0.1:3400` (`SSHKV_BIND`, `SSHKV_PORT`). Beim ersten Start legt
|
||
der Dienst `migrate` das Schema, den Notfall-Admin (`SSHKV_BREAKGLASS_*`) und die eingebauten
|
||
Vorlagen an; der Worker erzeugt den Deployment-Key der Instanz.
|
||
|
||
**Anmeldung:** über authentik (`SSHKV_OIDC_*`, Rollen über die Gruppen `sshkv-admins`,
|
||
`sshkv-operators`, `sshkv-readers`). Der Notfall-Admin richtet bei der ersten Anmeldung TOTP ein.
|
||
|
||
## Einen Host aufnehmen
|
||
|
||
1. **Hosts → + Host anlegen** (Name, Adresse, Port; Anmeldung als Dienstbenutzer `sshkv` mit sudo
|
||
– empfohlen – oder direkt als root).
|
||
2. **Host-Key abrufen**, den Fingerprint am Host vergleichen
|
||
(`ssh-keygen -lf /etc/ssh/ssh_host_ed25519_key.pub`) und vertrauen.
|
||
3. **Bootstrap:** einmalig per Passwort (wird nicht gespeichert) oder den angezeigten Befehl auf
|
||
dem Host einfügen und „Einrichtung prüfen“.
|
||
|
||
## Entwicklung
|
||
|
||
Node 24, pnpm 12, Docker. Konventionen und Befehle: [`CLAUDE.md`](CLAUDE.md).
|
||
|
||
```bash
|
||
pnpm install
|
||
pnpm db:up && pnpm db:migrate && pnpm db:seed
|
||
pnpm test:ziele:up # SSH-Testziele + Mock-OIDC
|
||
pnpm build && pnpm start # http://localhost:3400
|
||
pnpm worker # zweites Terminal
|
||
pnpm test && pnpm test:integration && pnpm test:e2e
|
||
```
|