Can VulnClaw Be Integrated With Other Tools? A Technical Guide to AI-Driven Security Orchestration

Yes, VulnClaw integrates with external security tools through three primary mechanisms: the MCP (Model-Context-Protocol) toolchain for remote services, a sandboxed plugin subsystem for Python extensions, and builtin tool wrappers for local utilities like nmap and Python execution.

VulnClaw, developed by Unclecheng-li, functions as an AI-driven penetration-testing orchestrator designed to natively interface with third-party scanners and automation frameworks. The platform exposes multiple architectural layers that allow large language models to invoke external tools without modifying core source code, enabling seamless integration into existing red-team pipelines and CTF workflows.

Three Core Integration Mechanisms

MCP Toolchain for Remote Services

The MCP (Model-Context-Protocol) toolchain provides the primary interface for remote tool integration. Located in vulnclaw/mcp/registry.py, the MCPRegistry class maintains a central catalog of MCPServerState objects and available tools in the _tools dictionary. When the LLM requires a remote capability—such as Chrome DevTools, Burp Suite, or custom HTTP servers—the vulnclaw/mcp/router.py dispatches JSON-RPC-like calls to the appropriate server endpoint.

The registry tracks health metrics and latency via record_tool_call, ensuring reliable orchestration across distributed toolchains. This layer enables VulnClaw to call out to any MCP-compliant server as if it were a native function.

Plugin Subsystem for Python Extensions

For low-coupling Python integrations, VulnClaw implements a plugin subsystem housed in vulnclaw/plugins/. Plugins are discovered via the registry and executed in a sandboxed runtime environment. Users invoke plugins through the CLI using vulnclaw plugins run <id>, which instantiates the plugin class and executes its run method with the current session state.

Results from plugin execution merge into the blackboard as Facts—structured data that the solver can reason about in subsequent OODA loops. Example implementations include vulnclaw/plugins/web/headers.py for web header analysis.

Builtin Tool Wrappers for Local Execution

When tools should run locally without external server overhead, VulnClaw uses builtin tool wrappers defined in vulnclaw/agent/builtin_tools.py. These Python functions—such as nmap_scan, python_execute, and crypto_decode—are registered automatically with the LLM client in vulnclaw/agent/llm_client.py.

Although these bypass the MCP layer, they still obey the same Fact/Intent flow, returning structured results that feed back into the reasoning engine.

Configuration-Driven Extensibility

Integration endpoints are configurable through a declarative YAML schema defined in vulnclaw/config/schema.py. Users enable, disable, or add MCP servers at runtime by editing ~/.vulnclaw/config.yaml or using CLI commands like vulnclaw config set mcp.servers.<name>.enabled true. The schema validates server names, transport types (stdio, HTTP), and command-line arguments before establishing connections.

How Tool Integration Works: The Data Flow

Understanding the integration architecture requires following the data flow from LLM decision to tool execution:

1. Registry Lookup – The LLM generates a tool call intent. The router queries MCPRegistry._tools to locate the target server and tool metadata.
2. Dispatch – The router forwards the payload to the appropriate MCPServerState instance, handling transport-specific communication.
3. Execution – For MCP servers, the remote process executes and returns results. For plugins, the sandboxed runtime invokes the run method. For builtins, local Python functions execute directly.
4. Fact Integration – All results normalize into Facts and merge into the blackboard, where vulnclaw/agent/solver.py consumes them for the next reasoning cycle.

This unified flow ensures that external tools—whether remote scanners or local decoders—integrate seamlessly into the AI's decision-making process.

Practical Integration Examples

Adding a Custom MCP Server (ZAP Proxy)

Configure a new OWASP ZAP instance via YAML:

# ~/.vulnclaw/config.yaml

mcp:
  servers:
    zap-proxy:
      enabled: true
      transport:
        type: stdio
        command: zap-cli
        args: ["-daemon", "-host", "127.0.0.1", "-port", "8090"]

Enable via CLI:

vulnclaw config set mcp.servers.zap-proxy.enabled true

Once started, ZAP tools like zap_spider become callable:

vulnclaw plugins run zap_spider --target https://example.com

Registering a New Tool via Python API

Programmatically register custom tools for LLM access:

from vulnclaw.mcp.registry import MCPRegistry

registry = MCPRegistry()
registry.register_server("my-http-server")
registry.register_tool(
    server_name="my-http-server",
    tool_schema={
        "name": "http_get",
        "description": "Simple HTTP GET request",
        "input_schema": {
            "type": "object",
            "properties": {"url": {"type": "string"}},
            "required": ["url"],
        },
        "server_name": "my-http-server",
    },
)

Running Builtin Tools from CLI

Execute local utilities directly:

# Run Nmap scan on ports 80-443

vulnclaw plugins run nmap_scan --target 192.168.1.100 --ports 80,443

Internally, this invokes vulnclaw/agent/builtin_tools.py:

from vulnclaw.agent.builtin_tools import nmap_scan

result = nmap_scan(target="192.168.1.100", ports=[80, 443])
print(result)  # Structured JSON of open ports

Loading Knowledge Base References

Integrate documentation for CTF workflows:

vulnclaw plugins run load_skill_reference \
    --skill ctf-web \
    --doc sql_injection_basic

This fetches reference files from vulnclaw/skills/ctf_web/ and returns prompt chunks for LLM reasoning.

Key Source Files for Integration

The following files implement the integration architecture:

• vulnclaw/mcp/registry.py – Central MCP registry, server metadata, and health tracking via record_tool_call
• vulnclaw/mcp/router.py – Dispatches tool calls to appropriate MCPServerState instances
• vulnclaw/plugins/web/headers.py – Example plugin implementation (web header analysis)
• vulnclaw/agent/builtin_tools.py – Local utility wrappers including nmap_scan and python_execute
• vulnclaw/config/schema.py – Pydantic schema for MCP configuration validation
• vulnclaw/agent/solver.py – Core OODA loop consuming Facts from external tools
• vulnclaw/cli/main.py – CLI entry point for plugin and configuration commands

Summary

• VulnClaw integrates with external tools through the MCP toolchain, plugin subsystem, and builtin wrappers.
• MCP servers like Chrome DevTools and Burp Suite register in vulnclaw/mcp/registry.py and route through router.py.
• Plugins run in a sandboxed environment and return Facts to the blackboard for solver reasoning.
• Builtin tools bypass the MCP layer for local execution while maintaining the same Fact/Intent flow.
• YAML configuration in vulnclaw/config/schema.py enables runtime server addition without code changes.

Frequently Asked Questions

Can VulnClaw integrate with Burp Suite and Chrome DevTools?

Yes. VulnClaw's MCP toolchain in vulnclaw/mcp/registry.py natively supports registering remote services including Chrome DevTools, Burp Suite, and custom HTTP servers. These tools expose their capabilities via the MCP protocol, allowing the LLM to invoke them through JSON-RPC-like calls routed by vulnclaw/mcp/router.py.

How do I add a custom MCP server to VulnClaw?

Add your server to ~/.vulnclaw/config.yaml under the mcp.servers section, specifying the transport type (stdio or HTTP), command, and arguments. The vulnclaw/config/schema.py validates the configuration. Once enabled via vulnclaw config set, the server’s tools become immediately addressable by name in the LLM toolchain.

What is the difference between plugins and builtin tools?

Plugins are external Python modules loaded into a sandboxed runtime from vulnclaw/plugins/, typically used for custom analysis scripts like JWT decoders. Builtin tools are local Python functions defined in vulnclaw/agent/builtin_tools.py (such as nmap_scan and crypto_decode) that execute directly without requiring an external MCP server process.

Where does VulnClaw store tool execution results?

Results from all integration mechanisms—MCP servers, plugins, and builtins—normalize into Facts and merge into the session blackboard. The solver in vulnclaw/agent/solver.py consumes these Facts during its OODA loop, allowing the LLM to reason about tool outputs in subsequent penetration testing steps.

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