VulnClaw Usage Examples: 6 Practical Ways to Run AI-Driven Penetration Tests

VulnClaw provides multiple CLI interfaces including quick scans, persistent testing modes, stage-specific commands, interactive REPL/TUI, and a web interface, all orchestrated through an AI agent core that executes natural language security testing workflows.

The Unclecheng-li/VulnClaw repository implements an AI-driven penetration testing framework that transforms natural language intent into full-stack security assessments. These VulnClaw usage examples demonstrate how to interface with its modular architecture—from the Typer-based CLI entry point in vulnclaw/cli/main.py to the goal-driven OODA loop in vulnclaw/agent/solver.py—to automate vulnerability discovery and exploitation against target systems.

Architecture Overview

VulnClaw operates through a layered architecture that processes natural language commands into executable security workflows. The system parses input into goals and stages (reconnaissance, scanning, exploitation), then manages execution through a Fact/Intent blackboard pattern implemented in vulnclaw/agent/solver.py.

The core workflow follows five phases:

1. Input Parsing – Natural language commands are converted into structured goals.
2. Reasoning – The solver reads the blackboard, proposes new Intents (exploration directions), and validates them against real tool output (Facts).
3. Exploration – Intents execute via the MCP toolchain in vulnclaw/mcp/router.py or built-in agents.
4. Evidence Gate – Claims must appear verbatim in tool output; otherwise they are rejected to prevent hallucination.
5. Termination – Upon goal verification or intent exhaustion, vulnclaw/report/generator.py produces Markdown reports and executable Python PoC scripts.

Quick One-Command Full Scan

The simplest VulnClaw usage example executes a complete autonomous assessment with a single command. This invokes the default solve engine, which automatically progresses through information gathering, vulnerability discovery, exploitation, and report generation.

vulnclaw run 192.168.1.100

This command triggers the Agent Core in vulnclaw/agent/core.py to initialize the OODA loop and begin tool orchestration via the MCP router.

Persistent Long-Running Testing

For comprehensive assessments requiring iterative cycles, use the persistent mode. This executes multiple rounds of testing across configurable cycles, auto-generating reports after each cycle.

# Default persistent execution

vulnclaw persistent 192.168.1.100

# Customized execution with 200 rounds per cycle for 5 cycles

vulnclaw persistent 192.168.1.100 --rounds 200 --cycles 5

The persistent mode maintains state across cycles, allowing the solver in vulnclaw/agent/solver.py to build upon previous Facts and refine Intents over time.

Stage-Specific Commands

VulnClaw supports granular control through stage-specific subcommands, allowing you to execute only reconnaissance, scanning, or exploitation phases.

Command	Purpose	Example
Reconnaissance	Information gathering only	vulnclaw recon target.com
Vulnerability Scan	Port and service scanning	vulnclaw scan target.com --ports 80,443
Targeted Exploitation	Exploit specific CVEs	vulnclaw exploit target.com --cve CVE-2024-1234
Report Generation	Create reports from session files	vulnclaw report session_xxx.json

These commands bypass the autonomous OODA loop and execute specific toolchains registered in vulnclaw/mcp/router.py.

Interactive REPL and TUI

VulnClaw provides two interactive interfaces for manual control and natural language interaction.

# Classic read-eval-print loop

vulnclaw repl

# Terminal User Interface (graphical)

vulnclaw tui

Within the REPL, you can input natural language commands directly:

🦞 vulnclaw> 对 http://target.example.com 进行渗透测试

The TUI implementation in vulnclaw/cli/tui.py provides a graphical interface for monitoring the agent's reasoning process and tool execution in real-time.

Web UI Interface

For browser-based operation, VulnClaw offers an optional web interface.

# Install web dependencies

pip install 'vulnclaw[web]'

# Start the web server

vulnclaw web

The web interface starts at http://127.0.0.1:7788 and provides a dashboard for configuring targets, monitoring the Fact/Intent blackboard, and reviewing generated reports.

LLM Provider Configuration

Before running assessments, configure your AI provider and API credentials.

# Set provider (OpenAI, MiniMax, etc.)

vulnclaw config provider minimax

# Set API key

vulnclaw config set llm.api_key sk-your-key-here

Configuration persists in ~/.vulnclaw/config.yaml, managed by the Pydantic settings model in vulnclaw/config/settings.py. The Knowledge Base in vulnclaw/kb/store.py maintains CVE data and technique references accessible to the configured LLM.

Key Implementation Files

Understanding these source files clarifies how VulnClaw executes the usage examples above:

• vulnclaw/cli/main.py – Typer entry point parsing all CLI commands.
• vulnclaw/agent/core.py – Central orchestrator managing agent state and tool execution.
• vulnclaw/agent/solver.py – Implements the OODA loop with Fact/Intent blackboard and evidence-level hallucination gates.
• vulnclaw/mcp/router.py – Routes LLM tool calls to MCP services (fetch, memory, chrome-devtools, burp).
• vulnclaw/kb/store.py – JSON-based knowledge base storing CVE and technique data.
• vulnclaw/report/generator.py – Builds Markdown reports and executable PoC scripts.
• vulnclaw/plugins/registry.py – Low-coupling plugin system for vulnerability detection modules.

Summary

• One-command scanning via vulnclaw run executes full autonomous workflows from vulnclaw/agent/core.py.
• Persistent mode supports long-running iterative assessments with configurable rounds and cycles.
• Stage commands (recon, scan, exploit) provide granular control over specific testing phases.
• Interactive modes (REPL, TUI, Web UI) support natural language input and real-time monitoring.
• Evidence gates in vulnclaw/agent/solver.py prevent hallucination by requiring verbatim tool output verification.
• Configuration stores provider settings in ~/.vulnclaw/config.yaml using Pydantic models.

Frequently Asked Questions

What is the difference between vulnclaw run and vulnclaw persistent?

vulnclaw run executes a single autonomous testing session that terminates upon goal completion or intent exhaustion, while vulnclaw persistent runs multiple cycles with configurable rounds (e.g., --rounds 200 --cycles 5), allowing the solver in vulnclaw/agent/solver.py to iteratively refine findings across extended time periods.

How does VulnClaw prevent AI hallucination during testing?

The framework implements an evidence-level hallucination gate in vulnclaw/agent/solver.py that requires any claimed vulnerability flag to appear verbatim in actual tool output (Facts) before acceptance. Claims lacking tool verification are rejected, ensuring the blackboard maintains only validated security findings.

Where does VulnClaw store configuration and session data?

Configuration persists in ~/.vulnclaw/config.yaml as defined by vulnclaw/config/settings.py, while session data and knowledge base entries (CVEs, techniques) are managed via vulnclaw/kb/store.py. Session files can be passed to vulnclaw report to generate post-assessment documentation.

Can VulnClaw target specific vulnerabilities rather than general scanning?

Yes, use the vulnclaw exploit command with the --cve flag (e.g., vulnclaw exploit target.com --cve CVE-2024-1234) to target specific vulnerabilities. This routes the request through the MCP toolchain in vulnclaw/mcp/router.py to execute precise exploitation plugins rather than broad autonomous discovery.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}