Sushank05/mcp-doorman
GitHub: Sushank05/mcp-doorman
mcp-doorman 是一个部署在 MCP 客户端与服务器之间的轻量级安全代理网关，为个人开发者提供工具调用策略管控、密钥脱敏、注入检测和审计日志等防护能力。
Stars: 0 | Forks: 0
# mcp-doorman
**MCP 服务器的安全网关 —— 每一次工具调用都会在门口接受检查。**
[CI](https://github.com/YOUR_GITHUB_USERNAME/mcp-doorman/actions/workflows/ci.yml)
[npm](https://www.npmjs.com/package/mcp-doorman)
[许可证：Apache-2.0](LICENSE)
[欢迎 PR](CONTRIBUTING.md)
`mcp-doorman` 是一个直接插入的代理，位于您的 AI 代理（Claude Desktop、Claude Code、Cursor、VS Code，任何 MCP 客户端）和它使用的 MCP 服务器之间。只需一条命令，零基础设施，每个 `tools/list` 和 `tools/call` 都会通过一个防护 pipeline：
- 🛂 **策略引擎** —— 支持基于 glob 匹配的、针对每个工具的 allow / deny / require-approval（允许 / 拒绝 / 需审批）规则
- 🕵️ **密钥脱敏** —— AWS key、GitHub/Slack/Stripe/OpenAI/Anthropic token、私钥、JWT、银行卡（经 Luhn 算法校验）……在到达模型*之前*，这些敏感信息就会从工具结果中被清除
- 💉 **Prompt 注入筛查** —— 标记或拦截那些试图指令模型的工具结果（以及工具*描述* —— 即工具投毒）
- 📌 **Rug-pull 检测** —— 工具定义在首次使用时会被哈希锁定；如果服务器静默替换了描述，该工具将被拦截，直到人工重新锁定
- 🚦 **速率限制** —— 针对每个工具的 token bucket（令牌桶）限制了失控代理循环的影响范围
- 🙋 **人工审批网关** —— 敏感工具会通过 [MCP elicitation](https://modelcontextprotocol.io/specification/draft/client/elicitation) 在您的客户端中直接触发交互式审批提示
- 🧾 **审计日志** —— 每次调用、拒绝、脱敏和标记都会记录在一个只追加的 JSONL 文件中
## 为什么会有这个项目
每个人都离交出自己未经审查的进程 API key 以及直通模型上下文窗口的通道仅一步之遥：只要执行一次 `npx some-random-mcp-server`。已记录的攻击类型是真实的，而非假设性的：
| 攻击 | 原理 |
| ----------------------------- | ----------------------------------------------------------------------------------------------------- |
| **工具投毒 (Tool poisoning)** | 恶意指令隐藏在工具的*描述*中，在大多数客户端 UI 中不可见 |
| **Rug pull (诱饵替换)** | 服务器在第 1 天提供无害的工具，在您批准后将它们的定义替换掉 |
| **间接 Prompt 注入** | 由*合法*工具获取的网页/工单/电子邮件中带有旨在影响模型的指令 |
| **密钥泄露** | 一个工具结果中泄露的凭据 + 一条注入的指令 = 您的密钥被发送到了其他人的服务器上 |
| **失控循环** | 困惑或被劫持的代理进行批量删除、批量发送邮件、批量抓取操作 |
面向拥有 Kubernetes 集群的平台团队，企业级 MCP 网关已经存在。**但没有任何轻量级的工具来保护个人开发者的笔记本电脑 —— 而这恰恰是 99% 的 MCP 服务器实际运行的地方。** 这正是本项目要填补的空白。
## 快速开始（60 秒）
```
# 1. 创建一个 config
npx -y mcp-doorman init
# 2. 编辑 doorman.config.json — 在其中放入你的真实服务器
# 3. 固定当前的 tool 定义（首次使用即信任）
npx -y mcp-doorman pin --config doorman.config.json
```
然后将您的客户端指向网关，而**不是**直接指向您的服务器。Claude Desktop / Claude Code / Cursor：
```
// BEFORE — every server talks straight to the model
{
"mcpServers": {
"github": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-github"] },
"filesystem": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-filesystem", "/repos"] }
}
}
// AFTER — one doorman guards them all
{
"mcpServers": {
"doorman": {
"command": "npx",
"args": ["-y", "mcp-doorman", "run", "--config", "/absolute/path/to/doorman.config.json"]
}
}
}
```
工具会以命名空间的形式显示，例如 `github__create_issue`、`filesystem__read_file` 等，此外还有两个内置工具：`doorman__status` 和 `doorman__recent_events`（您可以问您的代理：*“doorman 最近拦截了什么？”*）。
## 查看运行效果
```
git clone https://github.com/Sushank05/mcp-doorman && cd mcp-doorman
npm install
npm run demo
```
该演示将网关连接到了一个故意行为不端的服务器（[examples/demo-server.mjs](examples/demo-server.mjs)），该服务器会泄露虚假凭据、提供 Prompt 注入 payload，并提供一个破坏性工具 —— 展示了每个防护环节如何捕获它。
## 工作原理
```
flowchart LR
A["MCP client\n(Claude Desktop, Cursor, ...)"] -- stdio --> D
subgraph D [mcp-doorman]
direction TB
P[policy] --> R[rate limit] --> AP[approval] --> RD[redaction] --> I[injection scan] --> AU[(audit log)]
end
D -- stdio --> S1[github server]
D -- stdio --> S2[filesystem server]
D -- streamable HTTP --> S3[remote server]
```
该网关对于您的客户端来说是一个 MCP **服务器**，而对于每个上游（stdio 子进程或 streamable-HTTP endpoint）来说则是一个 MCP **客户端**，并将它们聚合在一个连接之后。它基于官方的 [TypeScript SDK](https://github.com/modelcontextprotocol/typescript-sdk) 构建。
## 配置
所有配置都存放在一个 JSON 文件中。包含所有选项的完整示例：
```
{
"servers": {
"github": {
"command": "npx",
"args": ["-y", "@modelcontextprotocol/server-github"],
"env": { "GITHUB_PERSONAL_ACCESS_TOKEN": "${GITHUB_TOKEN}" } // ${VAR} = read from gateway env
},
"remote": { "url": "https://mcp.example.com/mcp", "headers": { "Authorization": "Bearer ${MCP_TOKEN}" } }
},
"policy": {
"defaultAction": "allow", // "allow" | "deny" | "approve"
"rules": [ // first match wins, evaluated top-down
{ "match": "*__delete*", "action": "deny", "reason": "no destructive tools" },
{ "match": ["github__create_*", "*__send_*"], "action": "approve" },
{ "match": "filesystem__*", "action": "allow" }
]
},
"redaction": {
"enabled": true,
"disable": [], // built-in rule names to turn off
"enableOptIn": ["email"], // opt-ins: "email", "us-ssn", "ipv4"
"custom": [{ "name": "acme-id", "pattern": "ACME-[0-9]{6}" }],
"redactArguments": false // also scrub model-supplied arguments
},
"injection": {
"action": "flag", // "flag" (warn the model) | "block" | "off"
"scanToolDescriptions": true, // tool-poisoning check on tools/list
"custom": []
},
"pinning": {
"enabled": true,
"onNewTool": "pin", // "pin" (TOFU) | "block" (until `mcp-doorman pin`)
"onChangedTool": "block" // "block" | "warn"
},
"rateLimit": { "perMinute": 120, "perTool": { "*__send_*": 5 } },
"approval": { "fallback": "deny", "timeoutMs": 120000 }, // fallback when client lacks elicitation
"audit": { "enabled": true, "includeArguments": true, "includeResults": false },
"logLevel": "info"
}
```
锁定状态和审计日志默认存放在配置文件旁边的 `.pins.json` / `.audit.jsonl` 中。
### CLI
| 命令 | 作用 |
| --------------------------------- | ---------------------------------------------------------------------- |
| `mcp-doorman run --config ` | 通过 stdio 启动网关（默认命令） |
| `mcp-doorman pin --config ` | 连接到所有上游并锁定（信任）它们当前的工具定义 |
| `mcp-doorman init` | 写入一个带有合理默认值的初始配置 |
## 诚实的局限性
夸大其词的安全工具比没有还糟糕。请阅读本部分。
- **启发式方法是可以被绕过的。** 注入模式可捕获已记录的、常见的攻击形式。有动机的攻击者可以转换措辞绕过任何正则表达式。请使用 `deny`/`approve` 策略作为硬性边界；筛查只是纵深防御。
- **脱敏是尽力而为的。** 已知的 token 格式可以被可靠捕获；而没有上下文的随机十六进制密钥则不行。不要将代理指向凭据存储区。
- **这不是一个沙盒。** 上游服务器仍然以您用户的特权作为子进程运行。Doorman 保护的是*协议*；请将其与容器（例如 [ToolHive](https://github.com/stacklok/toolhive) 风格）结合使用，以保护*进程*。
- **TOFU（信任优先）只认首次所见。** 锁定检测的是*更改*，而不是从第一天起就存在恶意的工具 —— 这是描述扫描器和您自己审查的工作。
- **审批网关需要 elicitation（交互请求）。** 不支持 elicitation 的客户端将回退到 `approval.fallback`（默认拒绝）。
## 路线图 — 请求帮助 🙌
- [ ] `resources/*` 和 `prompts/*` 代理（目前仅支持工具）
- [ ] 透传 sampling 和 roots
- [ ] 社区规则包（`doorman-rules-finance`、`doorman-rules-healthcare`……）
- [ ] 学习模式：观察一周，提出最小权限策略
- [ ] OPA / Cedar 策略后端
- [ ] `mcp-doorman audit` 子命令：美观地打印和查询 JSONL 日志
- [ ] 用于审计可视化的 Web 仪表板
- [ ] 基于熵的通用密钥检测
认领以上任何内容，或者从一个 `[good first issue](https://github.com/YOUR_GITHUB_USERNAME/mcp-doorman/labels/good%20first%20issue)` 开始。新的检测规则是最简单的贡献方式：一个正则表达式 + 两个测试。请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 和 [docs/detection-rules.md](docs/detection-rules.md)。
## 开发
```
npm install
npm test # 69 tests: unit + full stdio e2e
npm run build
npm run demo # watch the guards fire live
```
## 许可证
[Apache-2.0](LICENSE) — 可免费用于任何目的，并包含明确的专利授权。
标签：AI安全, Chat Copilot, DLL 劫持, GNU通用公共许可证, MCP网关, MITM代理, Node.js, StruQ, 大语言模型, 安全策略引擎, 审计日志, 提示词注入防护, 时序数据库, 暗色界面, 自动化攻击