npm package: @modular-intelligence/boofuzz
Description: MCP server wrapping boofuzz for network protocol fuzzing
Latest version: 1.0.3

# Boofuzz MCP Server

A Model Context Protocol (MCP) server that wraps [boofuzz](https://github.com/jtpereyda/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
   ```bash
   python3 --version  # Should be 3.7+
   ```

2. **Boofuzz Package**: Install via pip
   ```bash
   pip install boofuzz
   ```

3. **Node.js/Bun**: For running the MCP server
   ```bash
   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

```bash
cd boofuzz
bun install
bun run build
```

## Usage

### Start the Server

```bash
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:**
```json
{
  "target_host": "testserver.example.com",
  "target_port": 80,
  "authorized": true,
  "protocol": "tcp",
  "template": "http",
  "max_test_cases": 500,
  "timeout": 300
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "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:**
```json
{
  "db_path": "/tmp/boofuzz-results.db"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "db_path": "/tmp/boofuzz-results.db",
  "crash_id": 1
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "protocol": "http"
}
```

**Returns:**
```json
{
  "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:**
```json
{
  "target_host": "testserver.example.com",
  "target_port": 80,
  "authorized": true,
  "protocol": "tcp",
  "timeout": 10
}
```

**Returns:**
```json
{
  "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:

```json
{
  "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):

```bash
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

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

### 2. Generate Protocol Template

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

### 3. List Available Primitives

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

### 4. Run Fuzzing Campaign

```json
{
  "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

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

### 6. Investigate Crashes

```json
{
  "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

```bash
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:

```bash
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](https://boofuzz.readthedocs.io/)
- [Model Context Protocol](https://modelcontextprotocol.io/)
- [OWASP Testing Guide](https://owasp.org/www-project-web-security-testing-guide/)

## License

MIT