KryptosAI/mcp-seatbelt

# MCP Seatbelt — AI Agent 工具的运行时护栏 **在协议层拦截危险的 MCP 工具调用。扫描、代理、执行。** [](https://github.com/KryptosAI/mcp-seatbelt/actions/workflows/mcp-seatbelt.yml) [](https://www.npmjs.com/package/@kryptosai/mcp-seatbelt) [](./LICENSE) [](https://nodejs.org) [](#contributors) []() [](https://github.com/KryptosAI/mcp-seatbelt/pkgs/container/mcp-seatbelt) []() []() 🌐 **网站:** [kryptosai.github.io/mcp-seatbelt](https://kryptosai.github.io/mcp-seatbelt/) — 演示、对比、定价 ## 存在的问题 AI 编程 agent（Cursor、Claude、VS Code、ChatGPT、Windsurf 等）会连接到暴露文件系统、shell 解释器、网络访问权限和环境变量的 MCP 服务器。静态扫描器会告诉你存在风险——但它们只能在事后采取行动。当扫描器标记出某个有风险的服务器时，agent 可能已经执行了破坏性的命令、泄露了凭据或连接到了不受信任的 endpoint。 **MCP Seatbelt 增加了一个运行时强制执行层。** 它作为 agent 和每个 MCP 服务器之间的策略代理，根据你控制的规则评估每一个 JSON-RPC 工具调用，并在危险请求到达上游之前将其拒绝。它不在 TCP 层面运行——而是在转发之前，在 L7（MCP 协议层）检查和门控每一次调用。 ## 它的功能 ### 检测与代理 - **检测 8 个客户端的 MCP 配置** — 自动从 Cursor、Claude Desktop、VS Code（用户 + 工作区）、ChatGPT Desktop、Codex、JetBrains IDE（IntelliJ、PyCharm、WebStorm 等）、Windsurf 以及项目本地文件（`.mcp.json`、`.mcp/config.json`）中发现 MCP 服务器配置。无需手动配置。 - **具有策略执行的运行时代理** — 在端口 9420 上启动透明的 JSON-RPC 2.0 代理。每个工具调用、资源访问和 prompt 请求都会被拦截，根据你的策略进行评估，并被允许、拒绝、警告或脱敏。三种模式：`default-deny`（零信任）、`allowlist`（已知安全项的白名单）和 `audit`（仅记录，不拦截）。 - **13 项内置风险规则** — 涵盖 shell 解释器（`bash`、`sh`、`zsh`、`python`、`node`）、沙箱绕过（`--no-sandbox`、`--disable-web-security`）、环境变量中的凭据暴露、Docker 特权容器、原始网络工具（`curl`、`nc`、`telnet`）、进程生成、破坏性的文件系统操作、远程 URL 访问、有风险的包运行器（`npx`、`uvx`）、权限提升（`sudo`、`chmod`）以及敏感的文件系统路径。 - **具有时间窗口规则、学习模式、规则继承和上下文感知的策略引擎** — 规则支持正则表达式匹配、精确匹配和子字符串包含。按星期几和小时范围（`timeWindow`）限制工具访问。根据客户端身份或请求速率（`contextCondition`）设置条件规则。策略可以 `extend`（继承）父模板。`audit` 模式可作为学习模式：运行它以观察实际的工具使用情况，然后再切换到 `enforce` 模式。 - **实时仪表板、SARIF 报告、CI/CD 集成和 observatory 桥接** — 实时 HTML 仪表板显示请求统计、拦截率、已连接客户端和最近被拦截的调用。生成用于 GitHub 代码扫描的 SARIF 2.1.0 报告。从 [mcp-observatory](https://github.com/KryptosAI/mcp-observatory) 导入安全发现，并自动将其转换为策略规则。当检测到严重风险时，`mcp-seatbelt check` 在 CI 中会以非零状态退出。 - **单次调用超时** — 挂起的工具调用将被终止，并返回清晰的 JSON-RPC 错误，而不是原始的 503 错误。可按规则进行配置（shell 命令为 10 秒，安全工具为 60 秒）。 ### 高级安全 - **OWASP LLM Top 10 映射** — 每个被拦截的调用都会标记 OWASP 类别（LLM01 Prompt Injection、LLM06 Excessive Agency 等） - **合规框架映射** — 策略规则带有 SOC2、HIPAA、GDPR、ISO 27001 和 PCI-DSS 控制标签 - **多步骤攻击链检测** — 基于 XState 的状态机跟踪调用序列：侦察 → 执行 → 持久化 → 数据窃取 - **Honeytoken 注入与检测** — 在工具响应中植入诱饵凭据（AWS key、GitHub token、数据库 URL），并在被访问时发出警报 - **取证会话捕获** — 将完整的请求/响应对记录为 `.mcpcap.json`，用于事件分析 - **Schema 感知的参数验证** — 根据声明的 JSON schema 验证工具参数，检测路径遍历和注入 - **威胁情报集成** — 查询 ThreatFox IOC 数据库以进行 IP/域名信誉检查 - **输入模糊测试** — 针对策略规则生成边缘情况的 payload，以发现绕过漏洞 - **基于角色的访问控制** — 使用 casbin 实现按 agent 分配权限。管理员可以执行所有工具，agent 获取范围内的访问权限 - **响应 DLP** — 扫描上游响应中的机密模式（API key、token、私钥）并将其脱敏 ## 快速开始 ``` npm install -g @kryptosai/mcp-seatbelt # or: brew install mcp-seatbelt npx @kryptosai/mcp-seatbelt init # scan all clients, assess risk, generate policy npx mcp-seatbelt proxy # start the enforcing proxy on port 9420 npx mcp-seatbelt dashboard # view live stats at http://localhost:9421 ``` 首次运行时，`init` 会创建 `.mcp-seatbelt/policy.yml`（你可编辑的规则集）和 `.mcp-seatbelt/risk-report.md`（每个服务器及其风险标记的摘要）。代理默认以 `audit` 模式启动——观察实际的工具使用情况，然后在准备好后切换到 `enforce` 模式。 ``` mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200 # find policy bypasses mcp-seatbelt record --output .mcp-seatbelt/sessions # forensic recording mode mcp-seatbelt rbac-init -o .mcp-seatbelt # init RBAC model + policy files ``` ### Docker 每次发布时，都会通过 GitHub Actions 自动构建并发布镜像。 ``` docker run -p 9420:9420 -v $(pwd)/.mcp-seatbelt:/app/.mcp-seatbelt ghcr.io/kryptosai/mcp-seatbelt:latest proxy ``` ### GitHub Action 使用官方 GitHub Action 将 MCP Seatbelt 作为 CI 安全门禁运行——它会检查检测到的 MCP 配置，针对具有代表性的工具调用模拟你的策略，并在出现严重风险时使构建失败。 #### CI/CD 集成 ``` - uses: KryptosAI/mcp-seatbelt@v0.4 with: mode: enforce fail-on-critical: true ``` 有关所有输入、输出和执行选项，请参见 [action.yml](./action.yml)。 ## 工作原理 ``` ┌─────────┐ JSON-RPC 2.0 ┌────────────────────────────────────┐ JSON-RPC 2.0 ┌─────────────┐ │ Agent │ ────────────────────▶ │ MCP Seatbelt Proxy │ ────────────────────▶ │ MCP Server │ │ (Cursor) │ │ (localhost:9420) │ │ (filesystem)│ └─────────┘ │ │ └─────────────┘ │ ┌──────────────┐ ┌───────────┐ │ │ │ Policy Engine│──│Interceptor │ │ │ │ ┌───────┐ │ │ ┌──────┐ │ │ │ │ │ Rules │ │ │ │Allow?│ │ │ │ │ │Allowlist│ │ │ │Deny? │ │ │ │ │ │Templates│ │ │ │Redact│ │ │ │ │ │TimeWin │ │ │ │Warn? │ │ │ │ │ └───────┘ │ │ └──────┘ │ │ │ └──────────────┘ └─────┬─────┘ │ │ │ │ │ ┌─────▼─────┐ │ │ │ Transport │ │ │ │ Client │ │ │ └───────────┘ │ └────────────────────────────────────┘ ``` - **代理** — 监听来自 AI agent 的入站 JSON-RPC 2.0 请求。管理服务器注册、代理 URL 路由和连接生命周期。 - **策略引擎** — 根据加载的策略评估每个请求。根据规则检查工具名称、参数和描述。返回 `allow`、`deny`、`warn` 或 `redact` 及其原因。 - **拦截器** — 应用引擎的决策。允许的调用将被转发。被拒绝的调用会收到 MCP 错误响应。被警告的调用会继续执行，但会被记录。`redact` 将匹配凭据模式的参数值替换为 `***`。 - **传输客户端** — 将允许的请求转发到真实的上游 MCP 服务器，并将响应流式传输回 agent。 代理永远不会向 agent 返回原始的上游错误。如果调用超过其超时时间，子进程将被终止，agent 会收到清晰的错误消息——没有 503 错误，也没有挂起的连接。 每个请求都会流经一个 **11 阶段的流水线**：RBAC → Schema 验证 → 路径安全 → 策略引擎 → 威胁情报 → Honeytoken → 攻击链 → 代理 → 响应 DLP → 取证 → 审计日志。 ## 对比 | 功能 | mcp-seatbelt | mcp-firewall | mcp-guardian | Prismor | mcp-proxy | |---|---|---|---|---|---|---| | 运行时拦截 | ✓ | ✓ | ✓ | ✓ | ✗ | | 安装前扫描 | ✓ | ✗ | ✗ | ✗ | ✗ | | 8+ 客户端检测 | ✓ | ✗ | ✗ | ✗ | ✗ | | 参数脱敏 | ✓ | ✗ | ✗ | ✗ | ✗ | | 学习模式 | ✓ | ✗ | ✗ | ✗ | ✗ | | 实时仪表板 | ✓ | ✗ | ✓ | ✗ | ✗ | | SARIF / GitHub 代码扫描 | ✓ | ✗ | ✗ | ✗ | ✗ | | mcp-observatory 集成 | ✓ | ✗ | ✗ | ✗ | ✗ | | 单次调用超时 | ✓ | ✗ | ✗ | ✗ | ✗ | | OWASP LLM Top 10 映射 | ✓ | ✗ | ✗ | ✗ | ✗ | | 合规性标记 (SOC2/HIPAA) | ✓ | ✗ | ✗ | ✗ | ✗ | | 攻击链检测 | ✓ | ✗ | ✗ | ✗ | ✗ | | Honeytoken/注入检测 | ✓ | ✗ | ✗ | ✗ | ✗ | | Schema 感知验证 | ✓ | ✗ | ✗ | ✗ | ✗ | | 威胁情报 (IOC 查询) | ✓ | ✗ | ✗ | ✗ | ✗ | | RBAC (按 agent 访问) | ✓ | ✗ | ✗ | ✗ | ✗ | Seatbelt 是唯一一款将安装前扫描与运行时强制执行相结合的工具，涵盖了所有主流的 AI agent 客户端，能够内联对凭据参数进行脱敏，并将来自 mcp-observatory 的静态分析结果桥接到实时策略规则中。 ## 高级安全功能 mcp-seatbelt 包含一个纵深防御安全流水线，通过多层评估每一个工具调用： | 层级 | 功能 | 描述 | |---|---|---| | 1 | **RBAC** | 基于 Casbin 的 agent 和工具角色访问控制。`mcp-seatbelt rbac-init` 生成模型和策略文件。 | | 2 | **Schema 验证** | 基于 AJV 的 JSON Schema 验证，根据编译的 schema 验证工具参数。 | | 3 | **路径安全** | 检测参数中的路径遍历、空字节注入和敏感路径访问。 | | 4 | **策略引擎** | 基于规则的评估，支持正则表达式/精确/包含匹配、时间窗口、上下文条件和参数约束。 | | 5 | **威胁情报** | 异步 ThreatFox IOC 查询，用于检查工具参数中的 IP 和域名。 | | 6 | **Honeytoken** | 在响应中植入诱饵凭据；当后续调用中出现 honeytoken 时检测数据窃取。 | | 7 | **攻击链跟踪** | 基于 XState 的状态机，跟踪多步骤攻击模式（侦察→执行→持久化→数据窃取）。 | | 8 | **取证捕获** | 启用后，将所有请求和响应记录在已签名的 `.mcpcap.json` 会话文件中。 | | 9 | **响应 DLP** | 扫描上游响应中的机密模式（API key、token、私钥）并将其脱敏。 | | 10 | **输入模糊测试** | 根据 JSON schema 生成边缘情况的 payload，并测试策略绕过的韧性。`mcp-seatbelt fuzz --policy policy.yml` | ### 输入模糊测试 `mcp-seatbelt fuzz` 使用 `json-schema-faker` 生成随机的工具调用参数，注入边缘情况的 payload（路径遍历、命令注入、SQL 注入、Log4Shell），并根据你的策略评估每个 payload。报告会指出绕过漏洞以及本应拦截它们的具体 payload 和规则。 ``` mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200 --json ``` ## 策略参考 ### CLI ``` mcp-seatbelt init --policy enforce # generate an enforcing policy mcp-seatbelt proxy --config my.yml # start proxy with custom policy mcp-seatbelt report --sarif # SARIF 2.1.0 output for CI mcp-seatbelt check # exit 1 if critical risks found mcp-seatbelt diff old.yml new.yml # compare two policy files mcp-seatbelt import-observatory # convert observatory findings to rules ``` ### 新命令 (v0.4.0) | 命令 | 描述 | |---------|-------------| | `mcp-seatbelt fuzz` | 针对 tool schema 模糊测试策略以发现绕过漏洞 | | `mcp-seatbelt record` | 以取证记录模式启动代理 | | `mcp-seatbelt rbac-init` | 初始化 RBAC 模型和策略文件 | | `mcp-seatbelt simulate` | 针对策略模拟工具调用并显示评估轨迹 | | `mcp-seatbelt` | 针对代理运行性能基准测试 | | `mcp-seatbelt test-policy` | 从测试 YAML 文件运行策略测试 | | `mcp-seatbelt baseline` | 从审计日志生成行为基线 | | `mcp-seatbelt verify-audit` | 验证已签名的审计日志完整性 | ### 内置规则（默认策略） | 规则 | 目标 | 描述 | |---|---|---| | `block-shell-execution` | command | 拦截直接的 shell 解释器调用（bash、sh、zsh、cmd、powershell） | | `block-sensitive-paths` | file | 拦截对 `/etc`、`/root`、`~/.ssh`、`~/.aws`、`C:\Windows` 的文件系统写入 | | `block-credential-access` | command | 拦截描述中提到密码、机密、token、密钥的工具 | | `redact-credentials` | command | 对键名匹配凭据模式的参数值进行脱敏 | | `block-private-network` | network | 拦截针对私有/回环地址范围的 HTTP 请求 | | `block-process-execution` | process | 拦截生成子进程或执行代码的工具 | | `allow-filesystem-writes-business-hours` | file | 仅允许在周一至周五 09:00-17:00 进行文件系统写入 | ### 策略模板 | 模板 | 默认操作 | 用例 | |---|---|---| | `minimal-workstation` | allow | 仅拦截 shell 执行和凭据访问；其他所有操作均允许 | | `pci-compliance` | deny | 拦截 shell、凭据、PAN/持卡人数据路径、篡改审计日志 | | `strict-production` | deny | 默认拦截所有工具调用、网络请求和文件系统操作 | 可以通过策略文件中的 `extends` 字段扩展模板： ``` version: '1' mode: enforce extends: - pci-compliance rules: - id: custom-rule target: network match: pattern values: ['.*'] action: deny ``` ### 规则 Schema ``` rules: - id: example-rule # unique identifier description: What this blocks # human-readable explanation target: command # command | file | network | env | process match: pattern # exact | pattern | contains values: # list of strings or regex patterns - '^rm\s+-rf' action: deny # allow | deny | warn | redact timeWindow: # optional — restrict by day/hour days: [Monday, Tuesday, Wednesday, Thursday, Friday] startHour: 9 endHour: 17 contextCondition: # optional — restrict by client or rate clientIn: [cursor, claude-desktop] maxRequestsPerMinute: 60 ``` ### 白名单 白名单中的条目将绕过所有拒绝规则。在运行 `init` 之后使用它，将已知安全的工具、路径、主机和环境变量列入白名单： ``` allowlist: tools: [safe-tool, read-only-fs] paths: [/home/user/projects/] hosts: [api.github.com] envVars: [NODE_ENV, PATH] ``` ## 客户端集成指南 启动代理后，更新每个客户端的 MCP 配置，使其通过 `localhost:9420` 路由。代理在启动时会打印一个代理 URL 表格——直接复制粘贴即可。 **Cursor** — `~/.cursor/mcp.json` ``` { "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } } ``` **Claude Desktop** — `~/Library/Application Support/Claude/claude_desktop_config.json` ``` { "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } } ``` **VS Code** — `.vscode/mcp.json` 或用户设置 ``` { "servers": { "my-server": { "url": "http://localhost:9420/my-server" } } } ``` **ChatGPT Desktop** — 应用配置 ``` { "mcpServers": { "my-server": { "url": "http://localhost:9420/my-server" } } } ``` **Codex / JetBrains / Windsurf** — 相同的模式：将 `command`/`args` 传输方式替换为 `"url": "http://localhost:9420/"`。 ## 与 mcp-observatory 结合使用 [mcp-observatory](https://github.com/KryptosAI/mcp-observatory) 可扫描静态的 MCP 服务器——审计源代码、供应链安全状况和清单规范。Seatbelt 提供了运行时的对应补充。 **工作流程：** 1. **优先扫描** — 在安装前运行 mcp-observatory 审计每个 MCP 服务器。它会生成一个安全发现工件（JSON）。 2. **转换** — `mcp-seatbelt import-observatory ./observatory-results.json` 将发现结果转换为策略规则。 3. **在运行时执行** — 代理加载这些规则，并拦截任何与 observatory 发现结果匹配的工具调用，从而闭环从静态分析到实时执行的全过程。 observatory 桥接 (`mergeObservatoryPolicy`) 可以将发现结果合并到现有的 Seatbelt 策略中，而不会覆盖你的自定义规则。 ## 性能 在 Apple M3、Node.js 22、macOS 上测量——以并发 10 对即时响应的上游发起 1,000 个请求（3 次运行的中位数，零失败请求）： | 指标 | 数值 | |---|---| | 吞吐量 | ~2,000 req/s（无代理直连为 ~4,300 req/s） | | 端到端延迟 (p50) | ~3.9 ms（比直连增加 ~2 ms） | | 端到端延迟 (p95) | ~6.6 ms | | 策略评估 (p50) | 6.6 µs (7 条规则)；8.5 µs (20 条规则) | | 策略评估 (p95) | 7.7 µs (7 条规则) | | DLP 开销 | 每个响应 ~+0.1 ms | | Schema 验证开销 | 每次调用 < 1 µs | | 内存（空闲） | ~74 MB | | 内存（负载下） | ~74 MB（10,000 个请求后保持平稳） | 策略大小（1 → 20 条规则）对端到端没有可测量的影响；每条规则的成本约为 ~0.25 µs，远低于传输 I/O。完整的方法论和分场景表格：[docs/benchmarks.md](docs/benchmarks.md)。可以在你自己的硬件上运行 `mcp-seatbelt benchmark`。 ## 企业版 [mcp-observatory Cloud](https://observatory.anomaly.ai) 为团队和组织提供托管仪表板、私有 CI 扫描、认证徽章和供应链合规报告。Seatbelt 集成为运行时执行层——observatory 验证你安装的内容；Seatbelt 控制它在执行时能做什么。 - Observatory Cloud：托管扫描、私有注册表、团队仪表板 - Seatbelt：具有策略执行、脱敏和实时监控的机器端代理 - 两者结合：静态扫描 + 运行时执行 = 完整的 MCP 安全生命周期 ## 路线图 - [x] 多客户端检测（8 个客户端） - [x] 具有请求拦截功能的运行时 JSON-RPC 2.0 代理 - [x] 支持正则表达式/精确/包含匹配、时间窗口、上下文条件的策略引擎 - [x] 风险评估引擎（13 项规则） - [x] 具有自动刷新功能的实时仪表板 Web UI - [x] SARIF 2.1.0 和 markdown 报告生成 - [x] mcp-observatory 集成桥接 - [x] CI/CD 检查命令 (`mcp-seatbelt check`) - [x] OWASP LLM Top 10 映射和合规框架标记 - [x] 多步骤攻击链检测（XState 状态机） - [x] Honeytoken 注入和检测 - [x] 取证会话捕获 (.mcpcap.json) - [x] Schema 感知的参数验证 - [x] 威胁情报集成（ThreatFox IOC 查询） - [x] 针对策略规则的输入模糊测试 - [x] 基于角色的访问控制（casbin RBAC） - [ ] 策略对比和迁移工具 ([#12](https://github.com/KryptosAI/mcp-seatbelt/issues/12)) - [ ] 用于可观测性技术栈的 Prometheus `/metrics` endpoint ([#15](https://github.com/KryptosAI/mcp-seatbelt/issues/15)) - [ ] OPA/Rego 策略集成 ([#18](https://github.com/KryptosAI/mcp-seatbelt/issues/18)) - [ ] 细粒度的工具控制权限——在同一服务器上允许工具 A 但拒绝工具 B ([#20](https://github.com/KryptosAI/mcp-seatbelt/issues/20)) - [ ] 使用 SQLite 的持久审计跟踪和请求日志记录 ([#22](https://github.com/KryptosAI/mcp-seatbelt/issues/22)) - [ ] 用于自定义风险规则的插件系统 ([#25](https://github.com/KryptosAI/mcp-seatbelt/issues/25)) ## 许可证 MIT — [mcp-seatbelt 贡献者](https://github.com/KryptosAI/mcp-seatbelt/graphs/contributors)

标签：AI代理, LNA, MCP协议, MITM代理, Streamlit, 人工智能, 代理网关, 暗色界面, 用户模式Hook绕过, 自动化攻击, 访问控制, 请求拦截