🗺️ FofaMap 2.0.2 · From asset discovery to evidence-backed reports

中文 · English

An evidence-driven AI tool for asset discovery and security analysis.

Developed by Hx0 Studio, FofaMap brings FOFA asset discovery, AI reflection, user-approved Nuclei validation and interactive reporting into one traceable workflow, connecting each assessment with its queries, reasoning and validation results.

Start with the keyboard-driven wizard, keep using the classic CLI, or connect AI assistants and automation through MCP / Skill / REST API. Ordinary searches need only a FOFA API key, with no model setup required; active scans require user approval.

What makes FofaMap useful?

For your first session, follow steps 1 → 2 → 3 below. Explore options, models, automation and service deployment later.

1. Install: choose your platform

Download the FofaMap 2.0.2 user source package, extract the entire ZIP, and open the folder containing install.bat, install.command and install.sh. See the 2.0.2 release page for other download options.

Choose your language first. The installer starts with 简体中文 / English. Installation messages, account setup and future sessions use your saved choice; no configuration-file editing is needed. Enter keeps the previous installation language or the system-language default.

The first installation needs network access. The installer prepares isolated Python and dependencies, checks the installation and registers fofamap. No manual environment activation or administrator access is required. Account setup opens at the end; continue with step 2. Reopen your terminal if the command is not yet available.

bash install.sh
bash start.sh --version

For Windows issues, see the Windows walkthrough and troubleshooting. For macOS/Linux, see manual installation. Rerun the installer for repair or uninstall; see maintenance.

2. Set your FOFA key

1. Sign in to FOFA and copy your API key from your account page; register first if needed.
2. Paste it into the account form opened by the installer. Email is optional. Save and verify as prompted.
3. If you only want ordinary searches, choose skip / N when offered AI model setup. Add a model later when you need the Agent.

If the form did not open, or you need to change the key, run:

fofamap --setup

A FOFA key searches assets; a model key calls AI. They serve different purposes. Keep real keys out of chats, issues and screenshots. Missing, damaged or invalid required configuration opens repair guidance on a later launch.

3. Run your first search

Start with the wizard

fofamap

1. Use the arrow keys to choose Asset search, then press Enter.
2. Paste domain="baidu.com" to find Baidu’s public websites. This is FOFA syntax entered into the app; no outer shell quotes are needed.
3. Set Maximum pages to 1, then choose Use configured fixed fields (or Smart selection). Skip advanced history/export options for now and answer N to Nuclei scanning.
4. Wait for the results table. Page size follows your configuration; use the command below if you want an explicit three-record cap.

Use arrows to select, Enter to confirm and Esc / Ctrl+C to go back. The image above shows the current input screen; the next image shows a completed search.

Or copy a command: three records, no scan

No model is needed. Use one explicit domain, one page, three rows per page, and a three-row cap; disable liveness and automatic saving.

fofamap -q 'domain="baidu.com"' -f host,ip,port,protocol,title \
  --size 3 --pages 1 --max-records 3 \
  --no-check-alive --no-full --no-save

A table of hosts, IPs, ports, protocols, and titles confirms the real query succeeded. The capture distinguishes the upstream matching population from the three-row collection cap; matched population is not collected inventory. HTTP/HTTPS and apex/www may be distinct endpoints even when they share an IP.

Read the command left to right: -q decides what to find; -f chooses returned fields; --size 3 sets page size; --pages 1 limits pages; --max-records 3 caps total rows. --no-save prevents file output, not FOFA quota consumption.

Windows beginners can use the wizard above to avoid CMD/PowerShell quoting differences. The command’s quoting is for macOS/Linux; see the Windows guide if you need shell-specific syntax.

You are ready to use FofaMap. Next, export a file, investigate in natural language, or connect your AI assistant.

4. Choose how you want to work

Three distinct operations: FOFA is passive index lookup. --check-alive actively connects to targets for HTTP liveness. -n enters Nuclei scan approval. Beginner searches here explicitly disable liveness and omit -n.

Home and settings menus

The home screen prioritizes the AI task assistant, asset search, host details, and distribution statistics. Batch/favicon searches live under More search methods, rules/fields under Query reference, and account/model/preferences/setup/updates under Settings. Esc returns from a submenu without exiting the application.

Explicit scan/no-scan instructions take priority over AI advice. A user-requested scan prepares candidates and asks for exact plan approval even when AI advises against it. Statistics-plus-scan retains aggregates and fetches bounded targets within the same query scope, reporting partial coverage. Empty targets, query errors, and missing plan approval prevent execution.

Change the interface language at any time

Open Settings → Interface language, choose Chinese or English, and save. It takes effect immediately and is remembered for future sessions without reentering credentials or models.

fofamap

5. Learn FOFA queries step by step

Query fields and return fields are different catalogues. domain="baidu.com" is a condition; -f host,ip,port chooses result columns. product.version may be a query condition but is not a Stats dimension; syntax fields such as sdk_hash are not necessarily return fields.

Use straight double quotes around strings. On macOS/Linux, outer single quotes preserve the inner double quotes. On PowerShell, prefer outer single quotes and verify the native argument retains inner quotes; PowerShell versions differ in native argument handling. Paste the FOFA expression into the wizard if needed. Avoid curly quotes. Use English city names; Chinese region names work for China, and country codes are supported.

Inspect the local syntax catalogue

This makes no FOFA request. Structural validation does not certify membership, app-name existence, or all server semantics.

fofamap syntax

Inspect return fields and membership capabilities

No FOFA quota is consumed. The capture is the final screen of the actual catalogue. For a complete machine-readable view, use the MCP tool fofa_fields(section="all").

fofamap fields

Where do I enable smart fields?

Choose it immediately after the page limit; it is no longer hidden in advanced options. Go to Asset search → enter query → maximum pages → Fields for this query → Smart selection. To save the default, use Settings → Returned fields → Smart selection. Ordinary queries need no model key.

fofamap

Ordinary queries initially default to off, configurable in Settings; AI tasks default to on. Add --smart-fields to enable or --no-smart-fields to disable. Selection follows account capabilities and the task; ordinary searches do not need an extra model key for this feature. Check “Smart fields: Yes” in the query overview. For fixed columns, use -f host,ip,port,title and disable smart fields; smart selection takes priority when both are enabled.

6. Everyday queries: find a recipe

Look up an official app name first

This ThinkPHP example only looks up local rules; it does not search global assets. Copy the returned query and add your authorized scope explicitly.

fofamap rules --rule ThinkPHP

Browse rule categories before choosing a product query

The bundled reference set contains 691 rules across 166 categories. 510 entries were verified against the signed-in official FOFA library on 2026-11-02, preserving its exact returned queries. 181 compatibility mappings were not reverified and are labelled legacy. These are local selections, not FOFA’s complete rule population. Categories cover web servers, frameworks, databases, OA/ERP/CRM, mail, operations, cloud/containers, network/security devices, AI, industrial control, cameras, printers, storage, remote management, and industry systems.

Collection stopped when the website reported its 100-search daily limit; unverified entries are not presented as newly verified official names. Official library · Category and rule details · Verification data.

fofamap rules --rule-categories

Filter industrial-control rules

This only reads local fingerprint names and queries; it does not connect to industrial equipment. Filter by an exact official category, or use -k product to search names and aliases.

fofamap rules --rule-category 工业控制

Filter artificial-intelligence rules

The list uses actually verified examples from FOFA’s AI category; unverified product names are not simply turned into app= guesses. Add an authorized scope and record caps before an asset search.

fofamap rules --rule-category 人工智能

MCP fofa_rules supports keyword, category, and limit (default 50, maximum 200). category_summary always lists the full category navigation; matched_count and has_more identify undisplayed matches. Inspect verified / verified_at. Earlier Chinese category terms such as 框架 / 中间件 / OA / 运维面板 remain searchable.

Combine a domain with an indexed HTTP status

The condition is applied by FOFA; it does not freshly request each website. Bare and quoted numeric status values are supported.

fofamap -q 'domain="baidu.com" && status_code=200' -f host,port,status_code --size 3 --pages 1 --max-records 3 --no-check-alive --no-full --no-save

Filter collected rows by status and keyword

This requests status_code explicitly, then applies -i 200 and -k 百度 (the Chinese name for Baidu) locally. Filtering happens after retrieval, so fetched rows may still cost quota. Without returned status_code, -i can trigger additional HTTP liveness requests.

fofamap -q 'domain="baidu.com"' -f host,port,status_code,title -i 200 -k 百度 --size 3 --pages 1 --max-records 3 --no-check-alive --no-full --no-save

Optional: actively check one website now

This actively connects to one collected HTTP(S) endpoint, unlike the passive index recipes. Use only an authorized scope; the capture checks one public Bing web endpoint.

fofamap -q 'domain="bing.com" && host="www.bing.com"' -f host,port --size 1 --pages 1 --max-records 1 --check-alive --no-save

Profile a single host

Requires Host API access. --no-host-detail requests compact output; omit it for per-port details. A domain may map to a shared IP; ports on that IP are not proof they all belong to the domain’s operator.

fofamap -hq www.bing.com --no-host-detail --no-save

Aggregate ports and protocols

Requires Stats API access. Buckets are not a complete inventory. A dimension can return no buckets; that does not prove no such protocol exists.

fofamap -cq 'domain="baidu.com"' -f port,protocol --size 5 --no-save

Stats dimensions: protocol, domain, port, title, os, server, country, asn, org, asset_type, fid, icp. Treat the public contract as the top five per dimension; --size cannot guarantee a larger upstream result. product is not a supported aggregation dimension.

Search by a website favicon hash

Fetches the specified site’s favicon/HTML, then searches FOFA by its MurmurHash3 hash. It is not a FOFA-only operation. A shared icon is a fingerprint clue, not proof of shared ownership.

fofamap -ico https://www.bing.com --size 3 --pages 1 --max-records 3 --no-check-alive --no-full --no-save

Use --icon-file instead of -ico for an existing file, up to 4 MiB. Fetching an arbitrary URL is not offline hashing.

Search multiple statements from a file

The repository includes examples/queries.txt, one domain query per line. --batch-group-size 1 keeps them separate. Each statement is capped at three rows, so the combined cap is six.

fofamap -bq examples/queries.txt --batch-group-size 1 --size 3 --pages 1 --max-records 3 --no-check-alive --no-full --no-save

The default group size is 100, allowing homogeneous IP/domain lines to be combined with OR. Keep deduplication keys, return fields, and per-group budgets explicit. For a beginner file, use query-only lines.

7. Save and share results

Confirm fields with a small query first. Each command below actually searches the same scope, caps the result at three rows, and writes a file. -o specifies the full filename; --outdir sets only the default directory. Captures show actual task output and artifact paths.

Export CSV

Useful for Excel, data platforms, and simple scripts.

fofamap -q 'domain="baidu.com"' -f host,ip,port,title --size 3 --pages 1 --max-records 3 --no-check-alive --export-format csv --save -o results/readme-demo/inventory.csv

Export JSONL

One JSON object per line, suitable for streaming; inspect the actual exported structure.

fofamap -q 'domain="baidu.com"' -f host,ip,port,title --size 3 --pages 1 --max-records 3 --no-check-alive --export-format jsonl --save -o results/readme-demo/inventory.jsonl

Export XLSX

Open directly in Excel or another spreadsheet application with headers.

fofamap -q 'domain="baidu.com"' -f host,ip,port,title --size 3 --pages 1 --max-records 3 --no-check-alive --export-format xlsx --save -o results/readme-demo/inventory.xlsx

Send machine-readable JSON to another program

--json removes decorative output for parsing. A multi-page CLI run may emit multiple JSON documents; do not assume the entire stream is one JSON array. Prefer --output-format jsonl or JSONL export for line-oriented processing.

fofamap -q 'domain="baidu.com"' -f host,ip,port --size 1 --pages 1 --max-records 1 --no-save --json

8. Before collecting more: pagination and quota

CLI/export allow up to 1,000,000 rows; start much smaller. MCP conversational search is capped at 1,000 rows / 20 pages; use fofa_export for larger inventories. body reduces effective page size to 500; cert/banner/header to 2,000. A smaller page does not automatically mean the population is exhausted.

Fetch two real pages: two rows each, four total

The same query displays two actual pages. Check page numbers, returned rows, and population. Collection stops at the cap rather than fetching indefinitely.

fofamap -q 'domain="baidu.com"' -f host,ip,port --size 2 --pages 2 --max-records 4 --no-check-alive --no-save

FOFA cursors are not stable snapshots. Continue immediately with the same query, fields, and size. Expiry 40070 maps to cursor_expired / restart_search; restarting is not the next page. Durable storage must handle deduplication across processes, restarts, or unknown cursor chains.

observe_cost=true adds account reads before and after an MCP search—two extra requests. Unchanged balances may reflect free pools, delay, caching, or concurrency; they do not prove zero cost. FOFA points and model tokens are separate. cost_budget stops subsequent pages after reported spending reaches the threshold; it is not a pre-billing hard monetary cap.

9. Turn a task description into an investigation

Configure a model first: DeepSeek is recommended

Open Settings & maintenance → AI model setup. DeepSeek is recommended and listed first. Presets also cover Kimi, MiniMax, Xiaomi MiMo, GLM, SiliconFlow, OpenAI, Anthropic, Ollama and LM Studio. Select a provider, enter your endpoint/model/key and verify as prompted. Ordinary queries can still skip this step. See model defaults and verification date.

fofamap

Check configured models

Plain queries need no model. -ai uses planner, repair, reflector, and summarizer routes. An empty model ID may trigger a model-list API call. Displaying a profile is not proof that a generation request succeeds.

fofamap models

Run a bounded real Agent task

The request pins a domain, caps it at two records, forbids expansion/scanning, and sets report language and path. This capture used real FOFA and the configured model, producing Markdown and HTML.

fofamap -ai 'Query only domain="baidu.com", at most 2 public website records. Do not expand scope or scan. Write an English briefing under 250 words.' --size 2 --pages 1 --max-records 2 --no-check-alive --no-deepseek-search --no-save --report-lang en --report-file results/readme-demo/report-en.md

Model prose is advisory and can contain inference errors. Review evidence, gaps, and counts. Corroboration is not legal ownership; no finding is not proof of no vulnerability. Preserve distinct hostnames as separate endpoints even on the same IP.

flowchart LR
  A["Request"] --> B["Plan + validate"]
  B --> C["FOFA"]
  C --> D["Dedupe + evidence + reflect"]
  D -->|Refine if needed| C
  D --> E["Markdown / HTML"]
  D --> F{"Scan requested?"}
  F -->|Yes| G["Exact plan + approval"]
  G --> H["Nuclei"]

Product exposure review: statistics and a one-row sample

Real Redis/Hefei/monthly-update review: aggregate first, then fetch. sample=true explicitly marks a sample; usage is returned. The scan block is simulated with executed=false, not an actual Nuclei scan.

python scripts/readme_demo.py exposure --language en --output results/readme-demo/exposure-en

Describe an AI task in the wizard

Select a feature with arrow keys and Enter. Esc/Ctrl+C goes back. An example shares the prompt line; your text starts on the next line. This captured interaction is cancelled before submitting its task.

fofamap

How to read the reports and find files

The task above writes results/readme-demo/report-en.md and a matching .html. Open HTML in a browser from your file manager. Sorting/filtering use data already embedded in the report; no backend service is needed.

Inspect the actual English Markdown report or English HTML report. Download HTML from GitHub and open it locally. These are the real task artifacts, not separately invented examples.

Reports include timing, execution steps, actual queries, collected counts, candidate evidence, AI prose, limits, model routes, and tokens. Tables support search, sorting, Shift multi-sort, restoring source order, field selection, visible-row CSV, and deduplicated TXT. Filtered exports are subsets, not the original full inventory.

MCP fofa_render_report / fofa_agent_run follow the saved interface language when report_language is omitted. Explicit zh, en or both takes precedence. Reconnect an already running MCP server after changing its saved language.

--report-lang zh/en/both controls report structure/UI language. both creates two versions but does not promise automatic translation of all original asset text or model prose. MCP fofa_render_report normally requires result_count to equal supplied rows. A larger count needs explicit sampled=true and sample_stop_reason; do not present a sample as complete inventory.

10. Use MCP / Skills in your AI assistant

MCP exposes deterministic tools. The Skill tells a host model how to choose tools, bound scope, handle errors, and report findings. Installing the Skill neither configures your FOFA credentials nor enables scans. If the host performs the analysis, there is no need to call fofa_agent_run.

You can give this task to an AI with terminal and local configuration access:

Use docs/AI_INSTALL.md from https://github.com/asaotomo/FofaMap to install MCP and the Skill for this host only. Verify the downloaded version, preserve existing configuration, use absolute Python/server paths, and never print secrets. Run quota-free checks first, then one baidu.com record after I configure FOFA. Do not automatically scan. Verify actual tool loading, version, and installed Skill hashes before reporting completion.

List supported hosts

There are nine dedicated installer targets. Other hosts can use their documented generic MCP configuration; a mentioned product name does not imply a built-in installer.

fofamap integrate --list

Install an integration into an isolated project folder

This writes a Cursor project configuration under results/readme-demo/host without changing existing user-level host configuration. Replace project-root with your actual project. For a user-level install, omit the project scope/root options after reviewing the destination.

fofamap integrate --agent cursor --scope project --project-root results/readme-demo/host

The installer pins absolute Python/server paths and cwd where supported. Reinstallation preserves existing env/custom cwd/timeouts and backs up configuration. A PATH failure from an old bare fofamap-mcp command is not evidence the service is broken. Restart/refresh that host and inspect the loaded tool list.

Check whether an installed Skill is stale

Read-only comparison of the release marker and all file hashes. Missing/extra files and changed content—even with the same version—produce a nonzero exit status.

fofamap integrate --agent cursor --scope project --project-root results/readme-demo/host --check-stale --json

Export, import, and verify a .skill package

These three lines form one task: export the bundled Skill, import it into the same isolated host, and verify it. Export refuses to overwrite an existing archive; use a fresh filename when repeating it.

fofamap integrate --export-skill results/readme-demo/fofamap.skill
fofamap integrate --agent cursor --scope project --project-root results/readme-demo/host --import-skill results/readme-demo/fofamap.skill
fofamap integrate --agent cursor --scope project --project-root results/readme-demo/host --check-stale --json

Perform a real handshake and release check

No FOFA or model calls. Success includes ok=true, version 2.0.2, 31 tools, the negotiated protocol, Python/server paths, and code fingerprint. Expected values must come from the intended release, not from an old executable describing itself.

fofamap-mcp --check --expect-version 2.0.2 --expect-build-date 2026-11-02 --expect-source .

Run a real MCP query workflow

Run the included example from the source directory; it starts an isolated stdio server, validates syntax, fetches at most two rows, and reads usage. It shows actual calls/data without printing credentials.

python scripts/readme_demo.py mcp --language en --output results/readme-demo/mcp-en

All 31 MCP tools

fofa_agent_run, fofa_export, and nuclei_execute return background jobs. Poll fofa_job_status to completed/failed/cancelled; stop work with fofa_job_cancel. Keep the same MCP server process alive; a hard restart does not resume jobs. Client timeout does not imply cancellation. REST Agent/scan endpoints differ and do not inherit the MCP async contract.

Resources: fofamap://fields, fofamap://rules, fofamap://account, fofamap://runtime, and fofamap://jobs/{job_id}. Runtime is quota-free; account reads the actual FOFA account. Tools-only hosts can still complete primary workflows. See the tool catalogue and reliability guide.

Choose stdio, Streamable HTTP, or SSE

Keep an HTTP server running in one terminal and connect from another terminal or host. Verify the address with fofamap-mcp --check-url URL --expect-version 2.0.2. The captures above and below show actual connection and installation checks. Non-loopback listening requires authentication, issuer, and resource configuration; do not expose an unprotected server publicly.

Reproduce real HTTP and SSE startup/checks

The example selects free loopback ports, starts both real MCP transports, validates version/tools/source, and cleans up. No FOFA/model quota is used.

python scripts/readme_demo.py transports --language en --output results/readme-demo/transports-en

11. Schedule inventory and track changes

Saving a schedule does not start the worker. Use item 15 in the wizard for AI-assisted or manual creation. Supported recurrence: once, every N minutes (minimum one), hourly, daily, weekly, monthly, with IANA timezones. Missing dates in a month are skipped; monthly is not a fixed 30-day interval.

Inspect schedules and worker heartbeat

Read-only; it does not run due tasks. An absent heartbeat means there is no evidence that a worker is polling.

fofamap schedule --schedule-action list --json

examples/schedule.json defines a fixed domain every ten minutes, capped at ten rows, analyze=false, check_alive=false. --schedule-spec creates a full specification. Do not apply that frequency to a large scope without reviewing cost.

Real due-time execution: create → worker → history → reports

This script uses a separate database and temporary worker so the tutorial cannot claim your existing jobs. It collects at most two records without a model or scanning, then stops/deletes the temporary schedule and retains reports.

python scripts/readme_demo.py schedule --language en --output results/readme-demo/schedule-en

Fixed queries make snapshots more comparable. After changing scope, inspect the comparable flag before interpreting additions/removals. check_alive=null follows global settings; explicit task wording takes priority. An unattended worker cannot use interactive-only model credentials; use an API credential or fixed queries with analysis disabled. Review paths, user, and environment file in deployment/fofamap-scheduler.service before installing a service.

12. Enable Nuclei when you need an authorized scan

Verify the installed Nuclei binary

Query-only work needs no Nuclei. If scanning requires a missing component, first choose Y=download official binary/templates, N=manual installation, default N. Y downloads the matching stable release, verifies SHA-256 and version, installs templates, then continues the approved scope. N/cancel downloads nothing, skips scanning, and retains query/report results. Components use a per-user tool directory without administrator rights; existing PATH / FOFAMAP_NUCLEI installations take precedence. For manual installation see official releases and installation docs. MCP/REST install_if_missing defaults to false and requires separate user installation consent before true; scanning still requires exact plan approval.

Open Settings → Nuclei component for the same install/update flow, or run:

fofamap --update-nuclei

nuclei -version

Inspect a real public-scope approval screen without executing

This command fetches at most one FOFA row and opens exact-plan approval. The captured demo is cancelled with Esc; it does not scan the public domain. Execute only after obtaining authorization and reviewing the scope.

fofamap -q 'domain="baidu.com"' --size 1 --pages 1 --max-records 1 --no-check-alive --no-save --no-scan-ai-dedupe -n --nuclei-id tech-detect --severity info

The default web-baseline contains ten templates: 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. It is not a full-template vulnerability scan. Allowlisting and template-defined protocols/ports are part of the authorized scope.

Actually execute a controlled local scan

This reproducible example creates a temporary local HTTP service, one info template for that fixture, an isolated database, and one-time approval. Real MCP/Nuclei execution verifies one match. The explicit --approve-local-fixture flag is required; the script accepts no arbitrary public target.

python scripts/readme_demo.py scan --approve-local-fixture --language en --output results/readme-demo/scan-en

CLI execution always requires approval. MCP/REST additionally require FOFAMAP_ENABLE_SCANNING=true and a FOFAMAP_SCAN_APPROVAL_SECRET of at least 24 characters. Administrators allowlist custom paths and IDs outside the baseline. Tokens bind exact scope and expiry and are one-use only; never log or reuse them. -batch does not bypass approval.

Workflow: capabilities → guide/templates → recommend → optional select_targets/customize → plan → approval → execute → job_status. Customization accepts mapped Nuclei flags such as -rl 5 -c 2 -timeout 10, not rate_limit=5 or arbitrary shell code. See the Nuclei guide.

13. Update, repair and uninstall

After installation with the one-click installer, run the command below to check and update FofaMap. It checks the official repository's latest stable GitHub Release, downloading that release's source ZIP or the source archive for its stable tag. It never installs development branches or downgrades. Downloads require GitHub HTTPS addresses; archive paths, project name, and version are validated, along with SHA-256 when provided for a release asset.

fofamap --update

The updater backs up and replaces program source, reinstalls dependencies, verifies version/MCP, and repairs the command entry. Configuration, keyring credentials, environment variables, .env, results, and local state remain intact. Backups, installation logs, and transaction status are under .fofamap-updates/<timestamp>/. Failure restores the old source and reinstalls the old package. If environment recovery also fails, status explicitly becomes source_restored_environment_needs_repair; rerun the installer to repair dependencies. Windows opens a separate update window and waits for the current launcher to exit, avoiding locked EXE files. Wait for completion before launching again. Stop other FofaMap/MCP processes before updating, then refresh hosts and check Skill freshness afterward. Environments installed separately with pip should use their original package manager; automatic source updates require the source directory and the installer's .venv.

This guide documents stable release 2.0.2. The update check follows GitHub's latest stable release and makes no changes when you are already current. The image above records a real check before publication, when the latest release was still 2.0.1. Update Nuclei/templates with fofamap --update-nuclei or fofamap -up.

Install, repair and uninstall

Run the same installer again to manage the application. A fresh installation offers Install; an existing installation in this directory or for the current user offers Repair / Uninstall / Cancel. Enter its number; Enter defaults to install or repair, and 0 cancels.

Uninstall preserves source, account settings, keys, databases, query results, reports and backups. Separately installed Nuclei and host MCP/Skill configuration are preserved too. Rerun the retained installer to install again; remove personal data yourself after backing it up if a complete data removal is wanted. Uninstalling an old directory preserves a command owned by another installation. Unknown tools directories, external environment links and user-modified launchers are retained with a message.

For unattended installs, add --language zh / --language en on macOS/Linux or -Language zh / -Language en on Windows. CI/redirected input uses the saved/system language unless overridden.

For automation, use bash install.sh --action install, --action repair or --action uninstall on macOS/Linux; install.bat -Action install, -Action repair or -Action uninstall in Windows CMD; or .\install.ps1 -Action ... in PowerShell. Without an explicit action, CI/redirected input installs a fresh copy or repairs an existing one; it never uninstalls automatically. Repair from a newly extracted directory installs its current source and switches the command to that directory, preserving the previous directory's data. First use or damaged settings still opens account setup after installation/repair. AI model setup remains optional for ordinary queries.

Confirm FofaMap and Python versions

Check the environment actually running before troubleshooting.

fofamap --version
python --version

Read the installed command help

No key is required. The capture shows a real first screen of the longer help output.

fofamap --help

14. Troubleshooting

Real error example: errors are not empty results

This command intentionally ends with a dangling &&. The capture shows the actual failure, which is not a successful zero-row result.

fofamap -q 'title="x" &&' --no-save --size 1 --pages 1 --max-records 1

15. Complete command-line reference

All current Click entry options are listed below by purpose. This is a reference, not an instruction to combine every flag. Complete commands and matching captures appear in the recipes above. Your installed --help is authoritative.

Queries and scope

Presentation and exports

Scanning and compatibility

Installation and integrations

Schedules

Exit codes: 0 for completion; 1/2 for argument/query/configuration/execution failure; 130 for some cancellation paths. Inspect background job status/error rather than only the first call’s exit code.

16. Configuration, credentials and advanced preferences

Prefer fofamap init or the wizard’s account/model/preferences menus. Back up YAML before editing; any file containing actual keys should be private and ignored by Git. Copying .env.example does not automatically load it; your shell/deployment tooling must explicitly inject variables.

Configuration lookup: explicit FOFAMAP_CONFIG → config/settings.yaml in the working directory → per-user config → legacy fallback. User locations: macOS ~/Library/Application Support/FofaMap/settings.yaml; Linux $XDG_CONFIG_HOME/fofamap/settings.yaml (default ~/.config); Windows %APPDATA%/FofaMap/settings.yaml.

This is a configuration shape, not executable credentials. See settings.example.yaml.

system:
  language: en
  output_dir: results
  scan_ai_dedupe: false
fast_check:
  check_alive: false
providers:
  my_model:
    protocol: openai_chat
    base_url: "https://your-provider.example/v1"
    model: "YOUR_ACTUAL_MODEL_ID"
    api_key_env: MODEL_API_KEY
    credential_kind: api_key
    timeout: 120
routing:
  default: my_model
  planner: my_model
  query_repair: my_model
  reflector: my_model
  summarizer: my_model
  allow_cross_provider_fallback: false

FOFA credential precedence: environment FOFA_API_KEY/legacy FOFA_KEY → system keyring → YAML compatibility storage. New queries reload configuration; environment changes outside a process still require restarting that service. Models normally use the variable named by api_key_env or the keyring; local YAML secrets require explicit wizard confirmation. Service state and CLI output roots can differ; inspect actual --check paths.

fofamap init

fofamap account

17. REST / OpenAPI for other programs

Real REST: start → request → return one row

The script starts a real FastAPI server on a random loopback port, reads OpenAPI, and POSTs a real FOFA query capped at one record, then shuts down. It is not TestClient or a mock.

python scripts/readme_demo.py rest --language en --output results/readme-demo/rest-en

For persistent use, run fofamap-api (equivalent to fofamap serve), defaulting to 127.0.0.1:8000. Swagger UI is /docs; the schema is /openapi.json. Keep that terminal running and send requests from another terminal, Swagger, or your program. Change the port with FOFAMAP_PORT.

A REST search body uses query, fields, size, page; cursor continuation also needs cursor. Export uses search + format + filename. REST errors and synchronous Agent/scan behavior differ from MCP envelopes/background jobs. Non-loopback deployment requires a Bearer token or JWT; MCP HTTP additionally needs issuer/resource metadata. See security policy and installation notes.

See the release contents guide for directory purposes.

Hx0 Studio and community

FofaMap is developed and maintained by Hx0 Studio. Report problems through Issues, contribute a pull request, or support the project with a star.

Studio website · Repository

Support development

If FofaMap saves you time, you are welcome to buy us a coffee. Thank you to everyone who tests, reports issues and supports development.

Acknowledgements

Thanks to Yuanlong Sec, the FOFA co-creator program, all contributors and our community.

Follow the studio

Use within lawful authorization. FOFA matches and model summaries do not establish ownership or confirm vulnerabilities; review scan findings. Include the version, platform and a redacted command in bug reports, without keys, approval tokens or private asset lists.