What It Does

Give it a natural language command and watch it run a full pentest:

User:   "Run a penetration test on http://target.example.com"

VulnClaw executes:
  Round 1:  Recon → Fingerprinting, port scan, directory enumeration
  Round 2:  Vulnerability Discovery → Injection points, known CVEs, misconfigs
  Round 3:  Exploitation → PoC verification, access obtained
  Round 4:  Reporting → Structured report + Python PoC script

Suitable for authorized pentests, CTF competitions, security training, and red team operations.

Features

• Model-Led Solver Engine (default) — Claude Code/Codex-style autonomous loop: the model decides the next action, tool usage, completion, user questions, or no-path termination
• Parallel Sub-Agent Fan-Out — The model can spawn multiple independent sub-agents in a single turn via spawn_subagents; each sub-agent inherits target constraints and evidence, runs concurrently with its own lifecycle budget; sub-evidence is merged back into the parent state with unified eNNN renumbering
• Cold/Hot Memory Separation — Hot conversation context retains only recent complete tool-exchange groups (default 48 messages / 32K tokens); older messages are archived to rotating JSONL shards; memory_search retrieves relevant archived turns on demand
• Unified Context Budget & Structured Compaction — All LLM call paths go through prepare_context(), which estimates tokens (including tool schemas), triggers structured compaction at 70% of usable context, and generates a deterministic [context digest v1] summary (target/scope/verified facts/evidence references) — no LLM free-form summarization needed
• TUI Sub-Agent Monitor — Real-time panel showing each sub-agent's role, status, step count, and latest progress via a private JSON-line protocol
• AgentState Evidence Memory — Tool results are stored in AgentState.evidence with complete raw text preserved; active context receives bounded high-signal previews by default, while evidence_search / evidence_view revisit raw evidence on demand
• Lightweight Correction Layer — Records repeated calls, degraded tools, timing, and new observations; repeated reads of the same evidence range are suppressed and evidence-only stalls trigger a stall guard without restoring the old stage planner
• Evidence-Level Anti-Hallucination Gate — Claims about flags/conclusions must appear verbatim in real tool output to be accepted; prevents fabricated flags
• Natural Language Driven — Describe your goal in plain English, auto-identifies phases and tools
• 13 LLM Providers — OpenAI / Anthropic / MiniMax / DeepSeek / Zhipu / Moonshot / Qwen / SiliconFlow / Doubao / StepFun / SenseTime / OpenRouter / local Ollama, one-command switch
• MCP Toolchain — 4 MCP services: fetch / memory run locally out-of-the-box, chrome-devtools / burp connect to external MCP servers for browser automation and HTTP interception
• Enhanced fetch request tool — Defaults to GET, returns the full response body, and supports HTTP/HTTPS, custom method/headers/params/cookies/body/data/form/json, timeout/redirect/TLS controls; TLS verification is off by default for CTF/lab HTTPS targets
• Native Traffic Evidence Store — In-scope request/response pairs land in an append-only JSONL index under evidence/traffic/. Built-in traffic_list / traffic_view / traffic_repeat / traffic_sitemap tools read and replay the store
• AI Agent Core — OpenAI-compatible protocol + Tool Calling + autonomous pentest loop
• Structured Reasoning + Adaptive Reflection — Facts/constraints/attack chains structured and injected into prompts; failures auto-classified with L0-L4 payload escalation
• Vulnerability Detection Plugin System — Low-coupling plugin runtime + built-in read-only Web plugins, results auto-merged into reports (vulnclaw plugins)
• 50 Specialized Skills — CTF, Web, intranet, reversing, vulnerability validation, and authorized red-team knowledge; skills are exposed as optional reference indexes only, and full reference bodies are loaded only when the model explicitly calls load_skill_reference
• Encode/Decode & Crypto Tools — 29 operations (Base64/Hex/URL/AES/JWT/Morse etc.), LLM calls them directly, no guessing
• Automatic Source Rendering — fetch / http_probe_batch automatically prepend clean source before raw bodies when they see highlight_file, highlighted HTML source, or noisy HTML/JS bodies; http_probe_batch disables TLS verification by default and records full response headers so runtime clues such as X-Powered-By are not lost; built-in source_extract remains available for revisiting saved evidence and pinning dangerous sinks, forms, inputs, and endpoints
• Local Command Verification — Built-in shell_command supports Codex-style local checks such as php -r serialization tests, exact curl requests, and rg/Select-String file searches; raw stdout/stderr are preserved in evidence, and large active-context observations use high-signal previews
• Runtime Differential Probing — Built-in runtime_diff_probe helps the model build compact local tables for regex/string-filter vs runtime-parser mismatches, including PHP serialize/unserialize lexical variants, target/local runtime version mismatch notes, and PHP5 signed-length candidates that must be verified remotely instead of being discarded due to newer local PHP behavior
• Python Code Execution — Built-in python_execute tool for payload crafting and response parsing; currently still a high-risk experimental capability, not a strong isolation sandbox
• Batch HTTP Probing — Built-in http_probe_batch compares URL/parameter/header/body/raw-URL variants in one call, preserves each raw response body in evidence, and shows the audited request surface plus high-signal response preview in model-visible output to reduce repeated LLM/tool rounds
• Near-Miss Stop Guard — solve keeps the evidence gate and adds a generic NO_PATH guard: when unresolved high-signal anchors such as source sinks, forms/parameters, request surfaces, local proof or response differentials exist, a single no-output/same-body payload attempt is not accepted as proof that the path is dead
• Persistent Pentesting — Cyclic runs (100 rounds/cycle × 10 cycles = 1000 rounds), auto-reports every cycle
• Thinking Process Control — think on/off toggles LLM reasoning visibility
• Sandbox Mode Prompting — Unlocks AI security testing capabilities, for CTF and authorized pentest scenarios
• Auto Report & PoC — Generates structured Markdown reports and runnable Python PoC scripts
• Web UI Mode — vulnclaw web launches a local web interface, default 127.0.0.1:7788
• Security Knowledge Base — Includes KB module and baseline seed data; retrieval augmentation being integrated
• CONTRIBUTING_EN.md — English contributing guide for international contributors

Quick Start

Installation

# Install from PyPI (recommended)
pip install vulnclaw

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

Run with Docker (optional)

The image bundles the Web UI plus runtimes (npx / uvx) for default MCP servers. All state persists in a /data volume.

cp .env.example .env          # add VULNCLAW_LLM_API_KEY etc.
docker compose up --build      # build the image and start the Web UI
# open http://127.0.0.1:7788

Or run a one-off CLI command:

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

⚠️ localhost inside the container refers to the container itself. To scan a host service use host.docker.internal. See DOCKER.md.

Four-Step Launch

# 1. Select provider (auto-fills Base URL and model name)
vulnclaw config provider minimax   # or openai / anthropic / deepseek / zhipu / moonshot / qwen / siliconflow / ollama

# 1.2 (optional) custom Base URL or model name
vulnclaw config set llm.base_url https://your-own-api.example.com/v1
vulnclaw config set llm.model your-model-name

# 2. Set API Key
vulnclaw config set llm.api_key sk-your-key-here
#    — or sign in with ChatGPT subscription (no API key needed):
#      vulnclaw login   (browser sign-in; note ToS caveat)

# 3. Default: open the original CLI / REPL
vulnclaw

# 4. Optional: open the TUI workbench
vulnclaw tui

Environment Check

vulnclaw doctor

Sample output:

🦞 VulnClaw Environment Check

  Python: 3.14.4
  Node.js: v24.14.1
  npx: installed
  nmap: installed

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

MCP Services:
  fetch: enabled [P0]
  memory: enabled [P0]
  ...

✅ Ready. Run vulnclaw to start.

CLI Command Reference

$ vulnclaw --help

🦞 VulnClaw — AI-powered penetration testing CLI

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

 Commands:
   run           🚀 Full pentest in one shot (defaults to the solve engine)
   solve         🧩 Goal-driven solver (model-led, no fixed rounds)
   persistent    🔄 Persistent pentesting (100 rounds/cycle)
   recon         🔍 Reconnaissance only
   scan          🔎 Vulnerability scanning
   exploit       💥 Exploitation phase
   report        📝 Generate report from session JSON
   repl          💬 Start the classic REPL
   config        ⚙️  Manage config (set/get/list/provider)
   plugins       🧩 Manage vulnerability detection plugins (list/info/run)
   init          🔧 Initialize configuration
   doctor        🏥  Check runtime environment
   tui           🖥️  Open the terminal UI workbench
   web           🌐 Launch local Web UI
   code          🧬 Local source-code security scan (no network target)

Usage

Mode 1: CLI / REPL (Default)

vulnclaw

No-args startup opens the 🦞 interactive shell for natural-language use:

🦞 vulnclaw> pentest 192.168.1.100 — this is my authorized lab

[*] Entering autonomous pentest mode. Press Ctrl+C to interrupt.
── Round 1 ──
  [+] Target: 192.168.1.100
  [+] Open ports: 22, 80, 443, 8080
  [+] Web fingerprint: Apache/2.4.62
── Round 2 ──
  [+] Discovered /manager/html (Tomcat Manager)
  [+] Matched CVE-202X-XXXX: Apache Tomcat Auth Bypass
── Round 3 ──
  [+] Vulnerability verified

🦞 192.168.1.100 | report> generate pentest report
[+] Report saved: ./reports/192.168.1.100_20260418.md
[+] PoC saved: ./pocs/CVE-202X-XXXX.py

REPL Built-in Commands:

Auto Pentest Trigger: Keywords like "pentest", "find flag", "bruteforce" + a target address auto-enter the multi-round autonomous loop. Ctrl+C to interrupt anytime.

Mode 2: TUI Workbench

Optional terminal UI workbench showing authorized target, check mode, runtime overview, and safety boundary — confirm scope before launching.

vulnclaw tui
vulnclaw tui --target https://target.example --mode quick --only-port 443
vulnclaw tui --dry-run --target https://target.example --mode deep --only-path /admin

The Rust workbench has configurable containers: Status on the left, Findings and Subagents stacked on the right, agent output in the center, and an input area below. Subagent data is currently unavailable.

• Drag a view title between sidebars or to reorder it. An orange preview shows the module's position and size after release; click v / > to collapse or expand.
• Drag a separator to resize neighboring containers or expanded views. Press Esc during a drag to cancel.
• The mouse wheel scrolls the view under the pointer. Click to focus, use arrow keys to scroll, Ctrl+Left/Right to cycle views, and Ctrl+Y to copy the focused view.
• An empty secondary sidebar collapses automatically. Drag a view to the workbench's right edge for an orange docking preview, then release to reopen it. The primary sidebar always keeps at least one view.
• Layout changes save automatically to VULNCLAW_HOME/tui/layout.json (default ~/.vulnclaw/tui/layout.json). The command palette grows the input area automatically. Small terminals show the required dimensions and restore the layout when enlarged.

Native text selection while mouse capture is active depends on your terminal's modifier keys; Ctrl+Y copies an individual view. On Windows terminals Ctrl+V, Shift+Insert, and the right mouse button read the system clipboard directly into the composer (Win32 API, microseconds; the platform has no bracketed paste, so pasting never depends on the terminal synthesizing keystrokes); Unix terminals paste via bracketed paste.

Common menus:

• Menu 3 — Set testing scope (host/port/path/allowed actions/blocked actions)
• Menu 7 — Environment diagnostics (full details via vulnclaw doctor)
• Menu 8 — Model/API settings (switch Provider, Base URL, Model, API Key)

Mode 3: Single Command

vulnclaw run 192.168.1.100                    # full pentest
vulnclaw recon 192.168.1.100                   # recon only
vulnclaw scan 192.168.1.100 --ports 80,443     # vuln scan
vulnclaw exploit 192.168.1.100 --cve CVE-2024-1234 --cmd id  # exploit
vulnclaw report session.json                   # generate report

Mode 4: Persistent Pentesting

For long-running deep pentesting. Runs in cyclic loops:

┌──────────────────────────────────────────────┐
│  Cycle 1 (100 rounds) → auto-report → continue │
│  Cycle 2 (100 rounds) → auto-report → continue │
│  ...                                             │
│  Until Ctrl+C or max cycles reached (default 10) │
└──────────────────────────────────────────────┘

vulnclaw persistent 192.168.1.100              # default 100 rounds/cycle × 10 cycles
vulnclaw persistent 192.168.1.100 -r 200 -c 5  # 200 rounds/cycle × 5 cycles
vulnclaw persistent 192.168.1.100 --no-report   # disable auto-report

# TUI mode
vulnclaw tui --target 192.168.1.100 --mode continuous

# REPL mode
🦞 vulnclaw> persistent 192.168.1.100

Features: Cross-cycle state / Cycle reports / Graceful interrupt / Incremental discovery / Fully configurable

Mode 5: Web UI

Operate the full pentest workflow through a browser.

git clone https://github.com/Netw0rkNoob/VulnClaw.git
cd VulnClaw
pip install -e '.[web]'       # install from a source checkout

# First run: build the React frontend (Node.js 18+)
cd frontend
npm install
npm run build
cd ..

vulnclaw web                  # launch (default 127.0.0.1:7788)
vulnclaw web --port 8080      # custom port

The published wheel does not contain the React build or its source files. Use the source-checkout installation above for the full Web UI. If you see the Fallback Web Shell (no full scan UI), frontend/dist/index.html is missing. Build as above, restart vulnclaw web, and hard-refresh. API endpoints such as /api/health still work while the SPA is unbuilt.

⚠️ By default binds to localhost only. For remote access pass --host 0.0.0.0 --allow-remote.

Architecture

Solver Engine

VulnClaw defaults to the model-led solve engine (switch back to fixed-round with vulnclaw config set session.engine rounds).

Model-Led Loop: The framework no longer decomposes a task into forced "research directions", and it no longer schedules directory scans, JS reconnaissance, or SQLi checks by phase templates. solve provides the target, conversation context, evidence memory, and tool catalog; the model decides the next action.

MODEL DECIDES → optional tool call → AgentState records full raw evidence + active-context high-signal preview + correction hints
        │
continue reasoning / continue tool use / ASK_USER / NO_PATH / FINAL
        │
FINAL passes evidence gate → accepted; otherwise the rejection is fed back and solve continues

Context Strategy: solve keeps ordinary conversation history by default. Hot context is bounded to 48 messages / 32K tokens; when exceeded, older messages are archived to cold-memory JSONL shards and retrievable via memory_search. The unified context budget (prepare_context()) estimates tokens (including tool schemas) across all LLM call paths and triggers structured compaction at 70% of usable context, generating a deterministic [context digest v1] summary with target/scope/verified facts/evidence references. Tool output is fully stored in AgentState.evidence, while large outputs enter active context as bounded high-signal previews. The same raw output appearing again gets a same_as=eXXX reference instead of repeating the body.

Evidence-Level Anti-Hallucination Gate: Records all real tool output as the sole trusted evidence. Claims about flags/conclusions must appear in real output or cite evidence ids before they are accepted. NO_PATH is also gated by the near-miss guard: if unresolved high-signal anchors remain in evidence, the rejection reason is fed back to the model for another concrete verification step instead of stopping immediately.

Automatic Solve Report: When solve reaches the goal, VulnClaw deterministically renders a Markdown replay report from AgentState and prints it by default. It does not make another LLM call; replay packets, curl commands and response excerpts come from real fetch / http_probe_batch evidence.

Authorized Red-Team Skills: Authorized red-team detail packs from codex-redteam-mode are imported as skills/knowledge for on-demand use; jailbreak, refusal-bypass, and session-patching content is not imported.

Core Modules

MCP Toolchain

Plus built-in Agent tools (http_probe_batch, python_execute, shell_command, source_extract, runtime_diff_probe, nmap_scan, crypto_decode, brute_force_login, load_skill_reference, evidence_list, evidence_search, evidence_view, etc.) — no MCP needed.

# Step 1: Start Chrome with remote debugging
# Windows
"C:\Program Files\Google\Chrome\Application\chrome.exe" --remote-debugging-port=9222 --user-data-dir=C:\tmp\chrome-debug
# Linux/Mac
google-chrome --remote-debugging-port=9222 --user-data-dir=/tmp/chrome-debug

# Step 2: Enable in VulnClaw
vulnclaw config set mcp.servers.chrome-devtools.enabled true

mcp:
  servers:
    chrome-devtools:
      enabled: true
      transport:
        type: stdio
        command: npx
        args: ["-y", "chrome-devtools-mcp@latest", "--browser-url=http://127.0.0.1:9222"]

# Step 1: Clone and build
git clone https://github.com/PortSwigger/mcp-server.git burp-mcp
cd burp-mcp
./gradlew embedProxyJar    # Windows: gradlew.bat embedProxyJar

# Step 2: Load into Burp Suite → Extensions → Add → Type: Java → select burp-mcp-all.jar

# Step 3: Enable in Burp's MCP tab

# Step 4: Enable in VulnClaw
vulnclaw config set mcp.servers.burp.enabled true

mcp:
  servers:
    burp:
      enabled: true
      transport:
        type: stdio
        command: java
        args: ["-jar", "~/.vulnclaw/tools/burp-mcp-all.jar", "--sse-url", "http://127.0.0.1:9876"]

See docs/mcp-deployment.md for detailed setup instructions.

Built-in Skills

Core Skills (7)

Specialized Skills (16)

Skills are resolved from user input into an optional reference index. VulnClaw does not automatically inject skill bodies, phase workflows, or methodology scripts into the system prompt. Specialized skills include detailed methodology documents in references/, and the model loads them only when it chooses to call load_skill_reference.

Built-in Encode/Decode & Crypto Tool (crypto_decode)

Configuration

LLM Providers

vulnclaw config provider --list    # list all providers
vulnclaw config provider minimax   # one-command switch

CLI Configuration

vulnclaw config list                          # view all settings
vulnclaw config get llm.model                 # view single setting
vulnclaw config set llm.api_key sk-xx         # set API key
vulnclaw config set session.max_rounds 30     # set max rounds (default 15)
vulnclaw config set session.show_thinking false  # hide thinking process

Execution Approvals (unattended execution)

Dangerous tools (shell / python / PoC) prompt Approve this execution? [y/N] before every run by default. Three ways to change that:

# 1. Persist to config (recommended)
vulnclaw config set safety.permission_mode full_access

# 2. Current REPL session only (falls back to the config file after restart)
mode full_access          # switch; without an argument, show the current mode

# 3. Single run
VULNCLAW_SAFETY_PERMISSION_MODE=full_access vulnclaw solve <target>

⚠️ Under full_access, target responses, page content and reports are untrusted input — prompt injection can drive unconfirmed arbitrary command execution. Reserve it for isolated labs, CTFs and throwaway VMs; for real engagements prefer auto_review plus your own trusted prefixes.

Configurable Options

Environment Variables

Priority: Environment Variables > Config File > Built-in Defaults

Config file: ~/.vulnclaw/config.yaml.

Language

VulnClaw ships with a built-in English / 中文 (Chinese) bilingual interface. The default is English (auto mode falls back to English), so international users never hit a language wall; Chinese is fully preserved and both modes produce identical behavior.

Switch the UI language any of three ways:

Everything user-visible in the CLI follows the current language: REPL messages and status banners, event stream, solve reports, knowledge-base status, and LLM retry/recovery notices. Agent detection keyword tables are bilingual, so English or Chinese task phrasing is classified the same way. (Note: the web dashboard is not yet localized; that's planned separately.)

Changelog

See CHANGELOG.md for full version history.

Contributing

Contributions are welcome! Please read CONTRIBUTING_EN.md (English) or CONTRIBUTING.md (Chinese) before submitting a pull request.

The project uses a dev branch for integration — all PRs should target dev, not main.

Security Notice

Public alpha: VulnClaw is public alpha software for authorized security testing, CTFs, labs, and controlled research. It is not a production security control or a replacement for human authorization. See SECURITY.md before using or reporting security issues.

VulnClaw is intended solely for authorized security testing. Before using this tool, ensure:

1. You have explicit authorization for the target system
2. Scope has been confirmed in writing with the target owner
3. You comply with all applicable local laws and regulations

Unauthorized penetration testing is illegal. The author assumes no liability for misuse.

License

MIT License

Join the Community

Connect with security enthusiasts to share, learn, and grow together.

Community Group	Developer Group
Join discussions and get the latest product updates and usage tips	Join us for open-source contributions and deep technical discussions
QQ Group: 954402631	QQ Group: 1065858551