endpoint-probe

端点探测

探测基础 URL，发现其 API 概况：类型、身份验证、端点、速率限制、CORS 和服务器指纹。

适用场景

• 用户提供基础 URL，并询问“有哪些 API 可用？”或“这里有哪些端点？”
• 在构建集成前，需要了解未记录或文档不完善的 API
• 用户询问“此 API 如何进行身份验证？”或“此端点需要什么身份验证？”
• 评估第三方服务，需要梳理其 API 概况
• 用户要求“发现”“探测”“探索”或“侦察”某个 API 端点
• 用户想在配置 MCP 服务前了解它提供了哪些工具
• 用户询问“此 MCP 服务提供什么？”或“MCP 服务 X 有哪些工具？”

请勿用于：

• 抓取 HTML 页面内容（使用 website-scraping）
• 对已知功能进行 QA 测试（使用 QA/测试技能）
• 配置 MCP 服务（使用 MCP 配置技能）——此技能用于发现 MCP 服务概况，不负责配置
• 长期监控 API（这是一种一次性发现工具）

工作流程

1. 运行探测脚本

python scripts/probe_api.py <base_url> [options]

选项：

标志	描述	默认值
--auth TOKEN	身份验证令牌/凭据	无
--auth-type	bearer、basic 或 apikey	bearer
--header "Key: Value"	自定义标头（可重复指定）	无
--timeout N	请求超时时间（秒）	10
--json	输出原始 JSON，而非格式化报告	关闭
--no-guess	跳过 REST 资源猜测	关闭
--api-version v1	资源探测使用的 API 版本前缀	无
--mcp	通过 HTTP（StreamableHTTP）将目标作为 MCP 服务进行探测	关闭
--mcp-stdio	通过 stdio 将目标作为 MCP 服务进行探测（启动子进程）	关闭
--mcp-env "KEY=value"	stdio MCP 服务的环境变量（可重复指定）	无
--allow-private	允许探测私有/内部 IP 地址	关闭

示例：

# Basic probe — no auth
python scripts/probe_api.py https://api.example.com

# With Bearer token
python scripts/probe_api.py https://api.example.com --auth "tok_abc123"

# With API key (sends X-API-Key header)
python scripts/probe_api.py https://api.example.com --auth "key_xyz" --auth-type apikey

# Skip resource guessing (faster, less noisy)
python scripts/probe_api.py https://api.example.com --no-guess

# JSON output for programmatic use
python scripts/probe_api.py https://api.example.com --json

2. 解读报告

探测按顺序运行 7 个阶段：

1. 服务器指纹——根据 Server 和 X-Powered-By 标头识别框架（Express、FastAPI、Django、Rails、Spring 等）
2. 知名路径——检查约 40 个发现路径：/openapi.json、/swagger.json、/docs、/graphql、/.well-known/、/health、/version 等
3. GraphQL 内省——向 /graphql、/api/graphql、/query 发送内省查询，并在成功时提取类型
4. OPTIONS / CORS——向 /、/api、/api/v1 发送 OPTIONS 请求，以发现允许的方法和 CORS 策略
5. 身份验证检测——不提供凭据访问可能受保护的端点，检查 401/403 响应和 WWW-Authenticate 标头
6. 速率限制——检查 X-RateLimit-*、RateLimit-*、Retry-After 标头
7. REST 资源猜测——探测约 50 个常见资源路径（/api/users、/api/orders 等），并报告响应状态不是 404 的路径

3. 使用探测结果

• 找到 OpenAPI → 解析规范，获取完整端点列表、请求/响应架构和身份验证方案。探测器已从规范中提取端点。
• GraphQL 内省成功 → 已获取完整类型系统。根据发现的类型构建查询。
• 仅找到 REST 资源 → API 未记录文档。将发现的资源路径作为起点，并使用 GET/POST/PUT/DELETE 探测各个端点。
• 检测到身份验证 → 后续所有请求均使用识别出的方案。
• 未发现任何内容 → API 可能需要先登录、使用非标准路径，或者该 URL 下并不存在此 API。请尝试提供身份验证凭据，或检查基础 URL 是否正确。

MCP 服务探测

探测器也支持发现 MCP（Model Context Protocol）服务的概况，包括工具、资源和提示词及其完整输入架构。这样，你就能在 Hermes 中配置 MCP 服务之前对其进行评估。

通过 HTTP 探测 MCP（StreamableHTTP 传输）

# Probe a remote MCP server
python scripts/probe_api.py "https://mcp.example.com/mcp" --mcp

# With auth headers
python scripts/probe_api.py "https://mcp.example.com/mcp" --mcp --auth "tok_abc123"

# With custom headers
python scripts/probe_api.py "https://mcp.example.com/mcp" --mcp --header "X-API-Key: mykey"

通过 stdio 探测 MCP（本地子进程）

# Probe a local MCP server (npx-based)
python scripts/probe_api.py "npx -y @modelcontextprotocol/server-time" --mcp-stdio

# Probe a Python-based MCP server
python scripts/probe_api.py "python3 /path/to/mcp_server.py" --mcp-stdio

# With environment variables
python scripts/probe_api.py "npx -y @modelcontextprotocol/server-github" --mcp-stdio \
  --mcp-env "GITHUB_PERSONAL_ACCESS_TOKEN=ghp_xxx"

MCP 探测器会发现什么

探测器会执行完整的 MCP 握手流程：

1. 初始化 — 通过 JSON-RPC 执行 initialize，并提供协议版本、客户端信息和功能。报告服务名称、版本、协议版本和服务端功能。
2. 工具 — tools/list → 所有工具名称、描述和完整输入架构（参数名称、类型、必填/可选、默认值、枚举）
3. 资源 — resources/list → 所有资源 URI、名称、描述和 MIME 类型
4. 提示词 — prompts/list → 所有提示词模板名称、描述和参数

MCP 与 MCP 配置技能的区别

方面	endpoint-probe --mcp	MCP 配置技能
用途	发现服务提供的内容	配置并使用服务
时机	决定是否使用服务之前	决定使用服务之后
输出	工具架构、资源、提示词	已注册到 Agent 工具集中的工具
是否需要重启	否	是（重启 Agent 以注册）
传输方式	HTTP 和 stdio	HTTP 和 stdio

工作流： 使用 endpoint-probe --mcp 评估服务 → 判断是否有用 → 使用 MCP 配置技能注册该服务 → 重启 Agent。

常见问题

1. 基础 URL 错误或过于具体。 https://api.example.com 是正确的；https://api.example.com/v1/users/123 则过于具体——探测器需要根路径来发现路径。请移除末尾路径。

   兼容 OpenAI 的 API： 如果基础 URL 是推理端点，例如 https://provider.ai/v1 或 https://provider.ai/zen/go/v1，探测器将无法发现任何内容，因为发现路径（/openapi.json、/docs 等）由域名根路径提供，而非推理前缀。请始终探测域名根路径（https://provider.ai），以查找 OpenAPI 规范和完整 API 范围。推理端点（/v1/chat/completions、/v1/models）通常只是更大型平台 API 的一小部分。

2. GraphQL 内省已禁用。 出于安全考虑，许多生产环境中的 GraphQL API 会禁用内省。探测器会显示状态码 200/400/403，并提示“introspection disabled”——这表示 GraphQL 存在，但架构被隐藏。可尝试发送简单查询，例如 {"query": "{ __typename }"}，以进行确认。

3. 需要身份验证的 API 返回 404，而不是 401。 某些 API 会对未经身份验证的请求返回 404，以隐藏端点是否存在。如果所有请求都返回 404，请尝试提供 --auth 凭据。

4. 探测期间遭遇速率限制。 脚本会并发发送约 80–100 个请求（8 个线程）。大多数 API 都能承受，但如果遇到 429，请增加 --timeout，或使用 --no-guess 减少请求数量。脚本会自动检测速率限制耗尽情况（通过 X-RateLimit-Remaining: 0），并跳过资源猜测以避免误报——请查看报告中的 rate_limited_skipped_guessing: true。

5. 统一返回 403 ≠ 需要身份验证。 如果所有发现路径都返回 403，且错误响应正文相同，则说明你受到了速率限制，而非被身份验证拦截。在将 403 解读为需要身份验证之前，请检查速率限制标头（X-RateLimit-Remaining）。真正需要身份验证的 API 会返回 401（附带 WWW-Authenticate），或在不同路径上混合返回 200/401/403，而非统一返回 403。

6. /graphql 返回 403 表示端点存在。 /graphql 返回 403，说明端点存在，但内省被拦截——并不表示 GraphQL 不存在。返回 404 则表示端点不存在。请勿混淆两者。

7. CORS 标头仅出现在 OPTIONS 响应中。 有些 API 只会在 OPTIONS 预检请求中发送 CORS 标头，而不会在 GET 请求中发送。因此，探测器会单独检查 OPTIONS。

8. /health、/status 路径可能产生误报。 即使 API 本身已宕机，负载均衡器或 CDN 也可能在这些路径上返回 200。应将其视为“有东西正在监听”，而非“API 运行正常”。

9. 服务指纹并不可靠。 代理通常会移除 X-Powered-By。框架提示仅供参考——请勿将其视为确定结论。

10. 自签名证书。 脚本使用 urllib，默认会验证证书。PYTHONHTTPSVERIFY=0 不会影响 urllib（它只影响 requests/httpx）。目前不支持自签名证书目标——内部主机可使用 --allow-private，但自签名 TLS 需要未来添加一个使用自定义 ssl.SSLContext 的 --insecure 标志。

11. 并发至关重要。 探测脚本使用 concurrent.futures.ThreadPoolExecutor(max_workers=8)，同时探测众所周知的路径和猜测资源。按顺序探测约 90 个路径时，面对响应缓慢的 API 会超时（>120s）。如果修改脚本，请保留线程池——不要改回顺序请求。

12. SPA 全路径匹配导致的误报。 Next.js、Nuxt 和其他 SPA 框架会对每个路径都返回相同的 HTML 页面（200 + text/html），包括 /api/users、/health、/openapi.json 等。这样会让报告充斥着虚假的“端点”，而这些其实只是 SPA 外壳。脚本会在 REST 资源猜测过程中自动检测这种情况（统一的 200 + text/html + 相似的正文长度 → 丢弃），并在 SOAP 检测过程中进行防护（WSDL 路径返回 text/html 不属于 SOAP）。不过，发现路径阶段仍可能显示许多 html-docs 条目——这些是 SPA 路由，不是真正的 API 文档。如果服务器指纹显示 Next.js/Nuxt，且大多数发现路径都返回 200 text/html，那么除 OpenAPI 规范（如果找到）外，都应视为 SPA 噪声。

13. MCP stdio 服务挂起。 某些 MCP 服务在 stdin 关闭后无法正常退出。探测程序会发送 terminate()，然后等待 5s 再调用 kill()。如果服务忽略 SIGTERM，探测可能会多花 5s。这是预期行为——探测程序总会清理资源。

14. 报告会隐藏凭据值，但不会隐藏身份验证协议。 身份验证检测仍会显示方案（Bearer、Basic、WWW-Authenticate、“需要 API 密钥”）、Cookie 名称。回显的 Authorization / X-API-Key 值、Set-Cookie 值，以及错误正文中形似令牌的字符串，都会替换为 ***，以便报告/日志安全分享。如果某个标头看起来“没有”机密，请检查是否有 ***——这表示存在机密，且已被清除。

15. MCP 协议版本不匹配。 探测程序发送的协议版本为 2025-06-18。较旧的 MCP 服务可能使用 2024-11-05——服务会协商版本，并在响应中返回其支持的版本。探测程序会在摘要中报告协商后的版本。如果初始化因协议错误而失败，服务可能要求使用较旧版本。

16. MCP HTTP 端点 URL。 MCP over HTTP 使用单个端点 URL（例如 https://mcp.example.com/mcp），而不是基于路径的路由。所有 JSON-RPC 请求都会通过 POST 发送到同一个 URL。不要追加 /tools/list 或类似路径——--mcp 标志会正确处理这一点。

17. MCP 资源/提示词可能不受支持。 并非所有 MCP 服务都实现了资源或提示词。探测程序会妥善处理 method not found 错误，并在不受支持的原语处报告“无”。这不是错误——这意味着该服务只实现了工具。

18. MCP StreamableHTTP 需要 Accept 标头。 现代 MCP 服务（协议版本 2025-06-18）使用 StreamableHTTP 传输，它要求请求标头中包含 Accept: application/json, text/event-stream。如果缺少此标头，服务会返回 406 Not Acceptable。探测程序会自动发送此标头。

19. MCP SSE 响应格式。 StreamableHTTP 服务可能以 text/event-stream（SSE）格式响应——data: {"jsonrpc":"2.0","result":{...}}——而不是纯 JSON。探测程序会自动检测并从 SSE 的 data: 行中提取 JSON。如果针对 MCP 服务时出现“Non-JSON response”错误，可能需要更新 SSE 解析器。

20. 凭据会通过进程 argv 暴露。 通过 --auth、--mcp-env 和 --header 传递的令牌会出现在 ps、Shell 历史记录和 Agent 日志中。对于基本身份验证，--auth 必须是 user:password（不能只有密码）。尽可能优先从环境变量或 .env 文件中读取凭据。SKILL.md 示例使用的是已隐藏的令牌——示例中切勿使用真实令牌。

21. SSRF 防护。 探测器会阻止私有/内部 IP 范围（RFC1918、回环地址、链路本地地址、CGNAT 100.64/10、ULA fc00::/7、IPv4 映射的 IPv6 地址，例如 ::ffff:127.0.0.1）和云元数据端点（169.254.169.254）。使用 ipaddress 模块进行准确检测，不依赖脆弱的字符串前缀匹配。探测器会禁用重定向，以防基于重定向的 SSRF。使用 --allow-private 可覆盖此限制（例如，探测用于本地开发 API 的 localhost）。如果探测时所有连接都出错，且目标为内部地址，请检查 JSON 报告中的 ssrf_warning 字段。

22. --mcp-stdio 的命令允许列表。 只允许已知的包运行器（npx、uvx、python3、python、node、bunx），不允许任意命令或绝对路径。这可以防止提示词注入的“MCP 服务”字符串执行任意命令。

23. 正文大小上限为 5 MiB。 响应正文上限为 5 MiB，以防止内存 DoS。被截断的响应正文中会包含 [truncated at 5 MiB]。如果 OpenAPI 规范或 GraphQL 模式超过此大小，内容将不完整。

24. 支持 MCP 会话 ID。 探测器会从初始化响应中获取 Mcp-Session-Id，并在所有后续请求中重新发送该 ID。需要会话的 StreamableHTTP 服务要求此 ID。无状态服务（Composio、AlphaVantage）会忽略此标头。

25. MCP stdio 会继承经过清理的环境。 子进程会继承一份经过清理的 os.environ 副本：只保留安全变量（PATH、HOME、USER、LANG、LC_*、TERM、SHELL、XDG_*）；包含机密子字符串（TOKEN、SECRET、PASSWORD、API_KEY、CREDENTIAL、PRIVATE_KEY、ACCESS_KEY、CLIENT_SECRET）的变量都会被剔除。请通过 --mcp-env 显式传递机密。如果 npx/node 位于继承的 PATH 中，macOS 即可正常运行；如有需要，可通过 --mcp-env 设置 PATH。

26. --mcp 和 --mcp-stdio 不能同时使用。 CLI 会拒绝同时指定这两个标志。如果需要为同一服务尝试两种传输方式，请分别运行两条命令。

已知限制（v1.2.3 修复后仍存在）

• 不解析 OpenAPI YAML 规范。 会探测 /openapi.yaml，但只解析 JSON。YAML 规范会显示为通用的 200 结果。解决方法：将其转换为 JSON，或使用能读取 YAML 的工具。
• 仅通过路径检测 gRPC-Web。 探测器通过 GET 检查 gRPC 路径，不检查内容类型或 Connect 协议。检测结果仅基于路径启发式规则，并非真正的 gRPC-Web 检测。
• SSE 解析器仅处理首个数据行。 多行 data: 帧或单个 SSE 流中的多条 JSON-RPC 消息可能无法正确解析。大多数 MCP 服务每个 SSE 事件只发送一条消息；否则可能需要更新解析器。
• stdio 平台支持。 如果 npx/node 位于 PATH 中，macOS 即可正常运行（环境变量会从当前进程继承）。尚未在 Windows 上测试 stdio MCP。
• DNS 重绑定 TOCTOU 问题。 验证时只解析一次主机名，urllib 会在连接时再次解析。检查时返回公网地址、连接时返回私有地址，就可能绕过 SSRF 防护。在不可信的 DNS 环境中，需要固定 IP；目前不在支持范围内。
• 允许列表中的运行器仍可拉取远程包。 npx -y pkg 会下载并执行来自 npm 的代码。允许列表可防止执行任意命令，但无法防止通过包名称发起的供应链攻击。
• 会阻止内联代码标志。 所有运行器都会拒绝 -c、-e、-p、--call、--eval、--exec、--print，以防通过提示词注入的命令字符串执行内联 RCE。

验证清单

• 基础 URL 是 API 根路径（末尾没有 /v1/users/123 这样的路径）
• 如果 API 需要身份验证，已提供身份验证凭据
• 报告中至少有一个非 404 的发现路径
• 如果发现了 OpenAPI：端点列表非空
• 如果发现了 GraphQL：内省结果明确显示成功或失败
• 已识别身份验证方案（或确认其为“无/开放”）
• 已检查速率限制标头（或确认其不存在）
• 探测过程中没有出现 429 错误
• 如果 REST RESOURCES 部分为空，但发现中有许多返回 200 text/html 的路径：请检查服务器指纹是否为 Next.js/Nuxt——可能已通过过滤 SPA 全局回退路径排除误报
• 如果处于 MCP 模式：初始化握手成功（status = "connected"）
• 如果处于 MCP 模式：工具数量 > 0（或 tools_error 已说明原因）
• 如果使用 MCP stdio：子进程已清理（没有遗留进程）

参考资料

• references/interpretation-guide.md — 使用真实 API（GitHub、Petstore、OpenRouter、OpenCode、Composio MCP、AlphaVantage MCP、library-rag MCP）进行测试后总结的报告解读模式。涵盖状态码模式、SPA 全局回退检测、OpenAI 兼容接口推断前缀问题、OpenAPI 规范的细微之处、CORS 注意事项、MCP 协议协商、Composio 元工具模式和性能基准。当探测报告含义模糊，或需要解读意外状态码时，请阅读此文档。
• references/code-review-history.md — 完整的 6 轮评审记录（R1-R6），包括收敛表、关键模式（拒绝列表回归、跨模型多样性、声称已修复但实际上未应用的修复）以及 Codex 沙盒说明。修改脚本前或调试安全问题时，请阅读此文档。