🗺️ FofaMap 2.0.1

把自然语言资产发现、FOFA 证据检索、AI 反思总结与经人工审批的 Nuclei 扫描，放进同一条可追溯工作流。

<p align="center"> <a href="https://github.com/asaotomo/FofaMap/releases/tag/v2.0.1"><img alt="Release" src="https://img.shields.io/github/v/release/asaotomo/FofaMap?label=Release&amp;color=00B8D9&amp;style=flat-square"></a> <a href="https://github.com/asaotomo/FofaMap/actions/workflows/ci.yml"><img alt="CI" src="https://img.shields.io/github/actions/workflow/status/asaotomo/FofaMap/ci.yml?branch=v2.0.1&amp;label=CI&amp;style=flat-square"></a> <a href="https://github.com/asaotomo/FofaMap/actions/workflows/security.yml"><img alt="Security" src="https://img.shields.io/github/actions/workflow/status/asaotomo/FofaMap/security.yml?branch=v2.0.1&amp;label=Security&amp;style=flat-square"></a> <a href="https://www.python.org/"><img alt="Python 3.10+" src="https://img.shields.io/badge/Python-3.10%2B-3776AB?logo=python&amp;logoColor=white&amp;style=flat-square"></a> <a href="LICENSE"><img alt="Apache 2.0" src="https://img.shields.io/badge/License-Apache_2.0-2563EB?style=flat-square"></a> <img alt="Windows, macOS and Linux" src="https://img.shields.io/badge/Platforms-Windows%20%7C%20macOS%20%7C%20Linux-64748B?style=flat-square"> </p> <p align="center"> <a href="#local-agent"><img alt="Agent" src="https://img.shields.io/badge/Agent-Self--Reflection-8B5CF6?style=flat-square"></a> <a href="#cli-reference"><img alt="CLI" src="https://img.shields.io/badge/CLI-Full_Reference-0EA5E9?style=flat-square"></a> <a href="#agent-mcp-skill"><img alt="MCP 2.0" src="https://img.shields.io/badge/MCP_2.0-15_Tools-111827?style=flat-square"></a> <a href="#agent-mcp-skill"><img alt="Agent Skill" src="https://img.shields.io/badge/Skill-Multi--Host-EC4899?style=flat-square"></a> <a href="#rest-api"><img alt="REST API" src="https://img.shields.io/badge/REST_API-OpenAPI_3.1-009688?style=flat-square"></a> <a href="#nuclei"><img alt="Nuclei approval" src="https://img.shields.io/badge/Nuclei-Approval_Gated-F97316?style=flat-square"></a> </p>

FofaMap 既能像传统 CLI 一样直接执行 FOFA 语句，也能让 Agent 把一句自然语言需求拆成多组查询，依据真实命中自我反思，最后输出带证据边界的资产简报。需要扫描时，它只先生成方案；目标、模板和严重级别必须经过一次性审批才能交给 Nuclei。

海报与截图不包含真实账号、密钥或资产信息。终端案例使用合成域名和文档保留网段。

📚 文档导航

| 新用户 | 日常使用 | AI 与平台接入 | 安全与维护 | |---|---|---|---| | 5 分钟上手 | FOFA 查询教程 | 本地 Agent | Nuclei 审批 | | Windows / macOS / Linux | 完整 CLI 参数 | MCP / Skill | 配置与密钥 | | 三种入口怎么选 | 分页、字段与导出 | REST / OpenAPI | 常见问题 |

快速链接：效果预览 · 项目结构 · 迁移指南 · 安全策略 · Agent 集成

---

✨ 为什么是 2.0.1

FofaMap 2.0 完成了从查询脚本到自然语言助手的跨越；2.0.1 把 Agent、Skill、MCP、CLI 和扫描审批收敛到同一套核心契约。

| 能力 | 2.0.1 的做法 | |---|---| | 经典查询 | -q / -hq / -cq / -ico / -bq 保持可用，不需要 AI 模型 | | 自然语言侦察 | 规划多组 FOFA 查询，按命中量和新增资产反思，最多两轮修正 | | 组织网站收集 | 输出 corroborated / observed / candidate 候选与证据，不把搜索命中直接写成归属结论 | | 高质量总结 | 固定覆盖结论、高置信资产、噪声、暴露面、证据缺口和下一步 | | Agent 接入 | 一条命令安装到 Cursor、Codex、Claude Code、LM Studio、OpenCode 等宿主 | | Nuclei 基线 | 默认组合 10 个低影响 Web/TLS 基线模板，覆盖常见配置与证书检查 | | 自定义扫描范围 | 模板 ID 和严重级别均可修改；输入 all 表示该维度全部执行 | | 审批边界 | 精确展示目标、模板和级别；一次性令牌绑定方案，-batch 也不能绕过 | | 数据输出 | XLSX / CSV / JSONL；连续分页、流式大结果导出、Markdown Agent 报告 |

工作流

flowchart LR
    A["自然语言或 FOFA 语句"] --> B["语法校验与查询规划"]
    B --> C["FOFA 检索"]
    C --> D{"结果质量足够？"}
    D -- "否" --> E["反思、收窄或补充策略"]
    E --> C
    D -- "是" --> F["证据分级与去重"]
    F --> G["资产表 + AI 简报"]
    G --> H{"用户要求扫描？"}
    H -- "否" --> I["结束"]
    H -- "是" --> J["展示精确扫描方案"]
    J --> K["一次性人工审批"]
    K --> L["Nuclei 执行与结果归档"]

Agent 负责规划和总结；查询、分页、字段映射、导出、审批与扫描均由确定性代码执行。鉴权失败、额度耗尽、权限不足、限速或网络错误会明确失败，不会被伪装成“0 结果”。

---

<a id="screenshots"></a>

🖥️ 效果预览

经典 FOFA 查询

普通查询不需要模型。终端展示适合人读的字段，导出文件仍保留完整字段。

Agent 证据化简报

开放式任务会组合域名、证书、页面品牌和内置规则；总结明确区分高置信资产、候选、噪声与尚未覆盖的证据。

all / all 扫描审批

模板 ID 和严重级别都支持 all。这意味着运行当前 Nuclei 可加载的全部模板和全部严重级别，程序会显示红色范围警告并再次要求审批。

截图中的 example-lab.com 为合成演示名称，192.0.2.0/24 为文档保留网段；它们不代表真实扫描结果。

---

<a id="quick-start"></a>

🚀 5 分钟上手

1. 安装

需要 Python 3.10+。macOS、Linux 和 Windows 均可运行。

git clone https://github.com/asaotomo/FofaMap.git
cd FofaMap
python3 -m venv .venv
. .venv/bin/activate                 # Windows: .venv\Scripts\activate
python -m pip install -e .

fofamap --version
fofamap --help

<a id="install-platforms"></a>

跨平台安装说明

<details> <summary><strong>macOS / Linux</strong></summary>

git clone https://github.com/asaotomo/FofaMap.git
cd FofaMap
python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e .

每次打开新终端后，在项目目录执行 source .venv/bin/activate。如果不想激活虚拟环境，也可以直接使用 .venv/bin/fofamap。

</details> <details> <summary><strong>Windows PowerShell</strong></summary>

git clone https://github.com/asaotomo/FofaMap.git
cd FofaMap
py -3 -m venv .venv
.\.venv\Scripts\Activate.ps1
python -m pip install --upgrade pip
python -m pip install -e .

如果 PowerShell 阻止激活脚本，可为当前用户设置签名策略，或直接运行 .\.venv\Scripts\fofamap.exe。Windows 命令中的 FOFA 双引号需要转义：

fofamap -q "app=\"ThinkPHP\" && country=\"CN\""

</details> <details> <summary><strong>更新、重装与卸载</strong></summary>

# Git 仓库更新
git pull
python -m pip install -e .

# 仅重装当前源码
python -m pip install --force-reinstall -e .

# 卸载 Python 包；不会主动删除 results/ 和本地配置
python -m pip uninstall fofamap

从 2.0 升级时不要直接复用旧版明文密钥配置，先阅读 MIGRATION.md 并轮换任何曾提交到 Git 的密钥。

</details>

安装 Nuclei（可选）

只有主动扫描需要 Nuclei；FOFA 查询、Agent、MCP 和 REST 的只读能力均可独立运行。

nuclei -version

如果找不到命令，请从 ProjectDiscovery Nuclei Releases 下载与操作系统匹配的版本，并放入 PATH 或项目根目录。更新 Nuclei 与模板：

fofamap -up

2. 初始化

fofamap init

向导会配置 FOFA API 密钥、可选的 AI 提供商，以及默认字段、分页、导出格式、存活检测和并发参数。密钥优先存入系统钥匙串；钥匙串不可用时，程序会明确询问是否写入本地配置文件。macOS/Linux 会将文件权限设为 0600；Windows 依赖当前用户目录 ACL，程序会明确提示优先使用系统钥匙串或环境变量。

也可以使用环境变量：

export FOFA_API_KEY='你的 FOFA API Key'
export OPENAI_API_KEY='仅本地 -ai 模式需要'

.env 只作为配置示例，程序不会自动加载。完整选项见 config/settings.example.yaml。

3. 第一次查询

# 无参数进入交互向导
fofamap

# 经典 FOFA 语法；不需要模型
fofamap -q 'domain="example.com"' -p 2 --size 100

# 自然语言 Agent；需要配置模型
fofamap -ai '收集 Example 公司的公开网站，区分高置信资产与待复核候选'

结果默认写入 results/{查询摘要}_{时间戳}/。

---

<a id="entrypoints"></a>

🧭 三种入口怎么选

| 使用方式 | FOFA 密钥 | 模型密钥 | 适合场景 | |---|:---:|:---:|---| | 交互向导 / 经典 CLI | ✅ | ❌ | 已知 FOFA 语法、主机画像、统计、图标和批量任务 | | 本地 -ai Agent | ✅ | ✅ | 用自然语言规划、反思、证据分级并生成报告 | | MCP / Skill | ✅ | ❌* | 让 Cursor、Codex、Claude Code、LM Studio 等宿主模型调用 |

* MCP 宿主本身提供对话模型，因此通常不需要再给 FofaMap 配第二套模型密钥。主动扫描还要求本机安装 Nuclei，并显式开启扫描能力。

交互向导

fofamap

方向键可选择标准查询、AI 智能侦察、主机画像、统计聚合、图标反查、批量查询、规则库、初始化或集成管理。

<a id="fofa-query-guide"></a>

🔎 FOFA 查询入门

查询语句与返回字段不是一回事

• 查询语句决定“找什么”，例如 domain="example.com" && status_code="200"；
• 返回字段决定“每条结果带回什么”，使用 -f host,ip,port,title；
• status_code 可以用于查询，但它是兼容返回字段，不保证所有账号和接口都能直接返回；
• 不确定字段权限时先运行 fofamap account 和 fofamap fields。

常用运算符

| 运算符 | 含义 | 示例 | |---|---|---| | = | 包含匹配 | title="login" | | == | 完全匹配，通常更快 | domain=="example.com" | | != | 排除匹配 | country!="US" | | && | 同时满足 | app="nginx" && country="CN" | | \|\| | 满足任一条件 | port="80" \|\| port="443" | | *= | 部分字段的模糊匹配 | 具体支持范围以 FOFA 当前接口为准 | | () | 分组并明确优先级 | (port="80" \|\| port="443") && country="CN" |

本地查看完整的官方语法目录，不消耗 FOFA 查询额度：

fofamap syntax
fofamap syntax --output-format json

常用查询字段

| 目标 | 示例 | 说明 | |---|---|---| | 根域名及子域 | domain="example.com" | 适合域名资产盘点 | | 精确根域名 | domain=="example.com" | 避免包含式扩大 | | IP / C 段 | ip="192.0.2.10"、ip="192.0.2.0/24" | 示例使用文档保留网段 | | 端口 | port="443" | 与产品、地域等组合使用 | | 标题 / 正文 | title="管理后台"、body="powered by" | 容易产生泛命中，应复核内容 | | 服务与产品 | protocol="https"、product="NGINX" | 产品字段取决于账号权限 | | FOFA 应用规则 | app="ThinkPHP" | 产品名应优先来自规则库 | | 国家 / 地区 | country="CN"、region="Zhejiang" | 过度限制可能导致 0 结果 | | 组织 / ASN | org="Example Org"、asn="13649" | 组织名命中不等于资产归属 | | ICP | icp="示例备案号" | 结合官网或权威来源复核 | | 证书 | cert.subject.org="Example Org" | 证书关联只是归属证据之一 | | 图标 | icon_hash="123456789" | 建议使用 -ico 自动计算 |

产品、OA、VPN、中间件、数据库、摄像头、CMS 或运维面板，请先查询内置规则库，不要猜测 app= 名称。

fofamap rules --rule ThinkPHP
fofamap rules -k OA
fofamap --rule ThinkPHP -p 2
# 组合条件时，把规则库返回值明确写入 -q
fofamap -q 'app="ThinkPHP" && country="CN"'

只传 --rule 时，FofaMap 会把规则名称映射为查询语句。组合地域、端口等条件时，请先查看规则库返回值，再明确写入 -q。完整规则以 FOFA 官方规则库为准，FofaMap 内置的是高价值、可审计子集。

Shell 引号速查

# macOS / Linux：外层单引号最省心
fofamap -q 'app="nginx" && country="CN"'

# Windows PowerShell：外层双引号，内部双引号转义
fofamap -q "app=\"nginx\" && country=\"CN\""

经典 CLI

# 标准检索
fofamap -q 'app="nginx" && country="CN"' -p 3 --size 100

# 主机聚合画像 / 统计聚合
fofamap -hq '1.1.1.1'
fofamap -cq 'app="nginx"' --size 10

# 网站图标哈希反查
fofamap -ico 'https://example.com'
fofamap --icon-file ./favicon.ico

# 内置规则库与批量查询
fofamap rules --rule ThinkPHP
fofamap -q 'country="CN"' --rule ThinkPHP
fofamap -bq queries.txt --export-format xlsx

筛选、存活检测与导出：

fofamap -q 'domain="example.com"' \
  -i 200,403 \
  -k login,admin \
  --check-alive \
  --dedupe-by host,ip,port \
  --export-format jsonl \
  -o results/example.jsonl

| 任务 | 兼容参数 | |---|---| | AI / 标准查询 | -ai / --ai-query、-q / --query | | 主机 / 统计 | -hq / --host-query、-cq / --count-query | | 图标 / 批量 | -ico / --icon-query、-bq / --bat-query | | 状态码 / 关键词过滤 | -i / --include、-k / --key-word | | 页数 / 字段 / 输出 | -p、-f、-o |

2.0 命令逐项对照见 V2 CLI 兼容清单。

<a id="cli-reference"></a>

🛠️ 完整 CLI 参数手册

查看当前安装版本的权威帮助：

fofamap --help
fofamap --version

功能命令

| 命令 | 是否用 FOFA 额度 | 用途 | |---|:---:|---| | fofamap | 视所选任务 | 打开中文交互向导 | | fofamap account | ✅ | 查看账号、会员等级、接口权限与额度 | | fofamap fields | ❌ | 查看返回字段、会员字段等级与聚合能力 | | fofamap syntax | ❌ | 查看内置的 FOFA 官方语法目录 | | fofamap rules | ❌ | 列出或搜索内置 app= 规则子集 | | fofamap init | ❌ | 打开安全初始化向导 | | fofamap integrate | ❌ | 安装、预览或卸载 MCP / Skill 集成 | | fofamap serve | ❌* | 启动 REST 服务，默认 127.0.0.1:8000 | | fofamap -V, --version | ❌ | 输出版本并退出 |

* 启动服务本身不消耗额度；调用查询接口时会消耗。

查询与分析参数

| 参数 | 值 | 作用 | 是否需要模型 | |---|---|---|:---:| | -ai, --ai-query | 自然语言 | Agent 规划、检索、反思、总结 | ✅ | | -q, --query | FOFA 语句 | 标准资产检索 | ❌ | | -hq, --host-query | IP 或域名 | Host 聚合画像 | ❌ | | --host-detail / --no-host-detail | 开关 | Host 是否返回端口详情；默认开启 | ❌ | | -cq, --count-query | FOFA 语句 | 统计聚合查询 | ❌ | | -ico, --icon-query | URL | 下载公网 favicon、计算 Hash 并反查 | ❌ | | --icon-file | 本地文件 | 对不超过 4 MiB 的本地图标计算 Hash | ❌ | | -bq, --bat-query | TXT 路径 | 批量读取 IP、域名或 FOFA 语句 | ❌ | | --rule | 规则名称 | 将内置规则映射为 app= 查询 | ❌ |

如果 -q / -ai / -hq / -cq / -ico / -bq 只写参数不写值，交互终端会提示输入；自动化脚本应始终显式传值。

范围、字段与过滤参数

| 参数 | 默认值 / 范围 | 说明 | |---|---|---| | -f, --query-fields | 配置文件字段 | 逗号分隔的返回字段，例如 host,ip,port,title | | --smart-fields / --no-smart-fields | AI 模式默认开启 | 按账号等级和任务选择字段；与 -f 同时出现时智能字段优先 | | -p, --pages | 配置 end_page；1–10000 | 本次最多查询页数 | | --size | 查询默认 100；1–10000 | 查询时为每页条数；统计时为每个维度的 Top N | | --max-records | 配置默认 10000；1–1000000 | 本次最多接收记录数 | | --batch-group-size | 100；1–100 | 批量 IP / 域名每组组合成一条 OR 查询；1 关闭组合 | | --full / --no-full | 跟随配置 | 是否查询历史数据；可能影响额度与权限 | | --dedupe-by | 不自动指定 | 逗号分隔的去重键，例如 host,ip,port | | -i, --include | 无 | 本地仅保留指定状态码，例如 200,301,403 | | -k, --key-word | 无 | 本地任一关键词匹配，例如 登录,后台 | | `--ch