Netw0rkNoob/VulnClaw

VulnClaw – AI‑driven penetration‑testing CLI

What it is – VulnClaw is a Python‑based command‑line (and optional web/TUI) tool that lets a user describe a penetration‑testing goal in natural language. An LLM‑powered agent then drives the whole testing workflow: reconnaissance, vulnerability discovery, exploitation, and report generation. The agent decides which tools to call, when to ask for clarification, and when a finding is solid enough to be reported.

Key capabilities

• Model‑led solve engine – The LLM runs a self‑directed loop, choosing tools and deciding when a task is finished. No fixed stage script is imposed.
• Evidence memory – Every real tool output is stored in AgentState.evidence. The agent can search or view raw evidence, and a “anti‑hallucination gate” only accepts conclusions that appear in that evidence.
• MCP toolchain – Built‑in services (fetch, memory) plus optional Chrome‑DevTools and Burp Suite MCP servers for browser automation and HTTP replay.
• Rich built‑in tools – HTTP fetching, batch probing, nmap scanning, shell command execution, Python code execution, 29 crypto/encoding helpers, source extraction, runtime diff probing, etc.
• Plugin system – Low‑coupling vulnerability‑detection plugins (e.g., web header analysis) that feed results into the report pipeline.
• Skill references – 50+ knowledge‑base “skills” (CTF, web, Android, crypto, OSINT, etc.) that the model can load on demand as reference material.
• Multi‑provider LLM support – Works with OpenAI, Anthropic, MiniMax, DeepSeek, Zhipu, Moonshot, Qwen, SiliconFlow, Doubao, StepFun, SenseTime, OpenRouter, Ollama and custom endpoints.
• Output – Generates a structured Markdown report and a runnable Python PoC script for each confirmed vulnerability.
• Interfaces – Plain CLI/REPL, a terminal UI (TUI) built with Rust, and an optional web UI (React front‑end).

Quick start

# Install from PyPI (recommended)
pip install vulnclaw

# Or install from source
git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClaw
pip install -e .

# Configure an LLM provider (example: OpenAI)
vulnclaw config provider openai
vulnclaw config set llm.api_key sk-YOUR_KEY

# Run a full test in one command
vulnclaw run http://target.example.com

The command launches the model‑led loop, automatically performing reconnaissance, scanning, exploitation, and finally writing reports/<target>_YYYYMMDD.md and pocs/<CVE>.py.

Typical workflows

Mode	How to start	When to use
CLI / REPL	vulnclaw (or vulnclaw repl)	Interactive, step‑by‑step testing, quick experiments
One‑shot	vulnclaw run <target>	Fully automated test with default solve engine
Targeted stage	vulnclaw recon <target> / vulnclaw scan <target> / vulnclaw exploit <target>	Run only a specific phase
Persistent	vulnclaw persistent <target>	Long‑running, cyclic testing (default 100 rounds per cycle, 10 cycles)
Web UI	vulnclaw web (default http://127.0.0.1:7788)	Browser‑based control and visualisation
TUI	vulnclaw tui	Terminal‑graphical dashboard with draggable panels

Architecture at a glance

• Agent core (agent/core.py) – orchestrates the solve loop, maintains AgentState and enforces evidence gates.
• Solver (agent/solver.py) – implements the model‑led reasoning cycle, handling tool calls, retries, and stall guards.
• MCP layer (mcp/registry.py, router.py) – registers local tools (fetch, memory) and external services (Chrome‑DevTools, Burp) and routes LLM tool‑call requests.
• Plugins (plugins/) – modular vulnerability detectors that run in isolation and return structured findings.
• Skills (skills/) – reference documents (PDF/MD) that the LLM can load on demand via load_skill_reference.
• Report generator (report/generator.py) – assembles a markdown summary and PoC code from the collected evidence without further LLM calls.

Safety note – The tool is explicitly marked “Authorized‑Only”. It is intended for use on systems you have permission to test (e.g., CTF challenges, red‑team exercises, security training). The repository includes a doctor command to verify that required binaries (nmap, node, etc.) are present before running.

---

For a full English‑language README see README_EN.md in the repository.