VulnClaw 🦞

AI-Powered Penetration Testing CLI — Speak plainly, find real bugs.

This project is a standalone AI penetration testing Agent.

Built on LLM Agent + MCP Toolchain + Pentest Skill orchestration, compatible with OpenAI / MiniMax / DeepSeek and similar models. Natural language input → automated "Recon → Vulnerability Discovery → Exploitation → Reporting".

Quick Start · Architecture · Skills

---

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

• Natural Language Driven — Describe your intent in plain English, it auto-identifies phases and tools
• 8 LLM Providers — OpenAI / MiniMax / DeepSeek / Zhipu / Moonshot / Qwen / SiliconFlow, one-command switch
• MCP Toolchain — Ships with 11 MCP service configs and 23 tool definitions; fetch / memory currently run in stable local mode, while most other MCP integrations remain preview or placeholder until full session lifecycle management is completed
• AI Agent Core — OpenAI-compatible protocol + Tool Calling + autonomous pentest loop
• 21 Pentest Skills — 7 core + 14 specialized skills (incl. CTF Web/Crypto/Misc, osint-recon, secknowledge-skill), 180 reference documents
• Encode/Decode & Crypto Tools — 29 operations (Base64/Hex/URL/AES/JWT/Morse etc.), LLM calls them directly, no guessing
• 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
• Persistent Pentesting — Cyclic runs (100 rounds/cycle × 10 cycles = 1000 rounds), auto-reports every cycle, runs until you stop it
• Thinking Process Control — think on/off toggles LLM reasoning visibility, off by default for clean output
• Sandbox Mode Prompting — Unlocks AI security testing capabilities, designed 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 for browser-based pentest operations, default 127.0.0.1:7788
• Security Knowledge Base — Includes the KB module and baseline seed data today; retrieval augmentation is being integrated into the main workflow incrementally

---

Quick Start

Installation

# Install from PyPI (recommended)
pip install vulnclaw

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

Four-Step Launch

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

# 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

# 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
  API Key: set
  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

Run vulnclaw --help to see all available commands:

$ vulnclaw --help

🦞 VulnClaw — AI-powered penetration testing CLI

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

 Options:
   --version  Show version and exit.
   --help     Show this message and exit.

 Commands:
   run           🚀 Full pentest in one shot
   persistent    🔄 Persistent pentesting (100 rounds/cycle)
   recon         🔍 Reconnaissance only (no exploitation)
   scan          🔎 Vulnerability scanning
   exploit       💥 Exploitation phase
   report        📝 Generate report from session JSON
   repl          💬 Start the classic REPL
   config        ⚙️  Manage config (set/get/list/provider)
   init          🔧 Initialize configuration
   doctor        🏥  Check runtime environment
   tui           🖥️  Open the terminal UI workbench
   web           🌐 Launch local Web UI

Command Reference

Command	Description	Example
vulnclaw	Open the original CLI / REPL by default	vulnclaw
vulnclaw tui	Explicitly open the terminal UI workbench	vulnclaw tui / vulnclaw tui --target target.com
vulnclaw repl	Start the classic REPL interactive shell	vulnclaw repl
vulnclaw run <target>	Full pentest in one shot	vulnclaw run 192.168.1.1
vulnclaw persistent <target>	Persistent pentesting	vulnclaw persistent 192.168.1.1
vulnclaw recon <target>	Reconnaissance only	vulnclaw recon target.com
vulnclaw scan <target>	Vulnerability scanning	vulnclaw scan target.com --ports 80,443
vulnclaw exploit <target>	Exploitation phase	vulnclaw exploit target.com --cve CVE-2024-1234
vulnclaw report <session>	Generate report from session	vulnclaw report session_xxx.json
vulnclaw config set <key> <value>	Set a config value	vulnclaw config set llm.api_key sk-xxx
vulnclaw config get <key>	View a config value	vulnclaw config get llm.model
vulnclaw config list	List all config	vulnclaw config list
vulnclaw config provider <name>	Switch LLM provider	vulnclaw config provider deepseek
vulnclaw init	Initialize config files	vulnclaw init
vulnclaw doctor	Check runtime environment	vulnclaw doctor
vulnclaw web	Launch local Web UI	vulnclaw web / vulnclaw web --port 8080

TUI Workbench

vulnclaw tui is the optional terminal UI workbench entry. It shows the authorized target, check mode, runtime overview, safety boundary, command preview, target history, report entry, and inline environment diagnostics before a task starts.

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 default vulnclaw command still opens the original CLI / REPL. The TUI opens only when users explicitly run vulnclaw tui. The runtime overview reads the selected target's snapshots, finding counts, persisted constraints, and blocked constraint violations so users can confirm context before continuing. The TUI "Set testing scope" flow can edit allowed actions and blocked actions directly, for example allowing only recon,scan or blocking exploit,post_exploitation.

Provider Configuration

# List all providers and switch
vulnclaw config provider --list    # list all available providers
vulnclaw config provider minimax   # switch to MiniMax

# Manual setup (custom mode)
vulnclaw config set llm.base_url https://your-api.com/v1
vulnclaw config set llm.model your-model-name
vulnclaw config set llm.api_key sk-your-key

---

Usage

Mode 1: Original CLI / REPL Interactive Mode (Default)

$ vulnclaw

No-args startup opens the original 🦞 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 at any time.
── Round 1 ──
  [+] Target: 192.168.1.100
  [+] Open ports: 22, 80, 443, 8080

Mode 2: TUI Workbench (Explicit)

$ vulnclaw tui

The TUI shows target, mode, runtime overview, and safety boundary before launching a task:

VulnClaw TUI Workbench

Authorized target    https://example.com
Check mode           Quick recon / recon
Runtime overview     history snapshots, findings, persisted constraints
Safety boundary      only port 443, block exploit/persistent/post_exploitation

1 Set authorized target
2 Choose check mode
3 Set testing scope
4 Start authorized security check
8 Model/API settings

Common launch examples:

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

Menu item 3, "Set testing scope", edits host, port, path, exclusions, allowed actions, and blocked actions. These boundaries are shown in the pre-launch confirmation and passed into the actual task command. Menu item 7, "Environment diagnostics", shows Python, Node/npx/uvx/nmap, LLM configuration, and MCP service/tool summaries inside the TUI. Run vulnclaw doctor only when you need the full details. Menu item 8, "Model/API settings", switches Provider, Base URL, Model, and API Key directly in the workbench. Saved changes are used by the current TUI session immediately.

Mode 3: Classic REPL Subcommand

$ vulnclaw repl

Enter the classic 🦞 interactive shell and chat in natural language:

🦞 vulnclaw> pentest 192.168.1.100 — this is my authorized lab

[*] Entering autonomous pentest mode. Press Ctrl+C to interrupt at any time.
── 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

Classic REPL Built-in Commands

Command	Description
target <host>	Set pentest target
status	View current state (target, phase, tools, thinking)
tools	List available MCP tools
think	Toggle thinking process display
think on / off	Explicitly control thinking visibility
persistent	Start persistent pentesting (100 rounds/cycle)
persistent <host>	Start persistent pentest on a target
clear	Clear current session
help	Show help
exit / quit / q	Exit VulnClaw

Autonomous Pentest Mode

VulnClaw auto-enters multi-round autonomous loop when it detects these keywords + a target:

Trigger	Example
Pentest command	pentest http://target.com
CTF / find flag	find the flag on http://ctf.site
Brute / bypass	bruteforce weak credentials on http://target.com
Explicit	target: http://target.com, enter autonomous mode

💡 Press Ctrl+C to interrupt the autonomous loop at any time. Switching targets automatically resets session context.

Mode 2: Single Command

# Full pentest in one shot
vulnclaw run 192.168.1.100

# Persistent pentesting (100 rounds/cycle × 10 cycles, auto-report)
vulnclaw persistent 192.168.1.100

# Custom cycle parameters
vulnclaw persistent 192.168.1.100 --rounds 200 --cycles 5

# Recon only
vulnclaw recon 192.168.1.100

# Vulnerability scan (specify ports)
vulnclaw scan 192.168.1.100 --ports 80,443,8080

# Exploitation (specify CVE)
vulnclaw exploit 192.168.1.100 --cve CVE-2024-1234 --cmd id

# Generate report
vulnclaw report session.json

Mode 3: Persistent Pentest

For long-running deep penetration. VulnClaw runs in cyclic loops:

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

Features: - Cross-cycle state — Each cycle preserves all previous findings, vulnerabilities, and step records - Cycle reports — Auto-generates independent Markdown report per cycle (new findings + cumulative summary) - Graceful interrupt — Ctrl+C at any time still generates the current cycle's report - Incremental discovery — Reports distinguish "new this cycle" from "cumulative total" - **