I'll fetch the README file from the Vuln-Z-Claw repository and translate it to English for you.I can see the README is actually in Chinese (Simplified), not Japanese. Let me translate it to English for you:
AI-powered penetration testing CLI tool — speak plainly, find vulnerabilities.
This project is a standalone AI penetration testing Agent.
Built on LLM Agent + MCP toolchain + penetration skill orchestration, compatible with OpenAI / MiniMax / DeepSeek and other compatible models. Accepts natural language input → automatically completes the entire "information gathering → vulnerability discovery → exploitation → report generation" workflow.
Input natural language, and AI automatically executes the full penetration testing workflow:
User Input: Perform penetration testing on http://target.example.com
VulnClaw automatically executes:
Round 1: Information Gathering → Fingerprinting, port scanning, directory enumeration
Round 2: Vulnerability Discovery → Injection point detection, known CVEs, config flaws
Round 3: Exploitation → PoC verification, privilege escalation
Round 4: Report Generation → Structured report + Python PoC script
Suitable for authorized penetration testing, CTF competitions, security education, red team exercises, etc.
- Goal-driven solver engine (default) — Abandons fixed-round workflows, uses "goal achieved / frontier exploration exhausted / safety budget" as termination conditions, auto-converges
- Blackboard graph state space search — Models penetration as search from origin to goal: Fact (confirmed facts) + Intent (exploration directions), structurally prevents "spinning in place"
- Evidence-level hallucination gate — Claims of flags/conclusions must appear verbatim in real tool output to be trusted; prevents fabricated flag victories
- Natural language driven — Describe penetration intent in plain language, automatically identify phases and tools
- 13 LLM Providers — OpenAI / MiniMax / DeepSeek / Zhipu / Moonshot / Qwen / SiliconFlow / Doubao / Baichuan / Stepfun / SenseTime / Yi, one-click switch
- MCP toolchain — 4 MCP services:
fetch/memorywork out-of-the-box locally,chrome-devtools/burpintegrate external MCP services for browser automation and HTTP sniffing/replay - AI Agent core — OpenAI-compatible protocol + Tool Calling + autonomous penetration loop
- Structured reasoning + adaptive reflection — Known facts/constraints/attack chains structured and injected into prompts; failures auto-classified with L0-L4 progressive payload bypass strategies
- Vulnerability detection plugin system — Low-coupling plugin runtime + built-in read-only Web plugins, results auto-merged into report pipeline (
vulnclaw plugins) - 21 penetration skills — 7 core + 14 specialized skills (including CTF Web/Crypto/Misc, OSINT recon, security knowledge), with 180 reference documents
- Encode/decode & encryption tools — 29 operations (Base64/Hex/URL/AES/JWT/Morse etc.), LLM can precisely invoke without guessing
- Python code execution — Built-in
python_executetool for payload construction and response parsing - Persistent penetration testing — Cycle loops (default 100 rounds/cycle × 10 cycles = 1000 rounds), auto-generate reports per cycle until manual stop
- Reasoning process display control —
think on/offtoggle to show/hide LLM thinking process, default off, clean output shows conclusions only - Sandbox mode prompts — Unlock AI security testing capabilities, CTF/authorized penetration scenarios only
- Auto-report & PoC — Generate structured Markdown reports and runnable Python PoC scripts
- Web UI mode —
vulnclaw weblaunches local Web interface, browser-based full penetration testing workflow, default127.0.0.1:7788 - Security knowledge base — Pre-built knowledge base module with seed data, CLI-maintainable
The old autonomous penetration was fixed-round loops (run N rounds then stop), easily falling into "repeatedly requesting same page, claiming to test injection but not sending packets" dead loops on weak models. The new version reconstructs penetration as directed search from origin (target) to goal (get flag / shell / confirm critical vulnerability) using two primitives:
| Primitive | Meaning |
|---|---|
| Fact | Objective facts confirmed by real tool output (exploration footing) |
| Intent | Declared exploration direction (not yet executed), starting from Fact, produces new Fact after conclusion |
Loop structure:
REASON (read full graph) → Goal achieved? / Propose new exploration direction / No proposal
│
EXPLORE (take one Intent) → Actually execute with tools → Write confirmed conclusion back as Fact
│
Terminate: Goal achieved / Exploration frontier exhausted / Safety budget exceeded
Why it structurally prevents spinning: Once "homepage is login form" becomes a Fact, Reason won't propose "go view homepage" again, but rather "test SQL injection"; each Intent is taken once, concluded once, preventing repetition.
Weak models often fabricate flags from thin air. The new engine records all real tool output (HTTP response bodies, python_execute output) as the only trusted evidence:
- Conclusion gate: Flags claimed in Explore conclusions must appear verbatim in real tool output → marked as
[unverified]if not - Completion gate: When Reason declares "goal achieved", if the goal requires flag but real output contains none → reject completion, continue exploring
- Instant convergence: Once evidence-verified flag obtained, complete immediately, no more verification rounds
# Install from PyPI (recommended)
pip install vulnclaw
# Install from source
git clone https://github.com/Unclecheng-li/VulnClaw.git
cd VulnClaw
pip install -e .# 1. Choose provider (auto-fills Base URL and model name)
vulnclaw config provider minimax (or openai/deepseek/zhipu/moonshot/qwen/siliconflow)
# 1.2 (optional) Customize 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 original CLI / REPL
vulnclaw
# 4. Optional: open TUI workbench
vulnclaw tuivulnclaw doctorvulnclaw --help # View all commands
Commands:
run 🚀 One-command full workflow penetration testing
persistent 🔄 Continuous penetration testing (100 rounds/cycle)
recon 🔍 Information gathering phase only
scan 🔎 Execute vulnerability scanning phase
exploit 💥 Execute exploitation phase
report 📝 Generate report from session records
repl 💬 Launch classic REPL interaction interface
config ⚙️ Manage configuration (set/get/list/provider)
init 🔧 Initialize configuration
doctor 🏥 Check runtime environment
tui 🖥️ Open terminal GUI workbench
web 🌐 Launch local Web UIVulnClaw supports all OpenAI-compatible APIs, with 8 built-in provider presets:
vulnclaw config provider --list # View all providers
vulnclaw config provider minimax # One-click switch| Provider | Command | Default Model |
|---|---|---|
| OpenAI | provider openai |
gpt-4o |
| MiniMax | provider minimax |
MiniMax-M3 |
| DeepSeek | provider deepseek |
deepseek-v4-pro |
| Zhipu GLM | provider zhipu |
glm-4.7 |
| Kimi | provider moonshot |
kimi-k2.6 |
| Qwen | provider qwen |
qwen3-max |
| SiliconFlow | provider siliconflow |
DeepSeek-V4-Flash |
| Doubao | provider doubao |
Doubao-Seed-2.0-Pro |
VulnClaw is for authorized security testing only. Before using this tool, ensure:
- You have explicit authorization to test the target system
- Testing scope has been confirmed in writing with the target owner
- You comply with local laws and regulations
Unauthorized penetration testing is illegal. The tool author is not responsible for misuse.
This is an AI-powered penetration testing framework that leverages LLMs + MCP toolchain to automate security assessments. It's designed for authorized testing professionals and CTF competitors, supporting multiple LLM providers and featuring advanced anti-hallucination mechanisms to ensure reliable vulnerability detection.