Security

Paper already blocks a lot: a connection throttle and an all-packets rate limiter. EmberMC adds the layer those two can't express - per-category limits, so a book edit and a sprint are governed by different rules - and a window into what is being blocked.

The Packet Guard

Every serverbound packet is sorted into a category and checked against that category's own limit, per connection, right after Paper's own limiter:

Category	what it is
movement	position, rotation, vehicle move, teleport-accept
arm-swing	the swing animation packet
interact	entity interact, use item, block place, player action
inventory	container clicks, slot changes, held-item
book / sign	book edits and sign updates (payload-size capped)
chat	chat messages
command	commands (signed and unsigned)
tab-complete	command suggestion requests
recipe	recipe-book placement
creative	creative-mode slot sets
plugin-message	custom-payload / BungeeCord-channel packets and cookie responses (payload-size capped)
other	everything else

Each category is a token bucket: a sustained rate plus a burst allowance, so a legitimate flurry - a row of shift-clicks, a sprint, a fast typist - is fine, and only a sustained flood runs it dry. Book and sign additionally have a maximum payload size; a book far past any real size is refused whatever its rate.

Actions

When a category is over its limit, the guard does one of:

• log - count it, let it through (measurement mode)
• warn - count it, let it through, one console line per five seconds
• throttle / drop - drop that packet, keep the player; the client simply re-sends, invisible in normal play
• kick - disconnect

Defaults are a busy survival server's headroom, not a tight cap: movement 200/s throttle, arm-swing 60/s drop, book/sign 4/s + 12 KB kick, command 15/s throttle, and so on. Every category's rate, burst, size cap and action is configurable.

Seeing it

/ember security

shows every category's limit, action, and allowed/blocked counts since start. ember_packets_blocked is exported to the metrics endpoint. The guard never logs packet contents, IP beyond what Paper already logs, or anything about authentication - the diagnostics are counts, nothing more.

Turn it off with security.packet-guard.enabled: false.

Decompression-exhaustion (a packet that inflates to a huge size) is not a category here because Paper already caps it: the compression decoder rejects a packet claiming to decompress past 8 MB before it inflates. Not reinvented.

Item and XP limits

Two anti-abuse backstops that live alongside the guard and also show in /ember security, both off by default:

• Item limits (entities.item-limits) cap dropped-item entities per loaded chunk against dupe floods and runaway farms; Paper only trims at unload. The oldest overflow goes first. See Item limits.
• XP-orb limits (entities.xp-limits) cap orb entities per chunk by folding overflow experience into the survivors, so no XP is ever lost. See XP-orb limits.

Reporting a vulnerability

Do not open a public issue for an exploit that works against live servers. Contact TheMeanOneDevelopments privately (details in the repository) with the build, a description and a reproduction. You'll get an acknowledgement quickly and a fix or workaround before any public disclosure.

Configuration

security:
  packet-guard:
    enabled: true
    movement:   { per-second: 200, burst: 400, max-bytes: 0, action: throttle }
    arm-swing:  { per-second: 60,  burst: 120, max-bytes: 0, action: drop }
    book-sign:  { per-second: 4,   burst: 8,   max-bytes: 12288, action: kick }
    command:    { per-second: 15,  burst: 30,  max-bytes: 0, action: throttle }
    # ... interact, inventory, chat, tab-complete, recipe, creative, other