nekiyRichie/recon-mcp

# recon-mcp 一个 MCP server，为 AI agent 提供 15 个基于免费、公开来源的 OSINT 工具。 无需 API 密钥，无需账户，无需注册——这里的每个数据源都允许在 未认证状态下访问。 它也是一个完整的实战示例，展示了当 MCP server 必须在实际使用中生存，而不仅仅是作为演示时，会发生哪些改变：响应格式化、上下文预算控制、针对不同 endpoint 的重试策略，以及将原本需要十次调用的固定流程压缩为一次的复合工具。 ``` "Map the attack surface of example.com" → recon_domain("example.com") 1 call, ~4s → 240 subdomains from Certificate Transparency → 15 resolved in parallel → 9 addresses profiled for open ports and known CVEs ``` ## 安装 ``` git clone https://github.com//recon-mcp && cd recon-mcp python -m venv .venv && . .venv/bin/activate pip install -e . ``` 将其注册到任何 MCP 客户端。对于 Claude Desktop / Claude Code： ``` { "mcpServers": { "recon": { "command": "/absolute/path/to/recon-mcp/.venv/bin/recon-mcp" } } } ``` 这就是全部设置。没有配置文件，也不需要进行任何 认证。 ## 工具 | 工具 | 功能 | |---|---| | `recon_domain` | 完整的初步扫描：CT → DNS → 主机暴露情况，一次调用完成 | | `crt_subdomains` | 从证书透明度日志 (Certificate Transparency logs) 获取子域名 | | `crt_certificates` | 原始 CT 条目 —— 颁发者、有效期、SAN | | `dns_records` | 一次并行调用获取 A/AAAA/CNAME/MX/NS/TXT/SOA 记录 | | `dns_lookup` | 查询一种特定的记录类型 | | `dns_reverse` | 查询 IPv4 地址的 PTR 记录 | | `host_profile` | Shodan InternetDB：端口、主机名、标签、CVE | | `host_ports` | 仅查询开放端口 | | `host_vulns` | 仅查询 CVE，并附带误报警告 | | `cve_lookup` | 查询单个 CVE：CVSS 分数、向量、描述 | | `cve_search` | 按关键字搜索 CVE，按最新排序 | | `rdap_domain` | 注册数据：日期、注册商、域名服务器 | | `rdap_ip` | 网络块所有者、IP 范围、国家 | | `wayback_urls` | 某个域名下归档的历史 URL | | `wayback_snapshots` | 某个 URL 随时间变化的快照，附带摘要 | 数据来源：[crt.sh](https://crt.sh)、Cloudflare 和 Google DNS-over-Https、 [Shodan InternetDB](https://internetdb.shodan.io)、[NVD](https://nvd.nist.gov)、 [RDAP](https://rdap.org)、[Wayback Machine](https://web.archive.org)。 ## 设计说明 这些部分经历了多次迭代，并最终呈现出当前的设计原因。 ### 统一响应格式，包括失败时 每个工具都返回相同的结构： ``` { "ok": true, "status": 200, "data": {}, "pivots": {"hosts": [], "ips": [], "emails": [], "urls": []}, "truncated": false, "hint": "..." } ``` 如果每个工具都自行发明返回格式，会导致模型在每次调用时都要重新理解数据结构。错误状态也保持相同的结构——如果一个工具在失败时返回一个纯字符串，会迫使 agent 在读取任何内容之前，必须先根据类型进行分支判断。 `hint` 字段携带了状态码无法表达的信息：例如 Shodan 返回 404 意味着“从未被爬取，可能没有暴露的端口”，而不是“工具损坏”；或者从 banner 匹配中获得的 CVE 列表在补丁被回溯移植时，可能会产生误报。 ### 默认紧凑模式，`full` 为可选 侦察 endpoint 返回的数据量通常很大。对一个活跃域名进行 CT 查询会返回数万条记录；将这些数据直接交给模型会导致会话上下文超限。因此，列表会被自动截断为 25 项，字符串会被截断为 6000 个字符，并设置 `truncated` 标志以确保不会有数据被静默丢弃。当调用者明确需要全部数据时，任何工具都可以接受 `full: true` 参数。 这个限制是有意设得很紧的。Agent 随时可以请求更多数据——但它无法恢复已经爆掉的上下文窗口。 ### `pivots` —— 无需解析步骤的下一跳 每次响应都会从 payload 中提取主机名、IP、邮箱和 URL。 接下来值得查询的标识符通常出现在难以预测的地方：主机名可能出现在证书主体中、重定向目标或 PTR 记录中，且它们的字段名各不相同。将这些信息集中提取出来，意味着 agent 可以直接进行链式查询，而无需通过解析自然语言来寻找下一个查询目标。 ### 针对 endpoint 的重试预算 为所有数据源设置相同的重试策略在两个极端情况下都是错误的。crt.sh 响应缓慢，且在高负载下容易出现网关错误：因此需要长超时、少重试、保持耐心。NVD 将未认证的调用者限制为大约每 30 秒 5 次请求：因此需要积极退避，并缓存一小时。DNS 查询快速且成本低：短超时，并立即使用备用解析器重试。 对一个已知损坏的 endpoint 重试四次，会将一次失败的调用变成让 agent 停滞四十秒——这在用户体验上等同于工具坏了。 ### 复合工具 针对域名的初步扫描流程总是相同的序列，模型在这些步骤之间的“推理”毫无价值，反而增加了真实的延迟。 `recon_domain` 在进程内运行，并并行展开这些调用：原本约 15 次的调用被压缩为 1 次。各个单源工具仍然保留，以便深入挖掘概览中发现的具体细节。 它的 `host_limit` 上限是关键所在。某些域名可能有成千上万个子域名；解析所有这些子域名将意味着进行数千次 DNS 查询，并产生一个无人能阅读的结果。该工具会选取最有潜力的部分进行查询，明确指出跳过了多少，并让调用者根据需要自行决定是否深入查询。 ### 故障限制在工具内部 如果 handler 中出现未捕获的异常，该异常将作为协议错误传播，并且（取决于客户端）可能会中断连接，或者导致 agent 对发生的事情一无所知。所有异常都会在边界处被捕获，并作为标准的失败响应返回：一个损坏的工具最多只会浪费一个对话轮次，而不会导致整个会话崩溃。 日志输出被重定向到 stderr，绝不输出到 stdout——因为 stdout 用于承载 MCP 协议数据，在那里出现的一行意外日志会破坏数据流，从客户端侧调试这种问题是非常痛苦的。 ## 适用范围与使用场景 该项目仅查询关于面向互联网的基础设施的公共数据库。它不会向目标本身发送任何流量：数据完全来源于证书日志、被动 DNS、归档的爬取记录和现有的扫描索引。这使得它非常适合用于攻击面映射、资产盘点和前期介入研究。 它不是扫描器，也不能确认任何漏洞状态。从 Shodan 获取的 CVE 是通过 banner 推断出来的，并且会过时；归档的 URL 可能早已失效。这里的所有信息都只是需要进一步验证的线索，而不是可以直接报告的发现。 ## License MIT

标签：ESC4, GitHub, MCP, OSINT, Python, 动态插桩, 实时处理, 无后门, 资产测绘, 逆向工具