🗝️ vault-conductor

Bitwarden Secret Manager にシークレットとして保存された SSH 鍵を提供する SSH エージェントです。

SSH 認証と Git コミット署名に対応しています。

デモ

特徴

Unix ドメインソケットサーバーとして SSH エージェントプロトコルを実装し、SSH クライアントと Bitwarden Secrets Manager の間の安全なブリッジとして機能します。

特徴は以下のとおりです:

• エージェントのライフサイクル: デーモン（バックグラウンド）またはフォアグラウンドプロセスとして実行され、/tmp/vc-$(whoami)-ssh-agent.sock の Unix ソケットで待ち受けます。
• 鍵の遅延読み込み: SSH 鍵は、要求されたときだけ Bitwarden の公式 Rust SDK 経由で取得され、その後メモリにキャッシュされます。
• 安全な SSH 操作: SSH クライアントが ID を照会したり署名を要求したりすると、エージェントは ssh-agent-lib クレートを使用して要求を処理し、秘密鍵をディスクに公開することはありません。
• プロセス管理: バックグラウンドモードは切り離された子プロセスを生成し、PID を追跡し、SIGTERM/SIGINT によるグレースフルシャットダウンをサポートします。
• セキュリティ: ソケットの権限は 0600（所有者のみ）に固定され、鍵はプロセスメモリ内にのみ存在し、Bitwarden API への呼び出しには、シークレットへのアクセスを細かく設定できるスコープ付きマシントークンを使用します。

内部では、非同期 I/O に Tokio を使用し、暗号操作には ssh-key クレートを使用しており、OpenSSH 形式の Ed25519 鍵と RSA 鍵の両方をサポートしています。

なぜ作ったのか

これは、私自身の必要性から生まれました。Bitwarden の GUI クライアントにある Bitwarden SSH Agent 機能は便利ですが、devbox の CLI だけを実行している場合には何を使えばよいのでしょうか？ CI/CD パイプラインで git コミットに署名するために、SSH 鍵を安全に持ち込むにはどうすればよいのでしょうか？ 秘密鍵をコピーせずに、一時的なコンテナや VM から SSH 接続を開く必要がある場合はどうすればよいのでしょうか？ キーチェーンに保存され、ログインセッションに結び付けられたパスフレーズを扱わずに済ませるにはどうすればよいでしょうか？

そこで私は、SSH 鍵を取得して、その秘密鍵（private counterpart）を公開せずに利用できるようにする小さな CLI ツールを書きました。

また、Bitwarden のボールト全体を環境に持ち込まないように、Bitwarden Secrets Manager を使用しています。これにより、どのマシンがどのシークレットにアクセスできるかを選択し、トークンの権限を細かく設定できます。

要件

• Bitwarden Secret Manager を設定済みの Bitwarden アカウント（無料で作成・設定できます）（セルフホスト型 Bitwarden のサポートは計画中）
• BWS にシークレット値として保存された、OpenSSH の新しい形式の Ed25519 または RSA の SSH 鍵
  • -----BEGIN OPENSSH PRIVATE KEY----- と -----END OPENSSH PRIVATE KEY----- の文字列を含めて保存する必要があります。
  • 注: 新しい OpenSSH 秘密鍵形式は、2018 年に OpenSSH 7.8 で導入されました。
• 過去 5 年以内にリリースされた macOS または Linux

インストール

以下のいずれかの方法を使用します。

poof

poof を使用する:

poof install pirafrank/vault-conductor

ワンライナースクリプト

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

Homebrew

brew tap pirafrank/tap
brew install vault-conductor

手動

または、最新の安定版 を手動でダウンロードして $PATH に配置します。

ソースから

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

設定

以下を指定する必要があります:

• BWS_ACCESS_TOKEN: 上記で設定したマシントークン。この環境変数は、Bitwarden 製 の bws CLI ツールと同じ名前です。
• BW_SECRET_IDS: 各秘密鍵が保存されているシークレットの UUID のカンマ区切りリスト。各シークレットの UUID は BWS Web アプリで確認できます（シークレット名の下に表示されます）。
• BW_SERVER_ENDPOINT（オプション）: カスタム Bitwarden サーバーエンドポイント（プロトコルなしのホストのみ）。指定しない場合、デフォルトは bitwarden.com です。有効な例は、bitwarden.eu（クラウド）、myvault.example.com、192.168.1.100、vault.internal（セルフホスト）です。

これらは、上記の環境変数（CI や DevOps 環境に適しています）または設定ファイルのどちらかで渡すことができます:

# 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

使い方

# 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

start コマンドは、カスタム設定パスを指定するための --config オプションもサポートしています。環境変数は常に設定ファイルよりも優先されます。

デバッグ

時には、奇妙な状況をデバッグする必要があり、できるだけ多くのログが必要になることがあります。フォアグラウンドで実行して詳細な標準出力ログを取得するには、次のコマンドを実行します:

vault-conductor start --fg -vv

サービスとしてインストール

ユーザー空間の Systemd サービスとしてインストールできます。詳細はこちらをご覧ください。

ドキュメント

コードの仕組みと構成に関する図は、docs ディレクトリを確認してください。 RSA 鍵を使用する前、またはエージェントを転送する前に、セキュリティポリシー を参照してください。

今後の予定

• 複数の SSH 鍵のサポート
• セルフホスト型 Bitwarden のサポート
• テストの改善
• より多くのインストール方法の提供（Homebrew、AUR、nix、.deb、.rpm）
• Bitwarden 以外のプロバイダーのサポート？

名前について

vault、/voːlt/ - 貴重品を保管するための地下室

conductor、/kənˈdʌk·tər/ - 指揮者、熱や電気を伝導するもの

転じて、Bitwarden のボールトから開発環境へ、あなたの貴重な SSH 鍵を導通させるもの。

ライセンス

このプロジェクトは MIT ライセンスの下でライセンスされています。

詳細は LICENSE ファイルを参照してください。