PhantomRecon

PhantomRecon은 AI(Agent Development Kit - ADK를 통한 Google Gemini) 기반의 자율적 공격적 보안 워크플로를 시연하도록 설계된 CLI 기반의 모듈식 에이전트 중심 레드팀 자동화 도구입니다.

빠른 시작 (CLI)

• 대화형 콘솔 실행(metasploit 스타일):
  root@kitploit:~

  python -m phantomrecon
  

• 일회성 비대화형 실행:
  root@kitploit:~

  python -m phantomrecon --target example.com --auto \
    --nmap-timeout 30 --nmap-top-ports 100 --nmap-args "-sV -Pn"
  

CLI 옵션

• --target <domain|ip>: 평가할 대상
• --auto: 정찰 → 계획 → 라우팅 → 보고서 실행
• --nmap-timeout <seconds>: NMAP_TIMEOUT 재정의
• --nmap-top-ports <N>: NMAP_TOP_PORTS 재정의
• --nmap-args "...": Nmap 인수(NMAP_ARGS)에 추가
• --nmap-disable: Nmap 비활성화(NMAP_DISABLE=1 설정)

환경 변수도 직접 지원됩니다: NMAP_TIMEOUT, NMAP_TOP_PORTS, NMAP_ARGS, NMAP_DISABLE.

운영상 유의사항

• 보고서는 버전 관리되지 않습니다. .gitignore는 reports/sample_report.md를 제외한 reports/*를 추적 대상에서 제외합니다.
• 생성된 HTML/MD 보고서는 로컬에서만 reports/ 아래에 저장됩니다.
• 필요에 따라 보고서를 삭제하거나 교체하십시오. 보고서는 커밋에 업로드되지 않습니다.

개념 증명(proof-of-concept)으로 제작된 이 도구는 대상 식별, 광범위한 정찰(Nmap, DNS, 웹 검색) 수행, LLM을 사용한 공격 전략 계획, 시뮬레이션된 익스플로잇의 조건부 실행, 보고서 생성을 시뮬레이션합니다.

프로젝트 구조

phantomrecon/
├── phantomrecon/             # Main package (exported orchestrator agent)
│   ├── __init__.py
│   ├── __main__.py           # CLI entrypoint (interactive and non-interactive)
│   └── agent/                # Agent graph and tools
├── agents/                   # Python modules containing agent/tool logic
│   ├── recon_logic.py        # Nmap, DNS (dig), seeded web analysis; ADK search enabled
│   ├── routing_logic.py      # Logic for the Exploit Router agent
│   ├── exploit_web_logic.py  # Functions for web exploits (currently simulated)
│   ├── exploit_sql_logic.py  # Functions for SQL exploits (currently simulated)
│   └── report_logic.py       # Functions for report generation using session state
├── configs/
│   └── targets.json          # (Optional) Target configuration
├── data/
│   └── dummy_scan_output.json # Example Nmap data if no target specified
├── demos/
│   └── walkthrough.md        # Demo steps
├── prompts/                  # Prompt templates for LLM agents
├── reports/
│   └── sample_report.md      # Example output report
├── requirements.txt          # Python dependencies (includes google-adk)
├── .gitignore                # Files excluded from version control
└── LICENSE                   # MIT License

현재 워크플로

1. 병렬 정찰(recon_workflow - 병렬 에이전트):
   • Nmap 스캔 실행(nmap_tool)
   • DNS/WHOIS 조회 실행(dns_tool)
   • 웹 검색 시뮬레이션(web_search_tool)
   • 상태: 각 도구는 결과를 세션 상태에 기록합니다.
2. 집계(aggregation_tool):
   • 병렬 워크플로의 결과를 결합합니다.
   • 상태: aggregated_recon_data를 세션 상태에 기록합니다.
3. LLM 계획(planning_agent - LlmAgent):
   • 집계된 데이터를 수신합니다.
   • Gemini와 attack_planner_prompt.txt를 사용하여 JSON 공격 계획을 생성합니다.
   • 상태: attack_plan을 세션 상태에 기록합니다.
4. 익스플로잇 라우팅(exploit_router - RouterAgent):
   • 상태에서 attack_plan을 읽습니다.
   • 계획에 따라 특정 익스플로잇 도구(web_exploit_tool, sql_exploit_tool)를 조건부로 실행합니다.
   • 상태: 익스플로잇 도구는 결과를 세션 상태의 exploit_results 목록에 추가합니다.
5. 보고(report_tool):
   • 세션 상태에서 관련 데이터(정찰, 계획, 결과)를 모두 읽습니다.
   • 최종 Markdown 보고서 파일을 생성합니다.

설정

1. 저장소를 클론합니다.
2. 필수 구성 요소가 설치되어 있는지 확인합니다: python3, pip, nmap, dig, whois, sqlmap, wapiti, wpscan, searchsploit.
3. 가상 환경을 생성합니다:
   root@kitploit:~

   python3 -m venv venv
   source venv/bin/activate  # On Windows use `venv\Scripts\activate`
   

4. 의존성을 설치합니다:
   root@kitploit:~

   pip install -r requirements.txt
   

5. API 키를 구성합니다 (env):
   • .env.example을 .env로 복사하거나(예시 파일이 있는 경우) .env를 편집합니다.
   • GOOGLE_API_KEY 변수에 Google API 키(AI Studio 또는 Vertex AI 설정에서)를 추가합니다.
   • Vertex AI를 사용하는 경우 GOOGLE_GENAI_USE_VERTEXAI를 True 또는 False로 설정하고 관련 변수(GOOGLE_CLOUD_PROJECT, GOOGLE_CLOUD_LOCATION)를 구성합니다.
6. 도구를 실행합니다:
   • CLI 대화형: python -m phantomrecon
   • CLI 일회성: python -m phantomrecon --target <target> --auto
   • ADK 러너(선택 사항): adk run phantomrecon

보안 공지

이 도구는 승인된 보안 테스트 및 교육 목적으로만 사용해야 합니다. 명시적 허가 없이 시스템에 사용하지 마십시오.

라이선스

이 프로젝트는 MIT 라이선스에 따라 라이선스가 부여됩니다 - 자세한 내용은 LICENSE 파일을 참조하세요.

사전 요구 사항

• Python 3.9+
• pip (Python 패키지 설치 관리자)
• Nmap (sudo apt install nmap 또는 brew install nmap)
• dig (sudo apt install dnsutils 또는 brew install bind)
• whois (sudo apt install whois 또는 brew install whois)
• sqlmap (sudo apt install sqlmap 또는 brew install sqlmap)
• wapiti (sudo apt install wapiti 또는 brew install wapiti)
• wpscan (sudo apt install ruby-full 그런 다음 gem install wpscan 또는 brew install wpscan)
• searchsploit (sudo apt install exploitdb 또는 brew install exploitdb)
• Gemini API가 활성화된 Google Cloud 프로젝트.
• Gemini API용 API 키.
• requirements.txt에 나열된 Python 라이브러리(pip install -r requirements.txt로 설치)

주요 기능

• 에이전트 기반 워크플로: 모듈식 구조를 위해 Google의 Agent Development Kit(ADK)을 활용합니다.
• 대화형 대상 입력: adk web 인터페이스를 사용하여 사용자에게 대상 IP/도메인을 요청합니다.
• 다단계 평가:
  • 정찰:
    • Nmap 포트 스캐닝(실제)
    • 향상된 DNS/WHOIS 조회(실제: dig, nslookup, dig +trace, AXFR 시도, whois)
    • 웹 검색(실제, Google 검색 사용)
    • 향상된 웹 콘텐츠 분석(실제: 링크, 폼, 주석, 스크립트, 헤더, 이메일, 기본 기술 탐지)
    • 데이터 집계
  • 계획: LLM(Gemini)이 정찰 데이터를 분석하여 우선순위가 지정된 공격 계획을 생성합니다(검증 포함).
  • 익스플로잇(조건부 라우팅): 계획에 따라 테스트를 실행합니다:
    • 웹: 기본 파일, 잘못된 구성(디렉터리 목록), SQL 인젝션(정제된 옵션을 사용한 sqlmap), Wapiti 스캔(구문 분석된 결과), WPScan(구문 분석된 결과, 조건부), 기본 반사형 XSS, 기본 명령 인젝션 - (실제 점검)
    • SQL: 기본 자격 증명(MySQL/PostgreSQL), 버전 취약점(정제된 쿼리를 사용한 searchsploit), 인증 후 열거(sqlmap 직접 연결) - (실제 점검)
    • SSH: 취약한 자격 증명, 버전 취약점(정제된 쿼리를 사용한 searchsploit), 구성 감사(ssh-audit 사용, 구문 분석된 결과) - (실제 점검)
  • 보고: Markdown 요약 보고서를 생성합니다.
• 상태 관리: ADK의 ToolContext를 사용하여 에이전트/도구 간에 데이터를 전달합니다.

아키텍처 (자율 멀티 에이전트 시스템)

PhantomRecon은 Google의 Agent Development Kit(ADK)을 기반으로 하는 완전 자율 멀티 에이전트 아키텍처를 사용합니다.

핵심 구성 요소

시니어 오케스트레이터 에이전트 (gemini-1.5-pro-latest)

• 자율적 의사 결정 및 전략 수립
• 호출할 전문 에이전트를 동적으로 선택
• 발견 사항에 따라 반복 수행(고정된 순서 없음)
• 완전한 자율성으로 포괄적인 보안 감사 수행

전문화된 보안 에이전트

• 정찰 에이전트: 포트 스캐닝, DNS 열거, 서비스 탐지
• 웹 보안 전문가: XSS, CSRF, SSRF, 경로 탐색, 오픈 리다이렉트
• SQL 인젝션 전문가: 주요 데이터베이스 전반의 모든 SQL 인젝션 기법
• SSH/네트워크 전문가: SSH 보안 감사, 네트워크 서비스 테스트
• 인증 전문가: 인증 우회, 세션 보안, 권한 상승
• 계획 에이전트: 발견 사항에 기반한 전략적 공격 계획
• 보고 에이전트: 포괄적인 보안 보고서 생성

자율 운영

오케스트레이터는 시니어 침투 테스터처럼 작동합니다:

1. 대상 도메인/IP를 입력받습니다.
2. 정찰 전략을 계획합니다.
3. 발견 사항을 분석하고 공격 표면을 식별합니다.
4. 발견 사항에 따라 전문 에이전트를 동적으로 호출합니다.
5. 새로운 정보가 나타나면 접근 방식을 반복하고 조정합니다.
6. 포괄적인 보안 감사 보고서를 생성합니다.

주요 특징:

• 고정된 워크플로 없음 - 오케스트레이터가 전략을 결정
• 효율성을 위한 병렬 에이전트 실행
• 발견된 취약점에 대한 반복적 심층 분석
• 대상 특성에 따른 적응형 접근
• 대상 입력부터 최종 보고서까지 완전한 자율성

기술 세부 사항

• context.session.state(ADK 세션)를 통한 상태 관리
• 실시간 진행 상황 시각화(Rich 라이브러리)를 통한 병렬 정찰
• 시간 제한이 있는 비동기 명령 실행(executor_fix.py)
• 구성 가능한 스캔 매개변수(Nmap 등용 환경 변수)

사용법

CLI로 실행(권장):

python -m phantomrecon --target <domain|ip> --auto

대화형 콘솔:

python -m phantomrecon

선택적 ADK 러너:

adk run phantomrecon -- --target <domain|ip> --auto