FofaMap 2.0.1: a FOFA asset-mapping agent with approval-gated Nuclei scanning

The gap FofaMap fills between a FOFA query and an asset brief

FOFA is a search engine for internet-facing assets, and its query language is precise but unforgiving. A practitioner who wants to know what an organisation exposes has to write several queries, read the raw hits, decide which ones actually belong to the target, and then remember that a search hit is not proof of ownership. FofaMap is built around that last problem. The README describes it as an evidence-driven agent: an open-ended task is broken into multiple FOFA queries, the results are graded, and the report separates corroborated assets from observed ones and from mere candidates.

The intended user is a security engineer or red teamer who already has FOFA API access. The project does not replace FOFA and does not crawl the internet itself. It is a client with an opinion about how query results should be interpreted. The classic query path needs no model at all: -q, -hq, -cq, -ico and -bq remain available, and the README states plainly that ordinary queries do not require a model. The AI layer is additive, not a prerequisite.

How the agent plans, reflects and hands off to deterministic code

The architecture splits responsibility in a way worth noting. The README's workflow diagram shows a loop: natural language or a FOFA statement goes into syntax validation and query planning, the queries hit FOFA, and a quality check decides whether the results are good enough. If not, the agent reflects and either narrows or supplements the strategy, for a maximum of two correction rounds. Once results pass, they are graded, deduplicated, and written to an asset table plus an AI brief.

The important constraint is stated in the README: the agent handles planning and summarisation, while querying, pagination, field mapping, export, approval and scanning are executed by deterministic code. That division matters for auditability. It also means failure is not disguised. Authentication failures, exhausted quota, insufficient permissions, rate limiting and network errors are reported as explicit failures rather than being rendered as a zero-result answer, which is the failure mode that makes a reconnaissance tool dangerous to trust.

The output surface is broad. Results export to XLSX, CSV or JSONL, with continuous pagination and streaming export for large result sets, and the agent produces a Markdown report. The README lists the fixed coverage of a high-quality summary: conclusion, high-confidence assets, noise, exposure surface, evidence gaps and next steps. Exposing the evidence gaps is the part most tools omit.

Installing FofaMap and running a first query

FofaMap requires Python 3.10 or newer and runs on Windows, macOS and Linux. The README's quick-start clones the repository, creates a virtual environment and installs the package in editable mode. After the install, the fofamap entry point should be on the path inside the activated environment; running the version and help commands is the check the README suggests.

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

On Windows the activation line differs. The README gives a PowerShell sequence using py -3 -m venv and .\.venv\Scripts\Activate.ps1, and notes that if the execution policy blocks the script you can either set a signature policy for the current user or call .\.venv\Scripts\fofamap.exe directly. It also warns that FOFA double quotes need escaping in Windows commands.

Configuration comes next. The init wizard sets the FOFA API key, an optional AI provider, and defaults for fields, pagination, export format, liveness checks and concurrency. Credentials are stored in the system keychain first; when the keychain is unavailable, the program asks explicitly before writing to a local config file, and sets file permissions to 0600 on macOS and Linux. Environment variables are an alternative:

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

One detail the README calls out is that .env is a sample file and is not loaded automatically. A first real query can be a classic FOFA statement, which needs no model, or a bare fofamap invocation, which opens the interactive wizard.

fofamap init
fofamap -q 'app="ThinkPHP" && country="CN"'

Nuclei is optional and only needed for active scanning. The README suggests checking with nuclei -version and, if the binary is missing, downloading the release for your operating system and placing it on PATH or in the project root. The fofamap -up command updates Nuclei and its templates.

The approval gate on Nuclei, and why -batch does not remove it

Scanning is opt-in and off by default. FOFAMAP_ENABLE_SCANNING is false in the sample environment file, and the README describes the scan path as two stages: the tool first produces a plan showing the exact targets, template IDs and severity levels, and only after a one-time human approval does it hand that plan to Nuclei. The README states that the one-time token is bound to the plan and that -batch cannot bypass it.

The default scan profile is deliberately narrow. The README describes a baseline of ten low-impact web and TLS templates covering common configuration and certificate checks. Both the template IDs and the severity levels can be changed, and entering all in either dimension means every template or every severity currently loadable by Nuclei. The README notes that this triggers a red scope warning and a second approval prompt, and the screenshot section illustrates the all / all case on a synthetic domain and the documentation-reserved 192.0.2.0/24 range.

Two environment variables exist to constrain this further: FOFAMAP_NUCLEI_TEMPLATE_ALLOWLIST and FOFAMAP_NUCLEI_ID_ALLOWLIST. There is also FOFAMAP_ALLOW_PRIVATE_NETWORK, which defaults to false. The README does not document a rollback path for a scan that has already started, and it does not document a way to revoke an approval token after issuance beyond the single-use property.

Where FofaMap is the wrong tool

The clearest boundary is the dependency on FOFA. FofaMap is a client for the FOFA API. Without a working key and remaining quota, the query, agent, MCP and REST paths have nothing to search, and the README explicitly lists quota exhaustion as one of the errors that surfaces as a failure rather than as an empty result. If your organisation does not use FOFA, this project is not a general-purpose asset discovery tool.

A second boundary is unattended operation. The approval design is a feature for teams that want a human in the loop before any active traffic reaches a target, and a friction point for anyone who wanted scheduled scanning. The README is explicit that -batch does not bypass the one-time token, so there is no documented way to run the scan stage fully automatically.

A third is scope. The agent's query planning is bounded at two reflection rounds. That is a deliberate cost control, but it means an open-ended task that needs many rounds of narrowing will stop early and report what it has, including the evidence gaps. Reading the gap section is not optional if you use the agent path.

FofaMap compared with FOFAX and Gofofa

The most direct alternatives people search for alongside FofaMap are FOFAX and Gofofa, both of which are also FOFA clients. The difference in approach is where the intelligence sits. A conventional FOFA client executes the statement you give it and returns the results, leaving interpretation to you. FofaMap inserts a planning layer that decomposes a natural-language request into several queries, evaluates whether the returned hits are good enough, and revises up to twice before producing a graded brief.

That layer costs a model provider and adds latency and token spend, which is why the classic -q path exists alongside it. If your workflow is a fixed set of FOFA statements run on a schedule, a plain client is simpler and cheaper, and the agent adds nothing. If your workflow starts with a vague question such as which assets belong to a given organisation, the grading and gap reporting are the reason to choose this project over a thinner client. The comparison is not about which tool can query FOFA; all of them can. It is about how much interpretation you want the tool to do before a human reads the output.

Licence, maintenance and the upgrade path from 2.0

FofaMap is licensed under Apache-2.0, with the licence file at the repository root and declared in pyproject.toml as a file reference. Apache-2.0 permits commercial use and modification and includes an explicit patent grant; it also requires that attribution and licence notices be preserved. If you redistribute a modified FofaMap, or embed it in a service, those obligations travel with the code. This is a description of the licence terms, not legal advice, and the terms that apply to your deployment are a question for your own counsel.

The repository is not archived, and the most recent push recorded is 2026-08-16, roughly a month before this writing. The v2.0.1 release is dated 2026-08-15, and v1.1.3 dates to 2023, so the project moved through a long quiet period before the 2.0 line. The version is declared as 2.0.1 in pyproject.toml.

Upgrade cost is concentrated in credentials. The README's update path is git pull followed by python -m pip install -e ., with a force-reinstall option for the current source. It warns that upgrading from 2.0 should not reuse the old plaintext key configuration, points to MIGRATION.md, and says to rotate any key that was ever committed to Git. The uninstall command removes the Python package but does not delete results/ or local configuration. Dependencies are pinned to ranges in requirements.txt, with requirements.lock recommended for reproducible CI builds, and the package pins mcp>=2,<3, fastapi>=0.116,<1 and SQLAlchemy>=2.0,<3 among others.

Editorial conclusion

Adopt FofaMap if you already hold FOFA API quota and want the query planning, evidence grading and scan approval to live in one auditable pipeline, with MCP or REST as the integration surface. Do not adopt it if you have no FOFA subscription, since the tool is a client for that API and not a scanner of its own, and do not adopt it if you need unattended scanning, because the one-time approval token binds to a single plan and the README states that -batch cannot bypass it. Before installing, verify three things in the repository: that Python 3.10 or newer is available, that your FOFA key works against the API you intend to query, and that the Nuclei allowlist variables in .env.example match the templates your team is permitted to run.

Frequently asked questions

Official sources

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