How to Integrate VulnClaw with External Tools Like Burp Suite and Frida

VulnClaw integrates with Burp Suite and Frida through its Modular Control Protocol (MCP) layer, which discovers and registers external tool APIs via SSE or stdio transports defined in vulnclaw/config/schema.py.

The Unclecheng-li/VulnClaw repository provides a unified framework for LLM-driven security testing by connecting to external tools through a standardized protocol. This integration allows security researchers to control Burp Suite for HTTP interception and Frida for runtime instrumentation using natural language prompts. All tool configurations, routing logic, and lifecycle management are implemented in the vulnclaw/mcp/ directory.

Understanding the MCP Architecture

VulnClaw communicates with external binaries through the Modular Control Protocol (MCP), an abstraction layer that handles connection lifecycle, tool discovery, and JSON-RPC-like messaging. The architecture separates transport concerns from business logic, enabling seamless switching between local scripts and remote services.

MCP Server Configuration

Built-in server definitions reside in vulnclaw/config/schema.py within the BUILTIN_MCP_SERVERS mapping. Each entry specifies the transport type, command path, or URL endpoint required to reach the external tool.

For Burp Suite, the default configuration uses an SSE transport pointing to http://127.0.0.1:9876 (lines 72–80). The Frida MCP server follows the same pattern, typically exposed via SSE or stdio depending on your deployment model. When enabled: true is set in the user configuration, the MCPLifecycleManager initializes these connections at startup.

Intent Routing and Tool Mapping

The router component in vulnclaw/mcp/router.py translates natural language intents into concrete MCP tool calls. Lines 24–33 define Burp-specific mappings where phrases like 抓包 (capture traffic) and 修改数据包 (modify request) trigger calls to get_proxy_http_history and send_http1_request respectively.

This mapping extends to Frida operations such as "hook signer," which the router directs to the frida_mcp server tools including spawn, attach, and get_messages.

Configuring Burp Suite Integration

Burp Suite integration requires enabling the MCP server in VulnClaw's configuration and launching Burp with its MCP plugin active.

Step 1: Enable Burp in Config

Edit your VulnClaw configuration file (typically ~/.vulnclaw/config.yaml) to activate the Burp server:

mcp:
  servers:
    burp:
      enabled: true
      transport: sse
      url: http://127.0.0.1:9876

The lifecycle manager reads this configuration during initialization via MCPLifecycleManager.start_enabled_servers in vulnclaw/mcp/lifecycle.py.

Step 2: Start Burp MCP Server

Launch Burp Suite with the MCP plugin that exposes the SSE endpoint on port 9876. Once active, VulnClaw probes the connection using _check_http_reachable and discovers available tools via _probe_sse_server. The available Burp tools—including proxy history access, repeater functions, and scanner controls—are registered automatically through _register_runtime_tools (lines 1291–1297 in lifecycle.py).

Step 3: Programmatic Usage

Invoke Burp tools directly through the Python API:

from vulnclaw.cli.main import VulnClawCLI

cli = VulnClawCLI()
result = cli.run_tool(
    server="burp",
    tool="send_http1_request",
    arguments={
        "content": "GET /api/users HTTP/1.1\r\nHost: target.com\r\n\r\n"
    },
)
print(result["content"])  # Access response data

The return dictionary contains ok, content, structured_content, and error_type keys for programmatic error handling.

Configuring Frida Integration

Frida integration follows the same MCP pattern, enabling dynamic instrumentation of mobile and desktop applications through the LLM interface.

Step 1: Enable Frida MCP

Add the Frida server entry to your configuration:

mcp:
  servers:
    frida_mcp:
      enabled: true
      transport: sse
      url: http://127.0.0.1:9877  # Adjust port as needed

The server definition lives conceptually alongside the Burp entry in vulnclaw/config/schema.py, utilizing the same schema validation for tool discovery.

Step 2: Runtime Instrumentation Workflow

Start frida-server on your target device or host, then launch the Frida-MCP server. VulnClaw automatically discovers tools including check_frida_status, list_applications, spawn, attach, and get_messages.

A typical workflow involves checking server status, spawning a target process, and retrieving messages from your instrumentation script:

import asyncio
from vulnclaw.mcp.lifecycle import MCPLifecycleManager
from vulnclaw.config.schema import VulnClawConfig

async def instrument_app():
    cfg = VulnClawConfig.parse_file("~/.vulnclaw/config.yaml")
    
    async with MCPLifecycleManager(cfg) as mgr:
        # Verify Frida server connectivity

        await mgr.health_check("frida_mcp")
        
        frida_session = await mgr._get_or_create_session("frida_mcp")
        
        # List installed applications

        apps = await frida_session.call_tool(
            "list_applications", 
            arguments={}
        )
        
        # Spawn target process (com.example.app)

        await frida_session.call_tool(
            "spawn",
            arguments={"package": "com.example.app"}
        )
        
        # Retrieve Frida script output

        messages = await frida_session.call_tool(
            "get_messages",
            arguments={}
        )
        print(messages["content"])

asyncio.run(instrument_app())

Lifecycle Management Deep Dive

The MCPLifecycleManager class in vulnclaw/mcp/lifecycle.py orchestrates server connections. When VulnClaw starts, the manager executes start_enabled_servers, which iterates through the configuration and initializes each MCP connection.

For Burp specifically, the manager uses the _call_burp dispatch method (lines 1525–1529) to handle tool invocations. The system lazily loads tool lists upon first connection, caching the available methods to minimize latency on subsequent calls.

Health check operations verify reachability before routing requests, ensuring the LLM receives immediate feedback if an external tool becomes unavailable.

Practical Integration Examples

Enable both servers via the CLI helper and run interactive sessions:

# One-time configuration

vulnclaw config set mcp.servers.burp.enabled true
vulnclaw config set mcp.servers.frida_mcp.enabled true

# Start interactive mode

vulnclaw

In the interactive chat:

• "抓包" triggers get_proxy_http_history via Burp
• "修改数据包" opens the request editor through Burp's repeater
• "hook signer" initiates Frida instrumentation via attach and spawn

Summary

• MCP Architecture: VulnClaw uses the Modular Control Protocol to abstract external tools, with configurations in vulnclaw/config/schema.py and routing logic in vulnclaw/mcp/router.py.
• Burp Integration: Enable via mcp.servers.burp.enabled, ensure the MCP plugin runs on 127.0.0.1:9876, and use intents like 抓包 to trigger get_proxy_http_history.
• Frida Integration: Configure frida_mcp server settings, start frida-server, and access tools including list_applications, spawn, and get_messages through the lifecycle manager.
• Lifecycle Management: MCPLifecycleManager handles startup, health checks, tool discovery via _probe_sse_server, and registration through _register_runtime_tools.

Frequently Asked Questions

What transport protocols does VulnClaw support for external tool integration?

VulnClaw supports SSE (Server-Sent Events) and stdio transports as defined in the MCP server configuration. Burp Suite typically uses SSE over HTTP at 127.0.0.1:9876, while Frida can operate via SSE or stdio depending on whether you run the MCP server as a persistent service or a subprocess.

Where does VulnClaw store the mapping between user intents and specific tool functions?

Intent-to-tool mappings are defined in vulnclaw/mcp/router.py. For example, the Chinese phrase 抓包 maps to Burp's get_proxy_http_history tool, while 修改数据包 routes to send_http1_request. These mappings allow the LLM to translate natural language requests into concrete MCP tool calls without hard-coding API specifics in the prompts.

How do I troubleshoot connection failures between VulnClaw and Burp Suite?

First, verify the Burp MCP plugin is active and listening on the configured port (default 9876). VulnClaw's MCPLifecycleManager runs _check_http_reachable during startup to validate connections. Check the ok and error_type fields in the tool response dictionary, or call await mgr.health_check("burp") programmatically to diagnose connectivity issues before attempting tool execution.

Can I integrate tools other than Burp Suite and Frida using the same method?

Yes. Any tool implementing the MCP specification can be integrated by adding a new entry to BUILTIN_MCP_SERVERS in vulnclaw/config/schema.py or via user configuration. The MCPLifecycleManager automatically discovers available tools through _probe_sse_server or _probe_http_server, making the system extensible to custom security scanners, debuggers, or fuzzing frameworks.

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