How to Run VulnClaw from Source: Complete Installation and Setup Guide

To run VulnClaw from source, clone the repository, install the package in editable mode with pip install -e ., configure your LLM provider credentials, and invoke the vulnclaw CLI commands.

VulnClaw is a pure‑Python penetration‑testing framework built around an LLM‑driven agent, a modular MCP (Model Context Protocol) toolchain, and a blackboard‑style solver. Running it directly from the Unclecheng-li/VulnClaw repository allows you to leverage the latest commits, customize the plugin subsystem, and debug the orchestration layer. This guide walks through the installation flow, runtime initialization, and command execution based on the actual source code architecture.

Prerequisites and System Requirements

Before installing from source, ensure your environment meets the following baseline:

• Python ≥3.10 (required for modern async/await patterns used in the agent core)
• Node.js ≥20 (optional but recommended for Chrome DevTools MCP integration)
• Git (for cloning the repository)
• pip (for editable installation)

The vulnclaw doctor command (available after installation) validates these dependencies and reports any missing binaries.

Cloning and Installing from Source

VulnClaw uses a standard Python package layout with pyproject.toml as the build configuration. Installing in editable mode (-e) creates a vulnclaw console script that maps to the Typer entry point in vulnclaw/cli/main.py.

Execute the following steps:

# Clone the repository

git clone https://github.com/Unclecheng-li/VulnClaw.git
cd VulnClaw

# Install in editable mode

pip install -e .

Upon completion, the vulnclaw command becomes available in your shell. The installation exposes several CLI modules located under vulnclaw/cli/*, including the main entry point and specialized commands for reconnaissance and reporting.

Configuring the LLM Provider

VulnClaw requires LLM credentials to power its reasoning engine. The configuration module (vulnclaw/config/settings.py) reads from ~/.vulnclaw/config.yaml and merges environment variables such as VULNCLAW_LLM_API_KEY.

Initialize your configuration:

# Check environment health

vulnclaw doctor

# Set provider (e.g., OpenAI)

vulnclaw config provider openai

# Set API key

vulnclaw config set llm.api_key sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

Alternatively, export the key directly:

export VULNCLAW_LLM_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxx

The configuration schema is defined in vulnclaw/config/schema.py using Pydantic models, ensuring type safety for all settings.

Understanding the Runtime Architecture

When you invoke a vulnclaw command, the system initializes a complex orchestration pipeline. Understanding these components helps troubleshoot execution flows and extend functionality.

CLI Entry Points and Command Structure

The vulnclaw executable launches from vulnclaw/cli/main.py, which registers Typer commands for different operational modes. Key commands include:

• vulnclaw run – Full penetration test with the default solver engine
• vulnclaw recon – Reconnaissance phase only
• vulnclaw web – Launch the optional web UI (requires pip install "vulnclaw[web]")

Commands that require agent execution delegate to vulnclaw/orchestrator.py, specifically the run_agent_task helper function.

Agent Core and Solver Engine

The agent logic resides in vulnclaw/agent/core.py, which coordinates LLM calls, tool routing, and blackboard updates. When using the default solve engine (session.engine=solve), the system invokes the OODA loop implementation in vulnclaw/agent/solver.py.

This solver drives the blackboard graph (composed of Fact and Intent nodes) through repeated cycles:

1. Reason – Generate prompts based on current state
2. Explore – Execute tools and analyze responses
3. Conclude – Update the goal status or terminate when the frontier is exhausted

The loop terminates when the penetration goal is achieved, the safety budget is consumed, or no further exploration paths exist.

MCP Router and Tool Execution

When the agent requires external data (e.g., fetching a webpage or querying memory), vulnclaw/mcp/router.py dynamically maps tool calls to the appropriate MCP service. Available services include:

• fetch – HTTP requests via httpx
• memory – Vector store queries
• chrome-devtools – Browser automation (requires Node.js)

Service definitions live in vulnclaw/mcp/registry.py, while lifecycle management (startup/shutdown) is handled by vulnclaw/mcp/lifecycle.py.

State Persistence and Snapshot Management

VulnClaw maintains session state through the target-state store (vulnclaw/target_state/store.py). The orchestrator's apply_target_state_to_agent function restores previous snapshots before running tasks, enabling resumable penetration tests.

Session data includes discovered findings, tool outputs, and the blackboard graph. The vulnclaw/plugins/runtime.py merges plugin outputs into session_state.findings, which vulnclaw/report/generator.py renders into Markdown or HTML reports.

Running Your First Scan

With the installation and configuration complete, execute a full penetration test against a target:

# Full automated scan

vulnclaw run http://target.example.com

For stage-specific execution:

# Reconnaissance only

vulnclaw recon http://target.example.com

To resume a previous session using the snapshot ID displayed in prior output:

vulnclaw run http://target.example.com --resume --snapshot-id abc123

Advanced Usage Patterns

Launching the Web Interface

The optional web UI provides a visual interface for monitoring scans. Install extra dependencies and launch:

pip install "vulnclaw[web]"
vulnclaw web

This opens http://127.0.0.1:7788 by default.

Developing Custom Plugins

The low-coupling plugin subsystem in vulnclaw/plugins/ allows you to extend vulnerability detection capabilities. Plugins feed findings back into the blackboard, where the solver integrates them into the reasoning loop. When running from source, modifications to plugin files take effect immediately without reinstallation.

Summary

• Installation: Clone Unclecheng-li/VulnClaw and run pip install -e . to expose the vulnclaw CLI via vulnclaw/cli/main.py.
• Configuration: Set LLM credentials via vulnclaw config or environment variables; storage is handled by vulnclaw/config/settings.py.
• Architecture: The vulnclaw/orchestrator.py manages the agent lifecycle, delegating to vulnclaw/agent/core.py and the OODA loop in vulnclaw/agent/solver.py.
• Tooling: MCP services route through vulnclaw/mcp/router.py, with definitions in vulnclaw/mcp/registry.py.
• Persistence: Session snapshots enable resumable scans via vulnclaw/target_state/store.py.
• Execution: Use vulnclaw run for full tests, vulnclaw recon for specific phases, and --resume with --snapshot-id to continue interrupted sessions.

Frequently Asked Questions

What Python version is required to run VulnClaw from source?

VulnClaw requires Python 3.10 or higher due to its reliance on modern asynchronous patterns and type hinting features used in vulnclaw/agent/core.py and the solver engine. The vulnclaw doctor command verifies your Python version before allowing execution.

Can I run VulnClaw without an LLM API key?

Yes, VulnClaw supports a key-less login flow through certain providers, though functionality may be limited compared to authenticated sessions. You can also configure local LLM endpoints that don't require API keys by modifying the provider settings in ~/.vulnclaw/config.yaml or via the vulnclaw config CLI commands.

How does VulnClaw maintain state between interrupted scans?

The framework uses a snapshot system implemented in vulnclaw/target_state/store.py. When you run a scan, the orchestrator periodically saves the session state, including the blackboard graph and findings. Use the --resume flag with the specific --snapshot-id (displayed in previous command output or via vulnclaw doctor) to restore the exact agent state and continue from the previous checkpoint.

Where are the vulnerability findings stored after a scan completes?

Findings are accumulated in session_state.findings by the plugin runtime (vulnclaw/plugins/runtime.py) during execution. Upon completion, the report generator (vulnclaw/report/generator.py) processes these findings into Markdown or HTML reports saved to your local filesystem. The specific output path is configurable through the vulnclaw/config/schema.py settings.

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