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

> Explore VulnClaw usage examples for AI-driven penetration tests. Discover 6 practical ways to leverage VulnClaw's CLI, REPL, and web interfaces for advanced security testing.

- Repository: [Unclecheng/VulnClaw](https://github.com/Unclecheng-li/VulnClaw)
- Tags: getting-started
- Published: 2026-07-03

---

**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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py) to the goal-driven OODA loop in [`vulnclaw/agent/solver.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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.

```bash
vulnclaw run 192.168.1.100

```

This command triggers the Agent Core in [`vulnclaw/agent/core.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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.

```bash

# 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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/router.py).

## Interactive REPL and TUI

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

```bash

# Classic read-eval-print loop

vulnclaw repl

# Terminal User Interface (graphical)

vulnclaw tui

```

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

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

```

The TUI implementation in [`vulnclaw/cli/tui.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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.

```bash

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

```bash

# 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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py). The Knowledge Base in [`vulnclaw/kb/store.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/cli/main.py)** – Typer entry point parsing all CLI commands.
- **[`vulnclaw/agent/core.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/core.py)** – Central orchestrator managing agent state and tool execution.
- **[`vulnclaw/agent/solver.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/agent/solver.py)** – Implements the OODA loop with Fact/Intent blackboard and evidence-level hallucination gates.
- **[`vulnclaw/mcp/router.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/router.py)** – Routes LLM tool calls to MCP services (fetch, memory, chrome-devtools, burp).
- **[`vulnclaw/kb/store.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/kb/store.py)** – JSON-based knowledge base storing CVE and technique data.
- **[`vulnclaw/report/generator.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/report/generator.py)** – Builds Markdown reports and executable PoC scripts.
- **[`vulnclaw/plugins/registry.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/config/settings.py), while session data and knowledge base entries (CVEs, techniques) are managed via [`vulnclaw/kb/store.py`](https://github.com/Unclecheng-li/VulnClaw/blob/main/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`](https://github.com/Unclecheng-li/VulnClaw/blob/main/vulnclaw/mcp/router.py) to execute precise exploitation plugins rather than broad autonomous discovery.