内容
# 🛡️ 守卫
[](https://pypi.org/project/warden-mcp/)
[](https://pypi.org/project/warden-mcp/)
[](LICENSE)
**适用于 MCP 的安全中间件。** 将您的 AI 客户端指向守卫（Warden），而不是原始工具服务器 - 只需一行配置，无需任何代码更改 - 每次工具调用都会被篡改证据记录，允许/拒绝/控制由策略决定，当操作危险时需要人工审批，并且会扫描注入和秘密/PII 外泄。
> 每个人的代理人都正在被构建。守卫（Warden）使它们可以安全运行。
## 工作原理
```
AI 客户端 ──MCP──▶ 守卫（Warden） ──MCP──▶ 下游 MCP 服务器
策略 · 审计 · 审批 · 防御 （文件系统，GitHub，支付，…）
```
守卫（Warden）是您客户端的 MCP **服务器**，也是每个真实服务器的 MCP **客户端**。它聚合了它们的工具（命名空间 `server__tool`）并路由每个 `tools/call` 通过：
**策略 → 审计（request）→ 防御（args）→ [拒绝 | 批准 | 允许] → 转发 → 防御（result）→ 审计（response）**
## 快速入门
```bash
uvx warden-mcp init # 编写一个启动器 warden.yaml
uvx warden-mcp run --config warden.yaml
uvx warden-mcp audit verify # 证明审计日志未被篡改
```
默认启用拉绳防御（TOFU 工具定义固定）- 下游工具在您首次批准后重新定义将被隔离，直到您重新批准。
### 可选：针对恶意操作员的篡改证据
普通审计日志检测编辑而无需重新链接。要使篡改可被具有主机写入权限的人检测到，请启用 **前向安全密封** （标准库，无需额外依赖）：
```bash
uvx warden-mcp audit setup-keys --out warden.seed # 打印一个验证种子 - 存储在盒子外
uvx warden-mcp run --seal-state warden_seal_state.json --anchor heads.jsonl
uvx warden-mcp audit verify --log warden_audit.jsonl --seed warden.seed # 验证密封
```
在泄露之前密封的记录无法被伪造或重写 - 密封它的密钥会被逐步推进并销毁。 （篡改**证据**，而非篡改**证明**：删除始终是可能的，您可以通过锚定的头部检测到它。）
将您的客户端指向它（例如 `.mcp.json` / Claude Desktop / Cursor）：
```json
{ "mcpServers": { "warden": { "command": "uvx", "args": ["warden-mcp", "run"] } } }
```
## 策略（`warden.yaml`）
```yaml
mode: allow # 允许（记录所有，控制列出的）| 严格（除非允许，否则拒绝）
servers:
filesystem:
cmd: ["npx","-y","@modelcontextprotocol/server-filesystem","/work"]
tools:
read_file: { action: allow }
write_file: { action: gate, reason: "文件写入" }
delete_*: { action: deny }
payments:
url: "http://localhost:9001/mcp"
tools: { "*": { action: gate } }
sensitive_actions: [transfer, send, delete, purchase, grant, deploy]
rules:
- id: dangerous-shell
match: { arg_regex: "rm\\s+-rf|DROP\\s+TABLE" }
action: deny
- id: secret-egress
match: { direction: result, contains: ["BEGIN PRIVATE KEY", "password="] }
action: redact_and_flag
```
`policies/` 中的启动策略：**paranoid · balanced · dev**.
### 跨服务器数据流：致命三重奏防御
每个调用的规则都看不到跨会话的攻击 - 从一个服务器读取不受信任的内容，通过注入的指令进行控制，通过另一个服务器进行外泄。标记结束，守卫（Warden）跟踪流：只要不受信任的 **源** 将内容返回到会话中，任何可以外泄的 **汇** 都将被拒绝（或控制）：
```yaml
flow:
on_violation: gate # 控制（询问人工）| 拒绝（默认，关闭）
sources: ["web__*", "email__read*"] # 工具的结果是不受信任的内容
sinks: ["email__send*", "http__post", "slack__*"] # 可以发送数据出去的工具
```
“不受信任的内容接触上下文不得在没有人工干预的情况下访问具有外泄能力的工具。”
## 远程部署：HTTP 网关 + OAuth 2.1
将守卫（Warden）作为可部署的 HTTP MCP 网关（可流式传输）运行，而不是 stdio：
```bash
pip install "warden-mcp[http,auth]"
uvx warden-mcp run --http --host 0.0.0.0 --port 8080 --config warden.yaml
```
通过 `auth:` 块，守卫（Warden）是一个 **OAuth 2.1 资源服务器** - 每个到达 `/mcp` 端点的请求都必须携带有效的持有者令牌，否则会被拒绝 **在到达任何工具之前**，并带有 `401` 和 `WWW-Authenticate` 挑战。它根据 MCP 授权规范进行验证：RFC 9728 受保护资源元数据（在 `/.well-known/oauth-protected-resource` 处提供），**RFC 8707 受众绑定**（为其他服务颁发的令牌将被拒绝），JWKS 签名验证（仅非对称 - 无 `alg:none`），以及范围强制。
```yaml
auth:
resource: https://warden.example/mcp
issuer: https://auth.example/
jwks_uri: https://auth.example/.well-known/jwks.json
required_scopes: [mcp:call]
```
（stdio 是一个本地单用户信任边界，无需令牌;`--http` 无 `auth:` 块公开提供 - 将其放在您自己的边界后面。）
### 远程审批（Telegram）
在无头/ `--http` 模式下，没有终端，因此受控调用将关闭。相反，从您的手机批准它们 - `pip install "warden-mcp[telegram]"` 并添加：
```yaml
approval:
channel: telegram
bot_token_env: WARDEN_TELEGRAM_TOKEN # 从环境中读取令牌，绝不读取文件
chat_id: "123456789"
```
每个受控调用都发送一条带有内联 **批准** / **拒绝** 按钮的消息;超时或任何错误都将关闭。
## `mcp-scan` - 在信任服务器之前审计它
守卫（Warden）在运行时保护工具调用;`mcp-scan` 是静态的、预先安装的伴侣。将它指向 MCP 服务器，它会检查每个工具 **定义** 以防止工具中毒/提示注入/隐藏在描述中、模式中的机密、危险功能和 **致命三重奏组合** （一个可以读取不受信任的内容 **和** 外泄的服务器）。如果存在风险，则退出非零，因此它控制 CI。
```bash
mcp-scan --command npx --arg -y --arg @some/mcp-server # 或 --url https://…/mcp，或 --config .mcp.json
warden scan --config .mcp.json --json # 相同，作为守卫子命令
```
它重用了守卫（Warden）自己的防御语料库、固定指纹和数据流分类法 - 静态一半的相同引擎。 （填补了 Invariant 的 `mcp-scan` 被收购和关闭后留下的空白。）
## `warden prove` - 证明控制实际上阻止了攻击
`scan` 表示服务器 *可能* 做什么，而 `report` 表示控制 *配置* 了什么; **`prove` 显示它们 *实际阻止* 了什么**。它通过生产中运行的精确拦截器运行一套确定性攻击（SSRF，路径遍历，命令和 SQL 注入，秘密外泄，功能升级） - 部分源自 *您的* 配置 - 并报告每次攻击是否阻止。退出 2 如果任何攻击泄漏，因此它控制 CI。
```bash
warden prove --config warden.yaml --html effectiveness.html # 进程内，配置派生
warden prove --live --config warden.yaml --html live_proof.html # 端到端：真实客户端 → 代理 → 真实服务器，通过 stdio
warden prove --config warden.yaml --sign warden_audit.jsonl --cert cert.json # 篡改证据
```
`--live` 面向真实的下游，通过真实的代理，并从其实时工具模式中生成攻击 - 证明在电线上发生阻塞，而不是仅仅在单元测试中。 `--sign` 将证明锚定在哈希链审计日志中，并发出一个证书，将报告的 `sha256` 与其链位置绑定，因此证据在事后无法编辑。参见 **[docs/CONTROLS.md](docs/CONTROLS.md)** 获取完整的控制集，策略优先级（包括 `capability_deny_overrides`）和配置模式。
## 为什么值得信赖
- **篡改证据审计** - 哈希链 JSONL;`warden audit verify` 检测任何编辑/插入/删除。添加 **前向安全密封** 以捕获即使是具有主机操作员权限的人也篡改和重新链的日志。
- **拉绳防御** - TOFU 固定隔离了一个工具，其定义在批准后更改。
- **关闭失败** - 批准超时，无通道，防护措施无警报，或任何非是 ⇒ 阻止。
- **深度防御** - 防御硬拒绝一个明确破坏性的有效载荷（`rm -rf`，`mkfs`，`DROP TABLE`）并在策略允许时编辑和隐藏泄漏的机密（提供者密钥，JWT，私钥）。`direction: result` 规则可以拒绝泄漏的响应（例如私钥）。
- **默认不信任下游** - 工具元数据被命名空间 + 验证 + 剥离，从不通过原始;恶意下游无法遮蔽另一个或通过工具描述注入。
- **零外泄** - 核心代理 + 防御不进行任何网络调用。防御是纯本地正则表达式 - 请求路径中没有 LLM（确定性，快速，无内容离开盒子）。
## 布局
```
warden/
schemas.py 共享合同（封闭枚举决策，默认哈希审计）
proxy.py MCP 上游服务器 + 下游客户端 + 命名空间 + 固定检查
interceptor.py 策略→审计→审批→防御管道（+ REDACT + 结果规则）
policy.py YAML → 允许/拒绝/控制/编辑/编辑并标记（+ 功能规则，功能拒绝覆盖）
runtime.py 单一控制线路源 - build_interceptor（生产 == 证明）
capabilities.py 工具 → 功能集（READ/WRITE/DELETE/EXECUTE/NETWORK/CREDENTIAL/FINANCIAL/ADMIN）
capsnapshot.py 功能基线快照 + CI 扩展门（warden 功能）
boundaries.py 网络域 / 文件系统根允许列表（资源边界）
argconstraints.py 类型参数值约束（类型/枚举/最小-最大/模式/电子邮件域）
postconditions.py 声明结果不变性 - 验证然后提交
effectiveness.py 进程内控制效果证明（warden prove）
liveprove.py 线上证明 - 真实客户端→代理→服务器，模式派生攻击（--live）
evidence.py 将证明锚定在哈希链中 → 可验证证书（--sign）
report.py 治理姿态 + 审计摘要证据报告（warden report）
targets/ 故意暴露的脆弱参考 MCP 服务器（--live 目标）
guard.py 提示注入语料库 + 机密/PII + shell/SQL/路径检测
audit.py 哈希链篡改证据日志 + 验证（+ 前向安全密封）
sealing.py 前向安全密封 + 外部锚定（敌对操作员防御）
pinning.py TOFU 工具定义固定（拉绳防御）
auth.py OAuth 2.1 资源服务器 - RFC 9728/8707，JWKS，范围（额外：[auth]）
http.py 可部署的 HTTP MCP 网关 + 持有者身份验证中间件（额外：[http]）
flow.py 跨服务器数据流 / 致命三重奏防御（会话污染跟踪）
scan.py mcp-scan - MCP 服务器工具的静态预安装风险审计
scan_cli.py `mcp-scan` 控制台脚本 + `warden scan` 子命令
approval/ 人工在环中 - CLI（/dev/tty）+ Telegram（无头/远程，额外：[telegram]）
```
Apache-2.0 · 由 Always Ready Allies LLC 构建。安全联系方式：请参见 `SECURITY.md`。
