🗝️ vault-conductor

Un agente SSH que proporciona claves SSH almacenadas como secretos en Bitwarden Secret Manager.

Admite autenticación SSH y firma de commits de Git.

Demostración

Características

Implementa el Protocolo de Agente SSH como servidor de socket de dominio Unix, actuando como un puente seguro entre tus clientes SSH y Bitwarden Secrets Manager.

Incluye:

• Ciclo de vida del agente: Se ejecuta como daemon (en segundo plano) o como proceso en primer plano, escuchando en un socket Unix en /tmp/vc-$(whoami)-ssh-agent.sock
• Carga diferida de claves: Las claves SSH se obtienen de Bitwarden mediante su SDK oficial de Rust solo cuando se solicitan y luego se almacenan en caché en memoria
• Operaciones SSH seguras: Cuando los clientes SSH consultan identidades o solicitan firmas, el agente gestiona las solicitudes usando la crate ssh-agent-lib sin exponer nunca las claves privadas al disco
• Gestión de procesos: El modo en segundo plano genera un proceso hijo separado, realiza un seguimiento del PID y admite un apagado controlado mediante SIGTERM/SIGINT
• Seguridad: Los permisos del socket están restringidos a 0600 (solo el propietario), las claves viven únicamente en la memoria del proceso y las API de Bitwarden se invocan mediante un token de máquina con ámbito limitado que puedes configurar con acceso granular a los secretos.

Internamente, está construido con Tokio para E/S asíncrona, usa la crate ssh-key para operaciones criptográficas y admite claves Ed25519 y RSA en formato OpenSSH.

Por qué

Nació de una necesidad mía. La función Bitwarden SSH Agent en el cliente GUI de Bitwarden es práctica, pero ¿qué usar si ejecutas tu devbox solo con CLI? ¿Cómo llevar tu clave SSH de forma segura a un pipeline de CI/CD para firmar commits de git? ¿Qué pasa si necesitas abrir una conexión SSH desde un contenedor o VM efímero sin copiar ninguna clave privada? ¿Cómo evitar lidiar con frases de contraseña almacenadas en el llavero y vinculadas a sesiones de inicio de sesión?

Así que escribí una pequeña herramienta CLI para recuperar claves SSH y hacerlas disponibles sin exponer su contraparte privada.

Y para evitar llevar toda tu bóveda de Bitwarden al entorno, usa Bitwarden Secrets Manager para que puedas elegir qué máquina puede acceder a qué secreto y establecer permisos de token granulares.

Requisitos

• Una cuenta de Bitwarden con Bitwarden Secrets Manager configurado (que puedes crear y configurar gratis) (el soporte para Bitwarden autoalojado está planificado)
• Una clave SSH Ed25519 o RSA en el nuevo formato OpenSSH guardada como valor de secreto en BWS
  • Debe guardarse incluyendo las cadenas -----BEGIN OPENSSH PRIVATE KEY----- y -----END OPENSSH PRIVATE KEY-----.
  • Nota: el nuevo formato de clave privada OpenSSH se introdujo con OpenSSH 7.8 en 2018.
• macOS o Linux lanzados en los últimos 5 años

Instalación

Usando uno de los métodos siguientes.

poof

Usando poof:

poof install pirafrank/vault-conductor

Script de una línea

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

Homebrew

brew tap pirafrank/tap
brew install vault-conductor

Manual

o descargando manualmente la última versión estable y colocándola en $PATH.

Desde el código fuente

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

Configuración

Debes proporcionar:

• BWS_ACCESS_TOKEN, el token de máquina que configuraste arriba. La variable de entorno tiene el mismo nombre que la herramienta CLI bws de Bitwarden
• BW_SECRET_IDS, lista de UUIDs de secretos separados por comas donde se almacena cada clave privada. Puedes leer el UUID de cada secreto en la aplicación web de BWS (consúltalo bajo el nombre del secreto).
• BW_SERVER_ENDPOINT (opcional), endpoint personalizado del servidor de Bitwarden (solo host, sin protocolo). Si no se proporciona, el valor predeterminado es bitwarden.com. Ejemplos válidos son bitwarden.eu (nube) y myvault.example.com, 192.168.1.100, vault.internal (autoalojado).

Puedes pasarlas como las variables de entorno anteriores (ideal para configuraciones de CI y DevOps) o mediante un archivo de configuración:

# 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

Uso

# 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

El comando start también admite la opción --config para proporcionar una ruta de configuración personalizada. Las variables de entorno siempre tienen prioridad sobre el archivo de configuración.

Depuración

A veces puede que necesites depurar una situación extraña y necesites la mayor cantidad de registros posible. Ejecuta lo siguiente para correr en primer plano y obtener registros detallados en la salida estándar:

vault-conductor start --fg -vv

Instalar como servicio

Puedes instalarlo como un servicio Systemd en el espacio de usuario. Lee más aquí.

Documentación

Consulta el directorio docs para encontrar diagramas sobre cómo funciona el código y cómo está organizado. Consulta la política de seguridad antes de usar claves RSA o reenviar el agente.

Próximos pasos

• Soporte para múltiples claves SSH
• Soporte para configuraciones de Bitwarden autoalojado
• Mejores pruebas
• Ofrecer más formas de instalación (Homebrew, AUR, nix, .deb, .rpm)
• ¿Soporte para proveedores distintos de Bitwarden?

Sobre el nombre

vault, /voːlt/ - una habitación subterránea, especialmente para guardar objetos de valor

conductor, /kənˈdʌk·tər/ - un director, algo que conduce calor o electricidad

por extensión, algo que conduce tu valiosa clave SSH desde una bóveda de Bitwarden hasta tu entorno de desarrollo.

Licencia

Este proyecto está licenciado bajo la Licencia MIT.

Consulta el archivo LICENSE para más detalles.