CalvinBackup/fuzzforge_ai
1
0 Fork 0
mirror of https://github.com/FuzzingLabs/fuzzforge_ai.git synced 2026-10-01 04:59:48 +02:00
Code Issues Packages Projects Releases Wiki Activity

docs: rewrite README for hub-centric architecture, remove demo GIFs

Browse Source
This commit is contained in:
AFredefon committed 2026-03-17 07:58:26 +01:00
1 parent c59b6ba81a
commit 575b90f8d4
3 files changed
+108 -134
Download Patch File Download Diff File Expand all files Collapse all files

No files matched your search

README.md
+108 -134
View File
@@ -17,9 +17,9 @@
<sub> <sub>
<a href="#-overview"><b>Overview</b></a> • <a href="#-overview"><b>Overview</b></a> •
<a href="#-features"><b>Features</b></a> • <a href="#-features"><b>Features</b></a> •
<a href="#-mcp-security-hub"><b>Security Hub</b></a> •
<a href="#-installation"><b>Installation</b></a> • <a href="#-installation"><b>Installation</b></a> •
<a href="USAGE.md"><b>Usage Guide</b></a> • <a href="USAGE.md"><b>Usage Guide</b></a> •
<a href="#-modules"><b>Modules</b></a> •
<a href="#-contributing"><b>Contributing</b></a> <a href="#-contributing"><b>Contributing</b></a>
</sub> </sub>
</p> </p>
@@ -32,39 +32,44 @@
## 🚀 Overview ## 🚀 Overview
**FuzzForge AI** is an open-source runtime that enables AI agents (GitHub Copilot, Claude, etc.) to orchestrate security research workflows through the **Model Context Protocol (MCP)**. **FuzzForge AI** is an open-source MCP server that enables AI agents (GitHub Copilot, Claude, etc.) to orchestrate security research workflows through the **Model Context Protocol (MCP)**.
### The Core: Modules FuzzForge connects your AI assistant to **MCP tool hubs** — collections of containerized security tools that the agent can discover, chain, and execute autonomously. Instead of manually running security tools, describe what you want and let your AI assistant handle it.
At the heart of FuzzForge are **modules** - containerized security tools that AI agents can discover, configure, and orchestrate. Each module encapsulates a specific security capability (static analysis, fuzzing, crash analysis, etc.) and runs in an isolated container. ### The Core: Hub Architecture
- **🔌 Plug & Play**: Modules are self-contained - just pull and run FuzzForge acts as a **meta-MCP server** — a single MCP endpoint that gives your AI agent access to tools from multiple MCP hub servers. Each hub server is a containerized security tool (Binwalk, YARA, Radare2, Nmap, etc.) that the agent can discover at runtime.
- **🤖 AI-Native**: Designed for AI agent orchestration via MCP
- **🔗 Composable**: Chain modules together into automated workflows
- **📦 Extensible**: Build custom modules with the Python SDK
FuzzForge AI handles module discovery, execution, and result collection. Security modules (developed separately) provide the actual security tooling - from static analyzers to fuzzers to crash triagers. - **🔍 Discovery**: The agent lists available hub servers and discovers their tools
- **🤖 AI-Native**: Hub tools provide agent context — usage tips, workflow guidance, and domain knowledge
- **🔗 Composable**: Chain tools from different hubs into automated pipelines
- **📦 Extensible**: Add your own MCP servers to the hub registry
Instead of manually running security tools, describe what you want and let your AI assistant handle it. ### 🎬 Use Case: Firmware Vulnerability Research
> **Scenario**: Analyze a firmware image to find security vulnerabilities — fully automated by an AI agent.
```
User: "Search for vulnerabilities in firmware.bin"
Agent → Binwalk: Extract filesystem from firmware image
Agent → YARA: Scan extracted files for vulnerability patterns
Agent → Radare2: Trace dangerous function calls in prioritized binaries
Agent → Report: 8 vulnerabilities found (2 critical, 4 high, 2 medium)
```
### 🎬 Use Case: Rust Fuzzing Pipeline ### 🎬 Use Case: Rust Fuzzing Pipeline
> **Scenario**: Fuzz a Rust crate to discover vulnerabilities using AI-assisted harness generation and parallel fuzzing. > **Scenario**: Fuzz a Rust crate to discover vulnerabilities using AI-assisted harness generation and parallel fuzzing.
<table align="center"> ```
<tr> User: "Fuzz the blurhash crate for vulnerabilities"
<th>1️⃣ Analyze, Generate & Validate Harnesses</th>
<th>2️⃣ Run Parallel Continuous Fuzzing</th> Agent → Rust Analyzer: Identify fuzzable functions and attack surface
</tr> Agent → Harness Gen: Generate and validate fuzzing harnesses
<tr> Agent → Cargo Fuzzer: Run parallel coverage-guided fuzzing sessions
<td><img src="assets/demopart2.gif" alt="FuzzForge Demo - Analysis Pipeline" width="100%"></td> Agent → Crash Analysis: Deduplicate and triage discovered crashes
<td><img src="assets/demopart1.gif" alt="FuzzForge Demo - Parallel Fuzzing" width="100%"></td> ```
</tr>
<tr>
<td align="center"><sub>AI agent analyzes code, generates harnesses, and validates they compile</sub></td>
<td align="center"><sub>Multiple fuzzing sessions run in parallel with live metrics</sub></td>
</tr>
</table>
--- ---
@@ -82,13 +87,13 @@ If you find FuzzForge useful, please **star the repo** to support development!
| Feature | Description | | Feature | Description |
|---------|-------------| |---------|-------------|
| 🤖 **AI-Native** | Built for MCP - works with GitHub Copilot, Claude, and any MCP-compatible agent | | 🤖 **AI-Native** | Built for MCP — works with GitHub Copilot, Claude, and any MCP-compatible agent |
| 📦 **Containerized** | Each module runs in isolation via Docker or Podman | | 🔌 **Hub System** | Connect to MCP tool hubs — each hub brings dozens of containerized security tools |
| 🔄 **Continuous Mode** | Long-running tasks (fuzzing) with real-time metrics streaming | | 🔍 **Tool Discovery** | Agents discover available tools at runtime with built-in usage guidance |
| 🔗 **Workflows** | Chain multiple modules together in automated pipelines | | 🔗 **Pipelines** | Chain tools from different hubs into automated multi-step workflows |
| 🛠️ **Extensible** | Create custom modules with the Python SDK | | 🔄 **Persistent Sessions** | Long-running tools (Radare2, fuzzers) with stateful container sessions |
| 🏠 **Local First** | All execution happens on your machine - no cloud required | | 🏠 **Local First** | All execution happens on your machine — no cloud required |
| 🔒 **Secure** | Sandboxed containers with no network access by default | | 🔒 **Sandboxed** | Every tool runs in an isolated container via Docker or Podman |
--- ---
@@ -102,27 +107,57 @@ If you find FuzzForge useful, please **star the repo** to support development!
▼ ▼
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
│ FuzzForge MCP Server │ │ FuzzForge MCP Server │
│ ┌─────────────┐ ┌──────────────┐ ┌────────────────────────┐ │ │ │
│ │list_modules │ │execute_module│ │start_continuous_module │ │ │ Projects Hub Discovery Hub Execution │
│ └─────────────┘ └──────────────┘ └────────────────────────┘ │ │ ┌──────────────┐ ┌──────────────────┐ ┌───────────────────┐ │
│ │init_project │ │list_hub_servers │ │execute_hub_tool │ │
│ │set_assets │ │discover_hub_tools│ │start_hub_server │ │
│ │list_results │ │get_tool_schema │ │stop_hub_server │ │
│ └──────────────┘ └──────────────────┘ └───────────────────┘ │
└───────────────────────────┬─────────────────────────────────────┘ └───────────────────────────┬─────────────────────────────────────┘
│ │ Docker/Podman
▼ ▼
┌─────────────────────────────────────────────────────────────────┐ ┌─────────────────────────────────────────────────────────────────┐
│ FuzzForge Runner │ │ MCP Hub Servers │
│ Container Engine (Docker/Podman) │ │ │
└───────────────────────────┬─────────────────────────────────────┘ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ │ │ Binwalk │ │ YARA │ │ Radare2 │ │ Nmap │ │
┌───────────────────┼───────────────────┐ │ │ 6 tools │ │ 5 tools │ │ 32 tools │ │ 8 tools │ │
▼ ▼ ▼ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
┌───────────────┐ ┌───────────────┐ ┌───────────────┐ │ ┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐ │
│ Module A │ │ Module B │ │ Module C │ │ │ Nuclei │ │ SQLMap │ │ Trivy │ │ ... │ │
│ (Container) │ │ (Container) │ │ (Container) │ │ │ 7 tools │ │ 8 tools │ │ 7 tools │ │ 36 hubs │ │
└───────────────┘ └───────────────┘ └───────────────┘ │ └───────────┘ └───────────┘ └───────────┘ └───────────┘ │
└─────────────────────────────────────────────────────────────────┘
``` ```
--- ---
## 🔧 MCP Security Hub
FuzzForge ships with built-in support for the **[MCP Security Hub](https://github.com/FuzzingLabs/mcp-security-hub)** — a collection of 36 production-ready, Dockerized MCP servers covering offensive security:
| Category | Servers | Examples |
|----------|---------|----------|
| 🔍 **Reconnaissance** | 8 | Nmap, Masscan, Shodan, WhatWeb |
| 🌐 **Web Security** | 6 | Nuclei, SQLMap, ffuf, Nikto |
| 🔬 **Binary Analysis** | 6 | Radare2, Binwalk, YARA, Capa, Ghidra |
| ⛓️ **Blockchain** | 3 | Medusa, Solazy, DAML Viewer |
| ☁️ **Cloud Security** | 3 | Trivy, Prowler, RoadRecon |
| 💻 **Code Security** | 1 | Semgrep |
| 🔑 **Secrets Detection** | 1 | Gitleaks |
| 💥 **Exploitation** | 1 | SearchSploit |
| 🎯 **Fuzzing** | 2 | Boofuzz, Dharma |
| 🕵️ **OSINT** | 2 | Maigret, DNSTwist |
| 🛡️ **Threat Intel** | 2 | VirusTotal, AlienVault OTX |
| 🏰 **Active Directory** | 1 | BloodHound |
> 185+ individual tools accessible through a single MCP connection.
The hub is open source and can be extended with your own MCP servers. See the [mcp-security-hub repository](https://github.com/FuzzingLabs/mcp-security-hub) for details.
---
## 📦 Installation ## 📦 Installation
### Prerequisites ### Prerequisites
@@ -140,11 +175,20 @@ cd fuzzforge_ai
# Install dependencies # Install dependencies
uv sync uv sync
# Build module images
make build-modules
``` ```
### Link the Security Hub
```bash
# Clone the MCP Security Hub
git clone https://github.com/FuzzingLabs/mcp-security-hub.git ~/.fuzzforge/hubs/mcp-security-hub
# Build the Docker images for the hub tools
./scripts/build-hub-images.sh
```
Or use the terminal UI (`uv run fuzzforge ui`) to link hubs interactively.
### Configure MCP for Your AI Agent ### Configure MCP for Your AI Agent
```bash ```bash
@@ -165,81 +209,20 @@ uv run fuzzforge mcp status
--- ---
## 📦 Modules ## 🧑‍💻 Usage
FuzzForge modules are containerized security tools that AI agents can orchestrate. The module ecosystem is designed around a simple principle: **the OSS runtime orchestrates, enterprise modules execute**. Once installed, just talk to your AI agent:
### Module Ecosystem ```
"What security tools are available?"
| | FuzzForge AI | FuzzForge Enterprise Modules | "Scan this firmware image for vulnerabilities"
|---|---|---| "Analyze this binary with radare2"
| **What** | Runtime & MCP server | Security research modules | "Run nuclei against https://example.com"
| **License** | Apache 2.0 | BSL 1.1 (Business Source License) |
| **Compatibility** | ✅ Runs any compatible module | ✅ Works with FuzzForge AI |
**Enterprise modules** are developed separately and provide production-ready security tooling:
| Category | Modules | Description |
|----------|---------|-------------|
| 🔍 **Static Analysis** | Rust Analyzer, Solidity Analyzer, Cairo Analyzer | Code analysis and fuzzable function detection |
| 🎯 **Fuzzing** | Cargo Fuzzer, Honggfuzz, AFL++ | Coverage-guided fuzz testing |
| 💥 **Crash Analysis** | Crash Triager, Root Cause Analyzer | Automated crash deduplication and analysis |
| 🔐 **Vulnerability Detection** | Pattern Matcher, Taint Analyzer | Security vulnerability scanning |
| 📝 **Reporting** | Report Generator, SARIF Exporter | Automated security report generation |
> 💡 **Build your own modules!** The FuzzForge SDK allows you to create custom modules that integrate seamlessly with FuzzForge AI. See [Creating Custom Modules](#-creating-custom-modules).
### Execution Modes
Modules run in two execution modes:
#### One-shot Execution
Run a module once and get results:
```python
result = execute_module("my-analyzer", assets_path="/path/to/project")
``` ```
#### Continuous Execution The agent will use FuzzForge to discover the right hub tools, chain them into a pipeline, and return results — all without you touching a terminal.
For long-running tasks like fuzzing, with real-time metrics: See the [Usage Guide](USAGE.md) for detailed setup and advanced workflows.
```python
# Start continuous execution
session = start_continuous_module("my-fuzzer",
assets_path="/path/to/project",
configuration={"target": "my_target"})
# Check status with live metrics
status = get_continuous_status(session["session_id"])
# Stop and collect results
stop_continuous_module(session["session_id"])
```
---
## 🛠️ Creating Custom Modules
Build your own security modules with the FuzzForge SDK:
```python
from fuzzforge_modules_sdk import FuzzForgeModule, FuzzForgeModuleResults
class MySecurityModule(FuzzForgeModule):
def _run(self, resources):
self.emit_event("started", target=resources[0].path)
# Your analysis logic here
results = self.analyze(resources)
self.emit_progress(100, status="completed",
message=f"Analysis complete")
return FuzzForgeModuleResults.SUCCESS
```
📖 See the [Module SDK Guide](fuzzforge-modules/fuzzforge-modules-sdk/README.md) for details.
--- ---
@@ -247,26 +230,17 @@ class MySecurityModule(FuzzForgeModule):
``` ```
fuzzforge_ai/ fuzzforge_ai/
├── fuzzforge-cli/ # Command-line interface ├── fuzzforge-mcp/ # MCP server — the core of FuzzForge
├── fuzzforge-cli/ # Command-line interface & terminal UI
├── fuzzforge-common/ # Shared abstractions (containers, storage) ├── fuzzforge-common/ # Shared abstractions (containers, storage)
├── fuzzforge-mcp/ # MCP server for AI agents ├── fuzzforge-runner/ # Container execution engine (Docker/Podman)
├── fuzzforge-modules/ # Security modules ├── fuzzforge-tests/ # Integration tests
│ └── fuzzforge-modules-sdk/ # Module development SDK ├── mcp-security-hub/ # Default hub: 36 offensive security MCP servers
├── fuzzforge-runner/ # Local execution engine └── scripts/ # Hub image build scripts
├── fuzzforge-types/ # Type definitions & schemas
└── demo/ # Demo projects for testing
``` ```
--- ---
## 🗺️ What's Next
**[MCP Security Hub](https://github.com/FuzzingLabs/mcp-security-hub) integration** — Bridge 175+ offensive security tools (Nmap, Nuclei, Ghidra, and more) into FuzzForge workflows, all orchestrated by AI agents.
See [ROADMAP.md](ROADMAP.md) for the full roadmap.
---
## 🤝 Contributing ## 🤝 Contributing
We welcome contributions from the community! We welcome contributions from the community!
@@ -274,7 +248,7 @@ We welcome contributions from the community!
- 🐛 Report bugs via [GitHub Issues](../../issues) - 🐛 Report bugs via [GitHub Issues](../../issues)
- 💡 Suggest features or improvements - 💡 Suggest features or improvements
- 🔧 Submit pull requests - 🔧 Submit pull requests
- 📦 Share your custom modules - 🔌 Add new MCP servers to the [Security Hub](https://github.com/FuzzingLabs/mcp-security-hub)
See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines. See [CONTRIBUTING.md](CONTRIBUTING.md) for guidelines.
assets/demopart1.gif
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 360 KiB

assets/demopart2.gif
BIN
View File
Binary file not shown.
Side by Side

Before

Width:  |  Height:  |  Size: 2.1 MiB