BashaarJavaid/MCP-Sentinel

# MCP Sentinel **面向 MCP 服务器的构建时安全扫描。** AI agent 会调用由 MCP server 暴露的工具，而仅一个不安全的工具就可能导致凭据泄露、运行任意命令，或劫持 agent。MCP Sentinel 能在您发布之前发现这些漏洞——它会扫描 MCP server 并报告安全发现，每一项都会映射到一个已知的威胁类别。 它分为三层工作：确定性的静态规则用于寻找候选问题，GPT-5.6 结合上下文对每个问题进行审查，以减少误报并对探测计划进行排序和参数化，最后由 Docker 隔离的沙箱运行四项探测，以确认是否存在可利用或不安全的运行时行为。每一项发现都映射到 OWASP Agentic Top 10（面向 AI agent 的行业威胁列表），并渲染为 console、JSON 或 SARIF —— 这是 GitHub 在其安全选项卡中读取的标准格式。 *想在运行任何东西之前先了解概述？请跳转至[它检查什么](#what-it-checks)以及[架构](#architecture)图。* ## 三分钟内试用 Sentinel 无需检出源代码或提供 OpenAI API key。安装预构建的 wheel，然后运行捆绑的 GPT replay 与真实的 Docker 探测。 ### 1. 下载 wheel 从 [`v0.1.0` GitHub Release](https://github.com/BashaarJavaid/MCP-Sentinel/releases/tag/v0.1.0) 下载 `mcp_sentinel-0.1.0-py3-none-any.whl`，或使用 [直接 wheel 下载](https://github.com/BashaarJavaid/MCP-Sentinel/releases/download/v0.1.0/mcp_sentinel-0.1.0-py3-none-any.whl)。 其 SHA-256 摘要为： ``` 4672e63413e87bf750113c06a21133162d00f1e71ca6259a8394028c22b677aa ``` ### 2. 检查 Docker 使用 Python 3.10、3.11 或 3.12，并在 Linux 上启动 Docker Engine，或在 macOS/Windows 上启动 Docker Desktop。Windows 上的 Docker Desktop 必须使用 Linux 容器。 ``` docker info docker buildx version ``` 首次运行可能会通过 Sentinel 受限的构建网络下载 Docker 镜像和 fixture 依赖项。被扫描的服务器没有运行时网络访问权限。 ### 3. 安装并运行 macOS 或 Linux： ``` cd /path/to/download-directory python3 -m venv sentinel-judge-env source sentinel-judge-env/bin/activate python -m pip install ./mcp_sentinel-0.1.0-py3-none-any.whl sentinel --version sentinel demo --replay-review --verbose ``` Windows PowerShell： ``` cd C:\path\to\download-directory py -3.12 -m venv sentinel-judge-env .\sentinel-judge-env\Scripts\python.exe -m pip install .\mcp_sentinel-0.1.0-py3-none-any.whl .\sentinel-judge-env\Scripts\sentinel.exe --version .\sentinel-judge-env\Scripts\sentinel.exe demo --replay-review --verbose ``` 演示应以退出代码 `0` 结束并显示 `Status: COMPLETE`，评估全部七条静态和四条动态规则，并报告从 `SENT-001` 到 `SENT-011` 的结果。它将经过验证的报告写入： ``` sentinel-demo-results/report.json sentinel-demo-results/report.sarif ``` 在 macOS 或 Linux 上独立验证 SARIF： ``` python -m sentinel.report.validate_sarif sentinel-demo-results/report.sarif ``` 在 Windows PowerShell 上： ``` .\sentinel-judge-env\Scripts\python.exe -m sentinel.report.validate_sarif sentinel-demo-results\report.sarif ``` 当报告有效时，验证器不会产生任何输出并以 `0` 退出。Replay 会被显著标明且不进行任何模型调用；从 GPT-5.6 捕获的已检查响应仍会流经生产解析器、证据和探测计划验证器、所有四个真实的 Docker 探测、合并逻辑以及报告验证。 查看已接受的实时 [`SENT-010` GitHub 代码扫描告警](https://github.com/BashaarJavaid/mcp-sentinel-action-demo/security/code-scanning/10) 以及完整的 [Action 证据](artifacts/phase4-action-evidence.md)。 ## 架构 ``` flowchart LR A[Untrusted MCP repository] --> B[AST + Semgrep rules] B --> C[Canonical candidates] C --> D[GPT-5.6 semantic review] D --> E[Constrained four-probe plan] E --> F[Docker sandbox] F --> G[Reviewed dynamic evidence] D --> H[Deduplication + provenance merge] G --> H H --> I[Console] H --> J[JSON 1.2.0] H --> K[SARIF 2.1.0] K --> L[GitHub code scanning] ``` 静态分析永远不会导入或执行目标代码。动态分析仅在全新的容器中运行本地 Python MCP 目标，且具有只读源代码、受限的构建出口网络、无运行时网络、资源限制以及强制清理。GPT 可以对四个永久的惰性模板进行排序和绑定；它无法发出可执行的探测代码或创建无规则的结果。 ## 它检查什么 每条规则都映射到 OWASP Agentic Top 10 中的一个类别；`ASI0x:2026` 代码是该列表的威胁标识符（例如 `ASI03` 代表 Identity & Privilege Abuse）。 | 规则 | 检测内容 | OWASP | 影响 | |---|---|---|---| | SENT-001 | 过于宽泛的工具权限范围 | ASI03:2026 | High | | SENT-002 | 工具输入触达不安全的执行环境 | ASI05:2026 | Critical | | SENT-003 | 缺少工具输入验证 | ASI02:2026 | Medium | | SENT-004 | 未经清理的工具内容进入 prompt | ASI01:2026 | High | | SENT-005 | 硬编码的凭据 | ASI03:2026 | Critical | | SENT-006 | 缺少或无效的路由身份验证 | ASI03:2026 | High | | SENT-007 | 未经核实的工具清单 | ASI04:2026 | Medium | | SENT-008 | 超出范围的工具执行 | ASI02:2026 | Critical | | SENT-009 | 接受过大的参数 | ASI05:2026 | Medium | | SENT-010 | 执行了注入的 payload | ASI05:2026 | Critical | | SENT-011 | 处理了格式错误的 schema 输入 | ASI02:2026 | Low | 请查阅[规则目录](docs/rules.md)以了解边界、误报风险、证据和修复方案。 ## 人类、Codex 和 GPT 的贡献 人类所有者定义了产品范围、架构、信任边界、威胁模型、阶段关卡和发布决策。 ### Codex 是如何被使用的 Codex 是整个构建过程的实现合作伙伴。其工作模式是设计优先：在任何实施之前，一场漫长的 Codex 会议讨论了范围和架构 —— MVP 与延期功能、发现结果如何映射到 OWASP 类别、发现结果的允许状态转换，以及语义审查是否应该是可选的（不应该；一个标志只会让它变成摆设）。该会议是构建项目其余部分的架构骨干。 此后，Codex 构建了静态规则引擎和 Semgrep 适配器、Docker 沙箱和 probe harness、报告管道、SARIF 验证器、跨平台测试矩阵、制品自动化以及文档。它还调试了较难的跨平台问题 —— Semgrep 输出解析和 Windows 上的运行时文件隔离，以及 GitHub 代码扫描正确渲染报告之前所需的两轮 SARIF 修复。 该仓库附带了一份 [`AGENTS.md`](AGENTS.md)，用于约束 Codex 在此代码库中的工作方式：宁可询问也不要假设、不进行投机性的复杂化、不进行无关的编辑、明确成功标准。设计决策仍由人类所有者掌握；Codex 加速了这些决策之后的所有流程。 ### GPT-5.6 是如何被使用的 GPT-5.6 位于发布的产品内部，而不仅仅是构建阶段。它在扫描时承担关键作用：它读取服务器代码，决定哪些静态候选对象是真正的发现结果，并对沙箱运行的四个 probe 进行排序和参数化 —— 关闭它你会得到不同的结果。它不会取代确定性检测器或 Docker 边界。 这些约束本身就是设计：针对带有版本的 schema 的严格 Structured Outputs，`store: false`，经过脱敏和限制的上下文，以及经过宿主机验证的源代码范围，因此模型无法引用不存在的代码行、发明规则集之外的发现结果，或发出可执行的 probe 代码。请参阅 [GPT-5.6 行为与披露](#gpt-56-behavior-and-disclosure) 了解完整的运行时契约，并查看 `artifacts/gpt-ablation.json` 获取针对仅使用规则、经 GPT 审查以及经动态确认的结果的量化比较。 ### Codex 会话记录 用于核心实现的主要 Codex `/feedback` 线程： `019f70e6-a5fb-7f13-8eae-bca041fc37ad`。 辅助实现线程： - `019f7469-e3ed-75a0-9906-7059299b1484` - `019f741f-cf91-7000-b12c-e9aa2a50ff03` - `019f77a1-f2f0-7ab2-9a5d-e72fa1ebc40e` 阶段 5 的 `/feedback` 记录是从上面的主线程提交的。 ## 要求与安装 支持的 CLI 环境是 Linux、macOS 和 Windows 上的 Python 3.10–3.12。完整的扫描和演示需要带 Buildx 的 Docker Engine 或 Docker Desktop。GitHub Action 运行在 Ubuntu 上。 检出开发版本： ``` uv sync --extra dev uv run sentinel --version ``` 兼容 pip 的开发路径是： ``` pip install -e ".[dev]" ``` [`v0.1.0` GitHub Release](https://github.com/BashaarJavaid/MCP-Sentinel/releases/tag/v0.1.0) 提供了由[成功的发布工作流](https://github.com/BashaarJavaid/MCP-Sentinel/actions/runs/29686427335)生成的预构建 wheel。 它通过了 Linux、macOS 和 Windows 测试矩阵、pip 和 pipx 安装冒烟测试，以及已安装 wheel 的 Docker replay。使用任一包前端直接安装该特定的 wheel： ``` python -m pip install mcp_sentinel-0.1.0-py3-none-any.whl # 或 pipx install mcp_sentinel-0.1.0-py3-none-any.whl ``` 该包尚未发布到 PyPI。 ## CLI ``` # 完整 static + GPT + Docker 分析 sentinel scan ./path/to/server # 已验证的 SARIF sentinel scan ./path/to/server --format sarif --output results.sarif # Static analysis 加上必需的 semantic review sentinel scan ./path/to/server --static-only # 当 GPT 不可用时明确允许未审查的候选项 sentinel scan ./path/to/server --static-only --allow-degraded # 默认使用紧凑输出；bounded evidence 为可选 sentinel scan ./path/to/server --verbose # 设置失败阈值；默认为 high sentinel scan ./path/to/server --fail-on critical ``` `--fail-on` 接受 `critical`、`high`、`medium`、`low` 或 `informational`，并决定哪些发现结果会产生退出代码 `1`。 `--color/--no-color` 覆盖显示检测。否则，`NO_COLOR` 会禁用样式，而交互式 TTY 会接收颜色。对于 JSON/SARIF，表示标志会被拒绝，而不是被静默忽略。 正常的扫描需要 `sentinel.target.yaml` 和 `sentinel.permissions.yaml`。`--static-only` 会省略 Docker 和启动配置，但仍需要语义审查。`OPENAI_API_KEY` 仅由 Sentinel 读取；它永远不会被打印、持久化、转发给目标，或被 Responses API 存储。 退出代码是稳定的： | 代码 | 含义 | |---:|---| | 0 | 完成扫描，未达到失败阈值的发现结果 | | 1 | 完成扫描，发现结果达到或超过阈值 | | 2 | 目标或配置错误 | | 3 | GPT、Docker、Semgrep、报告验证或内部失败 | 操作消息使用 `target error:`、`configuration error:` 和 `infrastructure error:` 前缀。`--debug` 添加内部 tracebacks。 ## 评判演示 该 wheel 包含易受攻击和干净的 fixture、schema 以及 GPT cassette。不需要检出源代码。 ``` # 离线 GPT replay 加上真实 Docker probes sentinel demo --replay-review --verbose # 实时 GPT review 加上真实 Docker probes export OPENAI_API_KEY=your-key sentinel demo --verbose ``` 这两个命令都会在 `./sentinel-demo-results/` 下自动刷新经过验证的报告；使用 `--output-dir` 更改位置。预期的漏洞使演示成功，因此完整的演示以 `0` 退出。 录制审查被显著标记，且永远不会被表示为实时调用。请参见[评判 runbook 与叙述](docs/demo.md)。 ## GPT-5.6 行为与披露 生产环境审查器使用 OpenAI Responses API 并具有以下特征： - 请求的模型为 `gpt-5.6-sol` 并记录返回的模型 ID； - `store: false`； - 默认为中等推理努力； - 使用带有版本的审查 schema 的严格 Structured Outputs； - 确定性的上下文选择、脱敏、批处理和候选上限； - 经过验证的源代码范围声明和受限的 probe 计划； - 当前/原始延迟、token、缓存、失败和微美元级的遥测。 Live 模式会调用模型。Replay 模式将已检查的实时响应馈送通过相同的解析器、验证器、合并逻辑、动态探测和报告。降级模式是显式的，将候选对象留在 `needs_review` 中，并且仍然符合 fail-on 条件。被抑制的候选对象连同其推理过程一起，在每份报告中保持可见。 ## GitHub Action ``` name: MCP Sentinel on: pull_request: push: branches: [main] permissions: contents: read security-events: write jobs: scan: runs-on: ubuntu-latest steps: - uses: actions/checkout@v4 - id: sentinel uses: BashaarJavaid/MCP-Sentinel@ee91e07d0fa78106dbb6d85b60bd8288173abd23 with: target-path: . fail-on: high openai-api-key: ${{ secrets.OPENAI_API_KEY }} ``` 该 Action 在上传前验证 SARIF，并暴露 `sarif-path`、`findings-count` 和 `highest-severity`。Fork 的 pull request 不会接收 secret；它们运行明显降级的分析并跳过代码扫描上传。非 Fork 运行保持 fail-closed。保留的实时证明记录在 [`artifacts/phase4-action-evidence.md`](artifacts/phase4-action-evidence.md) 中。 ## 报告与可重现性 ``` python -m sentinel.schema check python -m sentinel.report.validate_sarif results.sarif make artifacts-check make notices-check ``` `artifacts/example.sarif` 是经过检查的实时报告。 `artifacts/gpt-ablation.json` 在带版本的真理集上比较了仅使用规则、经 GPT 审查和动态确认的结果。日常生成使用 replay 和 Docker；最终的实时刷新有硬性上限： ``` make artifacts MAX_USD=0.50 make artifacts-live ``` ## 许可证 MCP Sentinel 基于 MIT 许可。依赖项许可证和打包的声明文件记录在 [`THIRD_PARTY_NOTICES.md`](THIRD_PARTY_NOTICES.md) 中。

标签：DevSecOps, DLL 劫持, Docker隔离, MCP服务器, SARIF, 上游代理, 图数据库, 大语言模型, 安全扫描, 插件系统, 时序注入, 请求拦截, 逆向工具