Boofuzz MCP Server

A Model Context Protocol (MCP) server that wraps boofuzz for network protocol fuzzing and security testing.

Overview

This MCP server provides tools for fuzzing network protocols using boofuzz, a powerful network protocol fuzzing framework. It supports multiple protocol templates, crash analysis, and session monitoring.

Features

• Protocol Fuzzing: Fuzz HTTP, FTP, SMTP, DNS, Modbus, MQTT, SIP, and Telnet protocols
• Primitive Discovery: List available boofuzz fuzzing primitives
• Session Analysis: Analyze fuzzing session results and crashes
• Protocol Templates: Generate ready-to-use fuzzing scripts
• Target Monitoring: Check service availability and connectivity
• Security Controls: Authorization requirements and private IP blocking

Prerequisites

Required Software

1. Python 3: Required to run boofuzz

   python3 --version  # Should be 3.7+

2. Boofuzz Package: Install via pip

   pip install boofuzz

3. Node.js/Bun: For running the MCP server

   bun --version  # or node --version

Permissions

CRITICAL: You must have explicit written authorization to fuzz any target system. Unauthorized fuzzing is illegal and unethical.

• Always set authorized: true only after obtaining permission
• Default behavior blocks private IP addresses
• Use ALLOW_PRIVATE_TARGETS=true environment variable for internal testing only

Installation

cd boofuzz
bun install
bun run build

Usage

Start the Server

bun run start

Environment Variables

• ALLOW_PRIVATE_TARGETS=true: Allow fuzzing private IP addresses (default: false)

Available Tools

1. boofuzz_fuzz

Fuzz a network protocol target using boofuzz with configurable templates.

Parameters:

• target_host (string, required): Target host IP or hostname
• target_port (number, required): Target port number (1-65535)
• authorized (boolean, required): Confirm authorization to fuzz this target
• protocol (enum, optional): Transport protocol - "tcp", "udp", or "ssl" (default: "tcp")
• template (enum, required): Protocol template - "http", "ftp", "smtp", "dns", "modbus", "mqtt", "sip", or "telnet"
• max_test_cases (number, optional): Maximum test cases to generate, max 10000 (default: 1000)
• timeout (number, optional): Max fuzzing duration in seconds, 30-600 (default: 120)

Example:

{
  "target_host": "testserver.example.com",
  "target_port": 80,
  "authorized": true,
  "protocol": "tcp",
  "template": "http",
  "max_test_cases": 500,
  "timeout": 300
}

Returns:

{
  "target": "testserver.example.com:80",
  "protocol": "tcp",
  "template": "http",
  "test_cases_run": 500,
  "crashes": [
    {
      "test_case_id": 42,
      "primitive": "s_string",
      "value_summary": "See crash analysis for details",
      "error": "Connection reset by peer"
    }
  ],
  "total_crashes": 1,
  "errors": []
}

2. boofuzz_list_primitives

List available boofuzz fuzzing primitives and their descriptions.

Parameters: None

Returns:

{
  "primitives": [
    {
      "name": "s_string",
      "description": "Fuzzable string with various mutations",
      "parameters": "value: str, max_len: int = None, fuzzable: bool = True"
    },
    {
      "name": "s_byte",
      "description": "Single byte (8-bit) value",
      "parameters": "value: int, fuzzable: bool = True, format: str = 'binary'"
    }
  ],
  "total_count": 20,
  "description": "Boofuzz fuzzing primitives for protocol definition and mutation"
}

3. boofuzz_session_results

Read and analyze boofuzz fuzzing session results from database.

Parameters:

• db_path (string, required): Path to boofuzz SQLite results database

Example:

{
  "db_path": "/tmp/boofuzz-results.db"
}

Returns:

{
  "session_id": "session_001",
  "start_time": "2026-02-09T10:00:00Z",
  "end_time": "2026-02-09T10:30:00Z",
  "total_test_cases": 1000,
  "total_crashes": 3,
  "crashes": [
    {
      "id": 1,
      "test_case": 42,
      "primitive": "s_string",
      "data_preview": "AAAA..."
    }
  ],
  "failures": []
}

4. boofuzz_crash_analysis

Analyze specific crash details from a boofuzz fuzzing session.

Parameters:

• db_path (string, required): Path to boofuzz results database
• crash_id (number, optional): Specific crash ID to analyze

Example:

{
  "db_path": "/tmp/boofuzz-results.db",
  "crash_id": 1
}

Returns:

{
  "crash_id": 1,
  "test_case": 42,
  "request_data_hex": "474554202f20485454502f312e31...",
  "response_data": "Connection reset by peer",
  "primitive_info": {
    "name": "s_string",
    "value": "AAAA...",
    "mutation_type": "overflow"
  },
  "reproduced": false,
  "stack_trace": "No stack trace available",
  "timestamp": "2026-02-09T10:15:00Z"
}

5. boofuzz_protocol_template

Generate a boofuzz protocol fuzzing template script.

Parameters:

• protocol (enum, required): Protocol to generate template for - "http", "ftp", "smtp", "dns", "modbus", "mqtt", "sip", or "telnet"

Example:

{
  "protocol": "http"
}

Returns:

{
  "protocol": "http",
  "template_code": "#!/usr/bin/env python3\nfrom boofuzz import *\n...",
  "description": "HTTP GET request fuzzer with path, host, user-agent, and accept headers",
  "fields_fuzzed": ["path", "host", "user_agent", "accept"],
  "usage": "Replace TARGET_HOST and TARGET_PORT with actual values, then execute with Python 3"
}

6. boofuzz_monitor_check

Check target service availability before or during fuzzing.

Parameters:

• target_host (string, required): Target host IP or hostname
• target_port (number, required): Target port number (1-65535)
• authorized (boolean, required): Confirm authorization to fuzz this target
• protocol (enum, optional): Transport protocol - "tcp", "udp", or "ssl" (default: "tcp")
• timeout (number, optional): Connection timeout in seconds, 5-30 (default: 10)

Example:

{
  "target_host": "testserver.example.com",
  "target_port": 80,
  "authorized": true,
  "protocol": "tcp",
  "timeout": 10
}

Returns:

{
  "target": "testserver.example.com",
  "port": 80,
  "protocol": "tcp",
  "reachable": true,
  "response_time_ms": 45,
  "banner": "HTTP/1.1 200 OK",
  "checked_at": "2026-02-09T10:00:00Z"
}

Security Features

Authorization Requirement

All tools that interact with network targets require explicit authorization:

{
  "authorized": true  // Must be set explicitly
}

Attempting to fuzz without authorization will result in an error.

Private IP Blocking

By default, fuzzing private IP addresses is blocked to prevent accidental internal network testing:

• 10.0.0.0/8
• 172.16.0.0/12
• 192.168.0.0/16
• 127.0.0.0/8 (localhost)
• IPv6 private ranges

To enable private IP fuzzing (for authorized internal testing only):

ALLOW_PRIVATE_TARGETS=true bun run start

Rate Limiting

• Maximum test cases: 10,000 per session
• Maximum timeout: 600 seconds (10 minutes)
• Connection timeout: 30 seconds maximum for monitor checks

Allowed Protocols

Only the following protocol templates are allowed:

• HTTP
• FTP
• SMTP
• DNS
• Modbus
• MQTT
• SIP
• Telnet

Example Workflow

1. Check Target Availability

{
  "tool": "boofuzz_monitor_check",
  "arguments": {
    "target_host": "testserver.example.com",
    "target_port": 80,
    "authorized": true
  }
}

2. Generate Protocol Template

{
  "tool": "boofuzz_protocol_template",
  "arguments": {
    "protocol": "http"
  }
}

3. List Available Primitives

{
  "tool": "boofuzz_list_primitives",
  "arguments": {}
}

4. Run Fuzzing Campaign

{
  "tool": "boofuzz_fuzz",
  "arguments": {
    "target_host": "testserver.example.com",
    "target_port": 80,
    "authorized": true,
    "protocol": "tcp",
    "template": "http",
    "max_test_cases": 1000,
    "timeout": 300
  }
}

5. Analyze Results

{
  "tool": "boofuzz_session_results",
  "arguments": {
    "db_path": "/tmp/mcp-boofuzz/fuzz_results.db"
  }
}

6. Investigate Crashes

{
  "tool": "boofuzz_crash_analysis",
  "arguments": {
    "db_path": "/tmp/mcp-boofuzz/fuzz_results.db",
    "crash_id": 1
  }
}

Supported Protocols

HTTP

• GET requests with fuzzable headers
• Path, host, user-agent, and accept field fuzzing
• Default port: 80

FTP

• USER and PASS command fuzzing
• Username and password field fuzzing
• Default port: 21

SMTP

• HELO, MAIL FROM, RCPT TO command fuzzing
• Email address and domain fuzzing
• Default port: 25

DNS

• DNS query packet fuzzing
• Transaction ID, flags, and query name fuzzing
• Default port: 53 (UDP)

Modbus

• Modbus TCP read holding registers fuzzing
• Transaction ID, function code, address fuzzing
• Default port: 502

MQTT

• MQTT CONNECT packet fuzzing
• Client ID, flags, and protocol level fuzzing
• Default port: 1883

SIP

• SIP INVITE request fuzzing
• URI, from, to, and call-ID fuzzing
• Default port: 5060 (UDP)

Telnet

• Telnet option negotiation fuzzing
• Command and option code fuzzing
• Default port: 23

Troubleshooting

Boofuzz Not Found

pip install boofuzz
# or
pip3 install boofuzz

Permission Denied

Ensure you have:

1. Written authorization to test the target
2. Set authorized: true in tool arguments
3. Set ALLOW_PRIVATE_TARGETS=true if testing private IPs

Connection Timeout

• Verify target is reachable
• Check firewall rules
• Increase timeout parameter
• Use boofuzz_monitor_check to verify connectivity

Python Import Errors

Ensure boofuzz is installed in the Python 3 environment:

python3 -c "import boofuzz; print(boofuzz.__version__)"

Best Practices

1. Always Get Authorization: Never fuzz systems without explicit written permission
2. Start Small: Begin with low test case counts to understand target behavior
3. Monitor Target: Use boofuzz_monitor_check before and during fuzzing
4. Analyze Results: Review crashes systematically with boofuzz_crash_analysis
5. Document Findings: Keep records of all fuzzing sessions and results
6. Responsible Disclosure: Report vulnerabilities responsibly to vendors

Legal Notice

This tool is provided for authorized security testing only. Unauthorized use of this tool against systems you do not own or have explicit permission to test is illegal and unethical. The authors assume no liability for misuse of this tool.

References

• Boofuzz Documentation
• Model Context Protocol
• OWASP Testing Guide

License

MIT