groundforgeai/groundforge-mcp-inspector

# GroundForge MCP Inspector GroundForge MCP Inspector 是一个本地 CLI 工具，用于在 MCP 服务器连接到 AI agent 之前审查其暴露的内容。 它会发现 MCP 工具、提示、资源、描述、输入 schema 和注解，然后生成一份包含规范化清单和发现时间点调查结果的 JSON 报告。 它回答的问题很简单： 该检查器不声称可利用性，也不批准生产环境的使用。它仅从 MCP 元数据中展示有证据支持审查点。 ## 为什么这很重要 MCP 服务器可以暴露读取数据、发送消息、修改系统、执行代码或向 agent 返回不受信任上下文的工具。在将 MCP 服务器连接到 agent 之前，团队应了解该操作面。 典型的审查问题： - 暴露了哪些工具、提示和资源？ - 哪些工具有输入 schema？ - 哪些工具看起来具有副作用、破坏性、特权、外部连接或执行能力？ - 描述、提示或资源中是否包含工具投毒或上下文注入模式？ - 调查结果是否足以支持审查，或者它们仅仅是微弱的元数据提示？ ## MCP Top 10 重点关注 本项目使用 **OWASP MCP Top 10** 作为主要的控制分类标准。 当前的开源检查器专注于从 MCP 元数据中可以合理检测到的发现期信号： - [MCP01:2025 - Token 管理不当与机密暴露](https://owasp.org/www-project-mcp-top-10/2025/MCP01-2025-Token-Mismanagement-and-Secret-Exposure) - [MCP03:2025 - 工具投毒](https://owasp.org/www-project-mcp-top-10/2025/MCP03-2025%E2%80%93Tool-Poisoning) - [MCP05:2025 - 命令注入与执行](https://owasp.org/www-project-mcp-top-10/2025/MCP05-2025%E2%80%93Command-Injection%26Execution) - [MCP08:2025 - 缺乏审计与遥测](https://owasp.org/www-project-mcp-top-10/2025/MCP08-2025%E2%80%93Lack-of-Audit-and-Telemetry) - [MCP10:2025 - 上下文注入与过度共享](https://owasp.org/www-project-mcp-top-10/2025/MCP10-2025%E2%80%93ContextInjection%26OverSharing) 当元数据提供合理的信号时，一些调查结果也会映射到这些 MCP 领域： - [MCP02:2025 - 通过范围蔓延实现权限提升](https://owasp.org/www-project-mcp-top-10/2025/MCP02-2025%E2%80%93Privilege-Escalation-via-Scope-Creep) - [MCP06:2025 - 意图流颠覆](https://owasp.org/www-project-mcp-top-10/2025/MCP06-2025%E2%80%93Intent-Flow-Subversion) - [MCP07:2025 - 认证与授权不足](https://owasp.org/www-project-mcp-top-10/2025/MCP07-2025%E2%80%93Insufficient-Authentication%26Authorization) MCP04 和 MCP09 很重要，但它们暂非此本地元数据检查器的主要关注点： - [MCP04:2025 - 软件供应链攻击与依赖篡改](https://owasp.org/www-project-mcp-top-10/2025/MCP04-2025%E2%80%93Software-Supply-Chain-Attacks-and-Dependency-Tampering) - [MCP09:2025 - 影子 MCP 服务器](https://owasp.org/www-project-mcp-top-10/2025/MCP09-2025%E2%80%93Shadow-MCP-Servers) ## 高层架构 ``` flowchart TD A["MCP server command / mcp.json config / inventory JSON"] --> B["Discovery"] B --> C["Normalized MCP inventory"] C --> D["Risk hints"] C --> E["MCP metadata checks"] C --> F["YARA metadata scan"] E --> G["Findings mapped to MCP Top 10"] F --> G C --> H["JSON scan report"] G --> H H --> I["Terminal summary"] H -. "optional import" .-> J["GroundForge platform"] subgraph CLI["Local CLI"] B C D E F G H I end ``` ## 安装 ``` python -m venv .venv source .venv/bin/activate pip install -e .[dev] ``` ## 使用方法 扫描本地 stdio MCP 服务器： ``` gf-mcp-inspector scan \ --command "python examples/mcp_servers/vulnerable_support/server.py" \ --output reports/vulnerable-support-report.json ``` 服务器名称通过命令推断得出。仅在需要覆盖报告标签时使用 `--name`。 从 `mcp.json` 扫描服务器： ``` gf-mcp-inspector scan \ --config examples/mcp.json \ --server vulnerable-support \ --output reports/vulnerable-support-report.json ``` 这避免了 shell 引号和 Docker 参数问题。检查器支持 MCP 客户端使用的常见 `mcpServers` 结构： ``` { "mcpServers": { "redis": { "command": "docker", "args": ["run", "-i", "--rm", "mcp/redis"], "env": { "REDIS_HOST": "host.docker.internal", "REDIS_PORT": "6379" } } } } ``` 从示例配置中扫描 Redis： ``` gf-mcp-inspector scan \ --config examples/mcp.json \ --server redis \ --output reports/redis-report.json ``` 扫描现有的清单 JSON： ``` gf-mcp-inspector scan \ examples/inventories/vulnerable_support_inventory.json \ --output reports/vulnerable-support-report.json ``` 使用自定义 YARA 规则目录： ``` gf-mcp-inspector scan \ examples/inventories/tool_poisoned_inventory.json \ --rules ./rules/yara/mcp-baseline \ --output reports/tool-poisoned-report.json ``` ## 运行示例 ``` $ gf-mcp-inspector scan \ > examples/inventories/tool_poisoned_inventory.json \ > --rules ./rules/yara/mcp-baseline \ > --output reports/tool-poisoned-report.json GroundForge MCP Inspector Target: Tool Poisoned MCP (stdio) Tools: 3 | Prompts: 0 | Resources: 0 Findings: critical=0 high=1 medium=1 low=0 info=0 (3 evidence items in JSON) Discovered tools ┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Tool ┃ Fields ┃ Risk hints ┃ ┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ summarize_ticket │ ticket_id │ sensitive_data │ │ update_ticket │ body, ticket_id │ write_action │ │ post_to_webhook │ payload, url │ external_communication, network_access │ └──────────────────┴─────────────────┴────────────────────────────────────────┘ Findings ┏━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓ ┃ Severity ┃ Finding ┃ Controls ┃ Target ┃ ┡━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩ │ high │ Instruction override language in MCP │ • MCP03:2025 │ tool:summarize_ticket │ │ medium confidence │ metadata │ • MCP10:2025 │ tool:update_ticket │ │ │ GF-MCP03-TOOL-POISONING-INSTRUCTION-OVERRI… │ │ │ │ │ evidence: content_pattern │ │ │ │ medium │ Hidden instruction language in MCP metadata │ • MCP03:2025 │ tool:summarize_ticket │ │ medium confidence │ GF-MCP03-TOOL-POISONING-HIDDEN-INSTRUCTION │ │ │ │ │ evidence: content_pattern │ │ │ └───────────────────┴─────────────────────────────────────────────┴──────────────────────────────┴─────────────────────────────┘ Wrote reports/tool-poisoned-report.json ``` 终端输出的是摘要。对于工具繁多的 MCP 服务器，具有相同规则的重复调查结果会在终端中分组显示，以保持审查的可读性。分组后的调查结果会列出所有受影响的工具。JSON 报告仍然包含完整的清单、每个工具的每项调查结果、控制措施、证据、置信度和建议。调查结果是发现阶段的审查项，而非已确认的漏洞。 ## 发现过程中的 MCP 服务器日志 默认情况下，检查器会抑制子 MCP 服务器发出的 stderr 日志，以便扫描输出专注于清单和调查结果。如果发现失败，捕获的服务器日志将包含在错误消息中。 当需要查看 MCP 服务器启动日志时，请使用 `--verbose`： ``` gf-mcp-inspector scan \ --command "uvx blender-mcp" \ --output reports/blender-report.json \ --verbose ``` 部分 MCP 服务器在成功返回元数据的同时，可能仍会报告依赖项问题。例如，桌面应用 MCP 服务器可能提示桌面应用程序未连接，但 `list_tools` 仍然有效。请将这些消息视为 MCP 服务器依赖日志，而非检查器的调查结果。 ## 如何解读调查结果 检查器将微弱的元数据信号与值得审查的调查结果区分开来。 | 术语 | 含义 | |---|---| | 风险提示 | 从名称、描述、schema、字段或注解中推断出的标签。风险提示会出现在工具表中。它们本身不是调查结果。 | | 调查结果 | 具有足够证据出现在调查结果表中的审查项。示例：通过自由格式输入实现的执行能力、工具投毒元数据、机密暴露语言、审计抑制语言或类似凭据的输入字段。调查结果并非已确认的漏洞利用。 | | 置信度 | 发现阶段的证据强度。大多数仅基于元数据的调查结果置信度为 `medium`。类似凭据的字段名通常置信度为 `low`。 | | 证据类型 | 调查结果是来自元数据、schema 字段、声明的描述、内容模式还是值模式。 | ## 内置 MCP 元数据检查 这些检查在规范化清单上运行。它们是通用的，不包含特定于服务器的例外情况。 | 检查组 | MCP 映射 | 捕获内容 | |---|---|---| | 清单规范性 | MCP03 | 缺失的输入 schema 和空的工具描述。 | | 命令/代码执行 | MCP05 | 暴露 shell、命令、脚本或代码执行的工具名称、描述或字段。 | | 宽泛输入的执行 | MCP05 | 具有宽泛字段（如 `command`、`code`、`script` 或 `payload`）且具备执行能力的工具。 | | 类似凭据的输入 | MCP01 | 诸如 `token`、`api_key`、`subscription_key`、`secret` 或 `password` 的字段名称。这并非泄露机密的证据。 | | 破坏性、财务和特权操作 | MCP02、MCP07 | 暗示删除、付款、退款或特权操作的工具元数据。诸如 `get`、`range`、`members`、`info` 和 `scan` 等类读取操作被视为清单上下文，而非写入调查结果。 | | 携带敏感数据的外部传输 | MCP10 | 将外部通信指示器与敏感数据指示器结合的工具元数据。 | ## 基础 YARA 规则 基础规则包是通用的。它由 MCP 元数据模式构建，应在不相关的 MCP 服务器中均具有意义。 | 规则 | 主要 MCP 映射 | 目的 | |---|---|---| | `GF-MCP01-SECRET-EXPOSURE-METADATA` | MCP01 | 检测机密暴露语言以及少部分具体的机密值模式。 | | `GF-MCP03-TOOL-POISONING-INSTRUCTION-OVERRIDE` | MCP03 | 检测指令覆盖语言，如“忽略之前的指令”或“系统覆盖”。 | | `GF-MCP03-TOOL-POISONING-HIDDEN-INSTRUCTION` | MCP03 | 检测隐藏或隐秘的指令语言。 | | `GF-MCP03-TOOL-POISONING-COVERT-CHAINING` | MCP03 | 检测指示 agent 静默调用另一个工具或将结果发送到别处的元数据。 | | `GF-MCP05-COMMAND-OR-CODE-EXECUTION-METADATA` | MCP05 | 检测声明的 shell、命令、脚本或代码执行语言。 | | `GF-MCP06-POLICY-BYPASS-METADATA` | MCP06 | 检测批准、审查、确认或绕过策略的语言。 | | `GF-MCP06-DESTRUCTIVE-ACTION-PRESSURE-METADATA` | MCP06 | 检测在未经批准的情况下施压进行破坏性或变更性操作的元数据。 | | `GF-MCP08-AUDIT-SUPPRESSION-METADATA` | MCP08 | 检测要求抑制日志、追踪或审计记录的元数据。 | | `GF-MCP10-CONTEXT-INJECTION-METADATA` | MCP10 | 检测试图将自身注入 system/developer 上下文的资源或提示元数据。 | | `GF-MCP10-DATA-EXFILTRATION-METADATA` | MCP10 | 检测批量导出、数据库转储、任意文件读取或外部数据传输语言。 | ## 规范规则组与控制映射 映射意味着“审查此领域”。这并不意味着 MCP 服务器是可利用的或不合规的。 | 规则组 | 示例 | 主要控制/风险映射 | |---|---|---| | Token 和机密暴露 | `GF-MCP01-SECRET-EXPOSURE-METADATA`、`GF-MCP01-CREDENTIAL-LIKE-INPUT` | - [MCP01:2025 - Token 管理不当与机密暴露](https://owasp.org/www-project-mcp-top-10/2025/MCP01-2025-Token-Mismanagement-and-Secret-Exposure) | | 范围蔓延与高影响能力 | `GF-MCP02-FINANCIAL-ACTION-CAPABILITY`、`GF-MCP02-DESTRUCTIVE-ACTION-CAPABILITY`、`GF-MCP02-PRIVILEGED-ACTION-CAPABILITY` | - [MCP02:2025 - 通过范围蔓延实现权限提升](https://owasp.org/www-project-mcp-top-10/2025/MCP02-2025%E2%80%93Privilege-Escalation-via-Scope-Creep) | | 工具投毒元数据 | `GF-MCP03-TOOL-POISONING-INSTRUCTION-OVERRIDE`、`GF-MCP03-TOOL-POISONING-HIDDEN-INSTRUCTION`、`GF-MCP03-TOOL-POISONING-COVERT-CHAINING`、`GF-MCP03-TOOL-MISSING-INPUT-SCHEMA` | - [MCP03:2025 - 工具投毒](https://owasp.org/www-project-mcp-top-10/2025/MCP03-2025%E2%80%93Tool-Poisoning) | | 软件供应链 | 在 v0.1 中默认未覆盖 | - [MCP04:2025 - 软件供应链攻击与依赖篡改](https://owasp.org/www-project-mcp-top-10/2025/MCP04-2025%E2%80%93Software-Supply-Chain-Attacks-and-Dependency-Tampering) | | 命令与代码执行 | `GF-MCP05-SHELL-EXECUTION-CAPABILITY`、`GF-MCP05-CODE-EXECUTION-CAPABILITY`、`GF-MCP05-FREEFORM-EXECUTION-INPUT`、`GF-MCP05-COMMAND-OR-CODE-EXECUTION-METADATA` | - [MCP05:2025 - 命令注入与执行](https://owasp.org/www-project-mcp-top-10/2025/MCP05-2025%E2%80%93Command-Injection%26Execution) | | 意图流颠覆 | `GF-MCP06-POLICY-BYPASS-METADATA`、`GF-MCP06-DESTRUCTIVE-ACTION-PRESSURE-METADATA` | - [MCP06:2025 - 意图流颠覆](https://owasp.org/www-project-mcp-top-10/2025/MCP06-2025%E2%80%93Intent-Flow-Subversion) | | 认证与授权审查 | 当元数据暗示存在破坏性、财务或特权操作时，高影响能力调查结果也可能映射到此处。 | - [MCP07:2025 - 认证与授权不足](https://owasp.org/www-project-mcp-top-10/2025/MCP07-2025%E2%80%93Insufficient-Authentication%26Authorization) | | 审计与遥测抑制 | `GF-MCP08-AUDIT-SUPPRESSION-METADATA` | - [MCP08:2025 - 缺乏审计与遥测](https://owasp.org/www-project-mcp-top-10/2025/MCP08-2025%E2%80%93Lack-of-Audit-and-Telemetry) | | 影子 MCP 服务器 | 在 v0.1 中默认未覆盖 | - [MCP09:2025 - 影子 MCP 服务器](https://owasp.org/www-project-mcp-top-10/2025/MCP09-2025%E2%80%93Shadow-MCP-Servers) | | 上下文注入与过度共享 | `GF-MCP10-CONTEXT-INJECTION-METADATA`、`GF-MCP10-DATA-EXFILTRATION-METADATA`、`GF-MCP10-EXTERNAL-DELIVERY-WITH-SENSITIVE-DATA` | - [MCP10:2025 - 上下文注入与过度共享](https://owasp.org/www-project-mcp-top-10/2025/MCP10-2025%E2%80%93ContextInjection%26OverSharing) | ## MCP 服务器示例 该代码库包含了具有故意设计的风险元数据的本地 MCP 服务器。 | 示例 | 演示内容 | |---|---| | `examples/mcp_servers/vulnerable_support` | 客户查询、退款、外部电子邮件、shell 执行、破坏性操作元数据以及退款运行手册资源。 | | `examples/mcp_servers/tool_poisoned` | 隐藏指令、指令覆盖、绕过审批以及外部 webhook 行为。 | | `examples/mcp_servers/oversharing_resources` | 敏感资源名称、类机密资源 URI、客户导出元数据以及宽泛搜索行为。 | 请勿部署这些示例服务器或将其连接到真实系统。 ## 项目结构 ``` groundforge-mcp-inspector/ groundforge_mcp_inspector/ cli.py models.py mcp_config.py risk_hints.py metadata_checks.py yara_scan.py discovery/stdio.py rules/yara/mcp-baseline/ mcp_metadata_baseline.yar examples/ mcp.json mcp_servers/ inventories/ docs/ schema.md roadmap.md ``` ## 高级风险扫描与策略控制 开源 CLI 用于本地 MCP 发现和初步检查。 GroundForge 平台增加了更深层次的风险扫描和策略控制： - 针对 MCP 工具和 agent 工作流的策略建议 - 受管制的应用/runtime 配置文件 - 对工具调用和追踪的 runtime 监控 - 可疑运行检测 - 追踪证据与追踪到测试的转换 - 审批工作流和审计证据 - 对允许、审查、拒绝和观察决策的 runtime 执行 有关更多信息，请参阅 [groundforge.ai](https://groundforge.ai)。 ## 许可证 基于 [Apache License 2.0]() 获得许可。

标签：MCP, 人工智能, 元数据分析, 安全审查, 文档结构分析, 用户模式Hook绕过, 逆向工具