LeafFuzz¶

1-command plugin & mod security scanner, LuckPerms permission-leak finder, GUI menu item-leak & bot stress tester (1..500 players), post-GC memory-leak detector, and unwired config/command auditor for Paper, Spigot, Folia, Fabric, and NeoForge.
Quick Start: 3-Step Server & Plugin QC¶
- Download: Drop
LeafFuzz-<version>.jarintoplugins/(Paper, Spigot, Folia) ormods/(Fabric, NeoForge) and start the server. - Run Command: Run
/fuzz check target=<PluginOrModName>(or/fuzz check target=TargetA,TargetB//fuzz check players=auto). - Check Results: Click
[Open Book Scorecard]in chat (or run/fuzz report), read the instant 5-stagePASS/WARN/FAILsummary, and openreports/<target>-qc-report.md(plusreports/<target>-qc-data.ymland.json) for copy-pasteableddminreproducers, LuckPerms/commands.ymlmitigations, post-GC leak slopes, and bytecode causal findings.
How the 5-Stage Automated QC Pass Works¶
| Stage | What It Verifies | Engine |
|---|---|---|
| 1. Command & Least-Privilege Audit | Scans live Brigadier & Bukkit command trees across default vs op tiers (augmented with white-box bytecode subcommand & inline permission hints) and flags state-mutating subcommands (reload, delete, give, admin, config) accidentally left open to unprivileged players. |
CommandSurfaceAuditor, BrigadierDispatcherInspector, PaperCommandTreeInspector, BytecodeCausalGraphScanner |
| 2. Persona Bot Boundary, GUI Menu & Swarm Fuzz Pass | Spawns in-JVM synthetic bots (NmsEmbeddedPlayerSession + PersonaPolicyBotActor) backed by 256-byte Int8[16x16] sleuth_persona_v1 policy genomes, steps autonomous player micro-skills, ramps concurrent player rosters across an Archimedean spiral (players=auto or 1..500), clicks salient GUI menu slots (auditing hazard:gui-item-leak icon extraction), dispatches commands across numeric boundary ladders ([min, -1, 0, 1, 16, 64, 256, 1024, max]), and drives follow-up behaviors (quit_lt1s, quit_delay, move, chunk_border_thrash, window_click, repeat, concurrent), shrinking any failure via Zeller's ddmin + binary numeric bisection. |
SleuthServerFuzzer, PersonaPolicyBotActor, LeafFuzzPaperEpisodeRunner, NmsEmbeddedPlayerSession, NodeBandit, NumericBoundaryLadder, FuzzActionShrinker |
| 3. Main-Thread Stall, Sync-Hazard & Exception Guard | Taps JUL root loggers and samples slow ticks (> 100 ms outside GC pause windows), sub-100ms main-thread synchronous hazards (hazard:sync-chunk:, hazard:sync-io:, hazard:blocking-wait:), and grey-box thread coverage (cov:), attributing the deepest plugin/mod stack frame to its exact .jar (exc:<Exception>:<Frame>, stall:<Frame>). |
LogAndStallSignatureOracle, JarClassOwnershipIndex |
| 4. Post-GC Class Retention Screen | Captures post-GC class histograms (GC.class_histogram) off-thread across an idle control checkpoint (qc-idle-control) and tick-paced episode batches, fitting Bonferroni-corrected OLS slopes (alpha = 0.05 / K) against player departures and command executions to name the exact leaking Java class and .jar. |
ClassRetentionScreener, LeakProbe |
| 5. Bytecode & Causal Audit | Scans target .jar bytecode and YAML resources without loading classes to verify first-order (0-hop command/event/config registration, including REGISTERED_CONFIG_GATED vs UNREGISTERED) and second-order ($k$-hop causal chains to terminal effect sinks, $k \le 4$) invariants (<DeclaredSurface> -> <CausalDefect>), corroborated with live Stage 2 telemetry and optional AST-grounded Jminor LLM explanations. |
BytecodeCausalGraphScanner, LlmCausalChainAuditor |
Commands (/fuzz, /leaffuzz, /qc)¶
/fuzz check [target=<plugin|mod|TargetA,TargetB|all>] [episodes=<n>] [players=<auto|ramp|1..500>] [stage=<all|commands|fuzz|faults|leaks|causal|snapshot>]— Run the 5-stage automated QC pass (ramping concurrent players dispersed across an Archimedean spiral until instability whenplayers=autoor up toplayers=100) and writereports/<target>-qc-report.md,reports/<target>-qc-data.yml, andreports/<target>-qc-data.json./fuzz report— Open the interactive in-game written-book scorecard (LeafFuzzMenuBuilder, audited byBookContrastValidator)./fuzz reset [scope=<all|faults|leaks|campaign>]— Clear recorded fault signatures, post-GC leak checkpoints, or campaign state./fuzz test— Run[FUZZ bit]PBIT/CBIT/IBIT self-tests (7core checks +3live-serverFUZZ-LIVE-*canaries)./fuzz reload— Validate and hot-reloadconfig.yml,messages.yml, and optionalpersonas.jsonl.java -jar LeafFuzz.jar triage (--input-dir ./submissions | --jar ./MyPlugin.jar) [--max-pass 200] [--threads <n>] [--out-json triage.json] [--out-csv triage.csv] [--out-md triage.md] [--fail-on-reject]— Headless Pass 1 zero-server static batch and single-submission triage CLI (closed-world causal hard-reject gate validated to< 0.5%empirical FPR on real-world corpora, composite delivery ranking, and constant-pool companion dependency inference).java -jar LeafFuzz.jar swarm --host 127.0.0.1 --port 25565 --players auto— Standalone CLI mode driving an external TCP protocol bot swarm and ramp-to-instability capacity check (java -jar LeafFuzz.jar extract-mineflayerextracts the bundledbench-swarm.jsscript).