FofaMap 2.0.1: a FOFA query agent that refuses to invent results

The gap between a FOFA query and a defensible asset list

FOFA returns hits. An asset inventory needs a reason to believe each hit belongs to the organisation you are mapping. FofaMap 2.0.1 is built around that distinction. Its stated purpose is to take a natural-language reconnaissance request, split it into multiple FOFA queries, reflect on the real hit counts, and produce an asset brief that carries an explicit evidence boundary rather than a flat list of IPs. The README describes the output of organisation website collection as three grades: corroborated, observed and candidate. The project is explicit that search hits are not written up as attribution conclusions. That is the design position, and it is a more conservative one than most tools in this category take. The audience is engineers doing attack surface management, OSINT collection or red team preparation who already have FOFA API access and who need the query layer to be reproducible. It is not aimed at someone who wants a scanner with a chat box bolted on.

Where the model stops and the deterministic code starts

The architecture splits responsibilities along a line the README states directly: the agent plans and summarises, while querying, pagination, field mapping, export, approval and scanning are all executed by deterministic code. The workflow runs from a natural-language request or a raw FOFA statement into syntax validation and query planning, then to FOFA retrieval. At that point a quality check decides whether the results are good enough. If not, the agent reflects, narrows or adds a strategy and queries again, capped at two correction rounds. Once the results pass, they are graded by evidence and deduplicated, producing an asset table plus an AI brief. Scanning is a separate branch that only opens if the user asks for it. That cap of two rounds matters: it bounds both cost and the chance of the agent wandering. The second design decision is error handling. Authentication failure, exhausted quota, insufficient permission, rate limiting and network errors are documented as explicit failures. They are not allowed to masquerade as a zero-result query. For anyone who has debugged a silent empty result set at 2am, that is the most useful sentence in the README.

Installing it and the exact commands involved

Python 3.10 or newer is required, and the project runs on macOS, Linux and Windows. The README gives this sequence: clone the repository, create a virtual environment, activate it, then run python -m pip install -e . from the project root. Verification is fofamap --version followed by fofamap --help. On Windows PowerShell the activation step is .\.venv\Scripts\Activate.ps1, and the README notes that FOFA double quotes need escaping in that shell, giving fofamap -q "app=\"ThinkPHP\" && country=\"CN\"" as the pattern. Initialisation is fofamap init, a wizard that configures the FOFA API key, an optional AI provider, default fields, pagination, export format, liveness checks and concurrency. Keys go to the system keychain first. When no keychain is available the program asks explicitly before writing to a local config file, sets permissions to 0600 on macOS and Linux, and on Windows falls back to the current user directory ACL while telling you to prefer the keychain or environment variables. FOFA_API_KEY and OPENAI_API_KEY are the environment variable names, and the README is clear that .env is a sample only and is not auto-loaded. Nuclei is optional; fofamap -up updates it and its templates.

The approval token is the part worth copying

Before any scan, FofaMap prints the exact targets, template IDs and severity levels it intends to use, then requires a one-time approval. The token is bound to that specific plan, and the README states that the -batch flag cannot bypass it. Both the template list and the severity list accept the value all, which means every template Nuclei can currently load across every severity. The documentation says the program responds by showing a red range warning and asking for approval a second time. The default scan profile is narrower: ten low-impact web and TLS baseline templates covering common configuration and certificate checks. This is a credible middle position between tools that scan immediately and tools that only report. It also means the human is the rate limiter. If your workflow assumes unattended overnight scanning, this design is working against you, and the README does not describe a supported way to remove the gate.

Output formats, and the cost of staying current

Results export to XLSX, CSV and JSONL, with continuous pagination and streaming export for large result sets, plus a Markdown report from the agent. The terminal view shows human-readable fields while the export keeps the full field set, which is the right split. On maintenance: the release history shows v1.1.3 in September 2023, v2.0.0 in January 2026 and v2.0.1 in August 2026. That is a long quiet period followed by a rewrite, so anyone on 1.x should read MIGRATION.md rather than assume compatibility. The migration note is specific and worth repeating: do not reuse an old plaintext key configuration, and rotate any key that was ever committed to Git. Upgrading from a Git checkout is git pull followed by python -m pip install -e . again. The licence is Apache-2.0, which permits commercial and closed-source use and requires preserving notices; the repository also carries SECURITY.md and docs/AGENT_INTEGRATIONS.md. Nothing here is legal advice, and the FOFA API terms and Nuclei template licences are separate obligations from the FofaMap licence itself.

Two failure modes and one wrong-tool case

The first failure mode is upstream and unavoidable: FOFA quota. The project documents quota exhaustion as a hard error, which is honest, but it does not remove the dependency. Every query the agent plans consumes quota, and the reflection loop can plan several queries per request, so a vague natural-language prompt is more expensive than a precise FOFA statement. The second is the reflection cap. Two correction rounds is a deliberate ceiling, and a task that genuinely needs five rounds of query refinement will return a partial brief with the gaps listed rather than a complete one. The README frames that as a feature, since the summary is supposed to name uncovered evidence, but you should read the output as a scoped result, not a final answer. The wrong-tool case is straightforward: if you want a single FOFA query with a clean table, the classic flags (-q, -hq, -cq, -ico, -bq) run without any AI model at all, and installing an agent stack for that is wasted surface area. The same applies if you have no FOFA API key, since nothing in the read-only path substitutes for it.

How it differs from running FOFA and Nuclei by hand

The obvious alternative is using the FOFA web interface or API directly, exporting the results, and running Nuclei yourself. The difference is not coverage; the underlying data comes from the same FOFA index. The difference is the layer FofaMap inserts between the two. Hand-rolled workflows leave query planning, pagination, field mapping, deduplication and evidence grading to whoever is at the keyboard, and the grading step is the one people skip. FofaMap fixes the summary structure to cover conclusion, high-confidence assets, noise, exposure surface, evidence gaps and next steps, so two analysts running the same request get comparable briefs. The trade is flexibility. A hand-built pipeline lets you write arbitrary post-processing, chain other data sources, or scan without an approval prompt. FofaMap gives you a defined contract across CLI, MCP, Skill and REST entry points, and the README notes the MCP 2.0 surface exposes fifteen tools and that installation into hosts such as Cursor, Codex, Claude Code, LM Studio and OpenCode is a single command. If your team already has a mature asset pipeline, FofaMap is more likely to be a component than a replacement.

Editorial conclusion

Adopt FofaMap if you already pay for FOFA API access and want the query planning, field mapping, pagination and export handled for you, with scanning kept behind a token that a batch run cannot bypass. Skip it if you only need a single FOFA query, if you have no FOFA key, or if you want an autonomous scanner that acts without a human in the loop. Before trusting it on real targets, verify three things yourself: that your key is in the system keychain rather than a config file, that the default ten low-impact Nuclei templates are the ones you actually want, and that an authentication failure surfaces as an error rather than as an empty result set.

Official sources

1. asaotomo/FofaMap on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases