🗝️ vault-conductor

Ein SSH-Agent, der in Bitwarden Secret Manager als Secrets gespeicherte SSH-Schlüssel bereitstellt.

Unterstützt SSH-Authentifizierung und das Signieren von Git-Commits.

Demo

Funktionen

Es implementiert das SSH-Agent-Protokoll als Unix-Domain-Socket-Server und fungiert als sichere Brücke zwischen deinen SSH-Clients und Bitwarden Secrets Manager.

Es bietet:

• Agent-Lebenszyklus: Läuft als Daemon (Hintergrund) oder Vordergrundprozess und lauscht auf einem Unix-Socket unter /tmp/vc-$(whoami)-ssh-agent.sock
• Lazy Loading der Schlüssel: SSH-Schlüssel werden nur bei Bedarf über das offizielle Rust-SDK von Bitwarden abgerufen und dann im Speicher zwischengespeichert
• Sichere SSH-Operationen: Wenn SSH-Clients Identitäten abfragen oder Signaturen anfordern, verarbeitet der Agent die Anfragen mithilfe der Crate ssh-agent-lib, ohne private Schlüssel jemals auf der Festplatte offenzulegen
• Prozessverwaltung: Der Hintergrundmodus erzeugt einen abgekoppelten Kindprozess, verfolgt die PID und unterstützt ein sauberes Herunterfahren über SIGTERM/SIGINT
• Sicherheit: Socket-Berechtigungen sind auf 0600 (nur Eigentümer) festgelegt, Schlüssel befinden sich nur im Prozessspeicher, und Bitwarden-APIs werden über ein eingeschränktes Machine-Token aufgerufen, das du mit granularem Secret-Zugriff konfigurieren kannst.

Unter der Haube ist es mit Tokio für asynchrone I/O gebaut, verwendet die Crate ssh-key für kryptografische Operationen und unterstützt sowohl Ed25519- als auch RSA-Schlüssel im OpenSSH-Format.

Warum

Es entstand aus einer persönlichen Notwendigkeit. Die Funktion Bitwarden SSH Agent im Bitwarden-GUI-Client ist praktisch, aber was verwendest du, wenn du auf deiner Devbox nur die CLI nutzt? Wie bringst du deinen SSH-Schlüssel sicher in eine CI/CD-Pipeline, um Git-Commits zu signieren? Was, wenn du eine SSH-Verbindung aus einem ephemeren Container oder einer VM öffnen musst, ohne einen privaten Schlüssel zu kopieren? Wie vermeidest du den Umgang mit Passphrasen, die im Schlüsselbund gespeichert und an Anmeldesitzungen gebunden sind?

Also habe ich ein winziges CLI-Tool geschrieben, um SSH-Schlüssel abzurufen und verfügbar zu machen, ohne deren privates Gegenstück offenzulegen.

Und um zu vermeiden, dass dein gesamter Bitwarden-Tresor in die Umgebung gelangt, verwendet es Bitwarden Secrets Manager, sodass du wählen kannst, welche Maschine auf welches Secret zugreifen darf, und granulare Token-Berechtigungen festlegen kannst.

Voraussetzungen

• Ein Bitwarden-Konto mit eingerichtetem Bitwarden Secret Manager (den du kostenlos erstellen und einrichten kannst) (Unterstützung für selbst gehostetes Bitwarden ist geplant)
• Ein Ed25519- oder RSA-SSH-Schlüssel im neuen OpenSSH-Format, der als Secret-Wert in BWS gespeichert ist
  • Er muss einschließlich der Zeichenfolgen -----BEGIN OPENSSH PRIVATE KEY----- und -----END OPENSSH PRIVATE KEY----- gespeichert werden.
  • Hinweis: Das neue OpenSSH-Format für private Schlüssel wurde 2018 mit OpenSSH 7.8 eingeführt.
• macOS oder Linux, das in den letzten 5 Jahren veröffentlicht wurde

Installation

Entweder mit einer der folgenden Methoden.

poof

Mit poof:

poof install pirafrank/vault-conductor

Einzeiler-Skript

curl -fsSL https://raw.githubusercontent.com/pirafrank/vault-conductor/main/install.sh | sh

Homebrew

brew tap pirafrank/tap
brew install vault-conductor

Manuell

oder lade manuell das neueste stabile Release herunter und lege es in $PATH ab.

Aus dem Quellcode

cargo install --locked --git https://github.com/pirafrank/poof --tag VERSION

Konfiguration

Du musst Folgendes angeben:

• BWS_ACCESS_TOKEN, das Machine-Token, das du oben eingerichtet hast. Die Umgebungsvariable hat denselben Namen wie das CLI-Tool bws von Bitwarden
• BW_SECRET_IDS, kommagetrennte Liste der UUIDs von Secrets, in denen die jeweiligen privaten Schlüssel gespeichert sind. Du kannst die UUID jedes Secrets in der BWS-Web-App ablesen (unterhalb des Secret-Namens).
• BW_SERVER_ENDPOINT (optional), benutzerdefinierter Bitwarden-Server-Endpunkt (nur Host, ohne Protokoll). Wenn nicht angegeben, lautet der Standardwert bitwarden.com. Gültige Beispiele sind bitwarden.eu (Cloud) und myvault.example.com, 192.168.1.100, vault.internal (selbst gehostet).

Du kannst sie entweder als die oben genannten Umgebungsvariablen übergeben (gut für CI- und DevOps-Setups) oder über eine Konfigurationsdatei:

# download the example config file at the default path, then customize to your needs
mkdir ~/.config/vault-conductor
curl -sSL https://github.com/pirafrank/vault-conductor/raw/refs/heads/main/config.yaml.example > ~/.config/vault-conductor/config.yaml
chmod 0600 ~/.config/vault-conductor/config.yaml

Verwendung

# set SSH Agent env var to vault-conductor socket
export SSH_AUTH_SOCK="/tmp/vc-$(whoami)-ssh-agent.sock"

# Start in foreground
# (recommended for first time users to verify config is ok)
vault-conductor start --fg

# Start the agent in background
vault-conductor start

# Stop the background agent
vault-conductor stop

Der Befehl start unterstützt zusätzlich die Option --config, um einen benutzerdefinierten Konfigurationspfad anzugeben. Umgebungsvariablen haben immer Vorrang vor der Konfigurationsdatei.

Debuggen

Manchmal musst du eine merkwürdige Situation debuggen und benötigst so viele Logs wie möglich. Führe Folgendes aus, um im Vordergrund zu laufen und ausführliche Sysout-Logs zu erhalten:

vault-conductor start --fg -vv

Als Dienst installieren

Du kannst es als Systemd-Dienst im Userspace installieren. Mehr dazu hier.

Dokumentation

Schau in das Verzeichnis docs, um Diagramme darüber zu finden, wie der Code funktioniert und aufgebaut ist. Lies die Sicherheitsrichtlinie, bevor du RSA-Schlüssel verwendest oder den Agent weiterleitest.

Was kommt als Nächstes

• Mehrere SSH-Schlüssel unterstützen
• Selbst gehostete Bitwarden-Setups unterstützen
• Bessere Tests
• Weitere Installationsmöglichkeiten anbieten (Homebrew, AUR, nix, .deb, .rpm)
• Andere Anbieter als Bitwarden unterstützen?

Über den Namen

vault, /voːlt/ - ein unterirdischer Raum, besonders zur Aufbewahrung von Wertsachen

conductor, /kənˈdʌk·tər/ - ein Dirigent, eine Sache, die Wärme oder Strom leitet

im weiteren Sinne etwas, das deinen wertvollen SSH-Schlüssel aus einem Bitwarden-Tresor in deine Entwicklungsumgebung leitet.

Lizenz

Dieses Projekt ist unter der MIT-Lizenz lizenziert.

Siehe die Datei LICENSE für Details.