🗝️ vault-conductor

Un agent SSH qui fournit les clés SSH stockées dans Bitwarden Secrets Manager sous forme de secrets.

Prend en charge l'authentification SSH et la signature des commits Git.

Demo

Fonctionnalités

Il implémente le protocole SSH Agent en tant que serveur de socket de domaine Unix, agissant comme un pont sécurisé entre vos clients SSH et Bitwarden Secrets Manager.

Il offre :

• Cycle de vie de l'agent : s'exécute en tant que démon (arrière-plan) ou processus de premier plan, en écoute sur un socket Unix à /tmp/vc-$(whoami)-ssh-agent.sock
• Chargement paresseux des clés : les clés SSH sont récupérées depuis Bitwarden via son SDK Rust officiel uniquement à la demande, puis mises en cache en mémoire
• Opérations SSH sûres : lorsque les clients SSH interrogent les identités ou demandent des signatures, l'agent traite les requêtes à l'aide de la crate ssh-agent-lib sans jamais exposer les clés privées sur le disque
• Gestion des processus : le mode arrière-plan lance un processus enfant détaché, suit le PID et prend en charge l'arrêt propre via SIGTERM/SIGINT
• Sécurité : les permissions du socket sont verrouillées à 0600 (propriétaire uniquement), les clés ne résident qu'en mémoire dans le processus, et les API Bitwarden sont appelées à l'aide d'un jeton machine à portée limitée que vous pouvez configurer avec un accès granulaire aux secrets.

Sous le capot, il est construit avec Tokio pour les E/S asynchrones, utilise la crate ssh-key pour les opérations cryptographiques et prend en charge les clés Ed25519 et RSA au format OpenSSH.

Pourquoi

C'est né d'un besoin personnel. La fonctionnalité Bitwarden SSH Agent du client graphique Bitwarden est pratique, mais quoi utiliser si vous n'utilisez que votre CLI sur votre machine de dev ? Comment amener en toute sécurité votre clé SSH dans un pipeline CI/CD pour signer des commits git ? Et si vous devez ouvrir une connexion SSH depuis un conteneur ou une VM éphémère sans copier de clé privée ? Comment éviter de gérer des phrases secrètes stockées dans le trousseau et liées aux sessions de connexion ?

J'ai donc écrit un petit outil CLI pour récupérer les clés SSH et les rendre disponibles sans exposer leur contrepartie privée.

Et pour éviter d'apporter tout votre coffre Bitwarden dans l'environnement, il utilise Bitwarden Secrets Manager afin que vous puissiez choisir quelle machine peut accéder à quel secret et définir des permissions de jeton granulaires.

Prérequis

• Un compte Bitwarden avec Bitwarden Secrets Manager configuré (que vous pouvez créer et paramétrer gratuitement) (la prise en charge de Bitwarden auto-hébergé est prévue)
• Une clé SSH Ed25519 ou RSA au nouveau format OpenSSH enregistrée comme valeur secrète dans BWS
  • Elle doit être enregistrée en incluant les chaînes -----BEGIN OPENSSH PRIVATE KEY----- et -----END OPENSSH PRIVATE KEY-----.
  • Remarque : le nouveau format de clé privée OpenSSH a été introduit avec OpenSSH 7.8 en 2018.
• macOS ou Linux publié au cours des 5 dernières années

Installation

Soit en utilisant l'une des méthodes ci-dessous.

poof

En utilisant poof :

poof install pirafrank/vault-conductor

Script en une ligne

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

Homebrew

brew tap pirafrank/tap
brew install vault-conductor

Manuellement

ou en téléchargeant manuellement la dernière version stable et en la plaçant dans $PATH.

Depuis les sources

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

Configuration

Vous devez fournir :

• BWS_ACCESS_TOKEN, le jeton machine que vous avez configuré ci-dessus. La variable d'environnement porte le même nom que l'outil CLI bws de Bitwarden
• BW_SECRET_IDS, liste séparée par des virgules des UUID des secrets où chaque clé privée est stockée. Vous pouvez lire l'UUID de chaque secret dans l'application web BWS (vérifiez sous le nom du secret).
• BW_SERVER_ENDPOINT (facultatif), point de terminaison serveur Bitwarden personnalisé (hôte uniquement, sans protocole). S'il n'est pas fourni, la valeur par défaut est bitwarden.com. Des exemples valides sont bitwarden.eu (cloud) et myvault.example.com, 192.168.1.100, vault.internal (auto-hébergé).

Vous pouvez soit les passer comme variables d'environnement ci-dessus (idéal pour les configurations CI et DevOps), soit via un fichier de configuration :

# 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

Utilisation

# 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

La commande start prend également en charge l'option --config pour fournir un chemin de configuration personnalisé. Les variables d'environnement ont toujours priorité sur le fichier de configuration.

Débogage

Il peut arriver que vous ayez besoin de déboguer une situation étrange et de disposer d'un maximum de logs. Exécutez la commande suivante pour lancer en premier plan et obtenir des logs verbeux sur la sortie standard :

vault-conductor start --fg -vv

Installation en tant que service

Vous pouvez l'installer comme service Systemd dans l'espace utilisateur. En savoir plus ici.

Documentation

Consultez le répertoire docs pour trouver des schémas sur le fonctionnement et l'organisation du code. Consultez la politique de sécurité avant d'utiliser des clés RSA ou de transférer l'agent.

Prochaines étapes

• Prise en charge de plusieurs clés SSH
• Prise en charge des configurations Bitwarden auto-hébergées
• Meilleure couverture de tests
• Proposer davantage de méthodes d'installation (Homebrew, AUR, nix, .deb, .rpm)
• Prendre en charge d'autres fournisseurs que Bitwarden ?

À propos du nom

vault, /voːlt/ - une pièce souterraine, en particulier pour stocker des objets de valeur

conductor, /kənˈdʌk·tər/ - un directeur, une chose qui conduit la chaleur ou l'électricité

par extension, quelque chose qui conduit votre précieuse clé SSH d'un coffre Bitwarden vers votre environnement de développement.

Licence

Ce projet est sous licence MIT.

Voir le fichier LICENSE pour plus de détails.