brokre — AI 安全的凭据代理

English | 简体中文

brokre 是一个面向 AI 代理和人类的本地凭据代理。可配合 Cursor、Claude Code、Kimi Code、Trae、OpenClaw、Hermes Agent、ChatClaw 以及其他支持 MCP 的客户端使用，运行 ssh、mysql、psql 等命令——密码永远不会进入 AI 上下文、环境变量或 ps 输出。它包装 PATH 上的任何 CLI——不仅限于 SSH 或 MySQL——并在提示符处注入已保存的密码，而不会将明文暴露给 AI 进程、shell 历史或进程环境。

由 Techinone（成都同创合一科技有限公司）开发。

0.2.17 中的新功能

0.2.17 是当前版本：默认通过 SessionRelay 路由 SSH、多跳堡垒机路由、默认仅本地列表，以及现有的一键 npm 安装 / 自动 MCP 注册 / 自动二进制升级流程。

npm — 安装、自动更新、自动 MCP 设置

npm install -g brokre          # or: npx -y brokre@latest

推荐的 MCP 配置（自动设置也会应用）：

{ "command": "npx", "args": ["-y", "brokre@latest"] }

堡垒机代理 — 集群管理

堡垒机层允许 AI 代理操作一个跳板机后面的许多主机，而无需将保险库密码复制到上下文中，也无需将机密散布在笔记本电脑上。

典型流程：一个入口主机后面的 K8s / 数据库 / 批处理集群：

brokre bastion enable b150
brokre bastion sync b150 --json          # pull inner alias catalog
brokre bastion unlock
brokre list --include-bastions --json    # b150::db, b150::worker-01, …
brokre ssh b150::db systemctl status   # MCP: brokre_exec with routed alias

MCP 等效操作：

{ "binary": "ssh", "args": ["b150::db", "uname", "-a"] }

门控策略（默认 vs 严格）——参见下面的 堡垒机门控策略。门控在 brokre bastion set-key 之前处于非活动状态；然后默认仅解锁堡垒机出站路径；严格要求每次执行都解锁，而列表保持仅本地，除非请求堡垒机发现。

有关设置详情，请参见下面的 跨网络列表继承 和 堡垒机代理。

Related MCP server: SSH Vault MCP

CLI 安全（核心）

brokre 围绕一条规则构建：机密远离 AI 的触及范围，也远离可观察的进程状态。

完整威胁模型：SECURITY.md、THREAT_MODEL.md。

PATH 上的任何 CLI（通用设计）

brokre 不是固定的数据库/SSH 包装器列表。核心模型是：

brokre <any-cli-on-PATH> [args...]

首次连接：原样运行，捕获您在提示符处输入的密码，提供保存为别名的选项。
下次：brokre <cli> <alias> … 自动注入——AI 和脚本只看到别名。

预设提示符模式适用于常见工具（ssh、mysql、psql、redis-cli、ftp、clickhouse、git、docker、kubectl、sudo 等）。其他所有工具使用通用的 password: / passphrase: 匹配器——无需修改代码。

brokre gsql prod-cluster -c "SELECT 1"    # any proprietary CLI on PATH
brokre kubectl get pods                   # if your cluster CLI prompts for a password
brokre my-internal-tool --host db.internal

需要时自定义：

• ~/.brokre/prompts.toml — 每个二进制的提示符正则表达式覆盖

• ~/.brokre/manage.toml — 管理 UI 中的自定义部分（例如 GaussDB、内部工具）

内置管理 UI 标签页（当二进制已安装时）包括 SSH、FTP、MySQL、PostgreSQL、Redis、ClickHouse、MinIO——仅为方便；PTY 包装器适用于任何 CLI。

安装（MCP 优先——推荐用于 AI）

npm 包 brokre 通过 stdio 为 Cursor、Claude Code、Kimi Code、Trae、OpenClaw、Windsurf、VS Code 和其他 MCP 客户端启动本地 brokre mcp 服务器。

选择您的安装路径

推荐的 MCP 入口（自动设置也会写入）：

{ "command": "npx", "args": ["-y", "brokre@latest"] }

无 Node——将 MCP 指向原生二进制：{ "command": "brokre", "args": ["mcp"] }。

路径 A — npm 一行命令（0.2.8+）

npm install -g brokre
# or without global install:
npx -y brokre@latest

在 npm install 时，自动发生三件事：

1. MCP 启动器 — brokre-mcp / npx -y brokre@latest 生成 brokre mcp。

2. IDE 自动注册 — postinstall 运行 brokre-setup-mcp：仅检测已安装的 IDE（应用、CLI 或实际使用痕迹——不是空文件夹），并将上述 MCP 条目合并到每个全局配置中。幂等；保留您的其他 MCP 服务器。

3. 二进制自动升级 — 每次 MCP 启动时，如果 PATH 或 ~/.brokre/bin/brokre 比 npm 包旧，则下载匹配的 GitHub Release。

自动设置覆盖的 IDE

重新运行注册（例如，您在 Cursor 之前安装了 brokre，然后稍后安装了 Cursor）：

brokre mcp setup              # via CLI — same logic as postinstall
npx brokre-setup-mcp          # via npm
brokre mcp setup --dry-run    # preview only
brokre mcp setup --force      # overwrite existing brokre entry

在 npm install 时跳过自动注册：BROKRE_MCP_SKIP_SETUP=1。禁用二进制自动下载：BROKRE_SKIP_AUTO_INSTALL=1。固定二进制：BROKRE_BIN=/path/to/brokre。

npm 路径需要 Node.js 18+。

路径 B — 原生 CLI（install.sh / Homebrew，无需 npm）

curl -fsSL https://raw.githubusercontent.com/Furowu/brokre/main/install.sh | bash

brew tap Furowu/brokre
brew install brokre

版本和升级（内置于 CLI——无需 npm）：

brokre version                # version, binary path, install type
brokre version --check        # compare with latest GitHub release
brokre version --check --json
brokre upgrade                # download latest release (curl + tar)
brokre upgrade --check        # exit 1 if an update is available
brokre upgrade 0.2.10         # install a specific version
brokre upgrade --force        # reinstall even when up to date

重新运行 install.sh 也会在存在较新版本时升级。

CLI 安装后注册 MCP（设置脚本需要 Node，或使用 npx 回退）：

brokre mcp setup

手动按 IDE 设置（可选）

仅当您跳过自动设置或需要项目级配置时使用。

Cursor — 一键安装，或 ~/.cursor/mcp.json：

{
  "mcpServers": {
    "brokre": { "command": "npx", "args": ["-y", "brokre@latest"] }
  }
}

Claude Code — 用户范围在 ~/.claude.json 或 claude mcp add --scope user brokre -- npx -y brokre@latest。项目范围：.mcp.json 中的 "type": "stdio"。

更多客户端和环境变量：packages/brokre-mcp/README.md。MCP Registry ID：io.github.Furowu/brokre。

MCP 工具及用法

MCP 与 CLI 对比（对 AI 代理至关重要）

brokre 不是 ssh / mysql 的直接替代品 — 必须加上 brokre 前缀才能进行保险库注入。

常见错误（AI 代理）

对于远程 SSH：别名后的令牌是 argv 片段，不是单个 shell 命令。简单命令使用拆分令牌；复杂脚本使用 shell_command。

MCP 提权会话（sudo / su，Unix）

默认情况下，brokre mcp 为每个 (alias, mode, user) 复用后台提权 shell，因此不会在每次调用时重新提示 sudo 密码。

brokre_exec_elevated（特权提升的首选）：

{
  "alias": "prod",
  "command": "systemctl status nginx",
  "mode": "sudo_login",
  "session": "reuse"
}

启用会话池后，响应除了 exit_code / stdout / stderr 外，还包含 session_reused 和 session_idle_expires_at。session_idle_expires_at 是一个滚动空闲窗口提示，每次调用都会刷新，不是固定的过期时间戳。stderr 在池路径上通常为空。stdout 仅包含远程命令输出 — TTY 回显、__BROKRE_* 框架和 shell 提示符均被剥离。

brokre_exec：binary=ssh 且 args 中包含 sudo/su 时自动使用同一池（始终 reuse；无 session=new|close）。示例：args=["prod","sudo","whoami"]。

编写远程脚本/文件（shell_command，仅 binary=ssh）：仅在 args 中传递别名；将完整 shell 脚本放在 shell_command 中（brokre 规范化为 sh -c）。不要在 args 中嵌入 sh -c '...'，也不要将 printf/重定向拆分为 argv 令牌。对于特权系统路径，使用 brokre_exec_elevated.command。

{
  "binary": "ssh",
  "args": ["prod"],
  "shell_command": "cat > /tmp/deploy.sh <<'EOF'\n#!/bin/sh\necho ok\nEOF"
}

堡垒机路由同样适用：args=["b150::db"] 配合 shell_command 作为远程脚本。

SessionRelay 隧道（默认）

brokre ssh b150::db 默认使用 SessionRelay 路径：笔记本电脑通过 SSH 在 b150 上启动 brokre tunnel agent --stdio，代理在堡垒机上运行 brokre ssh db。多跳路由每跳剥离一个代理（b1::b2::db 在 b1 上启动，然后 b1 继续使用 b2::db）。内部凭据保留在堡垒机保险库中；笔记本电脑仅中继终端字节。BROKRE_TUNNEL=0 是临时的旧版逃生通道，用于紧急回滚。

brokre tunnel doctor b150
brokre ssh b150::db uname -a

MCP brokre_exec 对路由 SSH 的响应包含 tunnel: { mode, active }。TcpForward、端点同步、Manage UI 隧道控制以及持久化 tunneld 属于后续阶段。

不支持：无命令的交互式 sudo -i、vim/top，或与保险库 password 字段不同的 sudo 密码。参见 THREAT_MODEL.md T12。

首次连接空保险库时，brokre 会在浏览器中打开 manage（http://127.0.0.1:56777/?t=…）。会话令牌保留在 localhost — 绝不返回给 AI。设置 BROKRE_MCP_NO_AUTO_OPEN=1 可禁用自动打开。

| MCP 工具 | 用途 |

添加凭据

CLI 安装后，管理器在首次运行时打开（brokre manage --onboard --open）。或随时：

brokre manage --open

或在首次交互式连接时保存（任何 CLI）：

brokre ssh root@10.0.0.1
brokre my-tool --host internal.corp

使用（AI 安全）

brokre mysql prod-db -e "SHOW TABLES"
brokre ssh prod-bastion uname -a
brokre <your-cli> <alias> [args...]

列出元数据（对 AI / 脚本安全）

brokre list --json              # local aliases with reachability status (default probe)
brokre list --no-probe --json   # metadata only, skip TCP/SSH probes
brokre list --reachable-only    # hide unavailable aliases
brokre list --all --json        # compat: show all (same as default unless --reachable-only)
brokre list --no-bastion-discovery   # local only — no bastion SSH discovery

当注册了堡垒机时，brokre list 默认仅限本地，不会 SSH 到堡垒机或触发堡垒机解锁。当您确实需要路由别名（如 b150::db）时，使用 brokre list --include-bastions（MCP：include_bastions=true）；该远程发现可能需要解锁。

OpenSSH 会话默认注入 ConnectTimeout=5（BROKRE_SSH_CONNECT_TIMEOUT）。使用 -o ConnectTimeout=N 或环境变量覆盖。堡垒机 RPC（brokre list --include-bastions / 远程列表）在 60 秒后超时（BROKRE_BASTION_RPC_TIMEOUT）。远程命令使用 ControlPath=none，因此不会附加到 ControlPersist mux 主进程。

跨网络列表继承（堡垒机代理）

用于跨网络访问 — 旅行、VPN、公共入口 — 当直接 LAN 别名在本地不可达，但可通过运行 brokre 的堡垒机访问时。

先决条件

1. 笔记本电脑：brokre bastion enable b150（b150 是已保存的 SSH 别名）

2. 堡垒机主机在 ~/.brokre/bin/brokre（标准安装 / npx 路径）运行 brokre，并保存了内部别名（例如 db）

路由列表

brokre bastion unlock            # if bastion key is set
brokre list --include-bastions   # includes b150::db (route=b150, access=via_b150)

跨网络时，需要路由别名时使用 --include-bastions。普通 brokre list 仅限本地，不会解锁或 SSH 到堡垒机。

执行

brokre ssh b150::db uname -a
# MCP: brokre_exec binary=ssh, args=["b150::db", "uname", "-a"]

当两条路径都可用时，列表会同时显示 db（direct）和 b150::db（via_b150）— 通过 access 区分。

堡垒机代理（跨网络 / 内网入口）

将任何远程主机运行 brokre 的已保存 SSH 别名提升为堡垒机代理。秘密保留在堡垒机上；笔记本电脑缓存元数据并通过 SSH 直通执行。

brokre bastion enable b150        # register ssh alias b150 as bastion
brokre bastion set-key              # set bastion unlock key (TTY)
brokre bastion unlock               # unlock outbound session (TTL, 30 min idle default)
brokre list --include-bastions --json # discover bastion-routed aliases
brokre ssh b150::db uname -a        # routed exec via b150 remote brokre
brokre bastion sync b150 --json     # fetch alias list from one bastion

• 路由分隔符 ::（: 在别名中非法）：db（本地）、b150::db（通过堡垒机）、b1::b2::inner（多跳，默认深度 ≤2）。

• 远程 brokre：路由执行在堡垒机上调用 ~/.brokre/bin/brokre（带 BROKRE_SOFT_MEMLOCK=1、BROKRE_ALLOW_FILE_KEYCHAIN=1、BROKRE_ROUTED_INNER=1 用于无头 Linux）。交互式命令（例如 sudo -i）自动获得 -tt。

• 防护措施：探测并发上限、毫秒超时、短缓存、循环检测、审计 route/bastion（HMAC v4）。

• 管理 UI：brokre manage Bastion 选项卡 — 注册/禁用堡垒机、Web 设置密钥和解锁/锁定、严格模式切换、同步远程别名；非 TTY 仍自动打开 /bastion-auth。审计选项卡按 bastion/source 过滤并显示路由字段。

堡垒机门控策略（默认 vs 严格）

堡垒机门禁（gate）是在敏感操作之前的人工解锁步骤。在设置堡垒机密钥（brokre bastion set-key）之前，它处于关闭状态。密钥存在后，解锁会建立一个本地 TTL 会话（brokre bastion unlock、TTY 口令、管理界面 /bastion-auth 或 MCP 浏览器引导）。

策略存储在 ~/.brokre/bastion/policy.json（strict_mode，默认 false）。

示例（默认模式，已设置密钥，会话已锁定）

在严格模式下，exec 行需要解锁；仅元数据的 brokre list 保持仅本地，除非使用 --include-bastions，否则不会解锁。

设置门禁模式

brokre bastion strict status    # default | strict
brokre bastion strict on        # strict — all exec gated; list stays local-only unless discovery is requested
brokre bastion strict off       # default — bastion outbound only

MCP 读取响应包含 strict_mode、gate_mode、key_set、unlocked。列表/执行响应包含 bastion_gate（required、unlocked_during_call、idle_expires_at）。

解锁会话 TTL（默认值）：空闲 30 分钟（BROKRE_BASTION_IDLE_SECS），最长 8 小时（BROKRE_BASTION_MAX_SECS）。在解锁状态下，每次受门禁保护的调用都会续期空闲窗口（通过 ~/.brokre/run/bastion_session.json 在 CLI、MCP 和管理界面之间共享）。堡垒机门禁认证独立于管理界面会话空闲过期。在 MCP 解锁时禁用自动打开浏览器：BROKRE_BASTION_NO_AUTO_OPEN=1。

显示 / 删除（仅限人工，真实 TTY）

brokre reveal mysql prod-db --field password
brokre rm ssh prod-bastion

审计日志（仅元数据）

brokre audit list --profile ssh --action exec --json
brokre audit verify --json

事件存储在 ~/.brokre/audit/audit.log（HMAC 链式）。命令参数统一以 <REDACTED> 脱敏。新事件包含 source 字段（cli、mcp 或 manage）。管理界面的 Audit log 标签页和 MCP brokre_audit_list 暴露相同的元数据。

管理界面安全

• 仅限 127.0.0.1；会话令牌在终端中

• 密码：仅可创建 / 轮换 — 无读取 API

• 删除 / 轮换需要显示口令（自动保存的记录为 YES）

• 15 分钟空闲超时

架构

┌─────────┐     ┌──────────┐     ┌─────────────┐     ┌────────────┐
│ AI/User │────▶│ brokre CLI│────▶│ OS Keychain │────▶│ Vault File │
└─────────┘     └──────────┘     └─────────────┘     └────────────┘
                      │
                      ▼
               ┌─────────────┐
               │  PTY + inj. │──▶ any CLI on PATH (ssh, mysql, gsql, …)
               └─────────────┘

• 双重加密：每个字段使用唯一的 DEK；分别为 exec 和 reveal 包装。

• 保险库元数据：profile、name、host_alias、saved_args 以明文形式与密文并列存储（THREAT_MODEL.md T3）。

• SSH 私钥：0600 临时文件 + 会话使用 -i（docs/HARDENING.md）。

预设管理界面分组

当二进制文件在 PATH 中时的便捷标签页：

路线图

当前： 通用 PTY 包装器 + manage.toml 分组 + prompts.toml 覆盖。

计划中： ~/.brokre/profiles/ 下的完整 TOML 连接器配置文件，包含按工具注入策略。

管道标准输入与 OpenSSH 共享

• 管道标准输入（tar | brokre ssh host 'tar xf -'）：仅在注入完成后才转发管道数据。

• OpenSSH 系列（ssh、scp、sftp）：当主机匹配时共享已保存的凭据。需要先进行交互式保存（TTY）。

开发

cargo test    # unit tests in src/ only (no tests/ integration suite in this repo)
cargo clippy --all-targets --all-features -- -D warnings
cargo build --release   # binary: target/release/brokre

发布版本在 VERSION 中声明（也反映在 Cargo.toml 和 packages/brokre-mcp/package.json 中）。官方二进制文件和 npm 包由 TechinOne 通过 GitHub Releases 和 CI 发布 — 不属于此开源树的一部分。

许可证

MIT — 参见 LICENSE。

Techinone · 成都同创合一科技有限公司