Skip to content

Commands & Permissions Reference (LeafFuzz)

LeafFuzz registers /fuzz alongside aliases /leaffuzz and /qc. All commands use explicit name=value parameter syntax (CommandsAPI, commands-api-ADR-001) and work identically on Paper, Spigot, Purpur, Folia, Fabric, and NeoForge.


Root Command & Subcommands (5 Subcommands)

Command Parameters Default Permission Description
/fuzz [target=<Plugin\|Mod\|A,B\|all>] [episodes=<1..100000>] [players=<auto\|ramp\|1..500>] [stage=<all\|commands\|fuzz\|faults\|leaks\|causal\|snapshot>] leaffuzz.admin (op) With no parameters, opens the interactive in-game written-book scorecard (/fuzz report). When target=, episodes=, players=, or stage= is provided (for example /fuzz players=auto or /fuzz target=RTP episodes=24), runs /fuzz check directly.
/fuzz check [target=<Plugin\|Mod\|A,B\|all>] [episodes=<1..100000>] [players=<auto\|ramp\|1..500>] [stage=<all\|commands\|fuzz\|faults\|leaks\|causal\|snapshot>] leaffuzz.admin (op) Runs the 5-stage automated QC pass (stage=all, default) with a concurrent player roster dispersed across an Archimedean spiral (players=100 or players=auto to ramp until the server becomes unstable) or a specific stage (stage=commands, stage=fuzz, stage=faults, stage=leaks, stage=causal, stage=snapshot) and writes status-leading reports/<target>-qc-report.md, reports/<target>-qc-data.yml, and reports/<target>-qc-data.json for BuiltByBit / Modrinth moderation evidence. Also accepts positional shorthand /fuzz check <Target> [episodes].
/fuzz report (none) leaffuzz.admin (op) Opens the interactive in-game written-book scorecard (LeafFuzzMenuBuilder) for the latest QC check, or prints a formatted chat scorecard on console.
/fuzz reset [scope=<all\|faults\|leaks\|campaign>] leaffuzz.admin (op) Clears recorded exception/stall/hazard signatures (faults), post-GC histogram checkpoints (leaks), and/or persisted campaign state and .jar.sleuth-disabled archives (campaign). Defaults to scope=all.
/fuzz test (none) leaffuzz.admin (op) Executes all [FUZZ bit] PBIT, CBIT, IBIT, and live-server (FUZZ-LIVE-*) self-test components off-thread.
/fuzz reload (none) leaffuzz.admin (op) Validates and hot-reloads config.yml, messages.yml, and personas.jsonl and refreshes the plugins/*.jar / mods/*.jar ownership index off-thread.

Stage Selector (stage=...)

stage= Value Behavior
all (default) Executes the full 5-stage automated QC pass (Command Surface Audit, Persona Bot & Swarm Fuzzing, Main-Thread Stall/Hazard & Exception Attribution, Post-GC Class Retention Screen, and First/Second-Order Bytecode & Causal Audit) and writes reports/<target>-qc-report.md (.yml / .json).
commands Runs Stage 1 only: audits live Brigadier & Bukkit command trees (augmented with white-box bytecode subcommand hints) for default vs op exposure and prints ready-to-paste LuckPerms mitigations.
fuzz Runs the full QC pass focused on Stage 2 synthetic player boundary & lifecycle fuzzing.
faults Inspects Stage 3 attributed exception (exc:), slow-tick stall (stall:), and synchronous main-thread hazard (hazard:) signatures filtered by target=.
leaks Runs Stage 4 Bonferroni-corrected OLS class retention screening across captured post-GC checkpoints for target=.
causal Runs Stage 5 zero-classloading bytecode & config causal graph audit (BytecodeCausalGraphScanner + optional LlmCausalChainAuditor), reporting Order-1 and Order-2 <DeclaredSurface> -> <CausalDefect> findings.
snapshot Captures an immediate off-thread post-GC GC.class_histogram checkpoint (manual-<n>) for manual retention comparison.

Standalone External Swarm CLI (java -jar LeafFuzz.jar)

The same LeafFuzz-<version>.jar artifact can be executed directly from a terminal to drive an external multi-player TCP protocol swarm and ramp-to-instability capacity test:

# Ramp concurrent offline-mode TCP players until the server becomes unstable (up to 100 players)
java -jar LeafFuzz.jar swarm --host 127.0.0.1 --port 25565 --players auto --duration-sec 30 --report swarm-report.md

# Fixed 100-player concurrent swarm without ramp stop
java -jar LeafFuzz.jar swarm --host 127.0.0.1 --port 25565 --players 100 --no-ramp --duration-sec 60 --max-rtt-ms 55.0

# Extract the bundled Mineflayer bench-swarm.js script to disk
java -jar LeafFuzz.jar extract-mineflayer --out ./bench-swarm.js

# Pass 1 zero-server static batch triage (filter 2,000 submission JARs down to <= 200 with < 0.5% FPR)
java -jar LeafFuzz.jar triage --input-dir ./submissions --max-pass 200 --out-json triage.json --out-csv triage.csv --out-md triage.md

# Single-JAR static triage with CI exit-code gate (--fail-on-reject exits with code 3 if rejected)
java -jar LeafFuzz.jar triage --jar ./MyPlugin.jar --fail-on-reject --out-md triage.md
CLI Flag Default Description
triage / scan (subcommand) Runs headless Pass 1 zero-server static bytecode batch triage across --input-dir (or single-file --jar), applying closed-world causal hard-reject checks (validated to < 0.5% empirical FPR on real-world corpora) and inferring constant-pool companion dependencies (Vault, PlaceholderAPI, WorldGuard, LuckPerms) with zero penalty.
--input-dir <dir> / -i / --jar <file.jar> (required for triage) Directory of candidate plugin/mod .jar submissions or a single .jar file to scan off-thread.
--max-pass <n> 200 Maximum number of top-ranked valid archives promoted to SHORTLIST_PASS (remaining valid archives are marked DEFERRED_RANK).
--threads <n> / -t availableProcessors Parallel worker thread count (1..64) for triage.
--out-json <path> (none) Writes the machine-readable JSON triage leaderboard and inferred dependency manifest for Pass 2 server provisioning.
--out-csv <path> (none) Writes the RFC 4180 CSV triage leaderboard.
--out-md <path> (none) Writes the human-readable Markdown triage leaderboard report.
--strict-s004-s005 / --no-strict-s004-s005 true Controls whether CONFIRMED (100%) S-004 (swallowed I/O exception) and S-005 (async worker main-thread world mutation) proofs trigger immediate REJECT.
--fail-on-reject false Returns exit code 3 when one or more scanned archives receive a REJECT verdict (for CI / pre-submission gating).
--host <host> / -H 127.0.0.1 Target Minecraft server hostname or IP address.
--port <port> / -p 25565 Target Minecraft server TCP port (1..65535).
--players <auto\|ramp\|1..500> / -n 100 (auto) Target concurrent offline-mode TCP bot sockets dispersed across an Archimedean spiral.
--ramp / --no-ramp --ramp Progressively ramps population (10 -> 25 -> 50 -> 75 -> 100+) and records the exact instability threshold (maxStablePlayers).
--duration-sec <sec> 15 Hold/step duration in seconds (1..3600).
--timeout-ms <ms> 3000 Socket connection and handshake timeout in milliseconds (200..30000).
--protocol <auto\|id> auto (-1) Minecraft protocol version number, or auto to detect via Server List Ping (SLP).
--max-rtt-ms <ms> 55.0 Maximum p95 ping/keep-alive RTT in milliseconds (>= 10.0) before declaring tick/network instability.
--report <path> (none) Writes a self-contained Markdown swarm readiness report to <path>.
extract-mineflayer [--out <path>] ./bench-swarm.js Extracts the bundled /META-INF/leaffuzz/swarm/bench-swarm.js Mineflayer harness from the JAR.

Permission Nodes

Permission Node Default Behavior
leaffuzz.admin op (Permission Level 4 on Fabric/NeoForge) Grants access to all /fuzz, /leaffuzz, and /qc quality-control, fuzzing, retention-screening, and diagnostic commands.