mcp-seatbelt

MCP Seatbelt — AI Agent 工具的运行时防护

在协议层拦截危险的 MCP 工具调用。扫描、代理、执行策略。

MCP 安全平台的一部分。 先使用 mcp-observatory（236★）扫描，再信任；然后使用 mcp-seatbelt 在运行时执行策略。📄 阅读技术白皮书。

🌐 网站： kryptosai.github.io/mcp-seatbelt — 演示、对比、定价

---

问题所在

AI 编码 Agent（Cursor、Claude、VS Code、ChatGPT、Windsurf 等）会连接到 MCP 服务，这些服务开放文件系统、Shell 解释器、网络访问和环境变量。静态扫描器会告诉你存在风险，但它们只能事后行动。等扫描器标记出有风险的服务时，Agent 可能已经运行了破坏性命令、窃取了凭据，或连接到了不可信的端点。

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 代理。每次工具调用、资源访问和提示词请求都会被拦截，根据策略进行评估，并被允许、拒绝、警告或脱敏。提供三种模式：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 集成和观测平台桥接 — 实时 HTML 仪表板显示请求统计、拦截率、已连接客户端和近期被拦截的调用。生成 SARIF 2.1.0 报告，用于 GitHub Code Scanning。从 mcp-observatory 导入安全发现，并自动将其转换为策略规则。在 CI 中运行 mcp-seatbelt check，检测到严重风险时会以非零状态码退出。

• 单次调用超时 — 挂起的工具调用会被终止，并返回简洁的 JSON-RPC 错误，而不是原始 503。可按规则配置超时时间（Shell 命令为 10s，安全工具为 60s）。

高级安全

• 映射至 OWASP LLM Top 10 — 每次被拦截的调用都会标注 OWASP 类别（LLM01 提示词注入、LLM06 权限过大等）
• 合规框架映射 — 策略规则带有 SOC2、HIPAA、GDPR、ISO 27001 和 PCI-DSS 控制标签
• 多步骤攻击链检测 — 基于 XState 的状态机跟踪调用序列：侦察 → 执行 → 持久化 → 数据外传
• 蜜罐令牌注入与检测 — 在工具响应中植入诱饵凭据（AWS 密钥、GitHub 令牌、数据库 URL），并在其被访问时发出警报
• 取证会话捕获 — 将完整的请求/响应对记录为 .mcpcap.json，用于事件分析
• 感知架构的参数校验 — 根据声明的 JSON 架构验证工具参数，并检测路径遍历和注入
• 威胁情报集成 — 查询 ThreatFox IOC 数据库，检查 IP/域名信誉
• 输入模糊测试 — 针对策略规则生成边界情况负载，以查找绕过方式
• 基于角色的访问控制 — 使用 casbin 为每个 Agent 设置权限。管理员可以执行所有工具，Agent 则只能访问指定范围内的工具
• 响应 DLP — 扫描上游响应中的机密模式（API 密钥、令牌、私钥），并将其脱敏

---

快速开始

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/[email protected]
  with:
    mode: enforce
    fail-on-critical: true

请参阅 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 → 架构验证 → 路径安全 → 策略引擎 → 威胁情报 → 蜜罐令牌 → 攻击链 → 代理 → 响应 DLP → 取证 → 审计日志。

---

对比

| 特性 | mcp-seatbelt | mcp-firewall | mcp-guardian | Prismor | mcp-proxy | |---|---|---|---|---|---|---| | 运行时阻止 | ✓ | ✓ | ✓ | ✓ | ✗ | | 安装前扫描 | ✓ | ✗ | ✗ | ✗ | ✗ | | 检测 8 种以上客户端 | ✓ | ✗ | ✗ | ✗ | ✗ | | 参数脱敏 | ✓ | ✗ | ✗ | ✗ | ✗ | | 学习模式 | ✓ | ✗ | ✗ | ✗ | ✗ | | 实时仪表板 | ✓ | ✗ | ✓ | ✗ | ✗ | | SARIF / GitHub Code Scanning | ✓ | ✗ | ✗ | ✗ | ✗ | | mcp-observatory 集成 | ✓ | ✗ | ✗ | ✗ | ✗ | | 单次调用超时 | ✓ | ✗ | ✗ | ✗ | ✗ | | OWASP LLM Top 10 映射 | ✓ | ✗ | ✗ | ✗ | ✗ | | 合规性标记（SOC2/HIPAA） | ✓ | ✗ | ✗ | ✗ | ✗ | | 攻击链检测 | ✓ | ✗ | ✗ | ✗ | ✗ | | 蜜罐令牌/注入检测 | ✓ | ✗ | ✗ | ✗ | ✗ | | 感知架构的验证 | ✓ | ✗ | ✗ | ✗ | ✗ | | 威胁情报（IOC 查询） | ✓ | ✗ | ✗ | ✗ | ✗ | | RBAC（按 Agent 控制访问） | ✓ | ✗ | ✗ | ✗ | ✗ |

Seatbelt 是唯一一款集成安装前扫描与运行时强制执行、覆盖所有主流 AI Agent 客户端、内联脱敏凭据参数，并将 mcp-observatory 的静态分析结果转化为实时策略规则的工具。

---

高级安全功能

mcp-seatbelt 包含一套纵深防御安全流水线，通过多个层级评估每次工具调用：

层级	功能	描述
1	RBAC	基于 Casbin 的 Agent 和工具角色访问控制。mcp-seatbelt rbac-init 可生成模型和策略文件。
2	架构验证	基于 AJV 的 JSON Schema 验证，根据已编译的架构检查工具参数。
3	路径安全	检测参数中的路径遍历、空字节注入和敏感路径访问。
4	策略引擎	基于规则的评估，支持正则／精确／包含匹配、时间窗口、上下文条件和参数约束。
5	威胁情报	异步查询 ThreatFox，检查工具参数中的 IP 地址和域名。
6	蜜罐令牌	在响应中植入诱饵凭据；当蜜罐令牌出现在后续调用中时检测数据外泄。
7	攻击链跟踪	基于 XState 的状态机，用于跟踪多步攻击模式（侦察→执行→持久化→外泄）。
8	取证捕获	启用后，将所有请求和响应记录到签名的 .mcpcap.json 会话文件中。
9	响应 DLP	扫描上游响应中的秘密内容模式（API 密钥、令牌、私钥）并将其编辑隐藏。
10	输入模糊测试	根据 JSON 架构生成边界情况载荷，并测试策略抵御绕过的能力。mcp-seatbelt fuzz --policy policy.yml

输入模糊测试

mcp-seatbelt fuzz 使用 json-schema-faker 生成随机工具调用参数，注入边界情况载荷（路径遍历、命令注入、SQL 注入、Log4Shell），并根据你的策略评估每个载荷。它会报告绕过情况，并提供具体载荷及本应拦截该载荷的规则。

mcp-seatbelt fuzz --policy .mcp-seatbelt/policy.yml --iterations 200 --json

---

策略参考

命令行

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	根据工具架构对策略进行模糊测试，以查找绕过情况
mcp-seatbelt record	以取证记录模式启动代理
mcp-seatbelt rbac-init	初始化 RBAC 模型和策略文件
mcp-seatbelt simulate	根据策略模拟工具调用并显示评估跟踪信息
mcp-seatbelt benchmark	对代理运行性能基准测试
mcp-seatbelt test-policy	根据测试 YAML 文件运行策略测试
mcp-seatbelt baseline	根据审计日志生成行为基线
mcp-seatbelt verify-audit	验证签名审计日志的完整性

内置规则（默认策略）

规则	目标	描述
block-shell-execution	命令	阻止直接调用 Shell 解释器（bash、sh、zsh、cmd、powershell）
block-sensitive-paths	文件	阻止向 /etc、/root、~/.ssh、~/.aws、C:\Windows 写入文件
block-credential-access	命令	阻止描述中提及密码、秘密、令牌、密钥的工具
redact-credentials	命令	编辑隐藏键名符合凭据模式的参数值
block-private-network	网络	阻止向私有／环回地址范围发送 HTTP 请求
block-process-execution	进程	阻止会启动子进程或执行代码的工具
allow-filesystem-writes-business-hours	文件	仅允许在周一至周五 09:00-17:00 写入文件

策略模板

模板	默认操作	使用场景
minimal-workstation	允许	仅阻止 Shell 执行和凭据访问；允许其他所有操作
pci-compliance	拒绝	阻止 Shell、凭据、PAN／持卡人数据路径以及审计日志篡改
strict-production	拒绝	默认阻止所有工具调用、网络请求和文件系统操作

可通过策略文件中的 extends 字段扩展模板：

version: '1'
mode: enforce
extends:
  - pci-compliance
rules:
  - id: custom-rule
    target: network
    match: pattern
    values: ['.*']
    action: deny

规则架构

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 表格 — 复制并粘贴这些 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/<server-name>"。

---

与 mcp-observatory 结合使用

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 次运行的中位数，失败请求为 0）：

指标	数值
吞吐量	~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
模式验证开销	每次调用 < 1 µs
内存（空闲）	~74 MB
内存（负载下）	~74 MB（10,000 个请求后保持稳定）

策略大小（1 → 20 条规则）对端到端性能没有可测量的影响；每条规则的开销约为 0.25 µs，远低于传输 I/O。完整方法和各场景数据表请参阅：docs/benchmarks.md。在自己的硬件上运行 mcp-seatbelt benchmark。

---

企业版

mcp-observatory Cloud 为团队和组织提供托管仪表板、私有 CI 扫描、认证徽章和供应链合规报告。Seatbelt 可集成为运行时强制执行层 — observatory 验证你安装的内容；seatbelt 控制这些内容在执行时可以做什么。

• Observatory Cloud：托管扫描、私有注册表、团队仪表板
• Seatbelt：在本机运行的代理，提供策略强制执行、脱敏和实时监控
• 两者结合：静态扫描 + 运行时强制执行 = 完整的 MCP 安全生命周期

---

路线图

• 多客户端检测（8 个客户端）
• 支持请求拦截的运行时 JSON-RPC 2.0 代理
• 策略引擎，支持正则表达式／精确／包含匹配、时间窗口和上下文条件
• 风险评估引擎（13 条规则）
• 支持自动刷新的实时仪表板 Web UI
• 生成 SARIF 2.1.0 和 Markdown 报告
• mcp-observatory 集成桥接
• CI/CD 检查命令（mcp-seatbelt check）
• OWASP LLM Top 10 映射和合规框架标记
• 多步骤攻击链检测（XState 状态机）
• 蜜罐令牌注入和检测
• 取证会话捕获（.mcpcap.json）
• 感知架构的参数验证
• 威胁情报集成（ThreatFox IOC 查询）
• 针对策略规则进行输入模糊测试
• 基于角色的访问控制（casbin RBAC）
• 策略差异对比和迁移工具（#12）
• 面向可观测性技术栈的 Prometheus /metrics 端点（#15）
• OPA/Rego 策略集成（#18）
• 按工具粒度控制——允许同一服务上的工具 A，同时拒绝工具 B（#20）
• 使用 SQLite 持久化审计跟踪和请求日志（#22）
• 用于自定义风险规则的插件系统（#25）

---

贡献

开发环境设置、测试说明和拉取请求指南，请参阅 CONTRIBUTING.md。安全问题应按照 SECURITY.md 中的流程处理。

• 485 项测试，分布于 18 个测试套件中（CLI、检测器、策略引擎、代理服务器、代理拦截、报告、安全模块、RBAC、威胁情报、大模型评审、取证、蜜罐令牌、攻击链、架构验证器、审计、通知、基线、集成）
• npm test 运行完整的 Vitest 测试套件；npm run typecheck 验证 TypeScript
• 新增规则、检测器或策略功能的 PR 应包含相应测试

---

许可证

MIT — mcp-seatbelt 贡献者