yyyutakaaa/mcpscan

# mcpscan **在恶意 MCP 服务器和中毒技能触及你的模型之前拦截它们。** [](https://github.com/yyyutakaaa/mcpscan/releases) [](https://github.com/yyyutakaaa/mcpscan/actions/workflows/ci.yml) [](LICENSE) mcpscan 会扫描你的配置、Python 代码和技能，排查真正关键的安全问题：注入攻击、权限过大的工具、泄露的机密以及 数据外传 endpoint。 ## 30 秒完成你的首次扫描 ``` pip install git+https://github.com/yyyutakaaa/mcpscan.git@v0.1.0 mcpscan . ``` 它会查找 MCP 配置、Python 服务器和技能文件夹，然后打印报告。如果发现任何 达到或超过阈值（默认：`high`）的问题，将以退出码 1 结束。可以直接在 CI 中运行——无需额外配置。该包直接从带有标签的 GitHub release 中安装。 ## 规则 **Prompt injection (MCP101–105)**：隐藏的 unicode 技巧、“忽略之前的 指令”类短语、可疑的超长工具描述，以及试图引导你避开其他工具的指令。 **危险代码 (MCP201–204)**：eval/exec、由用户输入驱动的 subprocess 调用、shell 执行，以及未检查路径是否保持在边界内的文件访问。 **配置不当的服务器 (MCP210–211)**：`--allow-all` 标志、根目录位于 `/` 或你的主目录的文件系统。 **数据外传 (MCP301–302)**：向硬编码的外部 URL 发送 POST/PUT 请求，URL 中 包含凭证。 **供应链 (MCP401–402)**：`curl | sh` 模式、没有版本锁定的 pip install。 **机密 (MCP501–502)**：AWS 密钥、GitHub token、API 凭证、高熵 环境变量。 完整规则表： | ID | Severity | Category | Detects | |---|---|---|---| | MCP000 | info | supply-chain | 无法解析的文件（格式错误的 JSON / Python） | | MCP101 | high | prompt-injection | 工具描述或技能文本中的指令覆盖短语 | | MCP102 | critical | prompt-injection | 隐藏在面向 agent 文本中的零宽 / bidi 控制字符 | | MCP103 | high | prompt-injection | "Always include/append/attach" + 数据名词（文件、密钥、token、对话） | | MCP104 | medium | prompt-injection | 长度超过 1500 个字符的工具描述 | | MCP105 | high | prompt-injection | 引用其他工具行为的工具描述 | | MCP201 | critical | permissions | `eval` / `exec` 调用 | | MCP202 | critical | permissions | 由工具参数驱动的 `subprocess` / `os.system`（命令注入） | | MCP203 | low | permissions | 使用常量或非工具派生参数的 Shell 命令执行 | | MCP204 | medium | permissions | 来自工具输入且未进行包含检查（路径遍历）的文件访问 | | MCP210 | medium | permissions | 使用 `--allow-all` / `--dangerously-skip-permissions` / `--no-sandbox` 风格标志启动的服务器 | | MCP211 | medium | permissions | 根目录位于 `/`、`~` 或整个驱动器的文件系统服务器 | | MCP301 | high | exfiltration | 工具函数内部向硬编码的非 localhost URL 发送的 HTTP POST/PUT 请求 | | MCP302 | medium | exfiltration | 包含嵌入凭证的 URL（`https://user:pass@…`） | | MCP401 | low | supply-chain | 技能文本中通过原始 URL 进行的 `curl … \| sh`、`wget … \| bash` 或 `pip install` | | MCP402 | low | supply-chain | 技能文本中未锁定版本的 `pip install` 命令（没有 `==`） | | MCP501 | critical | secrets | 已知格式的机密（AWS、GitHub、OpenAI、Anthropic、Slack、通用 API 密钥） | | MCP502 | medium | secrets | 服务器 `env` 块中的高熵值 | 规则 ID 是稳定的。机密信息始终会被掩码处理（前 4 个字符 + `****`）。 ## 运行 ``` mcpscan PATH [OPTIONS] Options: --format [terminal|json|sarif] (default: terminal) --output FILE write report to a file --fail-on [critical|high|...] (default: high) --rules DIR your own rules directory --exclude GLOB skip these files (repeatable) --version Commands: rules list all loaded rules ``` 退出码：`0` = 无发现，`1` = 发现达到/超过阈值，`2` = 错误。 ## 检测模型与局限性 mcpscan 是一款基于静态和启发式的扫描器。检测结果标记的是值得审查的 风险代码或文本；它并不能证明服务器是恶意的。反之，一次 干净的扫描也不能证明服务器是绝对安全的。 Python 检查会在 MCP 工具函数内部进行本地分析，包括直接参数 使用和通过本地赋值的传播。目前它们不会追踪经过 辅助函数、导入、容器或运行时生成的代码的数据。路径 包含检查在语法上被识别，因此审查者仍需验证该检查是否保护了文件操作所使用的相同路径和基础目录。 ## GitHub 集成 ``` name: mcpscan on: [push, pull_request] jobs: scan: runs-on: ubuntu-latest permissions: security-events: write steps: - uses: actions/checkout@v4 - uses: yyyutakaaa/mcpscan@v0.1.0 with: path: . fail-on: high ``` 结果会显示在 Security → Code scanning 中。 ## 添加自定义规则 将 YAML 文件放入某个目录中，并传入 `--rules ./my-rules`： ``` id: ORG001 title: Internal hostname in skill text severity: high category: exfiltration applies_to: [skill_text] # tool_description | skill_text | server_args | string_constant | any_text matchers: # rule fires if ANY matcher matches - type: regex pattern: "(?i)corp\\.internal\\.example" - type: substring # substring matchers are case-insensitive pattern: staging-db description: Leaks infrastructure details. remediation: Use environment variables instead. ``` 对于需要进行 AST 分析或熵检查的内容，请在 `src/mcpscan/rules/checks/` 中编写一个 Python 模块。实现 `run(parsed: ParsedTarget) -> list[Finding]`。 ## 未来 - 直接扫描 git URL - 支持 Node.js / TypeScript - 运行时代理以监控实时的 MCP 流量 - LLM 辅助的语义检查 ## 许可证 Apache-2.0 — 请参阅 [LICENSE](LICENSE)。

标签：AI代理, GraphQL安全矩阵, LNA, MCP服务器, Redis利用, StruQ, 安全扫描器, 逆向工具, 错误基检测, 零日漏洞检测, 静态代码分析