fofamap

Overview

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

1. pick the right FOFA operation,
2. detect the FOFA membership tier and capability profile,
3. run deterministic API calls through scripts/fofa_recon.py,
4. broaden the search when FOFA returns no useful data,
5. verify live web reachability when it matters,
6. track inventory drift with snapshot comparisons when the task is recurring,
7. export clean handoff files when the user needs deliverables,
8. summarize findings with clear caveats and next steps,
9. learn from prior runs so the next query, report, and handoff improve.

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. It now also keeps a bounded local memory so the skill can reflect on failed runs, recurring friction, and strong report patterns without turning into an uncontrolled self-modifying black box.

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
• run recurring asset monitoring and compare new, removed, or changed exposures
• 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 search-next --query 'title="login"' --fields host,ip,port,title --max-pages 3
• scripts/fofa_recon.py search-next --query 'app="nginx"' --size 100 --max-pages 2 --output nginx_deep.xlsx
• scripts/fofa_recon.py search --query 'cert.subject.org="Google"' --fields ip,port,product,product.version,cert.is_valid
• 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 monitor-run --query 'org="Example Corp"' --state-dir results/monitor_example --report-output results/monitor_example/latest_report.md
• scripts/fofa_recon.py monitor-run --query-file queries.txt --use-search-next --max-pages 3 --state-dir results/monitor_monthly --fail-on-change
• scripts/fofa_recon.py project-run --query 'app="nginx" && country="US"' --query 'app="grafana" && country="US"' --alive-check --split-exports
• scripts/fofa_recon.py learn-review
• 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 search-next when the user wants deeper harvesting through FOFA's official continuous paging cursor API.
• 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.
• Use monitor-run when the same queries will be rerun on a schedule and the user cares about newly added, removed, or changed assets.

host returns a normalized host_profile when FOFA exposes richer host data such as domains, protocols, ISP, rules, or per-port rule hints.

stats returns a normalized stats_summary with consumed_fpoint, required_fpoints, and lastupdatetime when FOFA includes them.

2. Read the FOFA capability profile first when permissions matter

Run scripts/fofa_recon.py login before planning when the user needs:

• host or stats and you are not sure the account supports those APIs
• advanced export fields such as product, body, product.version, cert.is_valid, or icon
• a field-heavy handoff where you need to know what FOFA will actually return

The helper returns a permission_profile object with:

• vip_level and human-readable tier name
• can_use_host_api and can_use_stats_api
• allowed_search_fields
• documented_search_export_field_count
• data_limit
• default_search_fields_csv
• search_field_presets

Use that profile to choose fields before issuing the search.

3. 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, references/permission-playbook.md, and references/syntax-arsenal.md.

When the user intent is fuzzy, exploratory, or hunt-style, search references/syntax-corpus.tsv by product, tag, rule name, or artifact string and use it to generate one precise query plus one or two controlled fallback queries. Treat the corpus as a seed library, not a hard limit on what FOFA combinations are allowed.

If the task is attack-infrastructure hunting, takeover review, honeypot suspicion, or cloud/API leak discovery, also load references/redteam-hunt-playbook.md.

If the user wants a polished report, persuasive delivery, or a specific analyst angle, also load references/report-templates.md and choose a suitable --report-profile such as attack-infrastructure, abnormal-exposure, or takeover-risk.

If the task is recurring, long-running, or the user explicitly wants the skill to improve from experience, also load references/evolution-playbook.md. The helper writes local episodic and semantic memory under results/fofamap_memory/ by default and exposes learning_artifacts plus learn-review.

When the user wants more than one ordinary page of results, prefer search-next over repeatedly emulating page numbers. It follows FOFA's official /api/v1/search/next cursor flow and returns next_cursor_to_resume, has_more, requested_size, effective_size, and cursor_trace so later runs can resume cleanly and explain any FOFA size cap that was applied.

4. 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.

5. 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

When the report needs to feel complete and operator-ready, choose a report profile instead of writing in a generic voice. Use:

• standard for baseline delivery
• attack-infrastructure for clustering, campaign-style, or suspicious infra review
• abnormal-exposure for admin panels, storage leakage, API exposure, and unusual services
• takeover-risk for dangling domains, placeholder pages, and ownership gaps

6. 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.

7. 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.

8. 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.

9. 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.

10. Use monitor mode for recurring asset watch

Use monitor-run when the user asks for daily, weekly, or monthly asset tracking.

• The first run establishes a baseline snapshot.
• Later runs compare against latest_snapshot.json and report added, removed, and changed assets.
• Prefer a stable --state-dir so scheduled runs always compare against the same monitoring profile.
• Add --use-search-next for larger inventories and --fail-on-change when an automation should raise an alert on drift.
• The command leaves behind latest_snapshot.json, latest_diff.json, latest_report.md, timestamped archives, and optional per-query exports.

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, inspect permission_profile first. The helper script will also drop known over-tier fields before the request and report that downgrade explicitly.
• 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.
• When local memory exists, read the latest reflection before repeating a similar task so the agent actually benefits from prior runs.

References

• references/setup.md: environment variables and command examples
• references/query-playbook.md: query patterns, field guidance, retry heuristics, and triage suggestions
• references/permission-playbook.md: vip-level capability model, field presets, and tier-aware field matching
• references/analysis-playbook.md: distilled tactics from the original AI and MCP workflows
• references/monitor-playbook.md: recurring asset monitoring, drift analysis, baseline handling, and report strategy
• references/redteam-hunt-playbook.md: attack infrastructure, deception, takeover, and cloud leak hunting tactics
• references/report-templates.md: fixed report lenses and persuasive delivery structure
• references/evolution-playbook.md: local memory, self-reflection, self-repair, and learn-review workflow
• references/syntax-arsenal.md: how to use the team's FOFA syntax corpus for divergent query planning
• references/syntax-corpus.tsv: extracted rule corpus from the workbook for grep-based query seeding