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
  1. fofamap init 실행 – FOFA API 키 (옵션으로 OpenAI/Anthropic 등 AI 모드용 키)를 저장하는 마법사입니다.
  2. 전통적인 쿼리 실행:
    fofamap -q 'app="nginx" && country="CN"' -p 2 --size 100
  3. 에이전트에게 무거운 작업을 맡기기:
    fofamap -ai 'Example 회사의 공개 웹사이트를 수집하고, 고신뢰 자산과 검증이 필요한 후보를 구분'
    에이전트는 다음을 수행합니다: 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 다이어그램 참조):

  1. 요청을 분석하고 필요한 FOFA 하위 쿼리 결정.
  2. 각 쿼리를 FOFA 구문 및 내장 규칙 라이브러리로 검증.
  3. 쿼리를 실행하고 히트를 수집, 결과 품질이 충분한지 확인.
  4. 충분하지 않으면 반성하여 개선된 쿼리 생성 (최대 2회 반복).
  5. 중복 제거 및 증거 수준 할당.
  6. 표와 Markdown 브리핑 생성. 항상 다음을 포함:
    • 고신뢰 자산
    • 노이즈/거짓 긍정
    • 확인되지 않은 증거 갭
    • 다음 단계 추천

🔧 Nuclei 스캔 (승인 게이트)

  1. Nuclei를 별도로 설치 (projectdiscovery.com)하고 PATH에 포함되어 있는지 확인.
  2. 스캔 활성화 환경 변수 설정:
    export FOFAMAP_ENABLE_SCANNING=true
export FOFAMAP_SCAN_APPROVAL_SECRET='랜덤한 고엔트로피 문자열 (≥24자)'
  3. -n (또는 --nuclei) 옵션으로 쿼리 실행. 도구는 다음을 수행:
    • 정확한 타겟 목록, 선택된 템플릿 ID, 심각도 필터 표시.
    • 계획 확인 (또는 수정) 요청.
    • 승인 후 선택된 템플릿으로 nuclei 실행.
  4. 템플릿 세트 커스터마이징 가능:
    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 참조).

🔗 유용한 링크

TL;DR

FofaMap은 보안 연구자와 레드팀이 FOFA를 직접 쿼리하거나 자연어로 검색하여, 검색을 자동으로 최적화, 증거를 등급화, 필요 시 사람의 승인을 거쳐 Nuclei 스캔을 게이트할 수 있는 단일 크로스플랫폼 CLI를 제공합니다. REST API 또는 AI 코딩 보조 도구 내에서 도구로도 호출 가능합니다.

관련

  • 프로젝트
    YUHAI0/fin-agent

    LLM과 Tushare 데이터를 활용한 AI 기반 금융 분석 어시스턴트로, 자연어를 통한 주식 스크리닝, 전략 백테스트, 포트폴리오 모니터링을 가능하게 합니다.

  • 프로젝트
    Kritt-ai/open-kritt

    open·kritt는 Codex, Claude Code, Grok Build 등으로 AI 에이전트를 오케스트레이션하는 오픈소스이며 자체 호스팅 가능한 플랫폼으로, 코드 리포지토리에서 사용자 정의 프롬프트 기반 보안 워크플로우를 실행합니다. 집중된 작업을 구성하고, 병렬로 Docker 컨테이너에서 실행하며, 발견 결과를 검증하고 중복 제거 및 순위 매기고, 완전한 보고서 번들을 내보냅니다. 버그 바운티 연구자와 DevSecOps를 위한 웹 UI와 헤드리스 CLI를 제공하며, 모든 모델 제공자와 호환되며 AGPL-3.0 라이선스로 배포됩니다.

  • 프로젝트
    StanleyNull/AutoHunter

    AutoHunter는 웹 취약점을 지속적으로 탐색하는 AI 기반 Docker 플랫폼입니다. LLM 가이드 에이전트(Collector, Worker, Reviewer)와 nmap, nuclei, sqlmap 같은 실제 도구를 결합하여 운영하며, 최종 검토만 사람이 수행합니다. 다양한 검색 엔진(FOFA, Quake, Shodan 등)을 지원하고 Vue 대시보드를 제공하며, 데이터는 SQLite에 저장됩니다. Apache 2.0 라이선스로 배포되며, 승인된 보안 테스트 용도로만 사용해야 합니다.