asaotomo/FofaMap

📌 What is FofaMap?

FofaMap is a Python‑based command‑line tool that combines FOFA (a search engine for internet‑exposed assets) with an AI‑driven agent. It can:

• Run classic FOFA queries directly.
• Accept a natural‑language request, let the built‑in agent plan multiple FOFA queries, reflect on the results, and produce a structured, evidence‑backed asset report.
• Export results as XLSX, CSV or JSONL.
• Optionally generate a Nuclei scanning plan that must be manually approved before any active scanning is performed.

The project bundles a REST API, MCP/Skill integration for AI‑coding assistants (Cursor, Claude, LM Studio, etc.), and a self‑reflection loop that can revise queries up to two times.

---

🚀 Quick start (5 min)

# clone & set up a virtual environment (Python 3.10+)
git clone https://github.com/asaotomo/FofaMap.git && cd FofaMap
python3 -m venv .venv
source .venv/bin/activate   # Windows: .venv\Scripts\activate
pip install -e .

# check installation
fofamap --version
fofamap --help

1. Run fofamap init – a wizard that stores your FOFA API key (and optionally an OpenAI/Anthropic/etc. key for the AI mode).
2. Perform a classic query:

   fofamap -q 'app="nginx" && country="CN"' -p 2 --size 100
   

3. Or let the agent do the heavy lifting:

   fofamap -ai '收集 Example 公司的公开网站，区分高置信资产与待复核候选'
   

   The agent will: 1️⃣ turn the natural language into one or more FOFA queries, 2️⃣ run them, evaluate hit counts, and if needed refine the queries (max 2 rounds), 3️⃣ de‑duplicate, grade evidence (corroborated, observed, candidate), 4️⃣ output a table and a Markdown report.

---

🛠️ Core features

Feature	What you get
Classic FOFA CLI	-q / -hq / -cq / -ico / -bq – full FOFA syntax, no AI required
Natural‑language agent	-ai – plan, reflect, and summarise assets automatically
Evidence grading	Results are labelled corroborated, observed or candidate with clear boundaries
Export formats	XLSX, CSV, JSONL; streaming for very large result sets
Nuclei integration	Generates a scan plan, shows targets/template/severity, requires a one‑time manual approval token before execution
MCP / Skill	One‑click registration of FofaMap as a tool for AI coding assistants (Cursor, Claude, LM Studio, etc.)
REST API	OpenAPI 3.1 definition; run fofamap serve to expose the same functionality over HTTP
Cross‑platform	Works on Windows, macOS and Linux
Security‑first	API keys stored in OS key‑chain when possible; clear error messages for quota, rate‑limit or permission problems

---

📚 How to use the agent (AI mode)

fofamap -ai '收集授权范围内中国地区的 Example 产品暴露面，按协议、端口和产品版本总结，最多返回 500 条'

The agent workflow (see the mermaid diagram in the README):

1. Parse the request and decide which FOFA sub‑queries are needed.
2. Validate each query against FOFA syntax and the built‑in rule library.
3. Execute the queries, collect hits, and check if the result quality is sufficient.
4. If not, reflect and generate a refined query (max two iterations).
5. Deduplicate and assign an evidence level.
6. Produce a table and a Markdown briefing that always lists:
   • high‑confidence assets,
   • noise/false‑positives,
   • uncovered evidence gaps,
   • next‑step recommendations.

---

🔧 Nuclei scanning (approval‑gated)

1. Install Nuclei separately (projectdiscovery.com) and ensure it is on your PATH.
2. Add the environment flag to enable scanning:

   export FOFAMAP_ENABLE_SCANNING=true
   export FOFAMAP_SCAN_APPROVAL_SECRET='随机高熵字符串（≥24字符）'
   

3. Run a query with -n (or --nuclei). The tool will:
   • Show the exact target list, selected template IDs and severity filters.
   • Ask you to confirm (or edit) the plan.
   • After approval, invoke nuclei with the chosen templates.
4. You can customise the template set:

   fofamap -q 'domain="example.com"' -n \
       --nuclei-id cors-misconfig --nuclei-id tech-detect \
       --severity low,medium
   

   Use --nuclei-id all and --severity all for a full‑scale scan (the tool warns you heavily).

---

📦 Integration with AI coding assistants (MCP/Skill)

# list supported agents
fofamap integrate --list
# install for Cursor (example)
fofamap integrate --agent cursor
# uninstall
fofamap integrate --agent cursor --uninstall

The installer writes a small wrapper (fofamap-mcp) that the host IDE can call as a tool. No secrets are copied; the wrapper simply points to the existing Python environment.

---

🗂️ Project layout (high‑level)

FofaMap/
├─ config/            # example settings, .env template
├─ docs/              # Agent integration guide, audit docs, etc.
├─ fofamap/           # core package (CLI, agent, MCP, REST)
├─ results/           # default output directory (timestamped sub‑folders)
├─ tests/             # unit / integration tests
└─ setup.py / pyproject.toml

---

🧩 When to choose which entry point

Entry	Needs FOFA key	Needs AI key	Best for
Interactive CLI / classic -q	✅	❌	Known FOFA syntax, quick look‑ups
Local -ai agent	✅	✅	Natural‑language scouting, evidence‑graded reports
MCP / Skill	✅	❌*	Use from Cursor, Claude, LM Studio etc. (host provides its own LLM)

---

❓ Common questions

• Do I need a paid FOFA account? Yes, the tool uses the FOFA API; the amount of data you can retrieve depends on your membership level.
• Can the AI run commands on my machine? No. The agent only calls FOFA, processes data, and (optionally) prepares a Nuclei plan. Execution of Nuclei is gated by manual approval.
• What AI providers are supported? OpenAI, Anthropic, DeepSeek, Ollama, LM Studio and any compatible OpenAI‑style endpoint.
• How are API keys stored? Preferably in the OS key‑chain (macOS Keychain, Linux Secret Service, Windows Credential Manager). If unavailable, the wizard asks whether to write them to a local file with 0600 permissions.

---

📦 Installation & upgrade notes

• Install with pip install -e . inside a virtual environment.
• To upgrade:

  git pull && pip install --force-reinstall -e .
  

• After a major version bump, rotate any previously stored FOFA keys (see MIGRATION.md).

---

🔗 Useful links

• Releases: https://github.com/asaotomo/FofaMap/releases/tag/v2.0.1
• Documentation index: docs/ (Agent integrations, REST OpenAPI, security policy)
• Issue tracker: open GitHub Issues for bugs or feature requests.

---

TL;DR

FofaMap lets security researchers and red‑teamers search FOFA with either raw queries or natural language, automatically refine the search, grade evidence, and optionally gate a Nuclei scan behind a human approval step—all from a single, cross‑platform CLI that can also be called via a REST API or as a tool inside AI coding assistants.