alexh-scrt/mcp-scanner

# MCP Scanner 🔍 [](https://www.python.org/) [](LICENSE) MCP Scanner 是一个专注于 CLI 安全的工具，用于发现和审计 **Model Context Protocol (MCP)** 在 Web 服务器和 API 上的端点。受到关键 **MCPwn** nginx UI 漏洞的启发，它会探测常见的 MCP URL 模式，测试认证要求，并检查未认证的工具和资源暴露情况。它生成结构化的安全报告（JSON、HTML 或彩色终端格式），适用于交互使用和 CI/CD 流水线。 ## 快速开始 ``` # 从 PyPI 安装 pip install mcp-scanner # 扫描单个目标 mcp-scanner scan https://your-api.example.com # 扫描多个目标并保存 JSON 报告 mcp-scanner scan https://api1.example.com https://api2.example.com --output report.json # 以更高并发度和详细输出进行扫描 mcp-scanner scan https://your-api.example.com --concurrency 20 --verbose ``` 仅此而已。MCP Scanner 会探测常见的 MCP 路径，测试认证，并将严重性评定的发现摘要打印到终端。 ## 为什么要使用 MCP Scanner？ 随着 AI 集成迅速采用 MCP，未认证的端点可能暴露敏感的工具列表，允许任意 JSON-RPC 方法调用，并泄露 Server-Sent Event (SSE) 流——全部无需凭证。MCPwn 漏洞类别已在生产 nginx 部署中展示了这一风险。MCP Scanner 为开发者和安全工程师提供了一种快速、自动化的方式，在自身基础设施中查找这些问题。 ## 功能特性 - **异步多目标扫描** — 并发探测大量主机的常见 MCP 端点模式（`/mcp`、`/sse`、`/api/mcp`、`/.well-known/mcp` 等），支持可配置的并发限制。 - **认证审计** — 对每个发现的端点测试缺失的 `Authorization` 头、未认证的 SSE 流、暴露的工具列表和开放的 JSON-RPC 方法调用。 - **严重性评定的发现** — 每个问题被分配 `CRITICAL`、`HIGH`、`MEDIUM` 或 `LOW` 严重性，并附带类似 CVE 的描述，映射到实际影响，引用 MCPwn 漏洞类别。 - **双格式报告** — 用于交互式使用的彩色 Rich 终端摘要；以及用于 CI/CD 流水线集成的机器可读 JSON 和 HTML 报告。 - **自定义词表和头部注入** — 通过内部 URL 模式扩展默认探测，并使用特定的 API 密钥或会话令牌进行测试。 ## 使用示例 ### 基础单主机扫描 ``` mcp-scanner scan https://myapp.example.com ``` ``` ╭─────────────────────────────────────────╮ │ MCP Scanner v0.1.0 │ ╰─────────────────────────────────────────╯ Scanning 1 target(s)... [CRITICAL] Unauthenticated MCP endpoint exposed URL: https://myapp.example.com/mcp Tools listing accessible without credentials. [HIGH] Open SSE stream detected URL: https://myapp.example.com/sse Server-Sent Events stream requires no authentication. Summary: 2 findings across 1 target (1 CRITICAL, 1 HIGH) ``` ### 从文件扫描多个主机 ``` mcp-scanner scan --targets-file hosts.txt --concurrency 30 --output results.json ``` ### 使用自定义词表进行内部路径模式探测 ``` mcp-scanner scan https://internal.corp.net \ --wordlist internal-paths.txt \ --header "X-Internal-Token: secret123" ``` ### JSON 报告输出（用于 CI/CD） ``` mcp-scanner scan https://staging.example.com --output report.json --format json ``` ``` { "scan_id": "a3f1c8e2-...", "started_at": "2024-07-01T12:00:00Z", "targets": ["https://staging.example.com"], "findings": [ { "severity": "CRITICAL", "title": "Unauthenticated MCP endpoint exposed", "url": "https://staging.example.com/mcp", "description": "The /mcp endpoint responds to unauthenticated requests and exposes a tools listing.", "evidence": "HTTP 200 with Content-Type: application/json" } ], "summary": { "total": 1, "critical": 1, "high": 0, "medium": 0, "low": 0 } } ``` ### 所有 CLI 选项 ``` mcp-scanner scan --help ``` ``` Usage: mcp-scanner scan [OPTIONS] [TARGETS]... Options: --targets-file PATH File containing one target URL per line. --concurrency INTEGER Max concurrent requests. [default: 10] --timeout FLOAT Per-request timeout in seconds. [default: 10.0] --wordlist PATH Custom URL path wordlist file. --header TEXT Extra request header (repeatable: -H "K: V"). --output PATH Write report to file. --format [terminal|json|html] Output format. [default: terminal] --verbose / --no-verbose Enable verbose logging. --version Show version and exit. --help Show this message and exit. ``` ## 项目结构 ``` mcp_scanner/ ├── pyproject.toml # Project metadata, dependencies, CLI entry point ├── README.md # This file ├── mcp_scanner/ │ ├── __init__.py # Package init, version, top-level symbols │ ├── cli.py # Click-based CLI entry point │ ├── scanner.py # Core async scanning engine │ ├── probes.py # MCP URL patterns, payloads, auth test strategies │ ├── auth_tester.py # Authentication bypass detection │ ├── reporter.py # Terminal, JSON, and HTML report generation │ └── models.py # ScanTarget, Finding, Severity, ScanReport dataclasses └── tests/ ├── __init__.py ├── test_scanner.py # Scanner engine tests (mocked HTTP) ├── test_auth_tester.py # Auth bypass detection tests ├── test_reporter.py # Report generation and schema tests ├── test_probes.py # Probe pattern completeness tests └── test_models.py # Dataclass serialization and helper tests ``` ## 配置 MCP Scanner 完全通过 CLI 标志配置，无需配置文件。关键选项如下： | 选项 | 描述 | 默认值 | |---|---|---| | `--concurrency` | 最大并发 HTTP 请求数 | `10` | | `--timeout` | 每个请求超时（秒） | `10.0` | | `--wordlist` | 自定义 URL 路径词表文件（每行一个路径） | 内置列表 | | `--header` | 每个请求发送的附加 HTTP 标头（可重复） | 无 | | `--format` | 报告输出格式：`terminal`、`json` 或 `html` | `terminal` | | `--output` | 报告输出文件路径（未指定则输出到标准输出） | 无 | ### 自定义词表格式 每行一个 URL 路径，可带或不带前导斜杠： ``` /mcp /api/mcp /internal/mcp/tools /.well-known/mcp custom-mcp-endpoint ``` ## 从源码安装 ``` git clone https://github.com/example/mcp-scanner.git cd mcp-scanner pip install -e . ``` ### 运行测试 ``` pip install -e ".[dev]" pytest tests/ -v ``` ## 许可证 MIT 许可证。详见 [LICENSE](LICENSE)。 *Built with [Jitter](https://github.com/jitter-ai) - an AI agent that ships code daily.*

标签：API安全, HTTP探测, JSON-RPC, JSON输出, MCP, MCPwn, nginx漏洞, Python, SSE流, URL模式探测, Web安全, 多目标并发, 安全扫描, 安全报告, 异步扫描, 无后门, 时序注入, 未授权访问, 模型上下文协议, 结构化报告, 网络安全, 蓝队分析, 认证审计, 逆向工具, 隐私保护, 颜色化输出