Skip to content

Zekiog/Vuln-Z-Claw

 
 

Repository files navigation

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:


VulnClaw 🦞 — English Translation

AI-powered penetration testing CLI tool — speak plainly, find vulnerabilities.

License: MIT Python 3.10+ OpenAI Compatible MCP PyPI Security

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.


What It Can Do

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.


Features

  • 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 / memory work out-of-the-box locally, chrome-devtools / burp integrate 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_execute tool 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 controlthink on/off toggle 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 modevulnclaw web launches local Web interface, browser-based full penetration testing workflow, default 127.0.0.1:7788
  • Security knowledge base — Pre-built knowledge base module with seed data, CLI-maintainable

Architecture Upgrade: From "Fixed-Round Workflow" to "Goal-Driven Solver"

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.

Evidence-Level Anti-Hallucination Gate

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

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 Steps to Launch

# 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 tui

Environment Check

vulnclaw doctor

CLI Commands Quick Reference

vulnclaw --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 UI

LLM Provider Configuration

VulnClaw 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

Security Statement

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

  1. You have explicit authorization to test the target system
  2. Testing scope has been confirmed in writing with the target owner
  3. You comply with local laws and regulations

Unauthorized penetration testing is illegal. The tool author is not responsible for misuse.


License

MIT License


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.

About

基于 AI Agent + MCP 工具链 + 渗透

Resources

License

Contributing

Stars

Watchers

Forks

Releases

No releases published

Packages

 
 
 

Contributors

Languages

  • Python 84.9%
  • TypeScript 11.6%
  • CSS 2.9%
  • HTML 0.6%