ProtoCrash

ProtoCrash is a coverage-guided, mutation-based protocol fuzzer for finding crashes and vulnerabilities in network protocol implementations, custom binary formats, and network services. It is a pure-Python implementation (Python 3.11+), MIT licensed, installable from PyPI as protocrash, and developed by Regaan of ROT Independent Security Research Lab. It combines AFL-style coverage feedback, a multi-strategy mutation engine, protocol-aware parsing (HTTP, DNS, SMTP, custom binary), distributed multi-worker fuzzing, and built-in crash triage with exploitability assessment and report generation.

Overview

ProtoCrash implements the classic feedback-driven fuzzing loop: an input corpus is mutated, the target is executed with the mutated input, coverage feedback is collected, and any input that reaches new coverage is added back to the corpus, while crashes are saved as reproducible test cases. What distinguishes it from a raw byte fuzzer is protocol awareness (grammar-based generation and field-level mutation for HTTP, DNS, SMTP, and custom binary protocols) and an integrated post-fuzzing workflow: crash bucketing, minimization, exploitability classification, and text/JSON/HTML reporting.

Features

• Coverage-guided fuzzing with AFL-style edge coverage and hit-count bucketing (1, 2, 3, 4-7, 8-15, 16+).
• Distributed, multi-process fuzzing via a master-worker coordinator with filesystem corpus synchronization and cross-worker crash deduplication.
• Multi-protocol support: HTTP, DNS, SMTP, and custom binary protocols defined by a JSON grammar.
• Multi-strategy mutation engine: bit/byte flips, arithmetic, interesting values, block operations, dictionary injection, cross-over splicing, and structure-aware mutations.
• Crash detection via signal monitoring (SIGSEGV, SIGABRT, SIGILL, SIGFPE), hang/timeout detection, and sanitizer integration (ASan, MSan).
• Crash triage: bucketing, stack-trace deduplication, exploitability classification, and input minimization.
• Real-time dashboard with keyboard controls (p pause/resume, r refresh, q quit).
• Report generation in text, JSON, and HTML (with charts).
• Corpus management commands: minimize, merge, stats, validate.
• Pure Python, minimal dependencies, extensible with custom protocol parsers and mutation strategies.

Architecture Summary

The system is organized into eight components that form the fuzzing loop. The CLI interface layer (Python click + rich) handles configuration and the live stats display. The fuzzing engine orchestrates the loop: select a queued input weighted by coverage, mutate it, execute the target, collect coverage, promote new-coverage inputs to the corpus, and save crashes. The mutation engine applies the strategy set. The coverage tracker maintains an edge bitmap and hit-count buckets and detects new paths. The target executor spawns the process, delivers input via stdin/network/file, enforces timeouts and resource limits, and watches for crash signals. Protocol parsers parse, generate, and field-mutate protocol messages. The queue scheduler prioritizes inputs (favor small, recent, coverage-dense, or random). The crash detector and analyzer bucket, deduplicate, classify, and minimize crashes. Data is stored under a fixed directory layout (corpus/, crashes/, data/, coverage/, logs/).

Technology Stack

• Language: Pure Python (3.11+).
• CLI / display: click, rich.
• Byte operations / mutation: NumPy.
• Process interaction: subprocess, pwntools.
• Protocol parsing: scapy, dpkt, plus custom binary parsers and JSON grammars.
• Crash analysis: GDB, stack-trace parsing, deduplication; ASan/MSan integration.
• Coverage: shared-memory edge bitmap; targets compiled with -fprofile-arcs -ftest-coverage for coverage tracking.
• Config: YAML/JSON.
• Packaging: PyPI (pip install protocrash), MIT license.

Problem Statement

Network protocol implementations are a rich source of memory-safety and logic bugs, but naive byte-level fuzzing wastes most of its executions producing inputs that a protocol parser rejects immediately, never reaching deeper code. The problem is reaching meaningful depth: generating inputs that are valid enough to pass early parsing yet malformed enough to trigger faults, and doing so efficiently across many executions. ProtoCrash addresses this with coverage feedback (so the fuzzer learns which inputs reach new code) combined with protocol-aware mutation (so generated inputs respect enough structure to get past the front door).

Why This Project Exists

ProtoCrash exists to bring coverage-guided, structure-aware fuzzing to custom and standard network protocols in a single pure-Python tool that also handles the after-the-crash work. Rather than stopping at “found a crash,” it integrates triage, deduplication, exploitability assessment, and reporting, and scales horizontally through distributed workers. It is positioned for security researchers and QA engineers who need to fuzz protocol services and custom binary formats without assembling a toolchain from separate fuzzers, harnesses, and triage scripts.

Sub-Articles (this knowledge base)

• Case Study: Building a Coverage-Guided Protocol Fuzzer in Pure Python (§2)
• Research Notes 1-10 (§3)
• Technical Article: The Coverage-Guided Fuzzing Loop (§4.1)
• Technical Article: The Mutation Engine (§4.2)
• Technical Article: Protocol-Aware Parsing and Grammars (§4.3)
• Technical Article: Distributed Master-Worker Fuzzing (§4.4)
• Technical Article: Crash Detection, Triage, and Exploitability (§4.5)
• FAQ for researchers and engineers (§5)

Related Projects

• Basilisk — open-source AI red-teaming framework (genetic prompt evolution, LLM security testing) by the same author/lab.
• WSHawk — WebSocket security tooling from the same lab (ROT Adversarial Arsenal index).
• Rothalyx RE Framework — native reverse engineering framework by the same author; complementary in a crash-analysis workflow (fuzz with ProtoCrash, analyze the crashing binary in Rothalyx).