asaotomo/FofaMap

一款证据驱动的 FOFA 资产测绘智能体：支持自然语言侦察、AI 反思、CLI / MCP / Skill / REST API，以及经人工审批的 Nuclei 扫描。

📌 什么是 FofaMap？

FofaMap 是一个基于 Python 的命令行工具，将 FOFA（互联网暴露资产的搜索引擎）与 AI 驱动的代理相结合。它能够：

直接运行经典的 FOFA 查询。
接受自然语言请求，让内置代理规划多个 FOFA 查询，反思结果，并生成结构化、有证据支持的资产报告。
将结果导出为 XLSX、CSV 或 JSONL 格式。
可选地生成一个 Nuclei 扫描计划，该计划在执行任何主动扫描前必须经过手动批准。

该项目捆绑了 REST API、AI 编码助手（Cursor、Claude、LM Studio 等）的 MCP/Skill 集成，以及最多可迭代两次的自我反思循环。

🚀 快速开始（5 分钟）

# 克隆并设置虚拟环境（Python 3.10+）
git clone https://github.com/asaotomo/FofaMap.git && cd FofaMap
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

# 检查安装
fofamap --version
fofamap --help

运行 fofamap init – 一个向导，用于存储您的 FOFA API 密钥（以及可选的 OpenAI/Anthropic 等密钥，用于 AI 模式）。

执行经典查询：

fofamap -q 'app="nginx" && country="CN"' -p 2 --size 100

或让代理完成繁重工作：
```
fofamap -ai '收集 Example 公司的公开网站，区分高置信资产与待复核候选'
```
代理将： 1️⃣ 将自然语言转换为一个或多个 FOFA 查询， 2️⃣ 执行查询，评估命中数量，如需则优化查询（最多 2 轮）， 3️⃣ 去重并为证据分级（corroborated、observed、candidate）， 4️⃣ 输出表格和 Markdown 报告。

🛠️ 核心功能

功能	你将获得
经典 FOFA CLI	`-q / -hq / -cq / -ico / -bq` – 完整的 FOFA 语法，无需 AI
自然语言代理	`-ai` – 自动规划、反思并总结资产
证据分级	结果被标记为 corroborated、observed 或 candidate，边界清晰
导出格式	XLSX、CSV、JSONL；支持超大数据集的流式输出
Nuclei 集成	生成扫描计划，显示目标/模板/严重性，执行前需一次性手动批准令牌
MCP / Skill	一键注册 FofaMap 为 AI 编码助手（Cursor、Claude、LM Studio 等）的工具
REST API	OpenAPI 3.1 定义；运行 `fofamap serve` 可通过 HTTP 暴露相同功能
跨平台	支持 Windows、macOS 和 Linux
安全优先	尽可能将 API 密钥存储在操作系统密钥链中；对配额、速率限制或权限问题提供清晰错误信息

📚 如何使用代理（AI 模式）

fofamap -ai '收集授权范围内中国地区的 Example 产品暴露面，按协议、端口和产品版本总结，最多返回 500 条'

代理工作流（参见 README 中的 mermaid 图）：

解析请求并决定需要哪些 FOFA 子查询。
验证每个查询是否符合 FOFA 语法和内置规则库。
执行查询，收集命中结果，并检查结果质量是否足够。
如果不足，则反思并生成优化后的查询（最多两次迭代）。
去重并分配证据等级。
生成表格和 Markdown 简报，始终包含：
- 高置信度资产，
- 噪声/误报，
- 未覆盖的证据缺口，
- 下一步建议。

🔧 Nuclei 扫描（审批门控）

单独安装 Nuclei（projectdiscovery.com），并确保其在您的 PATH 中。

添加环境变量以启用扫描：

export FOFAMAP_ENABLE_SCANNING=true
export FOFAMAP_SCAN_APPROVAL_SECRET='随机高熵字符串（≥24字符）'

使用 -n（或 --nuclei）运行查询。该工具将：
- 显示确切的目标列表、选定的模板 ID 和严重性过滤器。
- 要求您确认（或编辑）计划。
- 批准后，使用选定模板调用 nuclei。

您可以自定义模板集：

fofamap -q 'domain="example.com"' -n \
    --nuclei-id cors-misconfig --nuclei-id tech-detect \
    --severity low,medium

使用 --nuclei-id all 和 --severity all 进行全规模扫描（工具会强烈警告）。

📦 与 AI 编码助手集成（MCP/Skill）

# 列出支持的代理
fofamap integrate --list
# 为 Cursor 安装（示例）
fofamap integrate --agent cursor
# 卸载
fofamap integrate --agent cursor --uninstall

安装程序会写入一个小型包装器（fofamap-mcp），主机 IDE 可将其作为工具调用。不复制任何密钥；包装器仅指向现有 Python 环境。

🗂️ 项目结构（概览）

FofaMap/
├─ config/            # 示例设置，.env 模板
├─ docs/              # 代理集成指南、审计文档等
├─ fofamap/           # 核心包（CLI、代理、MCP、REST）
├─ results/           # 默认输出目录（带时间戳的子文件夹）
├─ tests/             # 单元/集成测试
└─ setup.py / pyproject.toml

🧩 何时选择哪个入口点

入口	需要 FOFA 密钥	需要 AI 密钥	最佳用途
交互式 CLI / 经典 `-q`	✅	❌	熟悉 FOFA 语法，快速查询
本地 `-ai` 代理	✅	✅	自然语言侦察，证据分级报告
MCP / Skill	✅	❌*	从 Cursor、Claude、LM Studio 等使用（主机提供其自己的 LLM）

❓ 常见问题

我需要付费的 FOFA 账户吗？ 是的，该工具使用 FOFA API；您能检索的数据量取决于您的会员级别。
AI 可以在我的机器上运行命令吗？ 否。代理仅调用 FOFA、处理数据，并（可选地）准备 Nuclei 计划。Nuclei 的执行由手动批准控制。
支持哪些 AI 提供商？ OpenAI、Anthropic、DeepSeek、Ollama、LM Studio 以及任何兼容 OpenAI 风格的端点。
API 密钥如何存储？ 优先存储在操作系统密钥链中（macOS Keychain、Linux Secret Service、Windows Credential Manager）。若不可用，向导会询问是否将密钥写入具有 0600 权限的本地文件。

📦 安装与升级说明

在虚拟环境中使用 pip install -e . 安装。

升级方法：

git pull && pip install --force-reinstall -e .

主版本升级后，请轮换之前存储的 FOFA 密钥（参见 MIGRATION.md）。

🔗 有用链接

发布版本: https://github.com/asaotomo/FofaMap/releases/tag/v2.0.1
文档索引: docs/（代理集成、REST OpenAPI、安全策略）
问题追踪: 在 GitHub Issues 中报告错误或功能请求。

TL;DR

FofaMap 让安全研究人员和红队人员能够通过原始查询或 自然语言 搜索 FOFA，自动优化搜索，分级证据，并可选地在人类批准步骤后门控 Nuclei 扫描——所有功能均来自一个跨平台 CLI，也可通过 REST API 或作为 AI 编码助手中的工具调用。