🗝️ vault-conductor

Un agente SSH che fornisce chiavi SSH salvate come segreti in Bitwarden Secret Manager.

Supporta l'autenticazione SSH e la firma dei commit Git.

Demo

Funzionalità

Implementa il protocollo SSH Agent come server su socket di dominio Unix, fungendo da ponte sicuro tra i tuoi client SSH e Bitwarden Secrets Manager.

Le sue caratteristiche includono:

• Ciclo di vita dell'agente: funziona come processo daemon (in background) o in primo piano, in ascolto su un socket Unix in /tmp/vc-$(whoami)-ssh-agent.sock
• Caricamento lazy delle chiavi: le chiavi SSH vengono recuperate da Bitwarden tramite il loro SDK Rust ufficiale solo quando richieste, poi memorizzate nella cache in memoria
• Operazioni SSH sicure: quando i client SSH interrogano le identità o richiedono firme, l'agente gestisce le richieste usando la crate ssh-agent-lib senza mai esporre le chiavi private su disco
• Gestione dei processi: la modalità background genera un processo figlio distaccato, tiene traccia del PID e supporta l'arresto graduale tramite SIGTERM/SIGINT
• Sicurezza: i permessi del socket sono bloccati a 0600 (solo proprietario), le chiavi vivono solo nella memoria del processo e le API di Bitwarden vengono chiamate usando un machine token con scope limitato che puoi configurare con accesso granulare ai segreti.

Sotto il cofano, è costruito con Tokio per I/O asincrono, usa la crate ssh-key per le operazioni crittografiche e supporta sia chiavi Ed25519 che RSA in formato OpenSSH.

Perché

È nato da una mia necessità. La funzionalità Bitwarden SSH Agent nel client GUI di Bitwarden è comoda, ma cosa usare se hai solo una devbox CLI? Come portare in modo sicuro la tua chiave SSH in una pipeline CI/CD per firmare i commit git? E se devi aprire una connessione SSH da un container o una VM effimeri senza copiare alcuna chiave privata? Come evitare di avere a che fare con passphrase salvate nel portachiavi e legate alle sessioni di login?

Così ho scritto un piccolo strumento CLI per recuperare le chiavi SSH e renderle disponibili senza esporre la loro controparte privata.

E per evitare di portare l'intero vault Bitwarden nell'ambiente, usa Bitwarden Secrets Manager così puoi scegliere quale macchina può accedere a quale segreto e impostare permessi granulari per i token.

Requisiti

• Un account Bitwarden con Bitwarden Secret Manager configurato (che puoi creare e impostare gratuitamente) (il supporto per Bitwarden self-hosted è in programma)
• Una chiave SSH Ed25519 o RSA nel nuovo formato OpenSSH salvata come valore segreto in BWS
  • Deve essere salvata includendo le stringhe -----BEGIN OPENSSH PRIVATE KEY----- e -----END OPENSSH PRIVATE KEY-----.
  • Nota: il nuovo formato di chiave privata OpenSSH è stato introdotto con OpenSSH 7.8 nel 2018.
• macOS o Linux rilasciati negli ultimi 5 anni

Installazione

Usa uno dei metodi seguenti.

poof

Usando poof:

poof install pirafrank/vault-conductor

Script one-liner

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

Homebrew

brew tap pirafrank/tap
brew install vault-conductor

Manualmente

oppure scarica manualmente l'ultima versione stabile e mettila nel $PATH.

Dal sorgente

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

Configurazione

Devi fornire:

• BWS_ACCESS_TOKEN, il machine token che hai configurato sopra. La variabile d'ambiente ha lo stesso nome dello strumento CLI bws di Bitwarden
• BW_SECRET_IDS, elenco separato da virgole di UUID dei segreti in cui è salvata ciascuna chiave privata. Puoi leggere l'UUID di ogni segreto nell'app web BWS (controlla sotto il nome del segreto).
• BW_SERVER_ENDPOINT (Opzionale), endpoint del server Bitwarden personalizzato (solo host, senza protocollo). Se non fornito, il valore predefinito è bitwarden.com. Esempi validi sono bitwarden.eu (cloud) e myvault.example.com, 192.168.1.100, vault.internal (self-hosted).

Puoi passarle come variabili d'ambiente sopra indicate (ottimo per setup CI e DevOps) oppure tramite file di configurazione:

# 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

Utilizzo

# 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

Il comando start supporta anche l'opzione --config per fornire un percorso di configurazione personalizzato. Le variabili d'ambiente hanno sempre la precedenza sul file di configurazione.

Debug

A volte potresti aver bisogno di fare debug di una situazione strana e ti serve la massima quantità di log possibile. Esegui quanto segue per avviare in primo piano e ottenere log verbose su stdout:

vault-conductor start --fg -vv

Installazione come servizio

Puoi installarlo come servizio Systemd nello spazio utente. Leggi di più qui.

Documentazione

Controlla la directory docs per trovare diagrammi su come funziona ed è organizzato il codice. Consulta la politica di sicurezza prima di usare chiavi RSA o fare forwarding dell'agente.

Prossimi passi

• Supporto di più chiavi SSH
• Supporto per setup Bitwarden self-hosted
• Testing migliore
• Offrire più metodi di installazione (Homebrew, AUR, nix, .deb, .rpm)
• Supportare provider diversi da Bitwarden?

Sul nome

vault, /voːlt/ - una stanza sotterranea, soprattutto per conservare oggetti di valore

conductor, /kənˈdʌk·tər/ - un direttore, una cosa che conduce calore o elettricità

per estensione, qualcosa che conduce la tua preziosa chiave SSH da un vault Bitwarden al tuo ambiente di sviluppo.

Licenza

Questo progetto è concesso in licenza sotto la MIT License.

Vedi il file LICENSE per i dettagli.