Netw0rkNoob/VulnClaw

VulnClaw – AI 기반의 펜테스트 CLI

무엇인가요 – VulnClaw는 사용자가 자연어로 펜테스트 목표를 설명할 수 있는 Python 기반의 명령줄 도구(옵션으로 웹/TUI)입니다. LLM 기반의 에이전트가 리콘나이선스, 취약점 탐지, 공격, 보고서 생성까지 전체 테스트 워크플로우를 제어합니다. 에이전트는 어떤 도구를 호출할지, 언제 확인을 요청할지, 어떤 발견이 보고할 만큼 확실한지 결정합니다.

주요 기능

• 모델 주도의 해결 엔진 – LLM이 자기 주도 루프를 실행하며 도구를 선택하고 작업이 완료되었는지 판단합니다. 고정된 단계 스크립트는 강제되지 않습니다.
• 증거 메모리 – 모든 실제 도구 출력은 AgentState.evidence에 저장됩니다. 에이전트는 증거를 검색하거나 원시 데이터를 확인할 수 있으며, "반-허구 게이트"는 증거에 나타나는 결론만 허용합니다.
• MCP 툴체인 – 내장 서비스(fetch, memory)와 옵션으로 Chrome-DevTools 및 Burp Suite MCP 서버를 통해 브라우저 자동화 및 HTTP 재생을 지원합니다.
• 풍부한 내장 도구 – HTTP 가져오기, 배치 탐색, nmap 스캔, 쉘 명령 실행, Python 코드 실행, 29개의 암호/인코딩 헬퍼, 소스 추출, 런타임 차이 탐색 등.
• 플러그인 시스템 – 웹 헤더 분석 등 저결합의 취약점 탐지 플러그인으로 결과를 보고서 파이프라인에 전달합니다.
• 스킬 참조 – CTF, 웹, 안드로이드, 암호, OSINT 등 50개 이상의 지식 기반 "스킬"을 모델이 필요 시 로드할 수 있습니다.
• 다중 LLM 제공업체 지원 – OpenAI, Anthropic, MiniMax, DeepSeek, Zhipu, Moonshot, Qwen, SiliconFlow, Doubao, StepFun, SenseTime, OpenRouter, Ollama 및 사용자 정의 엔드포인트와 호환됩니다.
• 출력 – 확인된 각 취약점에 대해 구조화된 Markdown 보고서와 실행 가능한 Python PoC 스크립트를 생성합니다.
• 인터페이스 – 일반 CLI/REPL, Rust로 구축된 터미널 UI(TUI), 옵션 웹 UI(React 프론트엔드).

빠른 시작

# PyPI에서 설치 (권장)
pip install vulnclaw

# 소스에서 설치
git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClaw
pip install -e .

# LLM 제공업체 구성 (예: OpenAI)
vulnclaw config provider openai
vulnclaw config set llm.api_key sk-YOUR_KEY

# 한 명령어로 전체 테스트 실행
vulnclaw run http://target.example.com

이 명령어는 모델 주도 루프를 시작하여 자동으로 리콘나이선스, 스캔, 공격을 수행하고, 마침내 reports/<target>_YYYYMMDD.md와 pocs/<CVE>.py를 생성합니다.

일반적인 워크플로우

모드	시작 방법	사용 시기
CLI / REPL	vulnclaw (또는 vulnclaw repl)	인터랙티브한 단계별 테스트, 빠른 실험
원샷	vulnclaw run <target>	기본 해결 엔진으로 완전 자동화 테스트
대상 단계	vulnclaw recon <target> / vulnclaw scan <target> / vulnclaw exploit <target>	특정 단계만 실행
지속적	vulnclaw persistent <target>	장시간 실행, 순환 테스트 (기본 100라운드/사이클, 10사이클)
웹 UI	vulnclaw web (기본 http://127.0.0.1:7788)	브라우저 기반 제어 및 시각화
TUI	vulnclaw tui	드래그 가능한 패널을 가진 터미널 그래픽 대시보드

아키텍처 개요

• 에이전트 코어 (agent/core.py) – 솔브 루프를 오케스트레이션하고 AgentState를 유지하며 증거 게이트를 강제합니다.
• 솔버 (agent/solver.py) – 모델 기반 추론 루프를 구현하며 도구 호출, 재시도, 정지 가드를 처리합니다.
• MCP 계층 (mcp/registry.py, router.py) – 로컬 도구(fetch, memory)와 외부 서비스(Chrome-DevTools, Burp)를 등록하고 LLM 도구 호출 요청을 라우팅합니다.
• 플러그인 (plugins/) – 격리된 환경에서 실행되며 구조화된 발견 결과를 반환하는 모듈식 취약점 탐지기입니다.
• 스킬 (skills/) – 필요 시 load_skill_reference를 통해 모델이 로드할 수 있는 참조 문서(PDF/MD)입니다.
• 보고서 생성기 (report/generator.py) – 추가 LLM 호출 없이 수집된 증거에서 Markdown 요약과 PoC 코드를 조립합니다.

안전성 주의사항 – 이 도구는 명시적으로 "승인된 사용자 전용"으로 표시되어 있습니다. CTF 챌린지, 레드팀 연습, 보안 교육 등 테스트 대상 시스템에 허가가 있는 경우에만 사용하도록 의도되었습니다. 리포지토리에는 실행 전에 필요한 바이너리(nmap, node 등)가 존재하는지 확인하는 doctor 명령어가 포함되어 있습니다.

---

자세한 영문 README는 리포지토리 내 README_EN.md를 참조하세요.