AtomGuard

Keep your Minecraft server safe from hackers, bots, and crashes.

Works with Paper 1.21.4 and Velocity 3.x

AtomGuard is a free, open-source security plugin that protects your Minecraft server from attacks, exploits, and cheaters — so you can focus on building your community.

⬇️ Download · 📖 Setup Guide · ❓ FAQ · 🤝 Contribute

💡 Why AtomGuard?

Running a Minecraft server is fun — until someone tries to ruin it. Bot attacks that flood your server with fake players, exploits that crash everyone out, duplication glitches that destroy your economy… the list goes on.

AtomGuard handles all of that for you. Just drop it in your plugins folder and your server is protected. No complicated setup, no networking degree required.

Here's what it protects you from:

🛡️ Bot & DDoS Attacks — Automatically detects and blocks waves of fake players and connection floods before they slow your server down.

🚫 VPN & Proxy Abuse — Stops banned players from rejoining on a VPN. Uses 7 different detection methods for accuracy, and won't accidentally block your real players.

🔧 Crash Exploits — Fixes 44+ known Minecraft exploits that hackers use to crash servers, including book crashes, NBT attacks, and packet exploits.

♊ Duplication Glitches — Prevents item duplication bugs that can wreck your server's economy.

⚡ Lag Machines — Limits redstone, explosions, pistons, and entities so players can't build devices that lag your server.

🌍 Country Filtering — Allow or block players from specific countries if you want a region-locked community.

🔐 Login Protection — Blocks brute-force password attacks and prevents the use of common passwords (works with AuthMe).

✨ Feature Highlights

🤖 Smart Bot Detection

AtomGuard doesn't just look at one thing — it scores each connecting player across 8 different signals like connection speed, client type, join pattern, and username. Players that score low enough get through instantly. Suspicious ones get a quick math challenge. Obvious bots get blocked.

Your regular players won't even notice it's running.

⚔️ Adaptive DDoS Protection

The SmartThrottle Engine automatically adjusts its defenses based on how bad an attack is:

During a serious attack, it locks down new connections while making sure your verified players can still get in. Once the attack stops, everything goes back to normal automatically.

🧠 Threat Intelligence

AtomGuard learns your server's normal traffic patterns over 7 days. When something unusual happens — like a sudden spike in connections at 3 AM — it automatically ramps up protection. This means fewer false alarms and faster response to real threats.

🏅 Player Trust Score

The more a player plays on your server without causing trouble, the more AtomGuard trusts them. Veteran players skip most checks entirely, which means faster logins for your loyal community and stricter checks for newcomers.

🍯 Honeypot

AtomGuard can run a fake Minecraft server on a different port. When bot scanners find it and try to connect, their IP gets instantly banned from your real server. It's like a trap for attackers.

🔬 Attack Reports

After every attack, AtomGuard saves a detailed report — what happened, when, how many IPs were blocked, and which defenses did the work. You can review these anytime to understand what your server faced.

📦 What You'll Need

🚀 Getting Started

Option 1: Paper Server (most people start here)

Step 1 — Download PacketEvents and put it in your plugins/ folder.

Step 2 — Download AtomGuard-core.jar and put it in the same plugins/ folder.

Step 3 — Start (or restart) your server. AtomGuard will create its config files automatically.

Step 4 — Customize the settings in plugins/AtomGuard/config.yml if you want — but the defaults work great out of the box!

Option 2: Velocity Proxy

If you run a Velocity network, install the proxy module for network-wide protection:

Step 1 — Download AtomGuard-velocity.jar and put it in your proxy's plugins/ folder.

Step 2 — Start (or restart) your proxy. Config files are created automatically.

Step 3 — Edit plugins/atomguard-velocity/config.yml to your liking.

Step 4 (optional) — Enable the Redis section in both configs if you want the proxy and backend servers to share ban lists and threat data.

💡 Tip: You can run both modules together! The Velocity module stops threats at the network edge, while the Core module handles in-game exploits on each server.

💻 Commands

All commands require the atomguard.admin permission unless noted otherwise.

Permissions

🌐 How VPN Detection Works

Instead of relying on a single provider (which can be inaccurate), AtomGuard queries 7 providers at the same time and only blocks a player if at least 2 providers agree the IP is a VPN or proxy. This dramatically reduces false positives — your players on normal internet connections won't get blocked.

🔧 Technical Details

These sections are for server admins who want to know exactly what's happening under the hood.

🔌 Developer API

Want to integrate with AtomGuard or build on top of it? There's a full API available.

<dependency>
    <groupId>com.atomguard</groupId>
    <artifactId>AtomGuard-api</artifactId>
    <version>1.2.2</version>
    <scope>provided</scope>
</dependency>

// Check an IP's reputation score
IReputationService rep = AtomGuardAPI.getInstance().getReputationService();
int score = rep.getScore(player.getAddress().getAddress());

// Enable or disable a module at runtime
IModuleManager modules = AtomGuardAPI.getInstance().getModuleManager();
modules.setEnabled("bot-koruma", false);

// Access trust scores, forensics, and intelligence
AtomGuardAPI.getInstance().getTrustScoreManager();
AtomGuardAPI.getInstance().getForensicsManager();
AtomGuardAPI.getInstance().getIntelligenceEngine();

// Listen for events
@EventHandler
public void onExploitBlocked(ExploitBlockedEvent event) {
    String module = event.getModuleName();
    Player player  = event.getPlayer();
}

❓ FAQ

Will this slow down my server? Nope. AtomGuard is designed to be lightweight. Heavy operations like VPN lookups and logging happen on separate threads so your server's performance isn't affected.

Will it block my regular players? Very unlikely. The VPN system requires 2 out of 7 providers to agree before blocking, and the bot detection uses a scoring system — not a simple on/off switch. Players using legitimate clients will pass through without noticing.

Does it work with cracked / offline-mode servers? Yes, but some features like Mojang account verification won't apply. Bot detection, DDoS protection, and exploit fixes work regardless of online/offline mode.

Can I use just the Velocity module or just the Core plugin? Absolutely. They work independently. Use both together for maximum protection, or just the one you need.

How do I update? Just replace the jar file and restart. AtomGuard automatically migrates your config to the new version and creates a backup of the old one.

I'm getting false positives — players are being blocked incorrectly. Try adjusting the bot detection threshold in your config, or add trusted IPs to the whitelist. The default settings are tuned for most servers, but every community is different.

Where do I get help? Open an issue on GitHub — we're happy to help!

📂 GitHub · 🐛 Report a Bug · 🤝 Contribute

Made with ❤️ by ATOMLAND Studios