How to Contribute to the VulnClaw Project: A Complete Developer Guide

Contributing to the VulnClaw project requires forking the repository, installing dependencies via Hatch, modifying the relevant modular component (Agent, CLI, or Skills), running the full pytest suite, and submitting a PR that includes updated documentation and version bumps for any public API changes.

VulnClaw is a modular, AI-powered penetration-testing framework developed by Unclecheng-li. When you contribute to the VulnClaw project, you are extending a codebase that strictly separates concerns between task orchestration, agent logic, and markdown-driven skills. This guide provides the exact file paths and code patterns found in the source code to ensure your changes align with the architecture.

Clone and Configure the Development Environment

Start by cloning the repository and installing Python dependencies via Hatch, the project's environment manager.

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

For frontend modifications, navigate to the frontend directory and install Node.js dependencies.

cd frontend && npm ci

The README.md provides a quick start guide, while CONTRIBUTING.md explains the repository layout in detail according to the Unclecheng-li/VulnClaw source code.

Understand the Modular Architecture

Before modifying code, identify the correct module to avoid "spaghetti" changes. The repository organizes functionality into distinct subsystems, each owning specific behaviors.

Key Entry Points and Subsystems:

• Task Orchestration – vulnclaw/orchestrator.py handles the shared "run → save → summarize" workflow for CLI, Web, and REPL interfaces.
• Agent Core – vulnclaw/agent/core.py and vulnclaw/agent/llm_client.py manage auto-pivot logic, tool calls, and LLM request handling with retries.
• CLI Interface – vulnclaw/cli/main.py defines Typer sub-commands, while vulnclaw/cli/tui.py and vulnclaw/cli/tui_textual.py manage the Textual dashboard and slash-command handling.
• Configuration – vulnclaw/config/schema.py uses Pydantic models to define configuration schemas and environment variable overrides.
• Skill System – vulnclaw/skills/ contains markdown-driven attack logic, with vulnclaw/skills/dispatcher.py mapping natural-language intents to skill IDs.
• Web Backend – vulnclaw/web/app.py exposes FastAPI endpoints for task management, while vulnclaw/web/services/ handles business logic.
• Report Generation – vulnclaw/report/generator.py renders markdown and HTML output with PoC sections.

Implement Changes by Subsystem

Add a New Skill

Skills in VulnClaw are markdown-driven. To add a new capability like SQL injection payload generation:

1. Create a directory under vulnclaw/skills/specialized/ (e.g., sql-injection/).
2. Add a SKILL.md file with YAML front-matter defining the name, description, and trigger keywords.
3. Update vulnclaw/skills/dispatcher.py to register the intent mapping.

---
name: sql-injection
description: Generate payloads for blind SQL injection
trigger:
  - "sql injection"
  - "sqli"
---

# SQLi Payload Generator

Step-by-step instructions here...

# In vulnclaw/skills/dispatcher.py

SKILL_INTENT_MAP["sql-injection"] = ["sql injection", "sqli"]

The dispatcher acts as the bridge that turns natural-language intent into a skill lookup, as implemented in the Unclecheng-li/VulnClaw repository.

Extend Agent Tools

To add a custom tool available to the LLM (e.g., an nmap wrapper), edit vulnclaw/agent/builtin_tools.py and use the register_tool function from the tool call manager.

# vulnclaw/agent/builtin_tools.py

from .tool_call_manager import register_tool

def nmap_scan(target: str, ports: str = "1-65535") -> str:
    """Run nmap and return the raw stdout."""
    import subprocess, shlex
    cmd = f"nmap -p {shlex.quote(ports)} {shlex.quote(target)}"
    result = subprocess.run(cmd, shell=True, capture_output=True, text=True, timeout=120)
    return result.stdout

register_tool(
    name="nmap_scan",
    func=nmap_scan,
    description="Perform an nmap port scan on a target host."
)

The tool_call_manager handles deduplication and execution, embedding results back into the Agent's prompt loop. This pattern mirrors existing tools like python_execute and mcp_bridge defined in the same file.

Modify CLI Behavior

For new CLI commands, edit vulnclaw/cli/main.py using Typer to add sub-commands or modify output formatting. For TUI dashboard changes, modify vulnclaw/cli/tui.py to adjust layouts, slash-command handling, or popup dialogs.

Validate Your Changes

Every contribution must pass the existing test suite and lint checks. Run the full backend test suite before submitting.

pytest -q

If you modified the frontend, run the Node.js test suite.

npm run test

The repository uses GitHub Actions (.github/workflows/ci.yml) to enforce these checks automatically. Additionally, verify that no secrets are exposed in your code, as the repository maintains a strict security policy against embedding credentials.

Submit a Pull Request

Push your feature branch to your fork and open a PR against the main branch. Fill out the PR template provided in .github/ISSUE_TEMPLATE/ and verify the following checklist from CONTRIBUTING.md:

• All tests pass (pytest -q).
• Documentation is updated (add entries to the Skill Index in README.md and update CLI usage tables if flags changed).
• Version is bumped in pyproject.toml and vulnclaw/__init__.py if you modified the public API.
• No security-related secrets are introduced.

Summary

• Fork and Branch: Create a feature branch from your fork of Unclecheng-li/VulnClaw.
• Target the Right Module: Edit the component that owns the behavior—Agent logic in vulnclaw/agent/, Skills in vulnclaw/skills/, and CLI in vulnclaw/cli/.
• Use the Dispatcher: Register new skills in vulnclaw/skills/dispatcher.py to map intents to skill IDs.
• Register Tools: Add custom capabilities via register_tool() in vulnclaw/agent/builtin_tools.py.
• Test Thoroughly: Run pytest -q and ensure CI passes via .github/workflows/ci.yml.
• Document Changes: Update README.md, skill indices, and usage tables alongside your code.

Frequently Asked Questions

Where should I add unit tests for new skills?

Add unit tests under tests/test_skills.py to ensure the skill loads correctly and the dispatcher resolves intents. Verify that the skill body contains expected content and that trigger keywords map to the correct skill ID according to the vulnclaw/skills/dispatcher.py logic.

How do I register a new tool for the LLM Agent?

Import register_tool from vulnclaw/agent/tool_call_manager in vulnclaw/agent/builtin_tools.py, define your function with type hints and proper shell escaping, and pass it to register_tool() with a name and description. The Agent will automatically discover it via the tool call manager and make it available for LLM invocation.

What documentation must be updated when contributing to VulnClaw?

Update the Skill Index in README.md (or README_EN.md) for new skills, modify the CLI usage table in vulnclaw/cli/main.py if you added flags, and bump the version in pyproject.toml and vulnclaw/__init__.py for public API changes. Always reference CONTRIBUTING.md for the full checklist and follow the "right-place" rule to document changes in the module that owns the behavior.

How does the Skill dispatcher map natural language to skills?

The vulnclaw/skills/dispatcher.py file contains a SKILL_INTENT_MAP dictionary that associates skill IDs with trigger keywords. When the Agent receives natural language input, it searches this map to identify which skill markdown file to load and execute, enabling the modular, markdown-driven architecture of the framework.

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