GeyserGuard

🛡️ 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)
• Global packet-rate spikes across all connections
• Repeated suspicious packets, which trigger a temporary IP ban
• 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)
• 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
• Configurable minimum/maximum packet size filtering
• Temporary bans with configurable duration and suspicious-hit threshold
• Persistent local ban database (bans survive a restart)
• IP/CIDR whitelist for trusted addresses (your own server, reverse proxy, load balancer, etc.)
• 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
   • 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