🗺️ FofaMap 2.0.1 - 一款证据驱动的 FOFA 资产测绘智能体

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

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

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

📚 文档导航

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

✨ 为什么是 2.0.1

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

工作流

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 结果”。

🖥️ 效果预览

经典 FOFA 查询

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

Agent 证据化简报

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

all / all 扫描审批

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

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

🚀 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

跨平台安装说明

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 .

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 .

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

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

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

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

安装 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/{查询摘要}_{时间戳}/。

🧭 三种入口怎么选

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

交互向导

fofamap

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

🔎 FOFA 查询入门

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

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

常用运算符

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

fofamap syntax
fofamap syntax --output-format json

常用查询字段

产品、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

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

🛠️ 完整 CLI 参数手册

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

fofamap --help
fofamap --version

功能命令

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

查询与分析参数

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

范围、字段与过滤参数

过滤顺序为：取得 FOFA 结果 → 必要时存活检测 → 状态码过滤 → 关键词过滤 → 展示与导出。若 FOFA 已返回可用状态码，不会为了 -i 无条件访问每个目标。

展示与导出参数

人类阅读使用 table；Shell、CI 或其他 Agent 调用使用 json/jsonl：

# 不保存文件，只把稳定 JSON 输出给下游程序
fofamap -q 'domain="example.com"' \
  -f host,ip,port,title \
  --output-format json \
  --no-save

# 大结果优先 JSONL 或 CSV
fofamap -q 'app="nginx"' \
  -p 10 --max-records 1000 \
  --export-format jsonl \
  -o results/nginx.jsonl

扫描、更新与兼容参数

批量文件格式

queries.txt 每行可写 IP、域名或完整 FOFA 语句；空行会忽略：

192.0.2.10
example.com
app="nginx" && country="CN"

• IP 会规范化为 ip="…"；
• 域名会规范化为 domain="…"；
• 已有 FOFA 语句保持原样；
• 默认把最多 100 个纯 IP / 域名组成有界 OR 查询，降低请求次数；
• --batch-group-size 1 可让每行独立查询。

退出码

🤖 Agent / MCP / Skill

本地 Agent

fofamap -ai '查找授权范围内暴露的 ThinkPHP，按证据等级总结并建议下一步'

Agent 会依次完成：

1. 识别资产检索、单主机、统计或图标任务；
2. 对产品名优先查询内置规则库，避免凭空编写指纹；
3. 生成并校验互补 FOFA 语句；
4. 基于命中数、新增量和样本质量最多反思两轮；
5. 去重并标记证据等级；
6. 输出资产表、Markdown 报告和“尚未执行”的扫描建议。

推荐把对象、范围、期望结果和是否允许扫描写清楚：

# 网站收集：强调证据和候选边界
fofamap -ai '收集 Example 公司的公开网站，给出每个候选的证据等级，不要把泛名称命中写成已确认归属'

# 暴露面分析：限制地域与结果预算
fofamap -ai '分析授权范围内中国地区的 Example 产品暴露面，按协议、端口和产品版本总结，最多返回 500 条'

# 明确扫描意图：仍会进入人工审批
fofamap -ai '收集授权域名 example.com 的网站，并对高置信目标建议 Web 基线扫描'

组织网站任务中的候选状态：

AI 总结固定关注：结论、高置信资产、噪声与误报、暴露面、证据边界、覆盖缺口和下一步。模型不会获得任意 Shell 权限，也不能自行执行 Nuclei。

AI 提供商支持 OpenAI、DeepSeek、Anthropic、Ollama、LM Studio 及兼容接口。规划、语法修复、反思和总结可分别路由；跨提供商回退默认关闭。

Skill 如何约束 Agent

Skill 不只是提示词示例，它规定了规则库优先、语法校验、按需翻页、大结果导出、证据边界和扫描审批顺序。

一键接入 AI 宿主

fofamap integrate --list
fofamap integrate --agent cursor
fofamap integrate --agent codex
fofamap integrate --agent claude
fofamap integrate --agent lmstudio
fofamap integrate --agent all --dry-run

当前集成覆盖 Cursor、Codex、Claude Code、OpenCode、DeepSeek Harness、LM Studio、OpenClaw、Hermes 和 Grok Build。安装器会自动写入当前 Python 与 mcp_server.py 的绝对路径，不依赖 GUI 应用的 PATH；同时会合并已有配置、首次修改前创建备份，并且不会读取或复制密钥。

如果曾用早期 2.0.1 安装器生成过 "command": "fofamap-mcp"，重新运行相同的集成命令即可原地升级。卸载只移除 FofaMap 管理的条目：

fofamap integrate --agent cursor --uninstall

集成参数：

项目级安装示例：

fofamap integrate \
  --agent claude \
  --scope project \
  --project-root /path/to/project

只有在宿主必须使用另一套已安装环境时，才需要覆盖默认命令：

fofamap integrate --agent cursor --server-command /absolute/path/to/fofamap-mcp

MCP 工具分层

推荐调用顺序：规则库 → 语法校验 → 单页查询 → 按 next_cursor 连续翻页 → 大结果导出。开放式中文需求可以直接调用 fofa_agent_run。

# 手工启动 stdio MCP
fofamap-mcp

# 本机 Streamable HTTP
fofamap-mcp --transport streamable-http --host 127.0.0.1 --port 8001

更详细的宿主路径、配置位置与故障排查见 Agent 集成文档；能力对齐结论见 Agent / Skill / CLI 审计。

☢️ Nuclei：扫描前必须审批

只对已获得明确授权的目标执行主动扫描。

Nuclei 是可选依赖。先确认它在 PATH 中：

nuclei -version

命令行会始终显示审批；MCP / REST 还需要显式打开扫描开关：

export FOFAMAP_ENABLE_SCANNING=true
export FOFAMAP_SCAN_APPROVAL_SECRET='至少24个字符的高熵随机值'

默认不是单模板

没有指定 --nuclei-id 时，2.0.1 使用有界的 web-baseline：

http-missing-security-headers  cors-misconfig  options-method
tech-detect                    waf-detect      weak-cipher-suites
deprecated-tls                 expired-ssl     self-signed-ssl
mismatched-ssl-certificate

这套基线覆盖常见 Web 安全头、CORS、OPTIONS、技术/WAF 识别和 TLS 配置检查。它是低影响基线，不等于全模板漏洞扫描。

自定义模板与严重级别

# 默认 10 模板基线
fofamap -q 'domain="example.com"' -n

# 指定模板 ID；可重复传入
fofamap -q 'domain="example.com"' -n \
  --nuclei-id cors-misconfig \
  --nuclei-id tech-detect \
  --severity info,low,medium

# 全部已安装模板 + 全部严重级别
fofamap -q 'domain="example.com"' -n \
  --nuclei-id all \
  --severity all

每次执行前，终端都会展示目标、模板范围、严重级别和 AI 判断。用户可执行、修改范围、仅生成报告或取消。确认令牌绑定这次方案和有效期，用后即废；-batch 不会跳过审批。

MCP / REST 的调用顺序是 nuclei_plan → 人工确认 → nuclei_execute。基线外的精确模板 ID 需要管理员通过 FOFAMAP_NUCLEI_ID_ALLOWLIST 加入允许列表。

📄 分页、字段与输出

分页预算

连续分页使用 FOFA cursor；明确设置 --dedupe-by 才按指定键去重。字段数量会依据账号能力和任务自动选择，也可以使用 -f 手动指定。

账号能力与智能字段

运行 fofamap account 查看当前账号，运行 fofamap fields 查看程序内置的完整字段和能力目录。当前 2.0.1 目录如下；FOFA 权限发生变化时，以账号接口的实时结果为准。

--smart-fields 会根据账号字段等级和任务类型选择字段数量；需要固定数据契约的脚本建议使用 --no-smart-fields -f ...。

结果目录

results/
└── domain_example_com_20260816_120000/
    ├── domain_example_com_20260816_120000.xlsx
    ├── report_20260816_120000.md
    ├── targets.txt
    └── nuclei/
        ├── targets.txt
        └── nuclei.jsonl

XLSX 适合人工查看，CSV / JSONL 适合大结果与后续管道。终端隐藏的字段仍会保留在导出文件中。

🧱 项目结构

FofaMap/
├── fofamap.py                    # CLI、向导、初始化与集成入口
├── mcp_server.py                 # MCP 2.0 stdio / Streamable HTTP 服务
├── pyproject.toml                # 包信息、依赖与 fofamap-* 命令
├── config/
│   ├── __init__.py               # 配置加载、Keyring 与兼容迁移
│   └── settings.example.yaml     # 无密钥配置模板
├── core/
│   ├── agent.py                  # 可恢复的规划、查询、反思和总结工作流
│   ├── client.py                 # 类型化 FOFA API 客户端
│   ├── fields.py                 # 字段等级与账号能力
│   ├── integrations.py           # MCP / Skill 跨宿主安装器
│   ├── models.py                 # CLI、REST、MCP 共用数据契约
│   ├── report.py                 # Markdown 报告
│   ├── rules.py / syntax.py      # 规则库和官方语法目录
│   ├── scans.py                  # 扫描方案、允许列表与一次性审批
│   └── scanner.py                # Nuclei 执行和结果解析
├── providers/                    # 模型服务适配器
├── service/                      # FastAPI、鉴权、任务与产物存储
├── utils/                        # Rich UI、图标 Hash、存活检测与日志
├── agent-kit/
│   ├── skills/fofamap/           # 通用 Agent Skill
│   └── plugins/fofamap/          # 跨宿主插件包
├── docs/                         # 集成、兼容和能力审计
├── tests/                        # CLI、Agent、MCP、REST、扫描与配置测试
└── results/                      # 默认任务产物目录

CLI、REST 和 MCP 共享数据契约、FOFA 客户端、字段能力、规则库和扫描审批逻辑，避免三套入口出现参数或安全语义漂移。

🌐 REST / OpenAPI

export FOFAMAP_SERVICE_TOKEN='请替换为足够长的随机值'
fofamap-api
# 等价入口：fofamap serve

默认地址为 http://127.0.0.1:8000，Swagger UI 为 http://127.0.0.1:8000/docs，OpenAPI JSON 为 /openapi.json。

REST 接口目录

REST 调用示例

curl -sS http://127.0.0.1:8000/v1/search \
  -H 'Authorization: Bearer 请替换为服务Token' \
  -H 'Content-Type: application/json' \
  -d '{
    "query": "domain=\"example.com\"",
    "fields": ["host", "ip", "port", "title"],
    "size": 100,
    "max_pages": 1,
    "max_records": 100
  }'

响应中的 next_cursor 是不透明值；继续翻页时必须原样传入 /v1/search/next，不要解析、修改或自行生成。

只有绑定回环地址时才允许无令牌运行；远程服务必须配置静态 Token 或 JWT。环境变量示例见 .env.example。

🔐 配置与环境变量手册

最小配置：

fofa:
  base_url: "https://fofa.info"

search:
  fields: "host,protocol,ip,port,title,domain,country"
  size: 100
  full: false
  end_page: 2
  max_pages: 10
  max_records: 10000

system:
  export_format: xlsx
  output_dir: results
  requests_per_second: 2.0
  allow_private_network: true

完整模板见 config/settings.example.yaml。

配置文件查找顺序

1. FOFAMAP_CONFIG 指定的文件；
2. 当前工作目录的 config/settings.yaml；
3. 操作系统用户配置目录；
4. 旧源码布局的只读迁移回退。

YAML 配置字段

模型提供商与路由

providers:
  openai:
    protocol: openai_responses
    base_url: "https://api.openai.com/v1"
    model: "你的模型 ID"
    api_key_env: OPENAI_API_KEY
    max_output_tokens: 32768
    timeout: 120

routing:
  default: openai
  planner: openai
  query_repair: openai
  reflector: openai
  summarizer: openai
  allow_cross_provider_fallback: false
  fallbacks: []

支持的协议适配器：

Ollama、LM Studio 等本地服务可以把 api_key_env 留空。模型 ID 会持续变化，README 不锁定“最新模型”，请填当前服务真实存在的 ID。

常用环境变量

FOFA 密钥读取优先级为：FOFA_API_KEY → FOFA_KEY → 系统钥匙串 → 明确确认过的本地 YAML。模型密钥读取优先级为环境变量 → 系统钥匙串。不要把真实值写进 README、截图、Issue、日志或提交记录。

安全边界

关键边界：

• FOFA 查询为只读，TLS 默认校验；
• 密钥优先来自环境变量或系统钥匙串，不应提交到 Git；
• 云元数据地址始终阻断；将 FOFAMAP_ALLOW_PRIVATE_NETWORK=false 可进一步只允许公网目标；
• 远程 MCP / REST 必须鉴权，无鉴权只允许回环地址；
• 主动扫描默认关闭，并受允许列表、目标上限和一次性审批令牌约束；
• FOFA 指纹、证书关联和页面品牌只是证据，不自动等同于法律或组织归属。

升级自 2.0 时请先阅读 MIGRATION.md。若密钥曾写入并提交过 config/settings.yaml，请立即轮换。完整威胁模型与部署要求见 SECURITY.md。

❓ 常见问题与排错

# macOS / Linux
source .venv/bin/activate
.venv/bin/fofamap --version

# Windows PowerShell
.\.venv\Scripts\Activate.ps1
.\.venv\Scripts\fofamap.exe --version

fofamap account
fofamap fields

fofamap integrate --list
fofamap integrate --agent cursor --dry-run
fofamap integrate --agent cursor
fofamap-mcp --help

nuclei -version
fofamap -up

🧪 开发与验证

python -m pip install -e '.[test]'
pytest -q
ruff check config core providers service utils fofamap.py mcp_server.py tests

CI 使用模拟响应，不需要真实 FOFA 或模型密钥。明确配置真实密钥后，可运行只读、少量消耗且不扫描的在线冒烟测试：

FOFAMAP_RUN_LIVE_TESTS=true pytest -q -m live

进一步阅读：

• Agent / Skill / CLI 对齐审计
• Agent 宿主集成指南
• 2.0 CLI 兼容清单
• 上游能力对照
• 安全策略

⚖️ 免责声明

本项目仅用于合法授权的资产管理、安全建设、内部演练和授权测试。使用前请确认符合所在地法律法规，并已取得目标所有者的明确授权。禁止将本项目用于未授权访问、破坏、窃取或其他非法活动。

FOFA 命中表示公开暴露信息；它不等于归属已确认，也不等于存在漏洞。Nuclei 结果必须由具备授权的人员复核。因使用者违反法律、授权范围或本说明造成的后果，由使用者自行承担。

🤝 社区

如果 FofaMap 对你有帮助，欢迎提交 Issue、Pull Request 或 Star。

FofaMap-V2.0.1由Hx0战队开发维护

【打赏支持❤️】代码传情跨山海，点滴支持皆温暖✨

虽然代码完全开源，但每杯咖啡都能让我们走得更远 ☕️

特别鸣谢～渊龙Sec团队

特别鸣谢～FOFA官方

FoFaMap 已加入 FOFA 共创者计划，感谢 FOFA 提供的账号支持。

【战队公众号】扫描关注战队公众号，获取最新动态

【战队知识星球】福利大放送，限时优惠-仅限前100名

Star History