🗝️ vault-conductor

一个 SSH Agent，用于提供以密钥形式存储在 Bitwarden Secrets Manager 中的 SSH 密钥。

支持 SSH 认证和 Git 提交签名。

演示

功能特性

它以 Unix 域套接字服务器形式实现 SSH Agent 协议，作为你的 SSH 客户端与 Bitwarden Secrets Manager 之间的安全桥梁。

其特性包括：

• Agent 生命周期：以守护进程（后台）或前台进程方式运行，监听位于 /tmp/vc-$(whoami)-ssh-agent.sock 的 Unix 套接字
• 密钥懒加载：SSH 密钥仅在请求时通过 Bitwarden 官方 Rust SDK 获取，然后缓存在内存中
• 安全的 SSH 操作：当 SSH 客户端查询身份或请求签名时，Agent 使用 ssh-agent-lib crate 处理请求，绝不将私钥暴露到磁盘
• 进程管理：后台模式会生成一个分离的子进程，跟踪 PID，并支持通过 SIGTERM/SIGINT 优雅关闭
• 安全性：套接字权限锁定为 0600（仅所有者），密钥仅存在于进程内存中，Bitwarden API 使用作用域限定的机器令牌调用，你可以配置细粒度的密钥访问权限。

在底层，它使用 Tokio 进行异步 I/O，使用 ssh-key crate 进行加密操作，并支持 OpenSSH 格式的 Ed25519 和 RSA 密钥。

为什么

它源于我自己的一个需求。Bitwarden GUI 客户端中的 Bitwarden SSH Agent 功能很方便，但如果你只运行纯命令行的开发环境，又该用什么？如何在 CI/CD 管道中安全地引入 SSH 密钥来签署 git 提交？如果你需要从临时容器或虚拟机建立 SSH 连接，而又不想复制任何私钥，该怎么办？如何避免处理存储在钥匙串中且与登录会话绑定的口令？

因此，我编写了一个小巧的 CLI 工具来检索 SSH 密钥，并在不暴露私钥的情况下使其可用。

此外，为了避免将整个 Bitwarden 密码库带入环境，它使用 Bitwarden Secrets Manager，以便你可以选择哪台机器可以访问哪个密钥，并设置细粒度的令牌权限。

环境要求

• 一个已配置 Bitwarden Secrets Manager 的 Bitwarden 账户（你可以免费创建并设置）（计划支持自托管 Bitwarden）
• 一个以 OpenSSH 新格式保存为 BWS 密钥值的 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 列表，以逗号分隔。你可以在 BWS Web 应用中查看每个密钥的 UUID（在密钥名称下方）。
• 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 选项以提供自定义配置路径。环境变量始终优先于配置文件。

调试

有时你可能需要调试一些奇怪的情况，并希望获得尽可能多的日志。执行以下命令以前台模式运行并获取详细的 stdout 日志：

vault-conductor start --fg -vv

安装为服务

你可以将其安装为用户空间的 Systemd 服务。更多信息请阅读此处。

文档

查看 docs 目录，了解代码工作原理和组织的相关图示。 在使用 RSA 密钥或转发 Agent 之前，请参阅安全政策。

后续计划

• 支持多个 SSH 密钥
• 支持自托管 Bitwarden 环境
• 更好的测试
• 提供更多安装方式（Homebrew、AUR、nix、.deb、.rpm）
• 支持 Bitwarden 以外的提供商？

关于名称

vault，/voːlt/ - 地下室，尤指用于存放贵重物品的房间

conductor，/kənˈdʌk·tər/ - 指挥者，传导热或电的物体

引申开来，即一种将你宝贵的 SSH 密钥从 Bitwarden 密码库传导到开发环境的东西。

许可证

本项目采用 MIT 许可证。

详情请参阅 LICENSE 文件。