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

Files

AFredefon e72c5fb201 docs: fix USAGE.md setup instructions for new users

2026-01-30 13:55:48 +01:00

15 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 --all-extras

# 2. Build the SDK and module images (one-time setup)
# First, build the SDK base image and wheel
cd fuzzforge-modules/fuzzforge-modules-sdk
uv build
mkdir -p .wheels
cp ../../dist/fuzzforge_modules_sdk-*.whl .wheels/
cd ../..
docker build -t localhost/fuzzforge-modules-sdk:0.1.0 fuzzforge-modules/fuzzforge-modules-sdk/

# Then build all modules
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

# Install all workspace dependencies including the CLI
uv sync --all-extras

This installs all FuzzForge components in a virtual environment, including:

fuzzforge-cli - Command-line interface
fuzzforge-mcp - MCP server
fuzzforge-runner - Module execution engine
All supporting libraries

3. Verify Installation

uv run fuzzforge --help

Building Modules

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

Important: The modules depend on a base SDK image that must be built first.

Build the SDK Base Image (Required First)

# 1. Build the SDK Python package wheel
cd fuzzforge-modules/fuzzforge-modules-sdk
uv build

# 2. Copy wheel to the .wheels directory
mkdir -p .wheels
cp ../../dist/fuzzforge_modules_sdk-*.whl .wheels/

# 3. Build the SDK Docker image
cd ../..
docker build -t localhost/fuzzforge-modules-sdk:0.1.0 fuzzforge-modules/fuzzforge-modules-sdk/

Build All Modules

Once the SDK is built, 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

Note: The first build will take several minutes as it downloads Rust toolchains and dependencies.

Build a Single Module

# Build a specific module (after SDK is built)
cd fuzzforge-modules/rust-analyzer
docker build -t fuzzforge-rust-analyzer:0.1.0 .

Verify Modules are Built

# List built module images
docker images | grep fuzzforge

You should see at least 5 images:

localhost/fuzzforge-modules-sdk   0.1.0    abc123def456    5 minutes ago    465 MB
fuzzforge-rust-analyzer           0.1.0    def789ghi012    2 minutes ago    2.0 GB
fuzzforge-cargo-fuzzer            0.1.0    ghi012jkl345    2 minutes ago    1.9 GB
fuzzforge-harness-validator       0.1.0    jkl345mno678    2 minutes ago    1.9 GB
fuzzforge-crash-analyzer          0.1.0    mno678pqr901    2 minutes ago    517 MB

Verify CLI Installation

# Test the CLI
uv run fuzzforge --help

# List modules (with environment variable for modules path)
FUZZFORGE_MODULES_PATH=/path/to/fuzzforge-modules uv run fuzzforge modules list

You should see 4 available modules listed.

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

Test MCP Server

After installation, verify the MCP server is working:

# Check if MCP server process is running (in VS Code)
ps aux | grep fuzzforge_mcp

You can also test the MCP integration directly in your AI agent:

GitHub Copilot: Ask "List available FuzzForge modules"
Claude: Ask "What FuzzForge modules are available?"

The AI should respond with a list of 4 modules (rust-analyzer, cargo-fuzzer, harness-validator, crash-analyzer).

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

Module Build Fails: "fuzzforge-modules-sdk not found"

ERROR: failed to solve: localhost/fuzzforge-modules-sdk:0.1.0: not found

Solution: You need to build the SDK base image first:

# 1. Build SDK wheel
cd fuzzforge-modules/fuzzforge-modules-sdk
uv build
mkdir -p .wheels
cp ../../dist/fuzzforge_modules_sdk-*.whl .wheels/

# 2. Build SDK Docker image
cd ../..
docker build -t localhost/fuzzforge-modules-sdk:0.1.0 fuzzforge-modules/fuzzforge-modules-sdk/

# 3. Now build modules
make build-modules

fuzzforge Command Not Found

error: Failed to spawn: `fuzzforge`

Solution: Install with --all-extras to include the CLI:

uv sync --all-extras

No Modules Found

No modules found.

Solution:

Build the SDK first (see above)
Build the modules: make build-modules

Check the modules path with environment variable:

FUZZFORGE_MODULES_PATH=/path/to/fuzzforge-modules 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.

If the server process isn't running:

# Check if MCP server is running
ps aux | grep fuzzforge_mcp

# Test the MCP server manually
uv run python -m fuzzforge_mcp

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

15 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 the SDK Base Image (Required First)

Build All Modules

Build a Single Module

Verify Modules are Built

Verify CLI Installation

MCP Server Configuration

GitHub Copilot

Claude Code (CLI)

Claude Desktop

Check MCP Status

Generate Config Without Installing

Remove MCP Configuration

Test MCP Server

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

Module Build Fails: "fuzzforge-modules-sdk not found"

fuzzforge Command Not Found

No Modules Found

MCP Server Not Starting

Module Container Fails to Build

Using Podman Instead of Docker

Check Logs

Next Steps

15 KiB

Raw Blame History