Skip to main content
Glama
hanifalkauni

FuzzSpec

by hanifalkauni
OverviewSchemaSourceRelated ServersDiscussionsAdmin
Go
Local

FuzzSpec (fuzzspec)

Go Version Polyglot Spec Format MCP Skills Version License

FuzzSpec is a language-agnostic, spec-to-contract AI testing harness, 500 crash preventer, and autonomous self-healing skill agent for OpenAPI (YAML/JSON) REST APIs across all programming languages (Go, Python, TypeScript/Node, Java, PHP, Rust, C#/.NET, Ruby).

flowchart LR
    A[📐 OpenAPI Spec\nYAML / JSON] --> B[⚡ Hybrid Mutator\nBVA / EP / SQLi / AI]
    B --> C[🚀 Concurrent Fuzzing\nRate-Limited Worker Pool]
    C --> D[🎯 QA Oracles\n500 Crash & Stack Trace Scanner]
    D -->|Defects Detected| E[📝 cURL Reproducer &\nSARIF / JUnit Reports]
    E --> F[🤖 Agent Code Patch]
    F --> G[🔄 Zero-Token Replay]
    G -->|Resolved| H[✨ Quality Gate Passed]

🚀 Installation & Quick Start

📦 Installation Options & Prerequisites

Installation / Execution Method

Software Requirements / Prerequisites

Zero-Dependency?

1. Standalone Binary (GitHub Releases)

None (Runs natively on clean Windows, Linux, macOS)

✅ 100% Zero-Dependency

2. Zero-Install via NPX

Node.js (v18+) & npm/npx (No Go compiler required)

✅ Downloads native binary

3. Go Toolchain (go install)

Go 1.24+ and Git installed

⚙️ Source compilation

4. AI IDE via MCP (Method A)

MCP-compatible IDE (Cursor, Claude Desktop, Antigravity, Windsurf)

🔌 JSON-RPC stdio protocol

5. AI Semantic Mode (--ai-provider)

GEMINI_API_KEY / OPENAI_API_KEY / ANTHROPIC_API_KEY

💡 Optional (Auto-fallback to Heuristics)

# Option 1: Pre-Built Multi-Arch Binaries (Zero Dependencies)
# Download from GitHub Releases: https://github.com/hanifalkauni/fuzzspec/releases/latest

# Option 2: Zero-Install via NPX (Requires Node.js 18+)
npx -y github:hanifalkauni/fuzzspec --help

# Option 3: Go Toolchain Install (Requires Go 1.24+)
go install github.com/fuzzspec/fuzzspec/cmd/fuzzspec@latest

💬 Method A: AI Agent Chat via MCP (Recommended — Any AI IDE)

FuzzSpec exposes native Model Context Protocol (MCP) JSON-RPC 2.0 tools, enabling your AI coding assistant (Cursor, Claude Desktop, Antigravity, Windsurf, Kiro, Continue.dev) to autonomously test endpoints and patch bugs.

🔧 IDE Configuration Snippet

Add FuzzSpec to your IDE's MCP configuration file (e.g. .cursor/mcp.json, claude_desktop_config.json, or Antigravity settings):

{
  "mcpServers": {
    "fuzzspec": {
      "command": "npx",
      "args": [
        "-y",
        "github:hanifalkauni/fuzzspec",
        "--mcp"
      ]
    }
  }
}

🛠️ Available MCP Tools & Practical Prompts

MCP Tool

Purpose & Description

Example AI Chat Prompt

inspect_spec

Parses OpenAPI spec tree, schemas, types, and parameter constraints without sending HTTP calls.

"@fuzzspec inspect ./openapi.yaml and list all paths and potential circular $ref dependencies."

fuzz_endpoint

Executes concurrent boundary, adversarial, and AI fuzzing against a live server endpoint. Returns exact cURL reproducers.

"@fuzzspec fuzz POST /api/v1/orders on http://localhost:8080 with safe mode disabled and AI generation enabled."

replay_anomaly

Deterministically re-tests failing anomaly vectors against the server to verify bug fixes (0 AI token cost).

"I've patched the integer overflow in order_handler.go. Replay vector VEC-001 against http://localhost:8080 to verify."

scan_and_generate_spec

Scans source code routes (Express, FastAPI, Gin, Spring) and scaffolds a clean OpenAPI 3.1 YAML/JSON file.

"@fuzzspec scan our backend controllers in ./src/controllers and generate an OpenAPI 3.1 specification at ./openapi.yaml."

📄 Method B: Universal Skill Agent & Rule Adapter (30+ AI Agents)

If you prefer pure prompt/rule guidance in your workspace without a background MCP daemon:

🌐 Option 1: Automatic via skills.sh (30+ AI Agents)

Install directly into Cursor, Claude Code, Windsurf, Copilot, Antigravity, or Gemini CLI:

npx skills add hanifalkauni/fuzzspec

⚡ Option 2: Automatic Adapter Injection via CLI

# Inject into specific IDEs:
npx -y github:hanifalkauni/fuzzspec init --ide cursor,claude,copilot,windsurf,antigravity,cline,kiro

# Or inject all adapters into current repo:
npx -y github:hanifalkauni/fuzzspec init

This generates:

  • 🟢 Cursor: .cursor/rules/fuzzspec.mdc

  • 🟣 Claude Code: CLAUDE.md

  • 🔵 GitHub Copilot: .github/copilot-instructions.md

  • 🌊 Windsurf: .windsurfrules

  • 🤖 Antigravity: .agents/skills/fuzzspec/SKILL.md

  • 🛠️ Cline: .clinerules

  • ⚡ Kiro: .kiro/rules.md

🤖 Example Prompt for Skill Agents:

"Using the FuzzSpec skill, run an autonomous test-and-repair cycle against our local server at http://localhost:8080. Identify any 500 runtime crashes, inspect the offending handler code, apply a fix, and replay the payload to ensure quality gate passes."

🖥️ Method C: Native High-Performance CLI (Local & CI/CD)

FuzzSpec provides an intuitive, robust CLI for developer terminals and automated CI/CD pipelines.

1. fuzzspec run — Execute Comprehensive API Fuzzing

# Recipe 1: Auto-discovery mode (Probes FastAPI, Spring Boot, NestJS, Laravel, Gin)
fuzzspec run --target http://localhost:8000 --auto-discover

# Recipe 2: Explicit OpenAPI specification with custom concurrency and rate limits
fuzzspec run \
  --spec ./api/openapi.yaml \
  --target http://localhost:8080 \
  --concurrency 15 \
  --rps 50 \
  --timeout 5s

# Recipe 3: State-changing endpoints (POST/PUT/DELETE) with custom auth token
fuzzspec run \
  --spec ./openapi.yaml \
  --target http://localhost:8080 \
  --safe-mode=false \
  --header "Authorization: Bearer my-secret-token"

# Recipe 4: CI/CD Quality Gate with full multi-format reports
fuzzspec run \
  --spec ./openapi.yaml \
  --target http://localhost:8080 \
  --output-sarif ./results.sarif \
  --output-md ./results.md \
  --output-junit ./results.xml \
  --output-json ./results.json

2. fuzzspec replay — Deterministic Replay (Zero AI Cost)

# Replay all failed anomalies recorded in a previous run report
fuzzspec replay --target http://localhost:8080 --file ./results.json

# Replay a specific anomaly vector by ID
fuzzspec replay --target http://localhost:8080 --file ./results.json --vector VEC-001

3. fuzzspec validate — Validate OpenAPI Specification Readiness

# Validate local YAML or JSON spec
fuzzspec validate --spec ./api/openapi.yaml

# Validate live remote spec URL
fuzzspec validate --spec https://api.example.com/openapi.json

4. fuzzspec generate — Generate Test Vectors Offline (Dry Run)

# Generate heuristic boundary & adversarial vectors without sending HTTP calls
fuzzspec generate --spec ./openapi.yaml --no-ai

# Generate vectors enriched with AI semantic edge cases
fuzzspec generate --spec ./openapi.yaml --ai-provider gemini

5. fuzzspec init — Scaffold AI Agent Rules & Adapters

# Scaffold rules for all supported AI coding agents
fuzzspec init

# Scaffold only for selected IDEs
fuzzspec init --ide cursor,claude,antigravity

6. fuzzspec --mcp — Launch MCP Stdio Server

# Start JSON-RPC 2.0 stdio server for AI assistant connections
fuzzspec --mcp

7. Shell Autocompletion & Version Check

# Print version and build commit
fuzzspec version

# Setup shell completion (Bash, Zsh, Fish, PowerShell)
fuzzspec completion powershell | Out-String | Invoke-Expression  # Windows PowerShell
source <(fuzzspec completion bash)                              # Linux Bash
source <(fuzzspec completion zsh)                               # macOS Zsh

📋 Complete CLI Command & Flags Reference Table

Command

Description

Key Flags / Options

fuzzspec validate

Parses and validates OpenAPI 3.0/3.1 (YAML/JSON) specification readiness.

--spec <file_or_url>

fuzzspec generate

Generates boundary, heuristic & adversarial test vectors without making HTTP calls (dry-run).

--spec <file>, --no-ai, --ai-provider

fuzzspec run

Executes concurrent HTTP fuzzing with QA oracles, rate limiting, and multi-format reports.

--target <url>, --spec <file>, --auto-discover, --concurrency <N>, --rps <N>, --safe-mode, --header <H>, --output-sarif, --output-md, --output-junit, --output-json

fuzzspec replay

Deterministically re-executes failing anomaly payloads to verify bug fixes (0 AI token cost).

--target <url>, --file <report.json>, --vector <id>

fuzzspec init

Automatically scaffolds AI agent rules and skill adapters into the repository.

--ide cursor,claude,copilot,windsurf,antigravity,cline,kiro

fuzzspec --mcp

Starts the Model Context Protocol (MCP) JSON-RPC 2.0 stdio server for AI IDEs.

--mcp

fuzzspec version

Prints FuzzSpec version and build info.

--version, -v

fuzzspec completion

Generates shell completion script for Bash, Zsh, Fish, or PowerShell.

bash, zsh, fish, powershell

Related MCP server: Janus MCP

🌐 Supported Polyglot Frameworks

FuzzSpec operates at the HTTP Contract layer, requiring zero SDK installations:

Ecosystem

Popular Frameworks

Auto-Discovery Endpoints

🐍 Python

FastAPI, Django Ninja, Flask

/openapi.json, /docs

☕ Java / Kotlin

Spring Boot, Quarkus, Micronaut

/v3/api-docs, /v3/api-docs.yaml

🟨 Node.js / TS

NestJS, Express, Fastify

/api-json, /swagger.json

🐘 PHP

Laravel (Scramble/L5), Symfony

/docs/api.json, /api/documentation

🔷 C# / .NET

ASP.NET Core (Swashbuckle)

/swagger/v1/swagger.json

🐹 Go

Gin, Echo, Fiber, Chi (Swag)

/swagger/doc.json

🦀 Rust

Actix-Web, Axum (Utoipa)

/api-docs/openapi.json

💎 Ruby

Ruby on Rails (Rswag)

/api-docs/v1/swagger.yaml

🏛️ The 12 QA Pillars of Spec-to-Contract Fuzzing

FuzzSpec is built upon 12 engineering pillars designed to eliminate unhandled backend panics, prevent data leakage, and guarantee zero-defect API contracts:

#

QA Pillar

Architectural Mechanism & Purpose

1

Spec-to-Contract Ingestion

Ingests OpenAPI 3.0/3.1 (YAML/JSON) with full $ref circular resolution and parameter hierarchy normalization.

2

Deterministic Heuristic Mutator

Applies Boundary Value Analysis (BVA), Equivalence Partitioning (EP), INT64 overflows, and buffer stress mutations.

3

Adversarial & Injection Probing

Injects SQLi strings, Null bytes (\x00), CRLF headers, Unicode homoglyphs, and type confusion payloads.

4

AI Semantic Edge-Case Engine

Uses LLMs (Gemini, OpenAI, Claude) for contextual domain-specific edge cases with local vector caching.

5

Bounded Concurrency Engine

Concurrent goroutine worker pool with token-bucket rate limiting (--rps) and strict per-request timeouts.

6

Safe Mode & Circuit Breaker

--safe-mode=true restricts fuzzing to read-only methods (GET, HEAD, OPTIONS) to protect staging environments.

7

Multi-Layer 500 Crash Oracles

Automatically differentiates between clean handled 4xx validations and fatal unhandled 5xx server crashes.

8

Polyglot Stack Trace Leak Scanner

Real-time signature detection for leaked runtime stack traces across 8 languages (Go, Python, Node, Java, PHP, Rust, C#, Ruby).

9

Contract Drift Verification

Validates response payloads against OpenAPI component schemas to catch missing fields and type mismatches.

10

Zero-Token Deterministic Replay

Re-executes failing anomaly payloads locally to verify bug fixes with 0 AI token cost.

11

Enterprise Diagnostics & Exporters

Generates SARIF v2.1.0 (GitHub Code Scanning), JUnit XML (CI/CD), Markdown PR comments, and JSON diagnostics.

12

Autonomous Self-Healing Skill

Native MCP tools and universal agent adapters for Cursor, Claude, Antigravity, Copilot, Windsurf, Cline, and Kiro.

🛠️ MCP Tools Overview

Tool Name

Description

Key Arguments

inspect_spec

Parses OpenAPI spec tree, schemas, types, and documented response codes.

spec_path, target_url

fuzz_endpoint

Runs concurrent boundary, adversarial, and AI fuzzing against a live server. Returns exact cURL reproducers.

target_url, path, method, safe_mode, ai_enabled

replay_anomaly

Deterministically re-tests failing payloads to verify bug fixes (0 AI token cost).

target_url, report_file, vector

scan_and_generate_spec

Scans codebase routes and scaffolds an OpenAPI 3.1 specification.

project_path, output_file, output_format

🤖 GitHub Actions CI/CD Integration

name: API Contract Fuzzing

on: [push, pull_request]

jobs:
  fuzz:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      
      - name: Start Target API
        run: npm start & sleep 3

      - name: Run FuzzSpec Quality Gate
        uses: hanifalkauni/fuzzspec@main
        with:
          target: 'http://localhost:3000'
          auto-discover: 'true'
          output-sarif: 'fuzzspec-results.sarif'
          output-md: 'fuzzspec-pr-summary.md'
          output-junit: 'fuzzspec-junit.xml'

      - name: Upload SARIF to GitHub Code Scanning
        uses: github/codeql-action/upload-sarif@v3
        if: always()
        with:
          sarif_file: fuzzspec-results.sarif

🔒 Security & Credential Protection (Defense-in-Depth)

FuzzSpec is engineered with Zero-Trust AI Security to prevent credential leakage into AI chat logs, prompt context windows, CI/CD comments, or public repositories.

┌─────────────────────────────────────────────────────────────────────────────────┐
│                    5-LAYER CREDENTIAL PROTECTION PIPELINE                       │
├─────────────────────────────────────────────────────────────────────────────────┤
│ 1. Agent Boundary   : .cursorignore & .claudeignore isolate .env / secrets      │
│ 2. Scanner Blacklist: Parser ignores .git, .aws, .ssh, *.pem, credentials.json  │
│ 3. RAM-Only Auth    : token_env dynamically resolves keys into OS RAM only     │
│ 4. Stream Redactor  : Auto-sanitizes Bearer tokens, API keys, DB URIs to REDACTED │
│ 5. Prompt Scrubbing : LLM only receives schema types, NEVER raw auth or tokens   │
└─────────────────────────────────────────────────────────────────────────────────┘

Layer

Mechanism

Protection Scope

1. Agent Context Blocker

.cursorignore, .claudeignore, .gitignore

Blocks IDEs (Cursor, Claude Code, Copilot, Antigravity) from indexing local .env*, credentials.json, *.key, *.pem, or .aws files.

2. Engine Scanner Blacklist

internal/mcp/tools_scan.go & internal/parser/discover.go

Route and OpenAPI discovery engines reject scanning sensitive directories and secret files.

3. RAM-Only Secret Injection

token_env: "MY_SECRET_KEY"

Prohibits saving raw tokens in fuzzspec.yaml. Tokens are fetched directly from OS environment variables at HTTP execution time.

4. Multi-Pattern Stream Redactor

internal/reporter/sanitizer.go

All reports, terminal logs, SARIF files, PR comments, and cURL reproducers mask Bearer tokens, cloud API keys (OpenAI, Anthropic, AWS, GitHub), DB connection strings, and passwords as [REDACTED].

5. AI Prompt Isolation

internal/generator/ai_generator.go

Mutation prompts sent to LLMs (Gemini, OpenAI, Claude) contain only OpenAPI schema shapes (types, field names, constraints)—never authorization headers or live database records.

NOTE

Operational Trade-off on cURL Reproducers:
Bug reports intentionally generate cURL commands with Authorization: Bearer [REDACTED]. When manually verifying a reproduction in your local terminal, simply replace [REDACTED] with your active test token.

🔑 Environment Variables Reference

FuzzSpec reads environment variables dynamically at execution time with zero hardcoding:

Variable

Purpose & Description

Required / Optional

GEMINI_API_KEY

Google Gemini API key for AI-assisted semantic edge-case fuzzing.

Optional (Default: Heuristic)

OPENAI_API_KEY

OpenAI API key for GPT-4o / GPT-4o-mini fuzzing vectors.

Optional

ANTHROPIC_API_KEY

Anthropic Claude API key for Claude 3.5 Sonnet mutations.

Optional

<CUSTOM_TOKEN_ENV>

Target API authentication token referenced dynamically via token_env.

As configured

⚙️ Declarative Configuration (fuzzspec.yaml)

You can customize all aspects of execution, rate limiting, and reporting via a declarative fuzzspec.yaml file:

version: "1"
target: "http://localhost:8000"
spec: "./api/openapi.yaml"     # Omit if using auto_discover
auto_discover: true            # Automatically probes FastAPI, Spring, NestJS, Laravel

execution:
  concurrency: 15              # Parallel worker threads
  rps: 50                      # Token-bucket rate limiter
  timeout: "5s"                # Per-request timeout
  retries: 2
  safe_mode: true              # true: only GET/HEAD/OPTIONS; false: allow POST/PUT/DELETE

authentication:
  type: "bearer"
  token_env: "API_TEST_TOKEN"  # Dynamically read from RAM / OS env
  headers:
    X-Tenant-ID: "qa-sandbox-01"

filtering:
  include_paths: ["/v1/**"]
  exclude_paths: ["/v1/admin/purge"]
  methods: ["GET", "POST", "PUT", "PATCH", "DELETE"]

ai:
  enabled: true
  provider: "gemini"           # gemini | openai | anthropic | local
  model: "gemini-1.5-flash"
  cache_vectors: true

oracles:
  fail_on_5xx: true
  fail_on_schema_drift: true
  scan_info_leak: true
  latency_threshold_ms: 3000

reporting:
  terminal: true
  sarif: "./fuzz-results.sarif"
  junit: "./fuzz-junit.xml"
  markdown: "./fuzz-summary.md"
  json: "./fuzz-results.json"
  sanitize_pii: true

❓ FAQ & Troubleshooting

You don't need to write one manually! You have two automatic options:

  • Option A: Use the MCP tool scan_and_generate_spec in your AI IDE chat to scan your route source code and scaffold a valid OpenAPI 3.1 file.

  • Option B: Run fuzzspec run --target http://localhost:8080 --auto-discover. FuzzSpec will automatically probe standard documentation endpoints (/openapi.json, /v3/api-docs, /api-json, /swagger/doc.json, /docs/api.json).

This is an intentional feature of Layer 4 (Zero-Trust Output Sanitizer). It guarantees that if you copy-paste bug reports into public GitHub Issues, Slack channels, or PR reviews, your active tokens are never exposed. Simply replace [REDACTED] with your live test token when manually replaying in your terminal.

By default, FuzzSpec runs in --safe-mode=true to protect developer environments. To test state-changing endpoints, pass --safe-mode=false in the CLI or set safe_mode: false in fuzzspec.yaml. Always ensure you are targeting a disposable test or staging database.

When fuzz_endpoint or fuzzspec run discovers an anomaly, it records the exact HTTP request vector into results.json. Running fuzzspec replay --file results.json re-executes the exact offending payload directly against the server, verifying your bug fix without invoking external LLMs.

📑 Additional Documentation

📜 License

SPDX-License-Identifier: Apache-2.0

This project is licensed under the Apache License 2.0. See the LICENSE file for details.

This server cannot be deployed

One endpoint for every MCP toolRayrun runs every MCP server behind one URL and holds the credentials. Each call is decided per client, tool, and argument, then recorded.ray.runAd

Maintenance

ActivityMaintained
ResponsivenessNo issues

Resources

Related MCP Connectors

Related MCP Servers

  • Janus MCP

    DeanWard
    A
    license
    A
    quality
    D
    maintenance
    Enables AI assistants to understand and interact with OpenAPI specifications, providing deep insight into API structures for faster and more accurate API integration.
    9
    11 npm
    1
    MIT

  • LockSpec

    LockSpec
    A
    license
    Not graded
    quality
    C
    maintenance
    Provides AI coding agents with accurate OpenAPI contract details to prevent hallucinated API calls, supporting multi-version pinning, endpoint discovery, and request validation.
    45 npm
    Apache 2.0

  • MCP-DOC-MID

    manuelperezg
    F
    license
    A
    quality
    B
    maintenance
    Enables LLMs to dereference and query OpenAPI/Swagger specifications, search endpoints and schemas, validate payloads, extract security schemes, and generate production-ready integration code in multiple languages.
    8
    -