VulnClaw 🦞

AI 기반 침투 테스트 CLI 도구 — 사람 말로, 취약점을 공략한다.

Kimi Open Source Friends

🌐 영어 버전: README_EN.md

이 프로젝트는 독립적으로 실행 가능한 AI 침투 테스트 Agent입니다.
프로젝트 공식 웹사이트: https://unclecheng-li.github.io/vulnclaw.com/

LLM Agent + MCP 도구 체인 + 선택적 Skill 참고 자료를 기반으로, OpenAI / Anthropic / MiniMax / DeepSeek 등 호환 모델과 함께, 자연어 입력 → 「정보 수집 → 취약점 발견 → 취약점 악용 → 보고서 생성」 전 과정을 자동으로 완료합니다.

빠른 시작 · 아키텍처 · 내장 Skill

무엇을 할 수 있나

자연어를 입력하면 AI가 침투 테스트 전 과정을 자동으로 수행합니다:

用户输入：帮我对 http://target.example.com 进行渗透测试

VulnClaw 自动执行：
  Round 1:  信息收集 → 指纹识别、端口扫描、目录枚举
  Round 2:  漏洞发现 → 检测注入点、已知 CVE、配置缺陷
  Round 3:  漏洞利用 → PoC 验证、权限获取
  Round 4:  报告生成 → 结构化报告 + Python PoC 脚本

승인된 침투 테스트, CTF 대회, 보안 교육, 레드팀 훈련 등의 시나리오에 적합합니다.

기능

모델 주도 솔루션 엔진(기본값) — Claude Code/Codex와 유사한 자율 루프로, 모델이 다음 단계를 스스로 결정하고, 언제 도구를 호출할지, 언제 완료/질문/막다른 길로 판정할지 결정합니다
AgentState 증거 기억 — 도구 결과는 통일적으로 AgentState.evidence에 기록되며 raw 원문은 완전히 보존됩니다. active context에는 기본적으로 고신호 미리보기만 주입되며, evidence_search / evidence_view는 필요 시 원본 증거를 다시 조회하는 데 사용됩니다
경량 교정 계층 — 도구 호출 전후에 중복 호출, 실패 강등, 소요 시간, 새로운 발견 등의 신호를 기록합니다. 동일한 evidence 범위를 반복해서 읽는 것은 억제되며, 연속적인 증거 공전은 stall guard를 트리거하지만 이전 단계 플래너를 복원하지는 않습니다
증거 수준 반환각 게이트 — 주장된 flag/결론은 실제 도구 출력에 문자 단위로 나타나야만 채택되어, flag를 허위로 날조하는 가짜 승리를 차단합니다
자연어 기반 — 일상 언어로 침투 의도를 설명하면 단계와 도구를 자동으로 식별합니다
13개 LLM Provider — OpenAI / Anthropic / MiniMax / DeepSeek / 智谱 / Moonshot / 千问 / SiliconFlow / 豆包 / 阶跃星辰 / 商汤 / OpenRouter / 로컬 Ollama, 원클릭 전환
MCP 도구 체인 — 4개 MCP 서비스: fetch / memory는 로컬 구현으로 즉시 사용 가능하며, chrome-devtools / burp는 외부 MCP 서비스와 연동하여 브라우저 자동화와 HTTP 패킷 캡처/재전송을 구현합니다
강화된 fetch 요청 도구 — 기본적으로 직접 GET하고 전체 응답 body를 반환하며, HTTP/HTTPS, 사용자 정의 method/headers/params/cookies/body/data/form/json, timeout/redirect/TLS 제어를 지원합니다. CTF/훈련장 HTTPS는 기본적으로 인증서를 검증하지 않습니다
네이티브 트래픽 증거 저장 — 실행 내 범위로 필터링한 후 추가 방식 JSONL 인덱스 + 요청별 원본 패킷을 evidence/traffic/에 저장하며, 내장 traffic_list / traffic_view / traffic_repeat / traffic_sitemap 도구로 직접 읽고 씁니다
AI Agent 코어 — OpenAI 호환 프로토콜 + Tool Calling + 자율 침투 루프
구조화 추론 + 적응형 성찰 — 알려진 사실/제약/공격 체인을 구조화하여 축적하며, 실패를 자동으로 분류하고 L0-L4 점진적 에스컬레이션으로 payload 우회 전략을 적용합니다
취약점 탐지 플러그인 체계 — 저결합 플러그인 런타임 + 내장 읽기 전용 Web 플러그인으로, 결과가 자동으로 보고서 체인에 통합됩니다(vulnclaw plugins)
50개 전문 Skill — CTF, Web, 내부망, 리버싱, 취약점 검증 및 승인된 레드팀 지식 베이스를 포괄합니다. Skill은 참고 자료 인덱스로만 모델에 노출되며, 본문은 모델이 load_skill_reference를 능동적으로 호출하여 필요 시 읽어야 하며, 더 이상 강제 시나리오로 컨텍스트에 주입되지 않습니다
인코딩/디코딩·암호화/복호화 도구 — 29가지 작업(Base64/Hex/URL/AES/JWT/Morse 등)으로, LLM이 정확하게 호출할 수 있으며 더 이상 추측에 의존하지 않습니다
소스 코드 자동 복원 — fetch / http_probe_batch가 highlight_file, HTML 하이라이트 소스 또는 HTML/JS가 혼재된 body를 만나면 자동으로 raw body 앞에 clean source를 추가합니다. http_probe_batch는 기본적으로 TLS 검증을 끄고 전체 응답 헤더를 기록하여 X-Powered-By 등 런타임 증거 손실을 방지합니다. 내장 source_extract는 여전히 필요 시 과거 evidence를 다시 읽는 데 사용할 수 있으며, 위험 sink, 폼, endpoint 신호를 고정합니다
로컬 명령 검증 — 내장 shell_command로 php -r 역직렬화 검증, curl 정밀 요청, rg/Select-String 파일 검색 등 Codex 스타일 로컬 디버깅 시나리오에 사용합니다. raw stdout/stderr는 완전히 evidence에 기록되며, 대용량 출력이 모델에 들어갈 때는 고신호 미리보기를 사용합니다
런타임 차분 탐지 — 내장 runtime_diff_probe로 정규식/문자열 필터와 런타임 파서가 불일치하는 시나리오에 사용하며, 모델이 "필터는 통과시키지 않지만 파서는 수용하는" 후보를 대량으로 생성하고 검증하도록 돕습니다. PHP 직렬화 모드에서는 대상/로컬 런타임 버전 차이를 알려주고, PHP5 signed length 후보를 반드시 원격 검증해야 한다고 표시하여 로컬 최신 PHP에 의해 잘못 차단되는 것을 방지합니다
Python 코드 실행 — 내장 python_execute 도구로 payload 구성과 응답 파싱에 적합합니다. 현재는 여전히 고위험 실험 기능이며 강력한 격리 샌드박스로 간주해서는 안 됩니다
배치 HTTP 탐지 — 내장 http_probe_batch로 한 번에 여러 URL/파라미터/header/body/raw URL 변형을 비교하며, 기본적으로 각 응답의 전체 body를 반환하고 모델 가시 출력에 실제 요청 면(method, URL, params, headers, cookies, body/json)을 표시하여 반복 LLM 라운드와 수작업 요청 코드를 줄입니다
근접 성공 방지 오탐 중단 — solve는 증거 게이트를 유지하며, 범용 NO_PATH 게이트를 새로 추가했습니다: 소스 sink, 폼/파라미터, 요청 표면, 로컬 proof 또는 응답 차이 등 고신호가 아직 소진되지 않은 경우, 모델이 단일 payload에 응답이 없거나 원격 same-body라는 이유만으로 조기에 실패로 판정하는 것을 허용하지 않습니다
지속적 침투 테스트 — 주기적 반복(기본 100회/주기 × 10주기 = 1000회), 각 주기마다 자동 보고서 생성
추론 과정 표시 제어 — think on/off 원클릭으로 LLM 사고 과정 표시/숨김 전환
샌드박스 모드 프롬프트 — AI 보안 테스트 기능을 해제하며, CTF / 승인된 침투 시나리오 전용
자동 보고서 & PoC — 구조화된 Markdown 보고서와 실행 가능한 Python PoC 스크립트 생성
Web UI 모드 — vulnclaw web으로 로컬 Web 인터페이스 시작, 기본 127.0.0.1:7788
보안 지식 베이스 — 지식 베이스 모듈과 기본 시드 데이터가 내장되어 있으며, 검색 증강은 점진적으로 메인 흐름에 통합 중입니다

빠른 시작

설치

# 从 PyPI 安装（推荐）
pip install vulnclaw

# 从源码安装
git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClaw
pip install -e .

Docker 실행(선택 사항)

이미지에는 Web UI와 기본 MCP 서비스에 필요한 런타임(npx / uvx)이 내장되어 있으며, 모든 상태는 /data 데이터 볼륨에 영구 저장됩니다.

cp .env.example .env          # 填入 VULNCLAW_LLM_API_KEY 等
docker compose up --build      # 构建镜像并启动 Web UI
# 打开 http://127.0.0.1:7788

也可用纯 docker 运行某条 CLI 命令：

docker run --rm -it \
  -e VULNCLAW_LLM_API_KEY=sk-your-key-here \
  -v vulnclaw-data:/data \
  vulnclaw:latest scan <target>

⚠️ 컨테이너 내부의 localhost는 컨테이너 자신을 가리킵니다. 호스트 머신의 서비스를 스캔하려면 host.docker.internal을 사용하고, 다른 컨테이너를 스캔하려면 네트워크를 공유하고 컨테이너 이름으로 접근하세요. 자세한 내용은 DOCKER.md를 참조하세요.

네 단계로 시작하기

# 1. 选择提供商（自动填充 Base URL 和模型名）
vulnclaw config provider minimax   (或 openai/anthropic/deepseek/zhipu/moonshot/qwen/siliconflow/ollama)

# 1.2（可选）自定义 Base URL 或模型名
vulnclaw config set llm.base_url https://your-own-api.example.com/v1 
vulnclaw config set llm.model your-model-name

# 2. 设置 API Key
vulnclaw config set llm.api_key sk-your-key-here
#    — 或改用 ChatGPT 订阅登录（无需 API Key）：
#      vulnclaw login   （浏览器登录；注意 ToS 风险）

# 3. 默认：打开原 CLI / REPL
vulnclaw

# 4. 可选：打开 TUI 工作台
vulnclaw tui

환경 확인

vulnclaw doctor

출력 예시:

🦞 VulnClaw 环境检查

  Python: 3.14.4
  Node.js: v24.14.1
  npx: 已安装
  nmap: 已安装

LLM 配置:
  Provider: openai
  Auth Mode: static
  Credentials: configured
  Base URL: https://api.openai.com/v1
  Model: gpt-4o

MCP 服务:
  fetch: 已启用 [P0]
  memory: 已启用 [P0]
  ...

✅ 环境就绪，运行 vulnclaw 开始

CLI 명령 빠른 참조

$ vulnclaw --help

🦞 VulnClaw — AI-powered penetration testing CLI

 Usage: vulnclaw [OPTIONS] COMMAND [ARGS]...

인기

VulnClaw