Aluer ServerGuard V5.0
AI-Powered Minecraft PaperMC Server Protection System
Quick Start •
Architecture •
Modules •
Meteor Coverage •
Deployment •
中文
---
## Overview
Aluer ServerGuard is a **next-generation intelligent security system** for Minecraft PaperMC servers. It employs a revolutionary **Agent Architecture** — a lightweight Paper plugin collects data from inside the server process, while an external Spring Boot analysis engine runs independently. The two communicate via **real-time bidirectional WebSocket**.
### Core Capabilities
| Capability | Description |
|---|---|
| **Full Anti-Cheat** | 100% coverage of all Meteor Client hack modules with real-time detection |
| **AI Decision Engine** | DeepSeek LLM auto-analysis → defense strategy → auto-execution (ban/kick/whitelist) |
| **ML Behavioral Analysis** | Isolation Forest anomaly detection + Time series prediction + Shannon entropy profiling + FFT analysis |
| **DDoS Multi-Layer Defense** | SYN/UDP/ICMP/HTTP/Slowloris/Minecraft protocol DDoS coordinated defense |
| **Server Self-Healing** | TPS/CPU/Memory anomaly auto-recovery, DDoS Under Attack mode auto-activation |
| **Dual-Mode Deployment** | Agent Plugin mode (recommended) + External RCON monitoring mode |
| **135+ Security Modules** | Anti-cheat · Network · Host · IDS · Forensics · Compliance |
---
## Quick Start
### One-Command Deploy
```bash
wget https://github.com/ZpjDev/Aluer/releases/latest/download/serverguard.jar
java -jar serverguard.jar
# Web Console: http://localhost:8080
```
### Agent Plugin Mode (Production)
```bash
# 1. Start ServerGuard engine
java -jar serverguard.jar
# 2. Copy JAR to Paper plugins/
cp serverguard.jar /opt/minecraft/plugins/AluerServerGuard.jar
# 3. Agent config
echo "server-url: ws://localhost:8080/agent" > /opt/minecraft/plugins/AluerServerGuard/config.yml
# 4. Start Paper — Agent auto-connects
cd /opt/minecraft && java -Xms4G -Xmx4G -jar paper-1.21.11.jar nogui
```
---
## Architecture
```
┌────────────┐ WebSocket ┌─────────────────────────────────────┐
│ PaperMC │◄═══════════════►│ ServerGuard Engine │
│ Server │ │ Spring Boot :8080 │
│ │ Agent → Server │ ┌──────────┐ ┌──────┐ ┌─────────┐ │
│ ┌────────┐ │ EVENT/METRICS/ │ │ 135+ │ │ ML/AI│ │ Web │ │
│ │ Agent │ │ ALERT/HEARTBEAT │ │ Security │ │Engine│ │ Console │ │
│ │ Plugin │ │ │ │ Modules │ │ │ │ │ │
│ │9 Event │ │ Server → Agent │ └──────────┘ └──────┘ └─────────┘ │
│ │Listenrs│ │ COMMAND/CONFIG │ ┌──────────┐ ┌──────────────────┐ │
│ └────────┘ │ │ │ DeepSeek │ │ Kernel Autonomy │ │
│ │ │ │ AI │ │ Engine │ │
│ Bukkit │ │ └──────────┘ └──────────────────┘ │
│ API │ │ ┌────────────────────────────────┐ │
└────────────┘ │ │ AutoExecutor → AgentDispatcher │ │
│ │ ban/kick/whitelist/clearlag │ │
└──┴────────────────────────────────┘ │
```
**Message Types (Agent → Server):** `EVENT` · `METRICS` · `ALERT` · `HEARTBEAT` · `HANDSHAKE` · `COMMAND_RESULT`
**Command Types (Server → Agent):** `BAN_IP` · `BAN_PLAYER` · `KICK` · `CLEAR_LAG` · `SET_SPAWN_RATE` · `ENABLE_WHITELIST` · `BROADCAST` · `SAVE_ALL` · `EXECUTE`
---
## Security Modules
### Anti-Cheat — 100% Meteor Client Coverage
Combat（16 modules）
`AntiKillAura` · `AntiReach` · `AntiAutoClicker` · `AntiCriticals` · `AntiAutoCrystal` · `AntiAutoTotem` · `AntiSurround` · `AntiAutoTrap` · `AntiAutoArmor` · `AntiChestSwap` · `AntiAutoLog` · `AntiHitboxes` · `AntiBowAimBot` · `AntiVelocity` · `AntiAnchor`
Movement（19 modules）
`AntiFly` · `AntiSpeed` · `AntiJesus` · `AntiNoFall` · `AntiTimer` · `AntiPhase` · `AntiBlink` · `AntiScaffold` · `AntiSpider` · `AntiStep` · `AntiNoSlow` · `AntiPacketFly` · `AntiAirJump` · `AntiLongJump` · `AntiAntiHunger` · `AntiFastFall` · `AntiVClip` · `AntiElytraFly`
World / Player（13 modules）
`AntiNuker` · `AntiAutoMine` · `AntiSpeedMine` · `AntiFastBreak` · `AntiFastUse` · `AntiNoInteract` · `AntiVeinMiner` · `AntiAutoTool` · `AntiAutoFish` · `AntiChestSteal` · `AntiXray` · `AntiBaritone` · `AntiGrief`
Misc（9 modules）
`AntiDupe` · `AntiFakePlayer` · `AntiPistonAura` · `AntiStashFinder` · `AntiInventoryManipulation` · `AntiNameSpoof` · `AntiSkinSpoof` · `AntiAltAccount` · `AntiOfflineModeSpoof`
### Server Exploit Protection
`AntiSignExploit` · `AntiBookBan` · `AntiResourcePackExploit` · `AntiTabCompleteCrash` · `CrashExploitProtection` · `CrashExploitSignatureDB` · `LagMachineDetection` · `PacketFloodProtection`
### Network Protocol Security
`ProtocolStateValidator` · `TokenBucketRateLimiter` · `BotFingerprintDetector` · `NBTExploitPrevention` · `ConnectionHandshakeValidator` · `DDoSProtection` · `DDoSDefenseCoordinator`
### Server Performance Protection
`ChunkLoadRateLimiter` · `EntityCountEnforcer` · `RedstoneUpdateLimiter`
### Chat & Social Security
`ChatFloodProtection` · `AntiAdvertisement` · `AntiPhishingLink` · `AntiCommandAbuse` · `PlayerPrivacy`
### ML/AI Behavioral Analysis
`BehavioralProfilingEngine` (5D features · Shannon entropy · Z-score · 6 profiles) · `ThreatScoreAggregator` (exponential decay · 4-tier escalation · EMA) · `MovementPatternAnalyzer` (FFT · rotation smoothness · saccadic analysis) · `CombatPatternRecognizer` (CPS variance · multi-target entropy · hit ratio) · `AnomalyDetector` (Isolation Forest) · `TimeSeriesPredictor`
### Defense-in-Depth & Host Security (30+ modules)
WAF · IDS · IPS · SIEM · Honeypot · EDR · ZeroTrust · JWT · SSL/TLS · GeoBlock · VPN Detection · DNS Tunnel · ARP Spoof · ReverseShell · Process Injection · File Integrity · Backdoor Plugin Scanner · Compliance · Forensics · Threat Hunting · Incident Response · Security Baseline · Container Security
---
## Meteor Client Coverage Matrix
| Category | Meteor Hacks | Aluer Counter-Modules | Coverage |
|----------|-------------|----------------------|----------|
| Combat | 15 | 16 | **100%** |
| Movement | 18 | 19 | **100%** |
| World | 12 | 13 | **100%** |
| Player | 5 | 9 | **100%** |
| Misc | 5 | 9 | **100%** |
| **Total** | **55** | **66** | **100%** |
---
## Deployment
### Mode Comparison
| Feature | Agent Plugin | External |
|---------|-------------|----------|
| Communication | WebSocket | RCON + Log |
| Latency | < 1ms (local) | RCON-dependent |
| Event Throughput | 50,000+ events/s | 10,000+ events/s |
| MC Invasiveness | Paper plugin required | Zero invasion |
| Memory (plugin) | ~50MB | 0 |
| Recommended For | **Production** | Monitoring/Evaluation |
### External Mode
```bash
# Enable RCON in server.properties
enable-rcon=true
rcon.port=25575
rcon.password=STRONG_PASSWORD
# Start ServerGuard
java -jar serverguard.jar
```
---
## Environment Variables
| Variable | Description | Default |
|----------|-------------|---------|
| `SERVERGUARD_MODE` | Run mode (plugin/external) | `external` |
| `DEEPSEEK_API_KEY` | DeepSeek AI API key | (empty = disabled) |
| `DEEPSEEK_BASE_URL` | DeepSeek API URL | `https://api.deepseek.com` |
| `DEEPSEEK_MODEL` | DeepSeek model name | `deepseek-chat` |
| `RCON_PASSWORD` | Minecraft RCON password | (empty) |
---
## WebSocket Protocol
All messages are single-line JSON over WebSocket text frames.
**Agent → Server (event):**
```json
{"type":"EVENT","agentId":"survival-01","timestamp":1715000000000,
"payload":{"eventType":"PLAYER_MOVE","playerName":"Steve","x":100.5,"y":64.0,"z":200.3}}
```
**Server → Agent (command):**
```json
{"type":"COMMAND","requestId":"550e8400-...","timestamp":1715000001000,
"payload":{"command":"KICK","target":"Hacker123","reason":"KillAura 94%"}}
```
---
## In-Game Commands
| Command | Permission | Description |
|---------|-----------|-------------|
| `/aluer status` | `aluer.status` | Protection status, TPS, players |
| `/aluer scan ` | `aluer.admin` | Deep player scan |
| `/aluerplayers` | `aluer.status` | Online player list with risk flags |
| `/aluerblock player ` | `aluer.admin` | Ban player |
| `/aluerblock ip ` | `aluer.admin` | Ban IP |
| `/aluerwhitelist on/off` | `aluer.admin` | Emergency whitelist |
---
## Build & Test
```bash
./apache-maven-3.9.6/bin/mvn compile # Compile
./apache-maven-3.9.6/bin/mvn test # 323 tests
./apache-maven-3.9.6/bin/mvn package -DskipTests # Build JAR
```
| Metric | Value |
|--------|-------|
| Source Files | 225 |
| Code Lines | 73,229 |
| Test Files | 19 |
| Test Cases | 323 |
| Test Result | **323/323 PASS, 0 failures** |
---
## Tech Stack
| Technology | Version | Purpose |
|-----------|---------|---------|
| Java | 21 | Core language |
| Spring Boot | 3.2.0 | Framework · Web · WebSocket · Mail · Shell |
| PaperMC API | 1.21.1-R0.1-SNAPSHOT | Minecraft integration |
| Apache Commons Math3 | 3.6.1 | Statistics · ML |
| Gson | 2.10.1 | JSON serialization |
| React 19 + Vite 6 | — | Web console |
---
## FAQ
Agent vs External mode?
Agent Plugin mode is recommended for production — zero latency, 50K+ events/s. External mode for evaluation or plugin-free setups.
Is DeepSeek AI required?
No. Without `DEEPSEEK_API_KEY`, AI auto-disables and the system falls back to rule engine + ML mode with full anti-cheat capabilities.
What Java version?
Java 21+. Paper 1.21.1 API (class version 65) requires Java 21 runtime.
---
## Version History
| Version | Date | Key Updates |
|---------|------|-------------|
| **V5.3** | 2026-05 | Meteor World/Player countermeasures |
| **V5.2** | 2026-05 | Meteor Movement countermeasures |
| **V5.1** | 2026-05 | Meteor Combat countermeasures |
| **V5.0** | 2026-04 | Agent WebSocket architecture · AI/ML engine |
| **V4.0** | 2026-03 | Core anti-cheat modules |
---
## License
Proprietary. All rights reserved.
Aluer ServerGuard — Protecting Every Minecraft Server