BungeeGuard: Securing Your Minecraft Proxy Network

Running a multi-server Minecraft network with a proxy? Then you've probably already heard that BungeeCord installations are insecure out of the box. Malicious players can bypass your proxy entirely and connect directly to backend servers, joining as any username or UUID they want. It's a well-known vulnerability that's taken down more than a few large servers.

Enter BungeeGuard. It's a straightforward Java plugin that adds token-based authentication between your proxy and backend servers. Instead of relying on complicated firewall rules (or shared hosting where you can't use them at all), BungeeGuard handles authentication for you.

What This Project Does

The idea behind BungeeGuard is almost laughably simple. Your proxy adds a secret authentication token to the login handshake when a player connects. Your backend servers check that the token is present and valid before allowing the player in. That's it. No firewall wizardry. No iptables nightmares. Just a plugin that works.

When a legitimate player connects to your proxy (let's call it proxy.example.com), BungeeGuard on the proxy embeds a pre-shared secret token into the connection data. When the player's client tries to join a backend server (maybe 192.168.1.50:25565), the backend's copy of BungeeGuard checks that token. If it's missing or wrong, the connection gets rejected immediately. If some random person tries to connect directly to that backend server without going through the proxy, there's no token, and they're blocked.

This works on both BungeeCord and Velocity proxies, which covers basically every large Minecraft network setup out there.

When You Need This

If you're running a small local network on your LAN, you probably don't need BungeeGuard. Your local network's probably not under attack. But if your servers are publicly accessible over the internet, or you've any servers exposed beyond your LAN, you're vulnerable.

This becomes critical if you're running a network where player progression or economy matter. Account takeovers, item theft, even just troll accounts joining with fake credentials can ruin the experience for legitimate players. The bigger your network, the more attractive a target you become.

You're also likely on shared hosting where you can't configure firewall rules yourself. BungeeGuard is your lifeline in that scenario.

How to Install BungeeGuard

Installation depends on whether you're using BungeeCord or Velocity. They're slightly different processes.

BungeeCord Setup

First, grab the latest BungeeGuard.jar from the releases page. The current version is v1.4.0, which includes an important security fix if you're upgrading from an older release. After updating, rotate your token in case anyone grabbed the old one.

Drop the jar into your BungeeCord plugins folder:

cp BungeeGuard.jar /path/to/bungeecord/plugins/
cd /path/to/bungeecord
java -jar BungeeCord.jar

Once BungeeCord starts, it'll create a `plugins/BungeeGuard/` directory with a `token.yml` file. Open that file and copy your token. You'll need it for your backend servers.

One important thing: make sure `ip_forward` is set to `true` in your BungeeCord `config.yml`. If you forget this, BungeeGuard won't work right.

Velocity Setup

If you're using Velocity (and you should be if you're building a modern network), the process is even simpler. Velocity 1.1.0 and newer come with BungeeGuard built in. You don't need to install the plugin at all.

Just edit your `velocity.toml` and set:

player-info-forwarding-mode = "bungeeguard"

Your forwarding secret is in that same config file. That's your BungeeGuard token right there.

Backend Servers

Now install BungeeGuard.jar in the plugins folder of every backend Spigot/Paper server:

cp BungeeGuard.jar /path/to/spigot/plugins/
cd /path/to/spigot
java -jar spigot.jar nogui

Restart your server. BungeeGuard will create its own config directory and generate a `token.yml` file. Open it and paste the token from your proxy server. Every backend server needs the same token.

If you're using multiple proxies (a sensible setup for load balancing), they all share the same token.

Key Features That Matter

Token-based authentication is the core feature, but there's more going on under the hood.

BungeeGuard verifies player information passed from the proxy to the backend. It's not just checking the token exists; it's validating that the token is correct and that the rest of the handshake data hasn't been tampered with. This prevents more sophisticated attacks where someone might try to forge the handshake data itself.

The plugin also handles Velocity's modern player info forwarding mode, which is a cleaner way to pass player data in newer setups. If you're building a network from scratch, Velocity with BungeeGuard built in is the right call.

One useful detail: BungeeGuard is incredibly lightweight. It doesn't add noticeable overhead, which matters when you're trying to support thousands of concurrent players across multiple servers.

Security Considerations and Gotchas

Your token is literally the security of your entire network. Treat it like a password. If someone gets your token, they can create legitimate-looking connections to your backend servers and impersonate anyone they want.

Store your token.yml files securely. Don't commit them to version control. Don't paste them in Discord. Just don't.

When you update to v1.4.0 (which you should do immediately), the maintainer recommends rotating your token after updating affected BungeeCord setups. This clears out any old tokens that might have been compromised. Velocity setups with the built-in BungeeGuard aren't affected by that vulnerability.

You also want firewall rules in addition to BungeeGuard, not instead of. Configure your firewall to block direct connections to backend servers from the internet. BungeeGuard is a great second layer of defense, but it shouldn't be your only layer. If you can set up iptables rules, do it. Then add BungeeGuard on top.

Test your setup before going live. Try connecting directly to a backend server without going through the proxy. You should get connection refused or a timeout. If you see a login screen, something's wrong with your BungeeGuard installation.

Similar Projects and Alternatives

Firewall rules (iptables, ufw) are technically an alternative, but they require system access and are error-prone. Most servers using BungeeGuard do both anyway.

Some hosting providers offer managed proxy solutions that handle authentication for you. But if you're running your own infrastructure or on shared hosting without that feature, BungeeGuard is really your best option. It's been battle-tested on networks with thousands of players.

The project itself is solid and actively maintained. It's MIT licensed (225 stars on GitHub, Java-based) and the maintainer takes security seriously, as evidenced by the recent vulnerability fix and responsible disclosure process.

If you're managing player data with sophisticated whitelisting or custom authentication, tools like Minecraft's whitelist creator work well alongside BungeeGuard. And for server administration, block search tools help when you need to audit your world for suspicious structures.