Ssh Broker MCP

ssh代理mcp（Rust）--ssh代理+mcp适配器（零知识证书）

此回购是 干净的骨架 对于您描述的架构：

• 这 MCP服务器/AI永远看不到凭据 （无密码、无私钥、无TOTP种子）。
• 该系统仍然提供 完整的SSH功能 通过暴露 会话句柄 （不透明ID）覆盖gRPC。
• 凭证管理支持 添加（带外） 和 删除；有 无查看/编辑 API获取机密。

架构/组件

• ssh-broker （受信任）：使用打开SSH会话的gRPC服务器 系统OpenSSH.
• ssh-broker-enroll （受信任，仅限本地）：CLI将凭据元数据写入SQLite，并将机密写入操作系统密钥环。
• ssh-broker-mcp （不受信任）：与通信的MCP stdio适配器 ssh-broker 通过gRPC。

- 不受信任的调用者（MCP工具、LLM等）仅与 ssh-broker 通过gRPC，只能引用 credential_id.

威胁模型/保证

• 施工保证：没有gRPC方法返回机密材料（原型中没有“获取密码/密钥”方法）。
• 密码/OTP需要受信任的组件：如果你想要无头身份验证，代理主机必须持有/派生密钥（例如，存储在操作系统密钥环中），否则你需要一个交互式用户提示。
• 更强的选择：使用 ssh代理/FIO2/TPM/ssh证书 因此，秘密是不可导出的或短暂的。

本地vs远程

本地模式（推荐）

• 在Linux/macOS:gRPC over 域套接字 具有文件系统权限(0600).
• 在Windows上：使用 TCP环回 （优选mTLS）。

例子：

cargo run -p ssh-broker -- --listen-uds ./run/ssh-broker.sock

远程模式（可选）

• TCP上的gRPC 弹药库鱼雷发射系统 （推荐）。

例子：

cargo run -p ssh-broker -- \
  --listen-tcp 0.0.0.0:7443 \
  --tls-cert ./tls/server.crt \
  --tls-key  ./tls/server.key \
  --tls-client-ca ./tls/client-ca.crt

凭证注册（添加/删除而不暴露机密）

添加基于SSH密钥的凭据（未存储秘密）：

cargo run -p ssh-broker-enroll -- add \
  --label prod \
  --username ubuntu \
  --auth-type ssh_key \
  --allowed-host my.vps.example.com

列出凭据（仅元数据）：

cargo run -p ssh-broker-enroll -- list

删除（删除元数据+密钥环密钥）：

cargo run -p ssh-broker-enroll -- delete --credential-id cred_...

主机密钥固定（建议用于生产）

经纪人使用 严格的 默认情况下进行主机密钥检查(StrictHostKeyChecking=yes)由经纪人管理 known_hosts 文件。

向代理已知主机添加主机密钥：

cargo run -p ssh-broker-enroll -- hostkey-add --host my.vps.example.com --port 22

UI（独立服务）

此回购包括 独立UI服务 （与经纪人彻底分离）：

• ssh-broker-ui （Rust/axum）：提供HTTP服务并与 ssh-broker 通过gRPC（本地UDS或远程TCP+mTLS）。
• ui-web （React/Vite）：调用UI服务的前端 /api/*.

在本地运行UI（无身份验证）

1. 启动经纪人：

cargo run -p ssh-broker -- --listen-uds ./run/ssh-broker.sock

1. 构建用户界面：

cd ui-web
npm install
npm run build

1. 启动UI服务：

cargo run -p ssh-broker-ui -- \
  --broker-uds ./run/ssh-broker.sock \
  --http-addr 127.0.0.1:8080 \
  --static-dir ui-web/dist \
  --auth-mode none

OIDC/SSO（用户界面服务）

设置：

• SSH_BROKER_UI_AUTH_MODE=oidc
• SSH_BROKER_UI_COOKIE_KEY_B64 （生成： openssl rand -base64 64)
• SSH_BROKER_UI_OIDC_ISSUER
• SSH_BROKER_UI_OIDC_CLIENT_ID
• SSH_BROKER_UI_OIDC_CLIENT_SECRET
• SSH_BROKER_UI_OIDC_REDIRECT_URL （必须以结尾 /auth/callback)

会话如何工作（OpenSSH ControlMaster）

• OpenSession 启动OpenSSH ControlMaster 连接（多路复用插座）。
• Exec 通过该控制套接字运行命令（快速，避免每次重新认证）。
• CloseSession 发送 ssh -O exit 并取下插座。

代理运行OpenSSH BatchMode=yes 对于密钥/证书/代理身份验证：

• 与密钥/代理/证书配合良好。
• 对于 auth_type=password_totp，代理使用受控 SSH_ASKPASS 流量(目前仅限Unix).秘密存储在本地 ssh-broker-enroll 在操作系统密钥环中，并且永远不会通过gRPC返回。

生产硬化（已实施）

政策

• allowed_hosts 支持 精确, 通配符 （例如。 *.example.com)，以及 无类别域间路由 （例如。 10.0.0.0/8)条目。
• 可选的用户名通过allowlist allowed_usernames （如果为空，则只允许使用默认用户名）。

限额+利率限制

经纪人默认执行限制；您可以通过env-vars对其进行调优：

• SSH_BROKER_MAX_RPM （0禁用）
• SSH_BROKER_MAX_EXEC_BYTES
• SSH_BROKER_MAX_SHELL_BYTES
• SSH_BROKER_MAX_SHELL_SECONDS
• SSH_BROKER_MAX_SCP_BYTES

审核日志记录

审计事件以JSONL格式写入 /audit.jsonl 默认情况下：

• SSH_BROKER_AUDIT_PATH
• SSH_BROKER_AUDIT_LOG_COMMANDS （默认情况下关闭；如果运行包含机密的命令，启用可能会捕获机密）

密码/OTP注意事项

该项目以生产为导向 SSH密钥/SSH代理/SSH证书.密码/OTP支持通过 auth_type=password_totp，但仍然是明确的选择加入。