Where to Find VulnClaw Documentation: Complete Guide to Setup and Usage

The complete VulnClaw documentation is hosted in the GitHub repository at Unclecheng-li/VulnClaw, primarily in the README files, docs/ directory, and inline source code comments.

VulnClaw is an AI-driven penetration-testing CLI that orchestrates LLM agents and MCP toolchains for authorized security testing. All user-facing documentation for this open-source tool lives directly within the repository, making it easy to access setup guides, architectural details, and API references without external dependencies. Whether you are installing from PyPI or building from source, the documentation covers every component from the goal-driven solve engine to the plugin registry.

Primary Documentation Locations

README Files (README.md and README_EN.md)

The main entry point for new users is README.md at the repository root, which contains the high-level introduction, quick-start instructions, and the CLI command reference. Non-Chinese readers can reference README_EN.md for the same content in English, ensuring accessibility for international contributors.

Specialized Deployment Guides

For specific deployment scenarios, the repository includes dedicated markdown files:

• docs/mcp-deployment.md – Detailed steps for configuring Model-Context-Protocol services including fetch, memory, chrome-devtools, and burp
• DOCKER.md – Containerization instructions covering environment variables, volume mounting, and port mapping
• SECURITY.md – Usage constraints and legal disclaimers emphasizing authorized testing only
• CONTRIBUTING.md – Guidelines for submitting patches, opening issues, and running the test suite

Architectural Documentation in Source Code

The architectural implementation is documented through well-commented source files in the vulnclaw/ directory. According to the VulnClaw source code, the system implements a goal-driven solve engine in vulnclaw/agent/solver.py, which replaces traditional fixed-round loops with a Fact/Intent blackboard graph. This engine stops when the target is reached, the frontier is exhausted, or the safety budget is depleted.

Key implementation files include:

• vulnclaw/agent/solver.py – Implements the OODA loop and blackboard logic
• vulnclaw/plugins/registry.py – Registers and loads vulnerability-detection plugins
• vulnclaw/mcp/router.py – Routes natural-language tool calls to MCP services
• vulnclaw/report/generator.py – Transforms session data into markdown or HTML reports
• vulnclaw/skills/crypto_tools.py – Houses the 29 built-in cryptographic and encoding utilities

The evidence-level anti-hallucination gate requires every claim (such as a captured flag) to appear verbatim in real tool output before acceptance, preventing LLM fabrication.

Skill Library and Plugin System

The documentation references a skill library containing 21 core skills (7 core plus 14 specialized) and a knowledge base of 180 reference documents, defined in vulnclaw/skills/. The plugin system maintains low-coupling vulnerability-detection plugins under vulnclaw/plugins/ that automatically feed findings into the report pipeline.

Quick Start Commands

The CLI documentation in the README provides these essential commands for authorized penetration testing:

# Install from PyPI (recommended)

pip install vulnclaw

# Or install from source

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

# Verify the environment

vulnclaw doctor

# One-click full scan (uses the default solve engine)

vulnclaw run <target>

# Continuous penetration testing (100 rounds per cycle)

vulnclaw persistent <target>

# Reconnaissance phase only

vulnclaw recon <target>

# Generate report from saved session

vulnclaw report session_123.json

# Start the Web UI (default port 7788)

vulnclaw web

Testing and CI Documentation

Continuous integration configuration is documented in .github/workflows/ci.yml, which defines the test matrix and publishing steps. The tests/ directory contains the validation suite that can be executed with pytest -q to verify core functionality against concrete examples.

Summary

• Primary documentation resides in README.md and README_EN.md at the repository root, with specialized guides in docs/ and DOCKER.md
• Architecture details are documented in source files like vulnclaw/agent/solver.py and vulnclaw/plugins/registry.py
• MCP deployment instructions are found in docs/mcp-deployment.md covering four built-in services
• CLI commands are fully documented in the README under "CLI 命令速查" with examples for vulnclaw run, vulnclaw persistent, and vulnclaw web
• Security and legal constraints are defined in SECURITY.md requiring authorized testing only

Frequently Asked Questions

Where is the official VulnClaw documentation hosted?

All official documentation is hosted within the GitHub repository at github.com/Unclecheng-li/VulnClaw. The primary documentation includes the root-level README files, the docs/ directory containing deployment guides, and extensive inline comments in the source code. There is no external documentation site; GitHub renders all markdown files automatically for browser viewing.

How do I configure the MCP services for VulnClaw?

MCP service configuration is documented in docs/mcp-deployment.md. This guide covers setting up the four built-in services: fetch for HTTP requests, memory for local state persistence, chrome-devtools for browser automation, and burp for traffic replay. The file includes detailed installation steps and connection parameters required by vulnclaw/mcp/router.py.

What is the difference between vulnclaw run and vulnclaw persistent?

According to the CLI documentation in the README, vulnclaw run <target> executes a one-click full scan using the default goal-driven solve engine, while vulnclaw persistent <target> runs continuous penetration testing with 100 rounds per cycle. Both commands utilize the OODA loop implementation in vulnclaw/agent/solver.py, but the persistent mode continues until manually stopped or the safety budget is exhausted.

Can I use VulnClaw without installing the MCP services?

Yes, but functionality will be limited. The MCP toolchain provides enhanced capabilities through four services that enable HTTP requests, browser automation, and traffic replay. Without these services, the agent cannot leverage the full routing capabilities of vulnclaw/mcp/router.py, though core vulnerability scanning through the plugin system in vulnclaw/plugins/ remains available.

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