vault-conductor v0.3.1
Bitwarden Secrets Managerに保存されたSSH鍵を提供するSSHエージェント
🗝️ 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 製 のbwsCLI ツールと同じ名前です。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 ファイルを参照してください。