---

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

Tier	Who	What Happens
🆕 New	Just joined	Full security checks
📅 Regular	Been around a while	Standard checks
✅ Trusted	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 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.

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

See the 7 providers

#	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

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

Connection Protection

• SYN Flood Detector — blocks IPs exceeding the connection threshold per second
• Slowloris Detector — identifies slow-drip connection drain attacks
• Traffic Anomaly Detector — Z-score, slow-ramp, and pulse attack detection
• Connection Fingerprinter — protocol + hostname + timing fingerprint to detect bot armies
• Subnet Analyzer — coordinated botnet detection at /24 and /16 level
• Sliding-Window Rate Limits — enforced at per-IP, per-subnet, and global levels
• Verified Player Shield — 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

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

Integration	What it does
MySQL + HikariCP	Persistent database storage with connection pooling
Redis Pub/Sub	Sync bans, threat data, and trust scores across your entire network
Discord Webhooks	Get instant Discord notifications when attacks happen
Web Panel	Browser-based dashboard with live stats
Config Migration	Automatic config upgrades when you update — with backups
Async Logging	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

Maven Dependency

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

Quick Examples

// 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 GitHub — we're happy to help!

---