REGAAN RASCII diagrams in the repo’s own documentation style, so they render anywhere (GitHub, docs sites, the paper). All are grounded in
SYSTEM_ARCHITECTURE.md,README.md, andUSAGE.md. Swap for rendered SVG/Mermaid later if the site supports it.
3.1 Eight-Component Architecture
┌──────────────────────────────────────────────────────────────────────┐
│ ProtoCrash │
│ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 1. CLI │─────▶│ 2. Fuzzing │─────▶│ 5. Target │ │
│ │ Interface │ │ Engine │ │ Executor │ │
│ │ (click/rich) │ │ (orchestr.) │ │ (subprocess/ │ │
│ └──────────────┘ └──────┬───────┘ │ pwntools) │ │
│ │ │ └──────┬───────┘ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ Input Corpus │ │ 3. Mutation │ │ 4. Coverage │ │
│ │ initial/ │ │ Engine │ │ Tracker │ │
│ │ queue/ │ │ (NumPy) │ │ (edge bitmap)│ │
│ └──────────────┘ └──────┬───────┘ └──────┬───────┘ │
│ │ │ │ │
│ ▼ ▼ ▼ │
│ ┌──────────────┐ ┌──────────────┐ ┌──────────────┐ │
│ │ 6. Protocol │ │ 7. Queue │ │ 8. Crash │ │
│ │ Parsers │ │ Scheduler │ │ Detector + │ │
│ │ http/dns/ │ │ favor small/ │ │ Analyzer │ │
│ │ smtp/binary │ │ recent/cov │ │ (GDB/ASan) │ │
│ └──────────────┘ └──────────────┘ └──────────────┘ │
│ │
└──────────────────────────────────────────────────────────────────────┘3.2 The Coverage-Guided Fuzzing Cycle
┌───────────────────────────────────────────────────────┐
│ │
▼ │
┌───────────┐ 1. select (coverage-weighted) │
│ CORPUS │──────────────────────────┐ │
│initial + │ ▼ │
│ queue │ ┌──────────────┐ │
└───────────┘ │ 7. Queue │ │
▲ │ Scheduler │ │
│ promote └──────┬───────┘ │
│ (new coverage) ▼ │
│ ┌──────────────┐ │
│ │ 3. Mutation │ │
│ │ Engine │ │
│ └──────┬───────┘ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 6. Protocol │ validate/fix │
│ │ Parser │ (keep magic, │
│ └──────┬───────┘ recompute │
│ ▼ length) │
│ ┌──────────────┐ │
│ │ 5. Target │ │
│ │ Executor │ │
│ └──────┬───────┘ │
│ ▼ │
│ ┌──────────────┐ │
│ │ 4. Coverage │───────────────┘
│ │ Tracker │ new coverage?
│ └──────┬───────┘
│ ▼
│ ┌───────────────────────┐
└────── yes ─────────│ DECISION │
│ new cov → corpus │
crash → crashes/ ◀────│ crash → save+triage │
discard ◀──────│ nothing → discard │
└───────────────────────┘3.3 Mutation Strategy Set
┌─────────────────────┐
│ MUTATION ENGINE │
│ mutate(bytes, str) │
│ weighted (yaml) │
│ NumPy byte ops │
└──────────┬──────────┘
┌────────────┬────────┼────────┬────────────┐
▼ ▼ ▼ ▼ ▼
┌───────────┐ ┌──────────┐ ┌────────┐ ┌─────────┐ ┌──────────┐
│ bit flip │ │byte flip │ │arithmet│ │interest.│ │ block │
│ │ │ │ │ ±small │ │ 0,-1, │ │ del/ins/ │
│ │ │ │ │ ints │ │ MAX_INT │ │ dup │
└───────────┘ └──────────┘ └────────┘ └─────────┘ └──────────┘
┌────────────┬─────────────────┬────────────┐
▼ ▼ ▼ ▼
┌───────────┐ ┌──────────┐ ┌──────────────┐
│dictionary │ │cross-over│ │ structure- │
│ keyword │ │ splice 2 │ │ aware │
│ injection │ │ inputs │ │ (grammar: │
│ │ │ │ │ keep magic, │
│ │ │ │ │ recompute │
│ │ │ │ │ length) │
└───────────┘ └──────────┘ └──────────────┘3.4 Distributed Master-Worker Model
┌────────────────────────┐
│ COORDINATOR (master) │
│ port 6666 │
│ - aggregate stats │
│ - cross-worker dedup │
└───────────┬────────────┘
│
┌────────────────┬───────┴────────┬────────────────┐
▼ ▼ ▼ ▼
┌───────────┐ ┌───────────┐ ┌───────────┐ ┌───────────┐
│ Worker 1 │ │ Worker 2 │ │ Worker 3 │ │ Worker N │
│ full loop │ │ full loop │ │ full loop │ │ full loop │
└─────┬─────┘ └─────┬─────┘ └─────┬─────┘ └─────┬─────┘
│ │ │ │
└────────────────┴───────┬────────┴────────────────┘
▼
┌────────────────────────┐
│ SHARED CORPUS (filesys) │
│ interesting cases sync │
└────────────────────────┘
Repository-reported scaling:
1 worker ~50,000 exec/sec
4 workers ~180,000 exec/sec
8 workers ~350,000 exec/sec (~87.5% efficiency)
(measurement conditions: Additional validation required)3.5 Crash Triage Pipeline
crashes/ (raw, many duplicates — e.g. 127)
│
▼
┌────────────────────┐
│ 1. detect │ signal: SIGSEGV/SIGABRT/SIGILL/SIGFPE
│ │ + hang timeout + ASan/MSan
└─────────┬──────────┘
▼
┌────────────────────┐
│ 2. stack trace │ GDB → symbolized frames
└─────────┬──────────┘
▼
┌────────────────────┐
│ 3. bucket + dedup │ by signal + stack signature
└─────────┬──────────┘ (cross-worker in distributed mode)
▼
┌────────────────────┐ e.g. 127 raw → 5 unique:
│ 4. minimize │ SIGSEGV null-deref 89
│ (per bucket) │ SIGSEGV heap-overfl 23
└─────────┬──────────┘ SIGABRT assert-fail 12
▼ SIGSEGV stack-overfl 2
┌────────────────────┐ SIGILL bad-instr 1
│ 5. exploitability │ classify severity
└─────────┬──────────┘ (classifier heuristics: A.V.R.)
▼
┌────────────────────┐
│ 6. report │ text · JSON (CI) · HTML (charts)
└────────────────────┘3.6 CLI Command Surface
protocrash
├── fuzz --target --protocol --corpus --workers --timeout
│ --max-time --max-execs --dictionary --coverage
│ (single-host) │ --distributed --coordinator --worker-id
│
├── analyze CRASH_DIR --triage --minimize --exploitability
│ --report out.html --stack-depth
│
├── corpus minimize │ merge │ stats │ validate
│
├── monitor SESSION_ID --live --refresh --export
│
├── reproduce crash.file --target ./binary
│
└── coordinator start --port 6666 (distributed master)
Dashboard keys while fuzzing: p pause/resume · r refresh · q quit