🛡️ GeyserGuard

GeyserGuard adds a defensive UDP protection layer for Geyser traffic, catching empty packets, malformed datagrams, fast bursts, and abusive packet rates before they reach the expensive parts of the network stack. Available for both Spigot/Paper/Purpur (per-server) and Velocity (proxy-wide) setups.

What it protects against

• Empty UDP packets
• Malformed or oversized datagrams
• Per-IP packet floods (rate limiting in packets per second), with strike-based escalation so a single burst never bans a legitimate player
• Global packet-rate spikes across all connections
• Repeated suspicious packets, which trigger a temporary IP ban
• Ping-flood / server-list scanning — optionally silences replies to Bedrock ping requests entirely, hiding the server from scanners without blocking real player connections
• IPv6 subnet-aware banning (bans the whole /64 block instead of a single address, since attackers can rotate through billions of individual IPv6 addresses within one subnet)
• Memory exhaustion (OOM) from spoofed IP floods — every internal tracking structure, not just the main filter, is capped and evicts oldest entries first
• Console/log spam suppression — malformed Bedrock/RakNet packets (valid packet ID but truncated payload) normally flood the console with repeated Netty/Geyser exception warnings; GeyserGuard silently catches these and bans the offending IP instead of spamming the log

⚙️ Features

• Configurable packets-per-second limit, per IP and globally
• Strike-based rate limiting: requires sustained flooding across consecutive windows before banning, so a reconnect burst, lag spike, or several real players sharing one CGNAT/mobile IP is never banned by mistake
• Optional ping-response suppression to hide the server from Bedrock server-list scanners and ping-flood tools, with zero impact on real connections
• Configurable minimum/maximum packet size filtering
• Temporary bans with configurable duration and suspicious-hit threshold
• Threshold-based attack alerts — only escalates to a console/chat warning once blocked packets build up past a configurable count (or immediately on an actual ban), so a harmless one-off drop never looks like an ongoing attack
• Persistent local ban database (bans survive a restart)
• IP/CIDR whitelist for trusted addresses (your own server, reverse proxy, load balancer, etc.), fully reloadable without a restart
• In-game and console alerts for admins, with optional IP masking
• Automatic memory protection: tracks a configurable maximum number of IPs and evicts the oldest inactive ones first, preventing memory exhaustion from spoofed IP floods
• Bilingual support (English/Spanish) via config.yml
• Low overhead, no external dependencies required

Commands & Permissions

OP players have all permissions by default. To grant them manually, use a permissions plugin like LuckPerms.

Why use it?

Servers that accept Bedrock players through Geyser expose a UDP listener that can be targeted directly with packet floods, spoofed IPs, and malformed datagrams — attacks that bypass normal Java-edition TCP protections. GeyserGuard inspects this traffic in real time and blocks abusive sources before they reach your server's core logic, without requiring a separate firewall or proxy setup.

📥 Installation

1. Download the .jar matching your platform (Spigot/Paper/Purpur or Velocity)
2. Place it in your server's (or proxy's) plugins folder
3. Restart the server
4. Edit the generated config.yml to adjust:
   • language — set to EN for English or ES for Spanish (Español); controls all plugin messages, alerts, and command output
   • packet-protection.pps-limit — max packets/second per IP
   • packet-protection.global-pps-limit — max packets/second overall
   • packet-protection.suspicious-hit-threshold / ban-seconds — when and how long IPs get banned
   • packet-protection.rate-limit-strikes-before-ban — how many consecutive over-limit windows before a real ban is applied
   • packet-protection.block-ping-response — hide the server from Bedrock ping/server-list scanners without affecting real connections
   • packet-protection.log-threshold — how many blocked packets must build up before an "attack detected" alert fires
   • ipv6.group-by-subnet — ban by IPv6 /64 subnet instead of single address
   • whitelist — IPs/CIDRs that are never blocked
   • alerts — console/chat alert behavior
5. Reload with /geyserguard reload or restart the server