npm package: @modular-intelligence/ffuf
Description: MCP server wrapping ffuf for web fuzzing and content discovery
Latest version: 1.0.2

# ffuf MCP Server

A Model Context Protocol (MCP) server that wraps the [ffuf](https://github.com/ffuf/ffuf) web fuzzing tool for content discovery and security testing.

## Overview

This MCP server provides secure access to ffuf's web fuzzing capabilities through a controlled interface with built-in security restrictions. It enables LLM agents to perform web content discovery, virtual host enumeration, parameter fuzzing, and other reconnaissance tasks.

## Features

- **Directory & File Fuzzing**: Discover hidden paths, backup files, and exposed content
- **Virtual Host Discovery**: Enumerate vhosts and alternative hostnames
- **Parameter Fuzzing**: Find hidden or undocumented HTTP parameters
- **Subdomain Enumeration**: Map subdomains for a target domain
- **Recursive Fuzzing**: Automatically fuzz discovered directories
- **Multi-Position Fuzzing**: Fuzz multiple URL positions simultaneously
- **Configuration Management**: Access common wordlists and fuzzing patterns

## Prerequisites

### 1. Install ffuf

**macOS (Homebrew):**
```bash
brew install ffuf
```

**Linux (from releases):**
```bash
wget https://github.com/ffuf/ffuf/releases/latest/download/ffuf_2.1.0_linux_amd64.tar.gz
tar -xzf ffuf_2.1.0_linux_amd64.tar.gz
sudo mv ffuf /usr/local/bin/
```

**From source:**
```bash
go install github.com/ffuf/ffuf/v2@latest
```

### 2. Install Wordlists

**SecLists (recommended):**
```bash
# macOS
brew install seclists

# Linux
git clone https://github.com/danielmiessler/SecLists.git /usr/share/seclists
```

**DirBuster wordlists:**
```bash
sudo apt-get install dirbuster  # Linux
```

### 3. Verify Installation

```bash
ffuf -V
# Should output: ffuf version 2.x.x
```

## Installation

```bash
cd /path/to/mi-mcp-servers/packages/ffuf
bun install
bun run build
```

## Usage

### Starting the Server

```bash
bun run start
```

Or add to your MCP client configuration:

```json
{
  "mcpServers": {
    "ffuf": {
      "command": "bun",
      "args": ["run", "/path/to/mi-mcp-servers/packages/ffuf/src/index.ts"]
    }
  }
}
```

## Available Tools

### 1. ffuf_dir_fuzz

Fuzz directories and files to discover hidden content.

**Parameters:**
- `url` (string, required): Target URL with FUZZ keyword (e.g., `http://target.com/FUZZ`)
- `authorized` (boolean, required): Must be `true` to confirm authorization
- `wordlist` (string, required): Absolute path to wordlist file
- `threads` (number, optional): Concurrent threads (1-50, default: 10)
- `rate` (number, optional): Requests per second (1-1000, default: 100)
- `extensions` (string, optional): File extensions (e.g., `.php,.html,.js`)
- `filter` (object, optional): Response filters (status_codes, size, words, lines)
- `timeout` (number, optional): Max duration in seconds (30-600, default: 120)

**Example:**
```json
{
  "url": "http://example.com/FUZZ",
  "authorized": true,
  "wordlist": "/usr/share/seclists/Discovery/Web-Content/common.txt",
  "threads": 20,
  "rate": 200,
  "extensions": ".php,.html",
  "filter": {
    "status_codes": "404,403"
  }
}
```

### 2. ffuf_vhost_fuzz

Discover virtual hosts by fuzzing the Host header.

**Parameters:**
- `url` (string, required): Base target URL
- `authorized` (boolean, required): Must be `true`
- `wordlist` (string, required): Wordlist path
- `host_header` (string, optional): Host pattern with FUZZ (default: `FUZZ.target.com`)
- `threads`, `rate`, `filter`, `timeout`: Same as dir_fuzz

**Example:**
```json
{
  "url": "http://10.10.10.100",
  "authorized": true,
  "wordlist": "/usr/share/seclists/Discovery/DNS/namelist.txt",
  "host_header": "FUZZ.example.com",
  "filter": {
    "size": "1234"
  }
}
```

### 3. ffuf_param_fuzz

Fuzz HTTP parameters (GET or POST).

**Parameters:**
- `url` (string, required): Target URL with FUZZ
- `authorized` (boolean, required): Must be `true`
- `wordlist` (string, required): Wordlist path
- `method` (enum, optional): "GET" or "POST" (default: "GET")
- `data` (string, optional): POST data with FUZZ (e.g., `param=FUZZ`)
- `threads`, `rate`, `filter`, `timeout`: Same as dir_fuzz

**Example (POST):**
```json
{
  "url": "http://example.com/login",
  "authorized": true,
  "wordlist": "/usr/share/seclists/Discovery/Web-Content/burp-parameter-names.txt",
  "method": "POST",
  "data": "FUZZ=test",
  "filter": {
    "status_codes": "404"
  }
}
```

### 4. ffuf_subdomain_fuzz

Enumerate subdomains for a domain.

**Parameters:**
- `domain` (string, required): Target domain (e.g., `example.com`)
- `authorized` (boolean, required): Must be `true`
- `wordlist` (string, required): Subdomain wordlist path
- `threads`, `rate`, `filter`, `timeout`: Same as dir_fuzz

**Example:**
```json
{
  "domain": "example.com",
  "authorized": true,
  "wordlist": "/usr/share/seclists/Discovery/DNS/subdomains-top1million-5000.txt",
  "filter": {
    "status_codes": "404"
  }
}
```

### 5. ffuf_recursive_fuzz

Perform recursive directory fuzzing.

**Parameters:**
- `url` (string, required): Target URL with FUZZ
- `authorized` (boolean, required): Must be `true`
- `wordlist` (string, required): Wordlist path
- `depth` (number, optional): Recursion depth (1-5, default: 2)
- `threads`, `rate`, `filter`, `timeout`: Same as dir_fuzz

**Warning:** Recursive fuzzing can generate many requests. Use cautiously.

**Example:**
```json
{
  "url": "http://example.com/FUZZ",
  "authorized": true,
  "wordlist": "/usr/share/seclists/Discovery/Web-Content/common.txt",
  "depth": 2,
  "threads": 10,
  "rate": 50
}
```

### 6. ffuf_multi_fuzz

Fuzz multiple positions with multiple wordlists.

**Parameters:**
- `url` (string, required): URL with multiple keywords (FUZZ, W2, W3)
- `authorized` (boolean, required): Must be `true`
- `wordlists` (array, required): Array of wordlist paths (1-3 wordlists)
- `mode` (enum, optional): "clusterbomb" or "pitchfork" (default: "clusterbomb")
- `threads`, `rate`, `filter`, `timeout`: Same as dir_fuzz

**Modes:**
- `clusterbomb`: Test all combinations (cartesian product)
- `pitchfork`: Iterate wordlists in parallel

**Example:**
```json
{
  "url": "http://example.com/FUZZ/W2",
  "authorized": true,
  "wordlists": [
    "/usr/share/seclists/Discovery/Web-Content/common.txt",
    "/usr/share/seclists/Discovery/Web-Content/common.txt"
  ],
  "mode": "clusterbomb"
}
```

### 7. ffuf_config_list

List common wordlists and configurations. No parameters required.

**Example:**
```json
{}
```

## Security Features

### Authorization Required

All fuzzing operations require explicit authorization confirmation:

```json
{
  "authorized": true
}
```

This ensures the user acknowledges they have permission to test the target.

### Private IP Blocking

The server blocks fuzzing of private IP addresses and localhost:
- `10.0.0.0/8`
- `172.16.0.0/12`
- `192.168.0.0/16`
- `127.0.0.0/8`
- `localhost`, `*.local`, `*.localhost`
- IPv6 loopback (`::1`) and link-local (`fe80::`)

### Rate Limiting

- Maximum 1000 requests per second
- Configurable per request
- Prevents overwhelming targets

### Thread Limiting

- Maximum 50 concurrent threads
- Prevents resource exhaustion
- Configurable per request

### Recursion Depth Limiting

- Maximum depth of 5 levels
- Prevents runaway recursive scans

### Wordlist Validation

- Must be absolute paths
- No path traversal (`..`)
- Must end in `.txt` or `.lst`

### Blocked Operations

- Cannot write output files (`-o`, `-of` flags blocked in CLI args)
- All output returned through MCP protocol

### Timeout Protection

- Default 120 seconds
- Maximum 600 seconds (10 minutes)
- SIGKILL cleanup on timeout

## Best Practices

### 1. Start Small

Always test with a small wordlist first to establish baseline filters:

```json
{
  "wordlist": "/usr/share/seclists/Discovery/Web-Content/common.txt",
  "filter": {
    "status_codes": "404"
  }
}
```

### 2. Use Appropriate Filters

Filter out noise by response characteristics:

```json
{
  "filter": {
    "status_codes": "404,403",
    "size": "1234",
    "words": "100"
  }
}
```

### 3. Be Respectful

Use appropriate rate limits:
- Development servers: 50-100 req/s
- Production servers: 10-50 req/s
- Shared hosting: 5-10 req/s

### 4. Test Authorization

Always ensure you have explicit written authorization before fuzzing.

### 5. Monitor Response Times

If requests are slow, reduce thread count and rate limit.

## Common Wordlists

| Name | Path | Entries | Use Case |
|------|------|---------|----------|
| Common | `/usr/share/seclists/Discovery/Web-Content/common.txt` | ~4.6k | Quick discovery |
| Big | `/usr/share/seclists/Discovery/Web-Content/big.txt` | ~20k | Thorough scan |
| RAFT Large | `/usr/share/seclists/Discovery/Web-Content/raft-large-directories.txt` | ~62k | Comprehensive |
| Parameters | `/usr/share/seclists/Discovery/Web-Content/burp-parameter-names.txt` | ~2.5k | Parameter fuzzing |
| Subdomains | `/usr/share/seclists/Discovery/DNS/subdomains-top1million-5000.txt` | ~5k | Subdomain enum |
| DirBuster Medium | `/usr/share/wordlists/dirbuster/directory-list-2.3-medium.txt` | ~220k | Deep discovery |

## Troubleshooting

### ffuf command not found

Ensure ffuf is installed and in your PATH:
```bash
which ffuf
ffuf -V
```

### Permission denied on wordlist

Ensure the wordlist file is readable:
```bash
ls -l /path/to/wordlist.txt
chmod +r /path/to/wordlist.txt
```

### Timeout errors

Increase timeout or reduce wordlist size:
```json
{
  "timeout": 300,
  "rate": 50
}
```

### Too many false positives

Add filters to remove noise:
```json
{
  "filter": {
    "status_codes": "404",
    "size": "1234",
    "words": "100-200"
  }
}
```

## Example Workflows

### Basic Directory Discovery

```json
{
  "url": "http://example.com/FUZZ",
  "authorized": true,
  "wordlist": "/usr/share/seclists/Discovery/Web-Content/common.txt",
  "extensions": ".php,.html,.txt",
  "filter": {
    "status_codes": "404"
  },
  "threads": 20,
  "rate": 100
}
```

### Virtual Host Enumeration

```json
{
  "url": "http://10.10.10.100",
  "authorized": true,
  "wordlist": "/usr/share/seclists/Discovery/DNS/namelist.txt",
  "host_header": "FUZZ.example.com",
  "filter": {
    "size": "1234"
  }
}
```

### API Parameter Discovery

```json
{
  "url": "http://api.example.com/v1/user?FUZZ=test",
  "authorized": true,
  "wordlist": "/usr/share/seclists/Discovery/Web-Content/burp-parameter-names.txt",
  "method": "GET",
  "filter": {
    "status_codes": "404,400"
  }
}
```

## Development

### Building

```bash
bun run build
```

### Testing

```bash
# Test with a safe target (your own server)
echo "test" > /tmp/test-wordlist.txt
```

Then call the tool with your test configuration.

## License

MIT

## Disclaimer

This tool is for authorized security testing only. Always obtain explicit written permission before testing any system you do not own. Unauthorized access to computer systems is illegal.

## Contributing

Contributions welcome! Please ensure all changes maintain security restrictions and add appropriate validation.