ffuf MCP Server

A Model Context Protocol (MCP) server that wraps the 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):

brew install ffuf

Linux (from releases):

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:

go install github.com/ffuf/ffuf/v2@latest

2. Install Wordlists

SecLists (recommended):

# macOS
brew install seclists

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

DirBuster wordlists:

sudo apt-get install dirbuster  # Linux

3. Verify Installation

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

Installation

cd /Users/ehenry/Documents/code/mcp-servers/ffuf
bun install
bun run build

Usage

Starting the Server

bun run start

Or add to your MCP client configuration:

{
  "mcpServers": {
    "ffuf": {
      "command": "bun",
      "args": ["run", "/Users/ehenry/Documents/code/mcp-servers/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:

{
  "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:

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

{
  "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:

{
  "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:

{
  "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:

{
  "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:

{}

Security Features

Authorization Required

All fuzzing operations require explicit authorization confirmation:

{
  "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:

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

2. Use Appropriate Filters

Filter out noise by response characteristics:

{
  "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:

which ffuf
ffuf -V

Permission denied on wordlist

Ensure the wordlist file is readable:

ls -l /path/to/wordlist.txt
chmod +r /path/to/wordlist.txt

Timeout errors

Increase timeout or reduce wordlist size:

{
  "timeout": 300,
  "rate": 50
}

Too many false positives

Add filters to remove noise:

{
  "filter": {
    "status_codes": "404",
    "size": "1234",
    "words": "100-200"
  }
}

Example Workflows

Basic Directory Discovery

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

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

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

bun run build

Testing

# 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.