mirror of https://github.com/FuzzingLabs/fuzzforge_ai.git synced 2026-02-12 19:12:49 +00:00

Files

AFredefon 404c89a742 feat: make Docker the default container engine

2026-01-30 13:20:03 +01:00

12 KiB

Raw Blame History

FuzzForge OSS Usage Guide

This guide covers everything you need to know to get started with FuzzForge OSS - from installation to running your first security research workflow with AI.

FuzzForge is designed to be used with AI agents (GitHub Copilot, Claude, etc.) via MCP. The CLI is available for advanced users but the primary experience is through natural language interaction with your AI assistant.

Quick Start
Prerequisites
Installation
Building Modules
MCP Server Configuration
Using FuzzForge with AI
CLI Reference
Environment Variables
Troubleshooting

Quick Start

Prerequisites: You need uv and Docker installed. See the Prerequisites section for installation instructions.

# 1. Clone and install
git clone https://github.com/FuzzingLabs/fuzzforge-oss.git
cd fuzzforge-oss
uv sync

# 2. Build the module images (one-time setup)
make build-modules

# 3. Install MCP for your AI agent
uv run fuzzforge mcp install copilot  # For VS Code + GitHub Copilot
# OR
uv run fuzzforge mcp install claude-code  # For Claude Code CLI

# 4. Restart your AI agent (VS Code, Claude, etc.)

# 5. Start talking to your AI:
#    "List available FuzzForge modules"
#    "Analyze this Rust crate for fuzzable functions"
#    "Start fuzzing the parse_input function"

Note: FuzzForge uses Docker by default. Podman is also supported via --engine podman.

Prerequisites

Before installing FuzzForge OSS, ensure you have:

Python 3.12+ - Download Python
uv package manager - Install uv
Docker - Container runtime (Install Docker)

Installing uv

# Linux/macOS
curl -LsSf https://astral.sh/uv/install.sh | sh

# Or with pip
pip install uv

Installing Docker

# Linux (Ubuntu/Debian)
curl -fsSL https://get.docker.com | sh
sudo usermod -aG docker $USER
# Log out and back in for group changes to take effect

# macOS/Windows
# Install Docker Desktop from https://docs.docker.com/get-docker/

Note: Podman is also supported. Use --engine podman with CLI commands or set FUZZFORGE_ENGINE=podman environment variable.

Installation

1. Clone the Repository

git clone https://github.com/FuzzingLabs/fuzzforge-oss.git
cd fuzzforge-oss

2. Install Dependencies

uv sync

This installs all FuzzForge components in a virtual environment.

3. Verify Installation

uv run fuzzforge --help

Building Modules

FuzzForge modules are containerized security tools. After cloning, you need to build them once:

Build All Modules

# From the fuzzforge-oss directory
make build-modules

This builds all available modules:

fuzzforge-rust-analyzer - Analyzes Rust code for fuzzable functions
fuzzforge-cargo-fuzzer - Runs cargo-fuzz on Rust crates
fuzzforge-harness-validator - Validates generated fuzzing harnesses
fuzzforge-crash-analyzer - Analyzes crash inputs

Build a Single Module

# Build a specific module
cd fuzzforge-modules/rust-analyzer
make build

Verify Modules are Built

# List built module images
docker images | grep fuzzforge

You should see something like:

fuzzforge-rust-analyzer    0.1.0    abc123def456    2 minutes ago    850 MB
fuzzforge-cargo-fuzzer     0.1.0    789ghi012jkl    2 minutes ago    1.2 GB
...

MCP Server Configuration

FuzzForge integrates with AI agents through the Model Context Protocol (MCP). Configure your preferred AI agent to use FuzzForge tools.

GitHub Copilot

# That's it! Just run this command:
uv run fuzzforge mcp install copilot

The command auto-detects everything:

FuzzForge root - Where FuzzForge is installed
Modules path - Defaults to fuzzforge-oss/fuzzforge-modules
Docker socket - Auto-detects /var/run/docker.sock

Optional overrides (usually not needed):

uv run fuzzforge mcp install copilot \
  --modules /path/to/modules \
  --engine podman  # if using Podman instead of Docker

After installation:

Restart VS Code
Open GitHub Copilot Chat
FuzzForge tools are now available!

Claude Code (CLI)

uv run fuzzforge mcp install claude-code

Installs to ~/.claude.json so FuzzForge tools are available from any directory.

After installation:

Run claude from any directory
FuzzForge tools are now available!

Claude Desktop

# Automatic installation
uv run fuzzforge mcp install claude-desktop

# Verify
uv run fuzzforge mcp status

After installation:

Restart Claude Desktop
FuzzForge tools are now available!

Check MCP Status

uv run fuzzforge mcp status

Shows configuration status for all supported AI agents:

┏━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Agent                ┃ Config Path                               ┃ Status       ┃ FuzzForge Configured    ┃
┡━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ GitHub Copilot       │ ~/.config/Code/User/mcp.json              │ ✓ Exists     │ ✓ Yes                   │
│ Claude Desktop       │ ~/.config/Claude/claude_desktop_config... │ Not found    │ -                       │
│ Claude Code          │ ~/.claude.json                            │ ✓ Exists     │ ✓ Yes                   │
└──────────────────────┴───────────────────────────────────────────┴──────────────┴─────────────────────────┘

Generate Config Without Installing

# Preview the configuration that would be installed
uv run fuzzforge mcp generate copilot
uv run fuzzforge mcp generate claude-desktop
uv run fuzzforge mcp generate claude-code

Remove MCP Configuration

uv run fuzzforge mcp uninstall copilot
uv run fuzzforge mcp uninstall claude-desktop
uv run fuzzforge mcp uninstall claude-code

Using FuzzForge with AI

Once MCP is configured, you interact with FuzzForge through natural language with your AI assistant.

Example Conversations

Discover available tools:

You: "What FuzzForge modules are available?"
AI: Uses list_modules → "I found 4 modules: rust-analyzer, cargo-fuzzer, 
    harness-validator, and crash-analyzer..."

Analyze code for fuzzing targets:

You: "Analyze this Rust crate for functions I should fuzz"
AI: Uses execute_module("rust-analyzer") → "I found 3 good fuzzing candidates:
    - parse_input() in src/parser.rs - handles untrusted input
    - decode_message() in src/codec.rs - complex parsing logic
    ..."

Generate and validate harnesses:

You: "Generate a fuzzing harness for the parse_input function"
AI: Creates harness code, then uses execute_module("harness-validator") 
    → "Here's a harness that compiles successfully..."

Run continuous fuzzing:

You: "Start fuzzing parse_input for 10 minutes"
AI: Uses start_continuous_module("cargo-fuzzer") → "Started fuzzing session abc123"

You: "How's the fuzzing going?"
AI: Uses get_continuous_status("abc123") → "Running for 5 minutes:
    - 150,000 executions
    - 2 crashes found
    - 45% edge coverage"

You: "Stop and show me the crashes"
AI: Uses stop_continuous_module("abc123") → "Found 2 unique crashes..."

Available MCP Tools

Tool	Description
`list_modules`	List all available security modules
`execute_module`	Run a module once and get results
`start_continuous_module`	Start a long-running module (e.g., fuzzing)
`get_continuous_status`	Check status of a continuous session
`stop_continuous_module`	Stop a continuous session
`list_continuous_sessions`	List all active sessions
`get_execution_results`	Retrieve results from an execution
`execute_workflow`	Run a multi-step workflow

CLI Reference

Note: The CLI is for advanced users. Most users should interact with FuzzForge through their AI assistant.

MCP Commands

uv run fuzzforge mcp status              # Check configuration status
uv run fuzzforge mcp install <agent>     # Install MCP config
uv run fuzzforge mcp uninstall <agent>   # Remove MCP config
uv run fuzzforge mcp generate <agent>    # Preview config without installing

Module Commands

uv run fuzzforge modules list                    # List available modules
uv run fuzzforge modules info <module>           # Show module details
uv run fuzzforge modules run <module> --assets . # Run a module

Project Commands

uv run fuzzforge project init             # Initialize a project
uv run fuzzforge project info             # Show project info
uv run fuzzforge project executions       # List executions
uv run fuzzforge project results <id>     # Get execution results

Environment Variables

Configure FuzzForge using environment variables:

# Project paths
export FUZZFORGE_MODULES_PATH=/path/to/modules
export FUZZFORGE_STORAGE_PATH=/path/to/storage

# Container engine (Docker is default)
export FUZZFORGE_ENGINE__TYPE=docker  # or podman

# Podman-specific settings (only needed if using Podman under Snap)
export FUZZFORGE_ENGINE__GRAPHROOT=~/.fuzzforge/containers/storage
export FUZZFORGE_ENGINE__RUNROOT=~/.fuzzforge/containers/run

Troubleshooting

Docker Not Running

Error: Cannot connect to Docker daemon

Solution:

# Linux: Start Docker service
sudo systemctl start docker

# macOS/Windows: Start Docker Desktop application

# Verify Docker is running
docker run --rm hello-world

Permission Denied on Docker Socket

Error: Permission denied connecting to Docker socket

Solution:

# Add your user to the docker group
sudo usermod -aG docker $USER

# Log out and back in for changes to take effect
# Then verify:
docker run --rm hello-world

No Modules Found

No modules found.

Solution:

Build the modules first: make build-modules
Check the modules path: uv run fuzzforge modules list
Verify images exist: docker images | grep fuzzforge

MCP Server Not Starting

Check the MCP configuration:

uv run fuzzforge mcp status

Verify the configuration file path exists and contains valid JSON.

Module Container Fails to Build

# Build module container manually to see errors
cd fuzzforge-modules/<module-name>
docker build -t <module-name> .

Using Podman Instead of Docker

If you prefer Podman:

# Use --engine podman with CLI
uv run fuzzforge mcp install copilot --engine podman

# Or set environment variable
export FUZZFORGE_ENGINE=podman

Check Logs

FuzzForge stores execution logs in the storage directory:

ls -la ~/.fuzzforge/storage/<project-id>/<execution-id>/

Next Steps

📖 Read the Module SDK Guide to create custom modules
🎬 Check the demos in the README
💬 Join our Discord for support

Built with ❤️ by FuzzingLabs

12 KiB Raw Blame History

FuzzForge OSS Usage Guide

Table of Contents

Quick Start

Prerequisites

Installing uv

Installing Docker

Installation

1. Clone the Repository

2. Install Dependencies

3. Verify Installation

Building Modules

Build All Modules

Build a Single Module

Verify Modules are Built

MCP Server Configuration

GitHub Copilot

Claude Code (CLI)

Claude Desktop

Check MCP Status

Generate Config Without Installing

Remove MCP Configuration

Using FuzzForge with AI

Example Conversations

Available MCP Tools

CLI Reference

MCP Commands

Module Commands

Project Commands

Environment Variables

Troubleshooting

Docker Not Running

Permission Denied on Docker Socket

No Modules Found

MCP Server Not Starting

Module Container Fails to Build

Using Podman Instead of Docker

Check Logs

Next Steps

12 KiB

Raw Blame History