内容
# infrabroker
[](https://github.com/luisgf/infrabroker/actions/workflows/go.yml)
[](https://github.com/luisgf/infrabroker/releases)
[](https://goreportcard.com/report/github.com/luisgf/infrabroker)
[](LICENSE)
[](https://luisgf.github.io/infrabroker/)
**基础设施访问代理，适用于 AI 代理 — SSH 和 Kubernetes。该模型从不接触凭证。** *(前身 `ssh-broker`)*
代理请求一个**操作** — 在主机上运行命令，查询或更改集群。infrabroker 会根据策略检查它，执行使用为该单个操作生成的凭证 — **短期的、范围受限的 SSH 证书** 或 **短期的绑定 ServiceAccount token** — 并返回**仅输出**。密钥、证书和令牌存储在代理的内存中，调用结束后会被丢弃：没有任何内容进入模型的上下文，因此注入模型的代理无法窃取。
三个前端共享同一个引擎（`internal/broker`）和工具表面（`internal/mcpserver`）：
- **MCP stdio（本地，推荐用于个人使用）** — `cmd/mcp-broker`。工具：
`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（远程，多用户）** — `cmd/mcp-broker-http`，
可流式传输的 HTTP。相同的工具，但每个客户端都使用本地验证的 **OIDC bearer token** 进行身份验证；
用户身份（和组，用于基于用户的 RBAC）被传播到签名者。
- **HTTP + mTLS** — `cmd/broker`，`POST /v1/ssh_run`（一次性），适用于使用客户端证书进行身份验证的网络代理。
## 文档
本 README 是一个入口页面。详细信息存放在专注的、单一来源的文档中：
| 文档 | 内容 |
|---|---|
| [架构.md](docs/ARCHITECTURE.md) | 图表、请求流程、设计决策、sudo 提升、会话、多 CA |
| [威胁模型.md](docs/THREAT_MODEL.md) | 参与者、信任边界、安全控制和明确的非目标/空白 |
| [操作.md](docs/OPERATIONS.md) | 运行手册：启动、添加主机、热重载、`broker-ctl`、PKI 轮换、配置 |
| [API.md](docs/API.md) | 所有服务的 HTTP 端点参考 |
| [用法.md](docs/USAGE.md) | MCP 工具（SSH + Kubernetes）、dry-run 和审计审查（适用于模型/操作员）的指南 |
| [安全.md](docs/SECURITY.md) | 漏洞披露政策 |
| [贡献.md](docs/CONTRIBUTING.md) · [编码风格.md](docs/CODING_STYLE.md) | 工作流程、版本控制、Go 风格 |
## 为什么选择 infrabroker
- **防外泄（提示注入）：** 短期密钥/证书/令牌仅存在于代理的内存中；它们从不进入模型的上下文。
- **无 kubeconfigs 的 Kubernetes：** 签名者为每个操作生成一个短期的**绑定 ServiceAccount token**（TokenRequest API）；
每个集群都是**默认拒绝**，具有每个动词/资源/命名空间的策略和相同的 dry-run、批准和审计路径，如 SSH。
- **防重用：** 每个证书都带有数分钟的 TTL、`source-address`（代理或堡垒 IP）和一次性 `force-command`。
在其主机/时间/IP 之外，它变得无用。
- **受控的提升：** `allow_sudo` / `allowed_sudo_users` 存在于签名者中；
一个被破坏的代理无法在策略禁止的情况下提升权限。
- **CA 泄露范围限定：** 每个主机组一个 CA 密钥（`ca_keys`），每个密钥可选地存储在 Azure Key Vault 中 —
私钥从不离开 HSM。
- **审计/不可否认性：** 追加日志，Ed25519 链式关联，由 `serial` 在签名者、代理和 `sshd` 之间关联。
完整的威胁模型 — 包括系统故意**不**防御的内容 — 在 [威胁模型.md](docs/THREAT_MODEL.md) 中。
## 工作原理
```
AI 模型 ──工具调用──> 代理 ──mTLS──> [控制平面] ──mTLS──> 签名者
(无凭证) (RAM 中的临时密钥 (批准 + (CA 密钥 +
，从不存储在磁盘上) 保护措施， 策略 + RBAC，
) 没有 CA 密钥) 签名证书)
│
└── 使用临时证书的 SSH ──> 堡垒 ──> 目标主机
└─ 标准输出/标准错误/退出代码 ─> 模型
```
代理发送一个**意图**（`{host, role, purpose, command?, sudo?, pty?, pubkey, …}`）；
签名者根据策略推导出每个证书约束并返回签名的证书。临时私钥在代理中生成，从未离开过它。
有关请求流程、设计决策和每跳 ProxyJump 证书图，请参见 [架构.md](docs/ARCHITECTURE.md)。
## 功能概述
| 功能 | 简介 | 更多信息 |
|---|---|---|
| **临时证书** | 每个操作的 RAM 中的 Ed25519 密钥对；分钟级、范围受限的证书。无可重用密钥。 | [架构](docs/ARCHITECTURE.md) |
| **外部签名者** | 单独的 `cmd/signer` 持有 CA 密钥和策略；代理绝不持有。 | [架构](docs/ARCHITECTURE.md) |
| **多 CA + HSM** | 通过 `ca_keys` 每个主机组一个 CA 密钥；本地 PEM 或 Azure Key Vault。 | [架构](docs/ARCHITECTURE.md#multi-ca--azure-key-vault-v1110) |
| **AI 操作防火墙** | 每个主机或**按组可组合**的命令策略（允许/拒绝/需要批准），POSIX-sh AST 解析，dry-run。 | [架构](docs/ARCHITECTURE.md#ai-action-firewall) · [用法](docs/USAGE.md) |
| **人工审批** | 可选控制平面门控 `require_approval` 命令，需经外部批准；签名者强制执行。 | [架构](docs/ARCHITECTURE.md#human-in-the-loop--control-plane) · [API](docs/API.md#control-plane-api) |
| **行为防护** | 按主题的异常检测（速率、新主机、新命令）；观察或强制执行。 | [架构](docs/ARCHITECTURE.md#human-in-the-loop--control-plane) |
| **RBAC** | 代理-CN 组（mTLS）+ 按最终用户 OIDC 组；失败关闭。 | [架构](docs/ARCHITECTURE.md#rbac) |
| **sudo / PTY** | 策略门控提升（`sudo -n`）和 PTY 分配，按主机。 | [架构](docs/ARCHITECTURE.md#privilege-elevation-sudo-nopasswd) |
| **Kubernetes 代理** | 具有每个操作的绑定 SA 令牌、默认拒绝动词/资源/命名空间策略、dry-run 的 `k8s_*` 工具。 | [用法 §10](docs/USAGE.md#10-kubernetes-tools-k8s_) |
| **会话记录** | `shell`/`pty` 会话到 ASCIIcast v2（`.cast`），按 `session_id` 索引。 | [用法 §8](docs/USAGE.md#8-session-recording) |
| **链式审计** | 追加日志，Ed25519 签名，SHA-256 链式关联；按 `serial` 关联。 | [用法 §7](docs/USAGE.md#7-reviewing-audit-logs) · [API](docs/API.md#audit-log-correlation) |
| **热重载** | `signer.json` 重新读取（并验证）而无需重启，通过 `POST /v1/reload` 或 SIGHUP。 | [操作 §3](docs/OPERATIONS.md#3-hot-reload) |
## 与现有解决方案的比较
几个工具解决了 SSH 访问控制或 AI 代理凭证安全问题，但没有一个能涵盖 infrabroker 在轻量级、自主托管包中针对的完整组合。
| 功能 | **infrabroker** | Teleport | Vault + SSH 引擎 | StrongDM | ssh-mcp |
|---|---|---|---|---|---|
| 内存中的临时证书（无磁盘） | ✅ | ✅ | ✅ | ❌ | ❌ |
| 单独的代理/签名服务 | ✅ | ✅ | 部分 | ❌ | ❌ |
| MCP 原生（AI 代理） | ✅ | ✅（2025） | ✅（2025） | ❌ | ✅ |
| MCP 传输上的 OAuth2/OIDC | ✅ | ✅ | ✅ | ❌ | ❌ |
| 按命令策略 + dry-run（AI 操作防火墙） | ✅ | ❌ | ❌ | ❌ | ❌ |
| AI 命令的人工审批 | ✅ | ❌ | ❌ | ❌ | ❌ |
| 按代理的行为防护（异常/速率） | ✅ | ❌ | ❌ | ❌ | ❌ |
| 会话记录（ASCIIcast v2，stdin+stdout+stderr） | ✅ | ✅ | ❌ | 部分 | ❌ |
| 加密链式审计日志 | ✅ | ❌ | ❌ | 部分 | ❌ |
| 单二进制/简单自主托管 | ✅ | ❌ | ❌ | ❌ | ✅ |
| CA 密钥的 HSM/KMS | ✅（AKV） | ✅ | ✅ | — | — |
**[Teleport](https://goteleport.com/)** 是最接近的商业等价产品 —
具有短期 SSH 证书、RBAC 和 2025 年的 *Secure MCP*；其 2026 年 1 月的 *Agentic Identity Framework* 针对相同的威胁模型。
区别在于操作权重：Teleport 需要一个专用的控制平面集群、记录代理和 Web UI —
比 Go 二进制文件 + 签名者大得多。
**[HashiCorp Vault SSH 秘密引擎](https://developer.hashicorp.com/vault/docs/secrets/ssh)**
是一个具有完整 HSM/KMS 支持的 SSH CA 和（2025 年）其自己的 MCP 服务器，但它只提供**签名**部分 —
您仍然需要自己构建执行层（`engine.go`、`session.go`、MCP 工具）。
**[StrongDM](https://www.strongdm.com/)** 隐藏凭证但存储
长期的密钥而不是在内存中生成临时证书，使其对窃取更脆弱。
**[Smallstep SSH CA](https://smallstep.com/)** 是一个轻量级、OIDC 集成的 SSH CA（接近 `cmd/signer`）而没有执行代理或 MCP 层。
**[ssh-mcp](https://github.com/tufantunc/ssh-mcp)** 通过 MCP 将 SSH 公开给 LLM，但使用**静态 SSH 密钥** —
正是此代理所防止的漏洞。
**[CyberArk PAM](https://docs.cyberark.com/)** 提供
可比较的 JIT 证书访问，但它是用于人类操作员的封闭企业平台，而不是 AI 工作负载。
**它适合哪里：** MCP 原生 AI 代理访问 + 内存中临时证书 +
单独的签名者 + ASCIIcast 记录 + 链式审计，作为一组 Go
二进制文件而无需集群。企业功能（Web UI、多区域 HA）正在路线图中（参见 [HANDOFF.md](docs/HANDOFF.md)）。
## 安装
- **预编译二进制文件** — 每个 [release](https://github.com/luisgf/infrabroker/releases)
都附带 `infrabroker_<ver>_{linux,darwin}_{amd64,arm64}.tar.gz`，包含所有六个
二进制文件，以及安装 tarball（`infrabroker-v<ver>.tar.gz`），用于 systemd 生产路径。
- **go install** — `go install github.com/luisgf/infrabroker/cmd/mcp-broker@latest`
（纯 Go，无 CGO；其他 `cmd/` 二进制文件也是如此）。
- **容器** — `ghcr.io/luisgf/infrabroker`（docker 或 podman，多架构；
入口点是 stdio MCP 前端）。参见 [CONTAINERS.md](docs/CONTAINERS.md)，
包括一个与玩具主机对抗的全栈运行的 compose 演示：
`cd examples/compose && docker compose up --build -d`（或 `make demo`）。
- **从源代码** — 快速入门如下。
使用 Claude Code 注册，单行：
```bash
claude mcp add infrabroker -- ~/bin/mcp-broker -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
```
## 快速入门
```bash
# 1. 构建（make 将 git 标签中的版本注入到每个二进制文件中）
make install # → ~/bin/{signer,broker,broker-ctl,mcp-broker,...}
# 或单个二进制文件： make signer
#（普通的 `go build ./cmd/...` 也有效；它会报告一个 dev-<commit> 版本）
# 2. 启动签名服务（必须在代理之前运行）
./signer.sh start
# 3. 添加主机并重载
broker-ctl host add --name web01 --addr web01.example.com:22 --user deploy --scan \
--groups prod-web --sudo
broker-ctl reload
# (--config 是一个全局标志，在子命令之前；每个二进制文件都接受 --version）
broker-ctl --config /secure/path/signer.json host list
broker-ctl --version # 短；添加 --verbose 获取构建详细信息
```
使用您的客户端注册 stdio MCP：
```jsonc
// Claude Code — ~/.claude.json
"infrabroker": { "type": "stdio", "command": "/Users/<you>/bin/mcp-broker",
"args": ["-config", "/secure/path/config.json"] }
// OpenCode — ~/.config/opencode/opencode.json （注意：类型 "local"，命令是数组）
"infrabroker": { "type": "local",
"command": ["/home/<you>/bin/mcp-broker", "-config", "/secure/path/config.json"],
"enabled": true }
```
完整的设置 — 本地或外部签名模式、远程 OAuth 前端、主机
字段、sudoers、PKI 和 `broker-ctl` — 在 [操作.md](docs/OPERATIONS.md) 中。
模型工具用法在 [用法.md](docs/USAGE.md) 中。
## API
完整参考：[API.md](docs/API.md)。
| 服务 | 端点 | 认证 | 描述 |
|---|---|---|---|
| 签名者 | `POST /v1/sign` | mTLS | 请求临时 SSH 证书 |
| 签名者 | `GET /v1/hosts` | mTLS | 列出可访问的主机（按调用者组过滤） |
| 签名者 | `POST /v1/reload` | mTLS | 热重载 `signer.json` 而无需重启 |
| 控制平面 | `POST /v1/sign`，`/v1/approvals/{id}`，… | mTLS | 转发 + 人工审批 |
| 代理 HTTP | `POST /v1/ssh_run` | mTLS | 执行一次性 SSH 命令 |
| MCP HTTP | `/.well-known/oauth-protected-resource` | 无 | OAuth2 发现（RFC 9728） |
| MCP HTTP | 流式 HTTP | OIDC 持有者 | MCP 工具 |
## 安全
安全态势 — 信任边界、层叠控制（RBAC、命令
策略、审批门控、防护、源地址/TTL 固定、链式审计），
以及**明确的非目标**（`mode=exec` 会话是代理预检查的，但不是主机强制的，无 KRL，机密日志记录原样，审计失败打开，…）— 在
[威胁模型.md](docs/THREAT_MODEL.md) 中记录。
要报告漏洞，请参见 [安全.md](docs/SECURITY.md)。CI 强制执行 `gofmt`、
`go vet`、`go test -race` 和 `govulncheck` 在每次推送和 PR 上。
## 测试
```bash
make test # go test -race ./... （证书构建、策略/RBAC/sudo/PTY、跳跃、…）
bash lab/run_signer_lab.sh # 外部签名者：代理无 ca_key + 策略 + 拒绝
bash lab/run_mcp_lab.sh # 堡垒 + 目标（ProxyJump）MCP 场景
bash lab/run_lab.sh # HTTP/mTLS 前端
```
## 许可证
Copyright (C) 2026 Luis González Fernández.
本程序是免费软件：您可以根据 **GNU 通用公共许可证 v3.0** 的条款重新分发它和/或修改它，由自由软件基金会发布。它被分发，希望它会有用，但**没有任何保证**。有关完整的文本，请参见 [LICENSE](LICENSE)。
