🗝️ vault-conductor

Um agente SSH que fornece chaves SSH armazenadas no Bitwarden Secret Manager como segredos.

Suporta autenticação SSH e assinatura de commits Git.

Demonstração

Funcionalidades

Ele implementa o protocolo do agente SSH como um servidor de socket Unix, atuando como uma ponte segura entre seus clientes SSH e o Bitwarden Secrets Manager.

Ele oferece:

• Ciclo de vida do agente: Executa como daemon (em segundo plano) ou processo em primeiro plano, escutando em um socket Unix em /tmp/vc-$(whoami)-ssh-agent.sock
• Carregamento sob demanda das chaves: As chaves SSH são buscadas no Bitwarden por meio do SDK oficial em Rust somente quando solicitadas e depois armazenadas em cache na memória
• Operações SSH seguras: Quando clientes SSH consultam identidades ou solicitam assinaturas, o agente lida com as solicitações usando o crate ssh-agent-lib sem nunca expor chaves privadas ao disco
• Gerenciamento de processos: O modo em segundo plano inicia um processo filho separado, rastreia o PID e suporta desligamento suave via SIGTERM/SIGINT
• Segurança: As permissões do socket são restritas a 0600 (apenas o proprietário), as chaves vivem apenas na memória do processo, e as APIs do Bitwarden são chamadas usando um token de máquina com escopo, que você pode configurar com acesso granular aos segredos.

Internamente, ele é construído com Tokio para I/O assíncrono, usa o crate ssh-key para operações criptográficas e suporta chaves Ed25519 e RSA no formato OpenSSH.

Motivação

A funcionalidade Bitwarden SSH Agent no cliente GUI do Bitwarden é prática, mas o que usar se você estiver usando apenas a CLI da sua máquina de desenvolvimento? Como trazer sua chave SSH com segurança para um pipeline de CI/CD para assinar commits git? E se você precisar abrir uma conexão SSH de um contêiner ou VM efêmero sem copiar nenhuma chave privada? Como evitar lidar com frases secretas (passphrases) armazenadas no keychain e vinculadas a sessões de login?

Isso nasceu de uma necessidade minha. Então escrevi uma pequena ferramenta CLI para recuperar chaves SSH e disponibilizá-las sem expor sua contraparte privada.

E para evitar levar todo o seu cofre Bitwarden para o ambiente, ela usa o Bitwarden Secrets Manager para que você possa escolher qual máquina pode acessar qual segredo e definir permissões granulares de token.

Requisitos

• Uma conta Bitwarden com o Bitwarden Secret Manager configurado (que você pode criar e configurar gratuitamente) (o suporte para Bitwarden self-hosted está planejado)
• Uma chave SSH Ed25519 ou RSA no novo formato OpenSSH salva como valor de segredo no BWS
  • Ela precisa ser salva incluindo as strings -----BEGIN OPENSSH PRIVATE KEY----- e -----END OPENSSH PRIVATE KEY-----.
  • Observação: o novo formato de chave privada OpenSSH foi introduzido com o OpenSSH 7.8 em 2018.
• macOS ou Linux lançados nos últimos 5 anos

Instalação

Use um dos métodos abaixo.

poof

Usando o poof:

poof install pirafrank/vault-conductor

Script de uma linha

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

Homebrew

brew tap pirafrank/tap
brew install vault-conductor

Manualmente

Ou baixe manualmente o último lançamento estável e coloque-o no $PATH.

A partir do código-fonte

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

Configuração

Você precisa fornecer:

• BWS_ACCESS_TOKEN, o token de máquina que você configurou acima. A variável de ambiente tem o mesmo nome da ferramenta CLI bws da Bitwarden
• BW_SECRET_IDS, lista separada por vírgulas de UUIDs de segredos onde cada chave privada está armazenada. Você pode ler o UUID de cada segredo no aplicativo web do BWS (confira abaixo do nome do segredo).
• BW_SERVER_ENDPOINT (Opcional), endpoint personalizado do servidor Bitwarden (somente host, sem protocolo). Se não for fornecido, o padrão é bitwarden.com. Exemplos válidos são bitwarden.eu (nuvem) e myvault.example.com, 192.168.1.100, vault.internal (self-hosted).

Você pode fornecê-los como as variáveis de ambiente acima (bom para configurações de CI e DevOps) ou via arquivo de configuração:

# 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

O comando start também suporta a opção --config para fornecer um caminho de configuração personalizado. As variáveis de ambiente sempre têm precedência sobre o arquivo de configuração.

Depuração

Às vezes, você pode precisar depurar uma situação estranha e obter o máximo de logs possível. Execute o seguinte para rodar em primeiro plano e obter logs detalhados na saída padrão:

vault-conductor start --fg -vv

Instalar como serviço

Você pode instalá-lo como um serviço Systemd no espaço do usuário. Leia mais aqui.

Documentação

Consulte o diretório docs para encontrar diagramas sobre como o código funciona e está organizado. Consulte a política de segurança antes de usar chaves RSA ou encaminhar o agente.

O que vem a seguir

• Suporte a múltiplas chaves SSH
• Suporte a configurações Bitwarden self-hosted
• Melhorar os testes
• Oferecer mais formas de instalação (Homebrew, AUR, nix, .deb, .rpm)
• Suportar outros provedores além do Bitwarden?

Sobre o nome

vault, /voːlt/ - um cômodo subterrâneo, especialmente para guardar objetos de valor

conductor, /kənˈdʌk·tər/ - um diretor, algo que conduz calor ou eletricidade

por extensão, algo que conduz sua valiosa chave SSH de um cofre Bitwarden para o seu ambiente de desenvolvimento.

Licença

Este projeto está licenciado sob a Licença MIT.

Consulte o arquivo LICENSE para obter detalhes.