fofamap

Overview

This skill turns natural-language recon requests into a stable FOFA workflow:

1. pick the right FOFA operation,
2. run deterministic API calls through scripts/fofa_recon.py,
3. broaden the search when FOFA returns no useful data,
4. verify live web reachability when it matters,
5. export clean handoff files when the user needs deliverables,
6. summarize findings with clear caveats and next steps.

This skill is distilled from the FofaMap project, but packaged for skill use instead of an interactive application. The host agent should do the reasoning, and the helper script should do the FOFA API work. The workflow keeps the project's key tactics: action routing, permission-aware field selection, zero-result reflection, live reachability verification, export-oriented delivery, and targeted follow-up suggestions.

For setup, the user only needs to provide FOFA credentials:

• FOFA_EMAIL
• FOFA_API_KEY

When To Use

Use this skill when the user asks for any of the following:

• find exposed assets, subdomains, services, or product fingerprints with FOFA
• profile a single IP or domain with FOFA host aggregation
• analyze distribution data such as country, port, title, ASN, or organization rankings
• derive an icon_hash query from a target website
• retry a failed FOFA search with broader, smarter fallback queries
• decide whether the findings justify a separate validation step such as nuclei

Do not use this skill for:

• general web scraping unrelated to FOFA
• active exploitation by default
• network scanning without explicit user approval
• tasks that require guaranteed real-time validation beyond FOFA's indexed data

Quick Start

If credentials are not configured yet, read references/setup.md.

Required credentials for this skill:

• FOFA email
• FOFA API key

Core helper:

• scripts/fofa_recon.py login
• scripts/fofa_recon.py search --query 'app="nginx" && country="US"'
• scripts/fofa_recon.py search --query 'app="nginx" && country="US"' --alive-check --output nginx_us.xlsx
• scripts/fofa_recon.py host --target 8.8.8.8
• scripts/fofa_recon.py host --target 8.8.8.8 --report-output host_report.md
• scripts/fofa_recon.py stats --query 'app="Redis"' --fields country,port,org
• scripts/fofa_recon.py stats --query 'app="Redis"' --fields country,port,org --report-output stats_report.md
• scripts/fofa_recon.py alive-check --target example.com --target 1.1.1.1:8443 --output alive.csv
• scripts/fofa_recon.py project-run --query 'app="nginx" && country="US"' --query 'app="grafana" && country="US"' --alive-check --split-exports
• scripts/fofa_recon.py icon-hash --url https://example.com

Workflow

1. Choose the correct mode

• Use search when the user wants concrete assets.
• Use host when the user gives one IP or one domain and wants details.
• Use stats when the user wants rankings, trends, or distribution.
• Use icon-hash when the user wants similar assets by favicon.

2. Start conservative

Default to safe, broadly available fields unless the user explicitly needs premium FOFA fields. The helper script already falls back to a safe field set if a higher-tier field request is rejected.

Before using advanced fields or highly specific filters, check references/query-playbook.md.

3. If the result set is empty, reflect and retry

Do up to three progressively broader retries:

1. remove the most brittle geographic or version-specific filter
2. replace host= with broader title=, body=, or product-style matching when appropriate
3. keep only the most distinctive keyword plus a coarse scope such as country or protocol

State clearly that the later attempts are broader fallback queries, not equivalent matches.

4. Summarize like an analyst

When reporting results, include:

• the user goal in one line
• the FOFA query or queries used
• the scope and major findings
• any important field or subscription limitations
• a cautious next-step recommendation

5. Add live verification when it changes the answer

Use --alive-check or alive-check when the user wants:

• a current reachable subset of FOFA results
• dead assets filtered out before handoff
• a cleaner candidate list for later validation work

If the user asks for a deliverable, prefer exporting the checked result set so the handoff includes the current HTTP status.

6. Export for handoff, not just for storage

Use:

• xlsx when handing off to analysts, red teams, or non-technical stakeholders
• csv when another tool or script will consume the result

If live checks were run, include the HTTP status in the export. This preserves one of the most practical parts of the original project: not just finding assets, but packaging them for the next operator.

7. Gate active follow-up

If the user wants active validation, ask or confirm before running tools such as nuclei, curl-based checks, or login probes. FOFA is passive indexed intelligence; active testing is a separate consent boundary.

8. Prefer project mode for real jobs

When the user has multiple queries, wants delivery files, or needs a mini operation bundle, prefer project-run. It preserves one of the original project's best ideas: a single task should leave behind a project directory with exports, targets.txt, a suggested Nuclei command, and a Markdown report.

If the user explicitly wants active scanning and has authorization, project-run --run-nuclei can extend that workflow into a local Nuclei scan and fold the log summary into the report.

Working Rules

• Prefer the helper script over ad hoc HTTP code so the workflow stays consistent.
• Keep output compact and analyst-friendly. Raw JSON is fine when another tool will consume it; otherwise summarize it.
• Call out when FOFA data may be stale, partial, or permission-limited.
• If the user asks for premium-only fields and FOFA rejects them, retry with safer fields and explain the downgrade.
• For high-risk follow-up suggestions, separate "observed from FOFA" from "needs live validation."
• When the task is analytical rather than mechanical, use the reporting patterns in references/analysis-playbook.md.
• When the task needs an operator handoff, create files, not just chat output.

References

• references/setup.md: environment variables and command examples
• references/query-playbook.md: query patterns, field guidance, retry heuristics, and triage suggestions
• references/analysis-playbook.md: distilled tactics from the original AI and MCP workflows