{"id":51440674,"url":"https://github.com/daedalus/fuzzer","last_synced_at":"2026-07-05T11:01:48.265Z","repository":{"id":366654171,"uuid":"1273637889","full_name":"daedalus/fuzzer","owner":"daedalus","description":null,"archived":false,"fork":false,"pushed_at":"2026-06-30T13:55:02.000Z","size":383,"stargazers_count":1,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2026-06-30T14:06:40.860Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/daedalus.png","metadata":{"files":{"readme":"README.md","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":"AGENTS.md","dco":null,"cla":null}},"created_at":"2026-06-18T18:09:54.000Z","updated_at":"2026-06-30T13:55:07.000Z","dependencies_parsed_at":null,"dependency_job_id":null,"html_url":"https://github.com/daedalus/fuzzer","commit_stats":null,"previous_names":["daedalus/fuzzer"],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/daedalus/fuzzer","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Ffuzzer","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Ffuzzer/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Ffuzzer/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Ffuzzer/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/daedalus","download_url":"https://codeload.github.com/daedalus/fuzzer/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/daedalus%2Ffuzzer/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":35151638,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-05-26T15:22:16.424Z","status":"online","status_checked_at":"2026-07-05T02:00:06.290Z","response_time":100,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2026-07-05T11:01:47.583Z","updated_at":"2026-07-05T11:01:48.258Z","avatar_url":"https://github.com/daedalus.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# fuzzer-tool\n\nCoverage-guided binary fuzzer with statistical novelty scoring, Markov chain generation, Monte Carlo mutations, and kernel crash verification.\n\n## Features\n\n### Mutation \u0026 Generation\n- **Mutation operators**: bit flip, byte flip, interesting values (8/16/32-bit), arithmetic (1/2/4/8-byte, LE/BE), block insert/delete/duplicate, havoc mode\n- **Dictionary support**: inject protocol tokens from dictionary files\n- **Markov chain**: learn byte-level transition probabilities from corpus, generate statistically similar inputs, persist across runs\n- **Monte Carlo scheduling**: Thompson sampling bandit for operator selection + Cross-Entropy Method for byte distribution learning\n- **Perplexity-gated generation**: model quality dynamically scales generation rate (more generation when model is lost, less when well-calibrated); rejects extreme-perplexity outputs as pure noise\n\n### Coverage \u0026 Scoring\n- **AFL SHM bitmap** coverage for instrumented targets (~65-200 eps)\n- **Ptrace edge coverage** with deep capstone disassembly for closed-source binaries (~18-20 eps)\n- **In-process execution**: persistent subprocess mode (~65-120 eps) with auto-restart on crash\n- **Good-Turing estimation**: prospective edge discovery count with saturation confidence\n- **KS significance testing**: replaces fixed JS thresholds with sample-size-aware p-values\n- **CRPS scoring**: proper scoring rule for execution time calibration (fixed indicator direction bug)\n\n### Scheduling Intelligence\n- **Subsumption weighting**: seeds fully covered by others get deprioritized\n- **Hitcount diversity (JS divergence)**: seeds with unusual frequency profiles get boosted\n- **Wasserstein spatial diversity**: seeds exploring different code regions get boosted\n- **Perplexity (MDL codelength)**: structurally novel seeds get 1.0-2.0x weight\n- **NCD similarity**: Normalized Compression Distance between corpus entries\n- **Weight caching**: edge tracker recomputes only when coverage changes\n\n### Crash Analysis\n- **Sanitizer detection**: automatic ASAN/MSAN/TSAN/LSAN/UBSAN crash classification\n- **Kernel crash verification**: async dmesg streaming for kernel-level crash detection\n- **Crash minimization**: delta-debugging to smallest reproducer (`tmin` subcommand)\n- **Corpus minimization**: greedy set-cover over SHM edge bitmaps (`minimize` subcommand)\n- **Crash exploitability tiers**: ASAN_EXPLOITABILITY classification in reports\n\n### Observability\n- **`--report` flag**: full explainability report with coverage, mutations, perplexity, corpus health, edge map\n- **`--replay-N` flag**: background crash reproducibility scoring\n- **Per-seed cost tracking**: wall-clock time per seed for cost-aware scheduling\n- **Discovery rate**: edges per 1k execs over sliding window\n- **Bitmap density**: map occupancy percentage (saturation detection)\n- **Dup rejection rate**: duplicate-rejection as saturation signal\n\n## Installation\n\n```bash\npip install -e \".[dev]\"\n```\n\n## Quick Start\n\n```bash\n# Basic fuzzing\nfuzzer-tool fuzz ./target\n\n# Coverage-guided with dictionary\nfuzzer-tool fuzz -c -D dictionary.txt ./target\n\n# In-process mode (fastest for .so targets)\nfuzzer-tool fuzz libfoo.so --inprocess --inprocess-func target_func -c\n\n# File-based target\nfuzzer-tool fuzz -F -A \"{file}\" ./target\n\n# With Markov and Monte Carlo\nfuzzer-tool fuzz --markov --markov-gen --mc-bandit --mc-cem ./target\n\n# Generate PNG corpus for libpng fuzzing\npython tools/corpus_png.py --out corpus --download\nfuzzer-tool fuzz libpng_read.so --inprocess --inprocess-func fuzz_png -c -D dictionaries/png.dict -d corpus/\n\n# Resume a previous fuzzing session\nfuzzer-tool fuzz ./target -c --resume\n\n# Run with crash reproducibility scoring\nfuzzer-tool fuzz ./target -c --replay-n 3\n\n# Full report after run\nfuzzer-tool fuzz ./target -c -n 5000 --report report.txt\n```\n\n## Fuzzing Options\n\n| Flag | Description |\n|------|-------------|\n| `-c` | Enable coverage-guided mode |\n| `--no-shm` | Skip AFL SHM, force ptrace |\n| `--deep-coverage` | Capstone-based basic block discovery |\n| `-F` | File mode (write input to temp file) |\n| `-D FILE` | Load dictionary tokens |\n| `-g GRAMMAR` | Grammar-aware mutations (built-in: json, http_request, elf) |\n| `--cmplog` | Comparison tracing via LD_PRELOAD |\n| `--markov-gen` | Markov-generated seeds (rate adapts to model quality via perplexity) |\n| `--mc-bandit` | Thompson sampling operator selection (Brier score calibration) |\n| `--mc-cem` | Cross-Entropy Method byte distribution |\n| `--inprocess` | Persistent subprocess mode (auto-restart on crash) |\n| `--resume` | Resume from saved state |\n| `-j N` | Parallel fuzzing with N workers |\n| `--max-corpus N` | Auto-minimize corpus at N entries |\n| `--replay-n N` | Replay each crash N times for reproducibility scoring |\n| `--report [FILE]` | Generate explainability report (stdout or file) |\n\n## Coverage Modes\n\n| Mode | Flag | Throughput | Notes |\n|------|------|-----------|-------|\n| SHM bitmap | `-c` (default) | 65–200 eps | For AFL-instrumented targets |\n| In-process | `--inprocess` | 65–120 eps | Persistent loader with crash recovery |\n| In-process direct | `--inprocess-direct` | 2k–34k eps | No crash isolation |\n| Ptrace basic | `-c --no-shm` | ~20 eps | Function-entry breakpoints |\n| Ptrace deep | `-c --no-shm --deep-coverage` | ~18 eps | Capstone BB discovery |\n\n## Statistical Metrics\n\n### Good-Turing Coverage Estimation\nEstimates undiscovered edges from the frequency spectrum (N₁²/2N₂). Reports saturation percentage and confidence level. Replaces the old \"we found N edges\" with \"we estimate X edges remain.\"\n\n### KS Significance Testing\nReplaces fixed JS divergence thresholds (JS \u003c 0.01 / JS \u003e 0.1) with sample-size-aware critical values. Early in a run (few samples), thresholds are high; later (many samples), thresholds drop to catch subtle changes.\n\n### CRPS (Continuous Ranked Probability Score)\nProper scoring rule for execution time calibration. Tracks the empirical CDF of execution times and scores new observations. Rising CRPS trend = target runtime behavior is drifting (possible ASLR, cache effects, or behavioral change).\n\n### Perplexity\nPP = 2^(codelength_per_byte) from the Markov model. Used to:\n- Gate generation rate (high PP → generate more, low PP → generate less)\n- Filter generated inputs (reject PP \u003e 512 as pure noise)\n- Boost structurally novel seeds in scheduling\n\n## State Persistence\n\n```bash\nfuzzer-tool fuzz ./target -c -n 10000\nfuzzer-tool fuzz ./target -c --resume -n 10000\n```\n\nState files:\n- `state.json` — exec counts, crash sigs, op stats, seed metadata\n- `edge_tracker.json` — per-seed edge coverage, cumulative edges, global hit counts\n- `markov.json` — persisted Markov chain transitions\n\n## In-Process Execution\n\n### Direct ctypes (`--inprocess-direct`)\nCalls target function directly via `ctypes.CDLL`. No crash isolation. ~2k–34k eps.\n\n### Persistent subprocess (`--inprocess`)\nKeeps one Python subprocess alive. Fork-per-call for crash isolation. Auto-restarts on subprocess death (SIGSEGV from target). No bitmap pipe transfer — parent reads SHM directly. ~65–120 eps.\n\n## Test Suite\n\n528 tests covering all modules. Run with:\n\n```bash\npip install -e \".[dev]\"\npytest\n```\n\n## Development\n\n```bash\npip install -e \".[dev]\"\npytest\nruff check src/ tests/\nruff format src/ tests/\n```\n\n## License\n\nMIT\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaedalus%2Ffuzzer","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdaedalus%2Ffuzzer","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdaedalus%2Ffuzzer/lists"}