ForgeGuard exploit and abuse coverage

ForgeGuard 0.6.0-alpha.1 has 26 server-side combat, building and movement checks (below), per-player violation levels, an opt-in response ladder, the configurable event-abuse budgets and bounded book-text inspection from 0.3. These are specific safeguards, not an assurance that a player is cheating or that every Minecraft exploit is blocked. The movement observation model remains restricted to its documented native 1.21.11 environments.

Implemented protections

Each player has separate budgets for each event family. A command flood therefore does not consume another player's budget or that player's inventory budget. Buckets start full and refill using elapsed time; normal tick and network bursts have headroom, while accumulated credit never exceeds the burst limit. Excesses do not add unbounded token debt.

The default mode is OBSERVE: incidents are recorded, and no event is cancelled by these guards. Setting guards.mode: CANCEL opts in to cancellation of the specific over-budget or oversized-book event. The guards never kick or ban automatically. Other plugins can subsequently change event cancellation, so the cancelled metric means cancellation requested by ForgeGuard.

Book defaults allow 100 pages, 4096 Unicode codepoints per page, 128 title codepoints and 1,048,576 UTF-8 text bytes across the title and pages. Astral characters count as one codepoint and four UTF-8 bytes. These defaults admit 100 pages of 1024 astral characters. The scanner short-circuits on limits and does not allocate encoded copies of each page. It reads already-decoded Bukkit book text, not the original packet payload, component JSON or full item NBT. Once a book-edit rate budget is exhausted, extra metadata copying/scanning is skipped in either mode and skippedBookScans increases; an OBSERVE event still proceeds.

Behaviour checks (0.6)

Judged only from the server's own state: entity positions and hitboxes, the player's reach attributes, block states and collision shapes, the break speed the server computes for that player, tool and block, and the knockback velocity the server itself sent. Each needs repeated violations before it becomes a case, and cases per check are rate limited (behaviour.case-cooldown-seconds, default 20). Movement checks pause for players above behaviour.max-ping-ms (300) and while the server is below behaviour.minimum-tps (17); buffers reset so a stall never completes a sequence.

Exempt from the movement checks: creative and spectator players; flight permission or flying, gliding, swimming, riptide, vehicles, lava, sleeping, death, levitation and slow falling; recent damage; nearby boats, minecarts, shulkers, armour stands and players; unloaded destination chunks; join, teleport, velocity and integration grace; translated or unidentified clients; and forgeguard.bypass. Flight additionally skips bouncy floors (slime, beds) and nearby pistons; glide skips wall contact (honey); no-slow and inventory move skip ice, slime, honey, bubble columns and soul blocks; water walk needs the feet out of liquid. Bad rotation is judged even for exempt players because a vanilla client cannot send it.

Limits: these are server-side geometry and timing, not a client prediction. Vanilla already refuses melee well beyond reach, so reach cases cover the gap between the reach attribute and the server's own limit. Attack-rate, autoclicker, hover, glide and inventory-move are statistical signals with legitimate edge cases, criticals and aim snap are experimental heuristics, and ground checks cannot see every modded or plugin-provided surface. Review the case, the player's context, /fg vl and /fg inspect before acting. The status's behaviour.lastAttack shows the most recent reach measurement for tuning.

Violation levels and the response ladder

Every case adds response.finding-weight (1.0) to the player's violation level for that check; levels fade by response.decay-per-minute (1.0) without new findings. /fg vl, /fg top, the player card and the website status show them. VL is a triage number: a protocol-invalid packet and a borderline experimental signal both add one point.

response.enabled (default false) turns on the ladder. Steps are {vl, action} entries: ALERT_STAFF, SETBACK (to the last verified floor), KICK (message), TEMPBAN (seconds 60–31,536,000 and reason, through the same audited UUID ban store as staff bans) or COMMAND (command, a console command without a leading slash). Placeholders {player}, {uuid}, {check}, {vl} and {case} are filled. Steps are sorted by VL, fire once each as the total climbs and only fire again after the VL has fully decayed. excluded-checks (default: packet rate, timer window, attack rate) never count toward VL. Protected (forgeguard.protected) and bypassing (forgeguard.bypass) players only ever trigger ALERT_STAFF. Each applied step is audited (response.<action>) before it runs; a failed audit means nothing happens.

Configuration

All listed defaults are available in config.yml. Reload after changing values.

guards:
  enabled: true
  mode: OBSERVE
  alert-cooldown-seconds: 15
  maximum-tracked-players: 10000
  rates:
    inventory-click: {enabled: true, burst: 240, per-second: 80}
    item-drop: {enabled: true, burst: 160, per-second: 40}
    interact: {enabled: true, burst: 400, per-second: 120}
    book-edit: {enabled: true, burst: 20, per-second: 4}
    command: {enabled: true, burst: 60, per-second: 12}
  book-limits:
    enabled: true
    maximum-pages: 100
    maximum-page-codepoints: 4096
    maximum-total-utf8-bytes: 1048576
    maximum-title-codepoints: 128

guards.enabled disables all six families; each rate family and the book limits can also be disabled individually. Supported modes are exactly OBSERVE and CANCEL (case insensitive). Booleans must be YAML booleans, numeric values must be finite, and integer fields reject fractions. Incorrect section shapes are rejected instead of silently using defaults.

Validated ranges: burst and refill 1–100,000; incident cooldown 1–3600 seconds; tracked players 1–100,000; book pages 1–1000; page codepoints 1–65,536; title codepoints 1–4096; total UTF-8 bytes 1–16,777,216. A configurable limit does not change Minecraft's own book, packet or protocol limits. Very low limits can disrupt legitimate play; choose limits from real server observations, including menu plugins and rapid inventory management, before enabling cancellation.

An explicit forgeguard.guard.bypass permission exempts a player; the permission defaults to false and is not granted simply by being an operator. Bypassed checks are counted. This permission is separate from the movement-observation bypass.

Visibility, memory and evidence

The health snapshot exposes the mode, enabled families, per-family thresholds and counters, checked events, violations, requested cancellations, bypasses, tracked players, capacity misses, aggregated reports, notification failures, skipped book scans and a maximum of 100 recent incidents. This data powers the in-game and web health views.

The first incident in a player/family cooldown is reported immediately. Further incidents are aggregated and delivered after the cooldown by the heartbeat, or flushed when the player leaves, settings reload or the plugin closes. Reports contain a UUID, bounded player name, family, reason code and counts. They never contain command arguments, passwords, book contents, inventory contents or raw packet data. The plugin's bounded audit writer handles persistence; guard reports are not deterministic movement replay cases.

Player state is capped by maximum-tracked-players. On capacity exhaustion, previously tracked players retain their budgets and new untracked events proceed without guard enforcement; capacityMisses and capacity-limited coverage make that gap visible. Player quit releases state. Reload resets budgets and pending player state, preserving lifetime counters and recent incidents. Counters reset when the service/plugin restarts. There is no packet-thread inventory access, recursive NBT traversal or blanket packet cancellation.

Coverage still absent

Verification and upstream context

Automated tests cover burst tolerance, sustained abuse, per-player and per-family independence, observe/cancel behavior, backwards clock handling, capacity exhaustion, cooldown aggregation, reload/quit cleanup, explicit bypass and revocation, Unicode and byte limits, rejection before page access, metadata-scan suppression during floods, invalid settings and incident-delivery failure. These tests establish the implemented mechanics; they are not a competitive cheat-client benchmark or proof of production compatibility with every menu/plugin combination.

API references: Paper 1.21.11 BookMeta, WritableBookMeta, PlayerEditBookEvent. These APIs expose already-decoded metadata; rejecting an edit at this layer cannot undo work already performed by the server's packet decoder.