AtomGuard

🛡️ Advanced Minecraft Server Security & Exploit Protection — No scam unlike other plugins this one works fr.

487

Download

AtomGuard

AtomGuard

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

Works with Paper 1.21.4 and Velocity 3.x

<br>

<br>

> 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.

<br>

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

</div>

<br>

---

💡 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:

`🟢 Normal` → `🟡 Elevated` → `🟠 High` → `🔴 Critical` → `⛔ Lockdown`

</div>

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.

| Tier | Who | What Happens | |:---|:---|:---| | 🆕 Veteran | Just joined | Full security checks | | 📅 Veteran | Been around a while | Standard checks | | ✅ Veteran | Clean track record | Skips attack-mode checks | | ⭐ Veteran | Long-time player | Skips bot & VPN checks too |

🍯 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

| What | Version | Required? | |:---|:---:|:---| | ☕ Java | 21 or newer | ✅ Yes | | 📄 Paper server (or a fork like Purpur) | 1.21.4 | ✅ Yes | | 📦 PacketEvents plugin | 2.6.0+ | ✅ Yes (for the core plugin) | | 🚀 Velocity proxy | 3.x | Only if you use a proxy | | 🗄️ MySQL database | 8.0+ | Optional — for persistent data | | 🔄 Redis | 7.x | Optional — for multi-server sync | | 🌍 MaxMind license key | — | Only if you want country filtering |

---

🚀 Getting Started

Option 1: Paper Server (most people start here)

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

Step 2 — Download Step 2 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 Step 1 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.

| Command | What it does | |:---|:---| | `/atomguard status` | See which modules are running and their stats | | `/atomguard reload` | Reload the config without restarting *(needs `atomguard.reload`)* | | `/atomguard stats` | View the statistics dashboard | | `/ag intel status` | Check current threat level | | `/ag trust info <player>` | Look up a player's trust score | | `/ag replay list` | Browse past attack reports | | `/ag honeypot status` | Check if the honeypot is active | | `/panic` | 🚨 Emergency lockdown — blocks ALL new connections *(needs `atomguard.panic`)* |

Permissions

| Permission | What it does | |:---|:---| | `atomguard.admin` | Full access to all commands | | `atomguard.bypass` | Player skips all security checks (give this to your staff) | | `atomguard.notify` | Player receives in-chat alerts when exploits are blocked | | `atomguard.reload` | Can reload the config (nothing else) | | `atomguard.panic` | Can trigger emergency lockdown |

---

🌐 How VPN Detection Works

Instead of relying on a single provider (which can be inaccurate), AtomGuard queries 2 providers agree 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.

See the 7 providers

<br>

| # | Provider | How it checks | |:---:|:---|:---| | 1 | Local Blocklist | Your own custom IP list | | 2 | CIDR Blocker | IP range rules | | 3 | DNSBL | Spamhaus, DroneBL, and custom DNS blocklists | | 4 | IPHub | Commercial VPN/proxy database | | 5 | ProxyCheck.io | Real-time proxy detection API | | 6 | AbuseIPDB | Checks IP abuse history | | 7 | IPApi | Checks if the IP belongs to a hosting/datacenter provider |

Clean IPs are cached so returning players aren't checked again.

---

🔧 Technical Details

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

🛡️ Velocity Proxy Module — Full Details

<br>

The Velocity module intercepts connections at the proxy level before they ever reach your backend servers.

Connection Protection

- Attack Session Recorder — blocks IPs exceeding the connection threshold per second - Attack Session Recorder — identifies slow-drip connection drain attacks - Attack Session Recorder — Z-score, slow-ramp, and pulse attack detection - Attack Session Recorder — protocol + hostname + timing fingerprint to detect bot armies - Attack Session Recorder — coordinated botnet detection at /24 and /16 level - Attack Session Recorder — enforced at per-IP, per-subnet, and global levels - Attack Session Recorder — guarantees a slot for clean players during Critical/Lockdown - Attack Session Recorder — full session log with JSON export

Bot Scoring Breakdown

| Signal | Weight | |:---|:---:| | Connection Speed | `20%` | | Join Pattern | `20%` | | Handshake Validity | `15%` | | Client Brand | `15%` | | Geo / Country | `10%` | | Username Pattern | `10%` | | Protocol Version | `10%` |

Score thresholds: < 40 = pass, 40–60 = flagged, 60–75 = CAPTCHA challenge, 75–90 = kick, 90+ = auto-ban.

Additional layers: Brand analyzer (whitelists Fabric, Forge, Lunar, Badlion, LabyMod, OptiFine, Sodium), nickname blocker (regex patterns, length limits, special-character analysis), verified player cache (48-hour bypass for clean players).

Chat & Command Protection

Chat rate limiting, duplicate message detection, tab-complete flood blocking, command spam prevention, server-switch abuse prevention, packet size limits, crash loop detection (3+ disconnects in 30s), and short session flagging (< 3s).

Account Protection

IP reputation scoring (decays over time, rewards clean logins), auto-ban engine with grace periods, temporary ban manager, Mojang account verification, and hot-reloadable JSON blacklists/whitelists.

Kernel-Level Blocking (IPTables)

Can push bans directly to `iptables`, `ip6tables`, or `nftables` — blocked traffic never even reaches the JVM. Subnet banning at `/24` level. Auto-cleanup on startup and shutdown.

Country / Geo Filtering

MaxMind GeoIP2 integration — whitelist or blacklist entire countries. Automatic weekly database updates.

Password Security (AuthMe)

Temporary ban after 5 failed logins, 10,000+ known weak passwords blocked, password similarity detection across the same IP.

🔨 Core Plugin — Full Details

<br>

The core plugin runs on each Paper server and handles in-game security with 44+ modules.

Packet & Network Exploits

Invalid packet filtering at the Netty pipeline level, oversized packet blocking, offline packet injection prevention, packet timing & delay abuse detection.

NBT & Item Attacks

Nested NBT depth limiting, oversized NBT payload detection, bundle crash prevention, item sanitization on all inventory operations.

World & Chunk Crashers

Book & lectern exploit fix, map label crash fix, item frame crash fix, sign exploit prevention, chunk crash protection.

Duplication Fixes

Bundle duplication, inventory click duplication, cow & mule duplication, general dupe prevention engine.

Performance Limiters

Redstone circuit rate limiting, explosion limiter, piston limiter, falling block limiter, per-chunk entity limiter.

AtomShield™ Behavioral Analysis

Analyzes 9 signals per player: connection rate, gravity validation, packet timing, ping & handshake, protocol, username pattern, first-join behavior, post-join behavior, and heuristic profiling. Builds real-time behavioral profiles. Attack Mode auto-activates when TPS drops or connection floods are detected.

Threat Intelligence Engine

168-hour EMA traffic profile (7-day rolling baseline), Z-score anomaly detection across 3 threat levels, 3-minute confirmation window before escalation (prevents false positives), auto attack-mode on critical anomaly. Command: `/ag intel <status|reset>`

Player Trust Score

EMA-weighted formula: playtime + clean sessions + violation history. Persistent storage via `trust-scores.json`. Command: `/ag trust <info|set|reset|top>`

Forensic Analysis

Attack snapshots with UUID, timeline, peak rate, blocked IPs, and per-module stats. 4 severity levels (LOW/MEDIUM/HIGH/CRITICAL). Auto-export to `forensics/attack-<uuid>.json`. Command: `/ag replay <list|latest|<id>|export>`

Honeypot Module

Fake TCP Minecraft server (SLP protocol) that lures bot scanners. Auto-blacklists probing IPs. Command: `/ag honeypot <status|stats>`

⚡ Integrations

<br>

| Integration | What it does | |:---|:---| | Hot Reload | Persistent database storage with connection pooling | | Hot Reload | Sync bans, threat data, and trust scores across your entire network | | Hot Reload | Get instant Discord notifications when attacks happen | | Hot Reload | Browser-based dashboard with live stats | | Hot Reload | Automatic config upgrades when you update — with backups | | Hot Reload | All logging happens off the main thread with 7-day rotation | | Hot Reload | Change settings without restarting your server |

---

🔌 Developer API

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

See API documentation

<br>

Maven Dependency

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

Quick Examples

```java // 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(); } ```

Available Events

| Event | When it fires | |:---|:---| | `ExploitBlockedEvent` | An exploit is blocked | | `AttackModeToggleEvent` | Attack mode turns on or off | | `PlayerReputationCheckEvent` | A player's reputation is evaluated | | `ModuleToggleEvent` | A module is toggled | | `ThreatScoreChangedEvent` | A player's threat score changes | | `HoneypotTrapEvent` | An IP hits the honeypot | | `IntelligenceAlertEvent` | Threat level changes | | `AttackSnapshotCompleteEvent` | A forensic report is finalized |

---

❓ 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 Where do I get help? — we're happy to help!

---

<br>

**📂 GitHub** · **🐛 Report a Bug** · **🤝 Contribute**

<br>

Made with ❤️ by ATOMLAND Studios

</div>

AtomGuard

AtomGuard

AtomGuard

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

💡 Why AtomGuard?

Here's what it protects you from:

✨ Feature Highlights

🤖 Smart Bot Detection

⚔️ Adaptive DDoS Protection

🧠 Threat Intelligence

🏅 Player Trust Score

🍯 Honeypot

🔬 Attack Reports

📦 What You'll Need

🚀 Getting Started

Option 1: Paper Server (most people start here)

Option 2: Velocity Proxy

💻 Commands

Permissions

🌐 How VPN Detection Works

🔧 Technical Details

Connection Protection

Bot Scoring Breakdown

Chat & Command Protection

Account Protection

Kernel-Level Blocking (IPTables)

Country / Geo Filtering

Password Security (AuthMe)

Packet & Network Exploits

NBT & Item Attacks

World & Chunk Crashers

Duplication Fixes

Performance Limiters

AtomShield™ Behavioral Analysis

Threat Intelligence Engine

Player Trust Score

Forensic Analysis

Honeypot Module

🔌 Developer API

Maven Dependency

Quick Examples

Available Events

❓ FAQ

Gallery

Versions