Netw0rkNoob/VulnClaw

VulnClaw – AI‑driven penetration‑testing assistant

What it is – VulnClaw is a Python‑based command‑line (and optional web/TUI) tool that lets a user describe a penetration‑testing job in natural language. It then drives a large language model (LLM) to run the whole testing workflow: reconnaissance, vulnerability discovery, exploitation, and report generation. The LLM decides which built‑in tools to call and when, while the framework records every tool’s raw output as evidence that the model must cite before claiming a finding.

Key capabilities

• Model‑led solve engine – The LLM controls the loop (similar to Claude‑Code), choosing tools, interpreting results, and deciding when the job is finished.
• Evidence memory – All tool results are stored in AgentState.evidence. The model can only declare a flag or vulnerability if the exact string appears in that evidence, preventing hallucinated results.
• MCP toolchain – A small “Model‑Context‑Protocol” layer provides services such as fetch (HTTP client), memory (local JSON store), and optional external services (chrome‑devtools, burp) for browser automation and traffic replay.
• Rich built‑in tools – HTTP probing (single and batch), nmap scanning, shell command execution, Python code execution, 29 crypto/encoding helpers, source extraction, runtime diff probing, etc.
• Skill references – Over 50 knowledge‑base “skills” (web pentest, CTF, crypto, Android, etc.) are available for the model to load on demand, giving it contextual guidance without hard‑coding scripts.
• Multi‑provider LLM support – Works with OpenAI, Anthropic, MiniMax, DeepSeek, Zhipu, Moonshot, Qwen, SiliconFlow, Doubao, Baichuan, StepFun, SenseTime, Yi, and local Ollama models.
• Output – Generates a structured Markdown report and a runnable Python PoC script for any discovered vulnerability.
• Interfaces – CLI REPL, Typer‑based sub‑commands, a terminal UI (vulnclaw tui), and an optional web UI (vulnclaw web). Docker images are provided for easy deployment.

Typical workflow

1. Configure an LLM provider and API key (vulnclaw config provider openai).
2. Run a command, e.g. vulnclaw run http://target.example.com or start the REPL and type a natural‑language request.
3. The model initiates rounds:
   • Round 1: reconnaissance (port scan, fingerprinting, directory enumeration).
   • Round 2: vulnerability discovery (CVE checks, injection points).
   • Round 3: exploitation (PoC validation, privilege escalation).
   • Round 4: report generation.
4. All tool calls are logged as evidence; the model must reference that evidence to claim a flag.
5. A Markdown report and PoC script are written to ./reports/ and ./pocs/.

Why it matters – VulnClaw showcases how LLMs can be harnessed for autonomous security testing while mitigating classic hallucination risks through evidence‑gating. It bundles the necessary plumbing (tool orchestration, memory, multi‑provider LLM access) into a single installable package, making AI‑augmented pentesting more approachable for authorized red‑team work, CTFs, or security training.

---

Quick start

pip install vulnclaw          # or `pip install -e .` from source
vulnclaw config provider openai
vulnclaw config set llm.api_key sk-xxxx
vulnclaw run http://target.example.com

Documentation links – English README (README_EN.md), Docker guide (DOCKER.md), MCP deployment docs, and full CLI reference are included in the repository.