infrabroker

infrabroker

面向 AI Agent 的基础设施访问代理 — SSH 和 Kubernetes。模型绝不会接触任何凭据。 （原名 ssh-broker）

Agent 请求执行某项操作 — 在主机上运行命令、查询或更改集群。infrabroker 会根据策略进行检查，并使用专为该次操作签发的凭据执行操作 — 由其自有 CA 签发的临时、范围受限的 SSH 证书，或短期绑定的 ServiceAccount 令牌 — 然后仅返回输出。密钥、证书和令牌仅保存在代理的内存中，并会在调用结束后销毁：没有任何内容进入模型上下文，因此遭到提示词注入的 Agent 无物可窃取。

一个二进制文件 — infrabroker — 通过三个传输方式暴露同一引擎（internal/broker）和工具接口（internal/mcpserver），由子命令选择。（旧版的各传输方式独立二进制文件 broker / mcp-broker / mcp-broker-http 仍作为这些子命令的轻量弃用包装器保留，因此现有配置仍可正常使用。）

• MCP stdio（本地，推荐个人使用） — infrabroker serve-mcp。工具：ssh_execute、ssh_session_open / ssh_session_exec / ssh_session_close、ssh_list_servers、ssh_put_file / ssh_get_file；配置集群后，还可使用 k8s_get / k8s_list / k8s_logs / k8s_apply / k8s_delete / k8s_list_clusters。无需传输身份验证 — 隔离由用户启动进程实现（符合 MCP 对 stdio 的建议）。
• MCP HTTP + OAuth2/OIDC（远程，多用户） — infrabroker serve-mcp-http，使用 Streamable HTTP。工具相同，但每个客户端都需通过OIDC bearer 令牌进行身份验证；该令牌会根据发行方的 JWKS 在本地验证。用户身份（以及用于按用户实施 RBAC 的用户组）会传递给签名器。
• HTTP + mTLS — infrabroker serve-http，提供 POST /v1/ssh_run（单次执行），供使用客户端证书进行身份验证的网络 Agent 使用。

文档

本 README 是一个入口页面。详细内容见各个专注于单一信息源的文档：

文档	内容
QUICKSTART.md	10 分钟内完成首次 ssh_execute — 单二进制本地模式，无需签名器/PKI
ARCHITECTURE.md	架构图、请求流程、设计决策、sudo 提权、会话、多 CA
THREAT_MODEL.md	参与者、信任边界、安全控制，以及明确不涵盖的目标/缺口
OPERATIONS.md	操作手册：启动、添加主机、热重载、broker-ctl、PKI 轮换、配置
MESH.md	在 NetBird / Tailscale 网状网络上运行 infrabroker — 叠加网络路径之上的会话层
SANDBOX.md	infrabroker 搭配沙箱化 Agent（ASP）：Agent 的代码运行在微型虚拟机中，凭据和操作由代理服务保护 — 各层实施的约束、OIDC 配置方案，以及实际限制
HA.md	说明为何目前采用单实例：状态清单、阻碍因素，以及复制部署会导致哪些功能降级
API.md	所有服务的 HTTP 端点参考
USAGE.md	MCP 工具（SSH + Kubernetes）、试运行和审计审查指南（供模型 / 操作员使用）
SECURITY.md	漏洞披露政策
CONTRIBUTING.md · CODING_STYLE.md	工作流、版本控制、Go 风格

为什么选择 infrabroker

• 防止数据外泄（提示词注入）： 临时密钥/证书/令牌仅存于代理服务的内存中，绝不会进入模型的上下文。
• 无需 kubeconfig 即可使用 Kubernetes： 签名器会为每次操作签发短期有效的绑定 ServiceAccount 令牌（TokenRequest API）；每个集群均采用默认拒绝策略，并按动词/资源/命名空间设置策略，同时使用与 SSH 相同的试运行、审批和审计流程。
• 防止重用： 每张证书都带有数分钟的 TTL、source-address（代理服务或堡垒机 IP），且一次性证书还带有 force-command。在其适用的主机/时间/IP 范围之外毫无用处。
• 受控提权： allow_sudo / allowed_sudo_users 配置在签名器中；若策略禁止提权，遭入侵的代理服务也无法提权。
• 限制 CA 遭入侵的影响： 每个主机组使用独立 CA（ca_keys），每个密钥都可选择存放在 Azure Key Vault 或 ssh-agent（YubiKey PIV / SoftHSM / TPM）中 — 私钥永不离开 HSM。
• 审计 / 不可抵赖性： 采用仅追加写入、由 Ed25519 链式连接的日志，通过 serial 关联签名器、代理服务和 sshd 的记录。

完整的威胁模型（包括系统明确不防御的威胁）见 THREAT_MODEL.md。

工作原理

AI model ──tool call──> broker ──mTLS──> [control-plane] ──mTLS──> signer
   (no credential)      (ephemeral key      (approval +          (CA key +
                         in RAM, never        guardrails,          policy + RBAC,
                         on disk)             no CA key)           signs the cert)
                            │
                            └── SSH with the ephemeral cert ──> bastion ──> target host
                                                                 └─ stdout/stderr/exit_code ─> model

代理服务发送一项意图（{host, role, purpose, command?, sudo?, pty?, pubkey, …}）；签名器依据策略推导所有证书约束，并返回签名后的证书。临时私钥在代理服务中生成，绝不会离开该服务。请求流程、设计决策以及逐跳 ProxyJump 证书示意图，请参阅 ARCHITECTURE.md。

功能概览

能力	一句话介绍	更多信息
临时证书	每次操作都会在 RAM 中生成一对 Ed25519 密钥；证书有效期为几分钟，并限定了作用范围。没有可重复使用的密钥。	架构
外部签名器	独立的 cmd/signer 持有 CA 密钥和策略；broker 不会持有它们。	架构
多 CA + HSM	通过 ca_keys 为每个主机组配置一个 CA 密钥；支持本地 PEM、Azure Key Vault 或 ssh-agent/HSM。	架构
AI 操作防火墙	按主机或按组组合配置命令策略（允许／拒绝／require_approval），支持 POSIX-sh AST 解析和试运行。对一次性操作具有权威性。	架构 · 用法
人工审批	可选的控制平面会拦截 require_approval 命令，要求通过带外方式审批；签名器负责强制执行。	架构 · API
操作预算（行为护栏）	限制 Agent 的操作量：设置每个 CN 的签名速率上限，以及每个主体的速率限制和新颖性升级机制（后续访问新主机／执行新命令时需要审批）；支持观察或强制执行。网络工具预算限制 Agent 可以访问或花费的资源；此处的预算则限制操作本身。	运维 · 架构
紧急停止开关	冻结某个主体（调用方 CN、最终用户、会话 ID 或证书序列号）：不再签发新证书、撤销授权，并在 revocation_poll_seconds 时间内强制关闭活动会话。	运维
密封执行	按主机选择启用（sealed_exec）：每条会话命令都会携带由签名器签名的信封，infrabroker-shim 会在目标主机上验证该信封，因此即使 broker 遭到入侵，逐条命令授权仍然有效。	威胁模型：缺口 1 · 部署
审批桥接器	approval-bridge 会通过 Slack（Socket Mode）将待处理审批发送到 Slack，并提供 Allow / Deny 按钮；仅允许出站连接，因此不会有任何拥有审批权限的组件暴露在互联网中。	运维
机密信息遮蔽	默认启用：命令中直接出现的凭据会在审计日志、会话录制和审批通知中被遮蔽（尽力而为的模式匹配，不是 DLP）。	威胁模型：缺口 8
RBAC	Broker-CN 组（mTLS）+ 每个最终用户的 OIDC 组；默认拒绝。	架构
sudo / PTY	按主机通过策略控制权限提升（sudo -n）和 PTY 分配。	架构
Kubernetes broker	提供 k8s_* 工具，为每项操作绑定 SA 令牌，默认拒绝所有动词／资源／命名空间，并支持试运行。	用法 §10
会话录制	将 shell/pty 会话录制为 ASCIIcast v2（.cast），并按 session_id 建立索引。	用法 §8
链式审计	仅追加、由 Ed25519 签名并通过 SHA-256 链接；按 serial 关联。	用法 §7 · API
热重载	无需重启即可重新读取（并验证）signer.json，可通过 POST /v1/reload 或 SIGHUP 触发。	运维 §3

与现有方案的比较

有几种工具可用于 SSH 访问控制或 AI Agent 凭据安全，但没有一种能像 infrabroker 一样，以轻量、可自托管的套件覆盖这一整套功能。

功能	infrabroker	Teleport	Vault + SSH 引擎	StrongDM	ssh-mcp
内存中的短期证书（不写入磁盘）	✅	✅	✅	❌	❌
独立的代理 / 签名服务	✅	✅	部分支持	❌	❌
原生支持 MCP（AI Agent）	✅	✅（2025）	✅（2025）	❌	✅
MCP 传输层上的 OAuth2/OIDC	✅	✅	✅	❌	❌
按命令制定策略 + 试运行（AI 操作防火墙）	✅	❌	❌	❌	❌
AI 命令的人工审批	✅	❌	❌	❌	❌
按 Agent 设置行为防护规则（异常检测 / 频率限制）	✅	❌	❌	❌	❌
会话录制（ASCIIcast v2，stdin+stdout+stderr）	✅	✅	❌	部分支持	❌
密码学链式审计日志	✅	❌	❌	部分支持	❌
单二进制文件 / 简单可自托管	✅	❌	❌	❌	✅
CA 密钥的 HSM/KMS 支持	✅（AKV、ssh-agent/HSM）	✅	✅	—	—

Teleport 是最接近的商业方案——提供短期 SSH 证书、RBAC，并从 2025 年起支持 Secure MCP；其 2026 年 1 月推出的 Agentic Identity Framework 针对相同的威胁模型。两者的区别在于运维开销：Teleport 需要专用的控制平面集群、录制代理和 Web UI，规模比 Go 二进制文件 + 签名器大得多。

HashiCorp Vault SSH secrets engine 是一个 SSH CA，全面支持 HSM/KMS，并在 2025 年推出了自己的 MCP 服务，但它只提供签名部分——执行层（engine.go、session.go 和 MCP 工具）仍需自行构建。

StrongDM 会隐藏凭据，但存储的是长期有效的密钥，而非在内存中生成的短期证书，因此防范数据外泄的能力较弱。Smallstep SSH CA 是一款轻量、集成 OIDC 的 SSH CA（与 cmd/signer 接近），但不含执行代理或 MCP 层。ssh-mcp 通过 MCP 向大模型开放 SSH，但使用静态 SSH 密钥——这正是本代理要防止的漏洞。CyberArk PAM 提供类似的 JIT 证书访问能力，但它是面向人工操作员的闭源企业平台，并非针对 AI 工作负载。

适用场景： 原生支持 MCP 的 AI Agent 访问 + 内存中的短期证书 + 独立签名器 + ASCIIcast 录制 + 链式审计；以少量 Go 二进制文件实现，无需集群。企业功能（Web UI、多区域高可用）已列入路线图（参见 HANDOFF.md）。

安装

• 预编译二进制文件 — 每个发行版 都会提供 infrabroker_<ver>_{linux,darwin}_{amd64,arm64}.tar.gz，其中包含所有二进制文件； 还会提供安装程序压缩包（infrabroker-v<ver>.tar.gz），供 deploy/install.sh 在 systemd 生产部署流程中使用。
• go install — go install github.com/luisgf/infrabroker/cmd/infrabroker@latest （纯 Go，无需 CGO；其他 cmd/ 二进制文件也一样）。
• 容器 — ghcr.io/luisgf/infrabroker（docker 或 podman，多架构； 入口点是 stdio MCP 前端）。参见 CONTAINERS.md， 其中包含一个 compose 演示，可针对玩具主机运行完整技术栈： cd examples/compose && docker compose up --build -d（或运行 make demo）。
• 从源代码安装 — 参见下方的快速入门。

只需一行即可在 Claude Code 中注册——使用原生二进制文件或容器：

claude mcp add infrabroker -- ~/bin/infrabroker serve-mcp -config /secure/path/config.json
claude mcp add infrabroker -- docker run -i --rm -v /secure/path:/config \
  ghcr.io/luisgf/infrabroker -config /config/config.json

快速入门

最快路径（本地、单个二进制文件）： QUICKSTART.md 将带你从 git clone 开始，在不到 10 分钟内使用一个二进制文件和一个 config.json 执行首次 ssh_execute——无需签名服务，也无需 PKI。以下步骤将搭建完整的远程堆栈（签名服务独立部署）；容器化演示见安装。

# 1. Build (make injects the version from the git tag into every binary)
make install                 # → ~/bin/{infrabroker,signer,broker,broker-ctl,mcp-broker,...}
# or a single binary:        make signer
# (plain `go build ./cmd/...` also works; it reports a dev-<commit> version)

# 2. Generate the local PKI + the two-service config (signer.json + config.json)
infrabroker init             # writes pki/, signer.json, config.json; --force to redo
# add --import-ssh-config to import hosts from ~/.ssh/config (Include followed;
# ProxyJump/ProxyCommand hosts are skipped with a note), --register-mcp to run
# `claude mcp add` for you

# 3. Start the signing service (must be running before the broker)
./signer.sh start

# 4. Add a host and reload
broker-ctl host add --name web01 --addr web01.example.com:22 --user deploy --scan \
  --groups prod-web --sudo
broker-ctl reload

# (--config is a global flag, before the subcommand; every binary takes --version)
broker-ctl --config /secure/path/signer.json host list
broker-ctl --version            # short; add --verbose for build details

向客户端注册 stdio MCP：

// Claude Code — ~/.claude.json
"infrabroker": { "type": "stdio", "command": "/Users/<you>/bin/infrabroker",
                "args": ["serve-mcp", "-config", "/secure/path/config.json"] }

// OpenCode — ~/.config/opencode/opencode.json  (note: type "local", command is an array)
"infrabroker": { "type": "local",
                "command": ["/home/<you>/bin/infrabroker", "serve-mcp", "-config", "/secure/path/config.json"],
                "enabled": true }

完整设置说明——本地与外部签名模式、远程 OAuth 前端、主机字段、sudoers、PKI 和 broker-ctl——请参阅 OPERATIONS.md。模型的工具用法请参阅 USAGE.md。

API

完整参考文档：API.md。

服务	端点	身份验证	描述
签名服务	POST /v1/sign	mTLS	请求临时 SSH 证书
签名服务	GET /v1/hosts	mTLS	列出可访问的主机（按调用方组筛选）
签名服务	POST /v1/reload	mTLS	无需重启即可热重载 signer.json
控制平面	POST /v1/sign、/v1/approvals/{id}、…	mTLS	转发与人工审批
Broker HTTP	POST /v1/ssh_run	mTLS	执行一次性 SSH 命令
MCP HTTP	/.well-known/oauth-protected-resource	无	OAuth2 发现（RFC 9728）
MCP HTTP	Streamable HTTP	OIDC Bearer	MCP 工具

安全

安全态势——信任边界、分层控制（RBAC、命令策略、审批关卡、防护措施、源地址/TTL 绑定、链式审计、默认启用的机密信息脱敏），以及明确的非目标（mode=exec 会话会经过 Broker 预检，但除非主机启用了 sealed_exec，否则不会在主机上强制执行；不支持 KRL；机密信息脱敏采用尽力而为的正则匹配，并非保证，……）——详见 THREAT_MODEL.md。

如需报告漏洞，请参阅 SECURITY.md。CI 会在每次推送和 PR 中执行 gofmt、 go vet、go test -race 和 govulncheck。

测试

make test                      # go test -race ./...  (cert build, policy/RBAC/sudo/PTY, hops, …)
bash lab/run_signer_lab.sh     # external signer: broker without ca_key + policy + denial
bash lab/run_mcp_lab.sh        # bastion + target (ProxyJump) MCP scenario
bash lab/run_lab.sh            # HTTP/mTLS frontend

许可证

版权所有 (C) 2026 Luis González Fernández。

本程序为自由软件：你可以根据自由软件基金会发布的 GNU 通用公共许可证 v3.0 条款重新发布和/或修改本程序。发布本程序是希望它能发挥作用，但不提供任何 保证。完整文本请参阅 LICENSE。