asaotomo/FofaMap

一款证据驱动的 FOFA 资产测绘智能体：支持自然语言侦察、AI 反思、CLI / MCP / Skill / REST API，以及经人工审批的 Nuclei 扫描。

📌 FofaMap とは何か？

FofaMap は、FOFA（インターネットに公開された資産を検索するエンジン）とAI駆動型エージェントを組み合わせた Python ベースのコマンドラインツールです。以下が可能になります：

クラシックな FOFA クエリを直接実行。
自然言語によるリクエストを受け取り、内蔵エージェントが複数の FOFA クエリを計画し、結果を検討して構造化された証拠付きの資産レポートを生成。
結果を XLSX、CSV、JSONL にエクスポート。
必要に応じて、Nuclei スキャン計画を生成（実行前に手動承認が必要）。

本プロジェクトは REST API、AI コーディングアシスタント（Cursor、Claude、LM Studio など）向けの MCP/Skill 統合、および最大 2 回までクエリを再検討する自己反映ループを備えています。

🚀 クイックスタート（5分）

# クローン & 仮想環境のセットアップ（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 .

# インストール確認
fofamap --version
fofamap --help

fofamap init を実行 – FOFA API キー（およびオプションで OpenAI/Anthropic などの AI キー）を保存するウィザードです。

クラシッククエリを実行：

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

エージェントに重い作業を任せます：
```
fofamap -ai 'Example会社の公開ウェブサイトを収集し、高信頼資産と検証が必要な候補を分類'
```
エージェントは以下の手順を実行します： 1️⃣ 自然言語を1つ以上の FOFA クエリに変換 2️⃣ クエリを実行し、ヒット数を評価。必要に応じてクエリを改善（最大2回） 3️⃣ 重複削除、証拠レベルの付与（corroborated, observed, candidate） 4️⃣ テーブルと Markdown レポートを出力

🛠️ コア機能

機能	得られるもの
クラシック FOFA CLI	`-q / -hq / -cq / -ico / -bq` – 完全な FOFA 構文、AI は不要
自然言語エージェント	`-ai` – 自動的に資産を計画・検討・要約
証拠のグレーディング	結果に明確な境界を持つ corroborated, observed, candidate をラベル付け
エクスポート形式	XLSX、CSV、JSONL；非常に大きな結果セットにはストリーミング対応
Nuclei 統合	スキャン計画を生成、ターゲット/テンプレート/深刻度を表示。実行前に一回限りの手動承認トークンが必要
MCP / Skill	Cursor、Claude、LM Studio などでの FofaMap をワンクリックでツールとして登録
REST API	OpenAPI 3.1 定義；`fofamap serve` を実行して HTTP で同じ機能を公開
クロスプラットフォーム	Windows、macOS、Linux で動作
セキュリティ最優先	可能であれば OS キークラウドに API キーを保存；クォータ、レート制限、権限問題の明確なエラーメッセージ

📚 エージェント（AIモード）の使い方

fofamap -ai '許可範囲内の中国地域の Example 製品の露出面を収集し、プロトコル、ポート、製品バージョンごとに要約。最大500件まで返す'

エージェントのワークフロー（README の mermaid 図を参照）：

リクエストを解析し、必要な FOFA サブクエリを決定。
各クエリを FOFA 構文および内蔵ルールライブラリで検証。
クエリを実行し、ヒットを収集。結果の品質が十分か確認。
不十分な場合、反映して改善されたクエリを生成（最大2回）。
重複削除し、証拠レベルを割り当てる。
テーブルと Markdown ブリーフィングを生成。常に以下の情報を含む：
- 高信頼資産
- ノイズ／偽陽性
- 見逃された証拠のギャップ
- 次のステップの推奨事項

🔧 Nuclei スキャン（承認ゲート付き）

Nuclei を別途インストール（projectdiscovery.com）し、PATH に追加されていることを確認。

スキャンを有効にする環境変数を設定：

export FOFAMAP_ENABLE_SCANNING=true
export FOFAMAP_SCAN_APPROVAL_SECRET='ランダムな高エントロピー文字列（≥24文字）'

-n（または --nuclei）を付けてクエリを実行。ツールは以下の動作をします：
- 実際のターゲットリスト、選択されたテンプレートID、深刻度フィルタを表示。
- 計画の確認（または編集）を求める。
- 承認後、選択されたテンプレートで nuclei を実行。
テンプレートセットをカスタマイズ可能：
```
fofamap -q 'domain="example.com"' -n \
    --nuclei-id cors-misconfig --nuclei-id tech-detect \
    --severity low,medium
```
完全スキャンには --nuclei-id all と --severity all を使用（ツールが強く警告します）。

📦 AI コーディングアシスタントとの統合（MCP/Skill）

# 対応するエージェント一覧
fofamap integrate --list
# Cursor 用のインストール（例）
fofamap integrate --agent cursor
# アンインストール
fofamap integrate --agent cursor --uninstall

インストーラーは小さなラッパー（fofamap-mcp）を書き込み、ホスト IDE がこれをツールとして呼び出せるようにします。シークレットはコピーされず、ラッパーは既存の Python 環境を指すだけです。

🗂️ プロジェクト構造（概要）

FofaMap/
├─ config/            # 例設定、.env テンプレート
├─ docs/              # エージェント統合ガイド、監査ドキュメントなど
├─ fofamap/           # コアパッケージ（CLI、エージェント、MCP、REST）
├─ results/           # デフォルト出力ディレクトリ（タイムスタンプ付きサブフォルダ）
├─ tests/             # ユニット／統合テスト
└─ setup.py / pyproject.toml

🧩 どのエントリポイントを選ぶべきか

エントリポイント	FOFAキーが必要	AIキーが必要	最適な用途
インタラクティブ CLI / クラシック `-q`	✅	❌	クラシック FOFA 構文がわかっている、即時確認
ローカル `-ai` エージェント	✅	✅	自然言語による探索、証拠グレーディングレポート
MCP / Skill	✅	❌*	Cursor、Claude、LM Studio などから使用（ホストが独自の LLM を提供）

❓ 一般的な質問

有料の FOFA アカウントが必要ですか？ はい。本ツールは FOFA API を使用しており、取得できるデータ量は会員レベルに依存します。
AI はマシン上でコマンドを実行できますか？ いいえ。エージェントは FOFA の呼び出し、データ処理、および（オプションで）Nuclei 計画の準備のみを行います。Nuclei の実行は手動承認で制限されています。
どの AI プロバイダーがサポートされていますか？ OpenAI、Anthropic、DeepSeek、Ollama、LM Studio、および OpenAI 形式互換エンドポイント。
API キーはどこに保存されますか？ OS キークラウド（macOS Keychain、Linux Secret Service、Windows Credential Manager）を優先。利用不可の場合は、0600 権限でローカルファイルに保存するか尋ねられます。

📦 インストール・アップグレードノート

仮想環境内で pip install -e . でインストール。

アップグレードには：

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

メジャーバージョンアップ後は、以前に保存された FOFA キーをローテーション（MIGRATION.md を参照）。

🔗 有用なリンク

リリース: https://github.com/asaotomo/FofaMap/releases/tag/v2.0.1
ドキュメントインデックス: docs/（エージェント統合、REST OpenAPI、セキュリティポリシー）
イシュー追跡: バグや機能リクエストは GitHub Issues を開いてください。

TL;DR

FofaMap はセキュリティ研究者やレッドチームが、FOFA を直接クエリするか、自然言語で検索し、検索を自動的に最適化し、証拠をグレーディングし、必要に応じて人間の承認を経て Nuclei スキャンを実行できる一元的なクロスプラットフォーム CLI を提供。REST API や AI コーディングアシスタント内でのツールとしても呼び出せます。