Peijun Zhao
c8a1037f9e
- README.md/EN: 架构图、模块清单、双模式部署、WebSocket协议、75种告警类型 - docs/DEVELOPER.md: 五核心设计模式、七步添加新模块模板、事件监听器、Agent协议 - docs/PROJECT_SUMMARY.md: 模块统计、100% Meteor Client覆盖矩阵、竞品对比 - docs/USER_MANUAL.md: 安装、配置详解、CLI命令、Web控制台、性能调优、故障排查
48 KiB
48 KiB
Aluer ServerGuard V5.0
AI-Powered Comprehensive Protection System for Minecraft PaperMC Servers
Project Overview
Aluer ServerGuard is a next-generation intelligent security protection system designed for Minecraft PaperMC servers. The system features an Agent architecture with a lightweight Paper plugin serving as the data collection frontend, paired with an external Spring Boot analysis engine, delivering comprehensive real-time server protection.
Key Features:
- AI Behavioral Analysis: Anomaly detection based on Isolation Forest and time series prediction
- DeepSeek LLM Integration: Automated security alert analysis and defense strategy generation
- Full Anti-Cheat Coverage: Countermeasures against every hack module in Meteor Client and similar cheat clients
- Server Self-Healing: Automatic recovery from TPS/CPU/Memory anomalies, built-in DDoS defense
- Dual-Mode Deployment: Plugin embedded mode and External monitoring mode
- 135+ Security Modules: Covering anti-cheat, network security, host security, intrusion detection, and forensic analysis
Version History
| Version | Date | Key Updates |
|---|---|---|
| V5.3 | 2026-05 | Meteor Client world/player/misc countermeasures: SpeedMine, FastUse, NoInteract, AutoMine, VeinMiner, AutoTool, FakePlayer, PistonAura, Anchor, StashFinder |
| V5.2 | 2026-05 | Meteor Client movement countermeasures: NoSlow, Spider, Step, PacketFly, AirJump, LongJump, AntiHunger, FastFall, VClip |
| V5.1 | 2026-05 | Meteor Client combat countermeasures: Criticals, AutoTotem, Surround, AutoTrap, AutoCrystal, AutoArmor, ChestSwap, AutoLog, Hitboxes, BowAimbot |
| V5.0 | 2026-04 | Agent architecture refactoring, WebSocket real-time communication, Timer/Velocity/Phase/Blink/FastBreak/ElytraFly anti-cheat |
| V4.0 | 2026-03 | KillAura/Reach/Speed/Jesus/NoFall/Scaffold/Nuker/AutoClicker anti-cheat, player behavior, server protection |
Architecture
+---------------------------------------------------------------------+
| Aluer ServerGuard System Architecture |
+---------------------------------------------------------------------+
| |
| +------------------+ WebSocket +----------------+ |
| | PaperMC Server | <========================> | ServerGuard | |
| | | ws://host:8080/agent | Spring Boot | |
| | +------------+ | | +----------+ | |
| | | AluerPlugin| | EVENT ---------------> | | Security | | |
| | | (Agent) | | METRICS --------------> | | Modules | | |
| | | | | ALERT -----------------> | | (135+) | | |
| | | Bukkit | | HEARTBEAT -------------> | +----------+ | |
| | | Events | | | +----------+ | |
| | +------------+ | <-------- COMMAND ----- | | ML/AI | | |
| | | <-------- CONFIG ------ | | Engine | | |
| | Event Listeners | | +----------+ | |
| | + Combat | | +----------+ | |
| | + Block | | | DeepSeek | | |
| | + Movement | | | Analysis | | |
| | + Inventory | | +----------+ | |
| | + Chat | | +----------+ | |
| | + Command | | | Web | | |
| | + Entity | | | Dashboard | | |
| | + Packet | | +----------+ | |
| | + World | +----------------+ |
| +------------------+ | |
| | |
| +------------v-------+ |
| | Self-Healing | |
| | Shield / Kernel | |
| | Autonomy Engine | |
| +--------------------+ |
+---------------------------------------------------------------------+
Communication Protocol: All messages are single-line JSON transmitted via WebSocket text frames in both directions.
Agent-to-Server message types:
EVENT-- Bukkit event data (player movement, combat, block operations, etc.)METRICS-- Server metrics (TPS, CPU, Memory, online player count)ALERT-- Security alertsHEARTBEAT-- Keep-alive heartbeatHANDSHAKE-- Initial connection handshakeCOMMAND_RESULT-- Command execution acknowledgment
Server-to-Agent command types:
COMMAND-- Execute action (BAN_IP, BAN_PLAYER, KICK, CLEAR_LAG, etc.)CONFIG-- Dynamic configuration updateSHUTDOWN-- Close connection
Technology Stack
| Technology | Version | Purpose |
|---|---|---|
| Java | 21 | Core language |
| Spring Boot | 3.2.0 | Application framework |
| Maven | 3.9.6 | Build management |
| PaperMC API | 1.21.1-R0.1-SNAPSHOT | Minecraft server API |
| Spring WebSocket | 3.2.0 | Agent communication |
| Spring Mail | 3.2.0 | Email alerts |
| Spring Shell | 3.1.3 | CLI interaction |
| SnakeYAML | 2.2 | YAML configuration |
| Smile | 2.6.0 | Machine learning algorithms |
| Apache Commons Math | 3.6.1 | Math/statistics |
| Gson | (embedded) | JSON serialization |
Complete Security Module Inventory
I. Anti-Cheat -- Combat (15 modules)
| Module | Hack Detected | Detection Method |
|---|---|---|
| AntiKillAuraService | KillAura | Multi-target switching, aimbot angle consistency, max-range attack patterns |
| AntiReachService | Reach | Attack distance validation, position backtracking |
| AntiSpeedService | Speed | Horizontal movement speed anomaly analysis |
| AntiCriticalsService | Criticals | Zero-velocity crits, no-jump crits, crit rate statistics |
| AntiAutoCrystalService | AutoCrystal | Crystal placement/detonation speed, optimal position calculation detection |
| AntiAutoTotemService | AutoTotem | Totem re-equip speed (ms-level), consecutive totem usage pattern |
| AntiSurroundService | Surround | Four-direction block placement speed, defensive block pattern recognition |
| AntiAutoTrapService | AutoTrap | Target player cage construction speed, piston trap automation |
| AntiAutoArmor | AutoArmor | Multi-slot armor switching speed, backpack scan pattern |
| AntiChestSwap | ChestSwap | Chestplate/elytra swap tick-level detection |
| AntiAutoLog | AutoLog | Post-damage disconnect pattern, low-HP disengagement detection |
| AntiHitboxes | Hitboxes | Edge hit rate, ray trace distance distribution analysis |
| AntiBowAimbot | BowAimbot | Moving target hit rate, trajectory consistency, instant precision |
| AntiVelocityService | Velocity | Knockback magnitude anomaly, anti-knockback detection |
| AntiAutoClickerService | AutoClicker | CPS statistics, click interval entropy analysis |
II. Anti-Cheat -- Movement (18 modules)
| Module | Hack Detected | Detection Method |
|---|---|---|
| AntiFlyDetectionService | Fly | Vertical/horizontal velocity, hover duration, movement pattern analysis |
| AntiJesusService | Jesus | Water/lava surface movement validation |
| AntiNoFallService | NoFall | Landing detection, fall damage validation |
| AntiSpeedService | Speed | Horizontal movement speed anomaly analysis |
| AntiTimerService | Timer | Game tick interval anomaly, movement speed frequency analysis |
| AntiPhaseService | Phase | Block clipping/penetration detection, solid block pass-through validation |
| AntiBlinkService | Blink | Rapid disconnect damage evasion detection |
| AntiSpiderService | Spider | Non-climbable block wall movement, vertical wall movement detection |
| AntiStepService | Step | Full-block step-up without jump detection |
| AntiNoSlowService | NoSlow | Item-use movement speed detection (eating/bow/shield) |
| AntiPacketFlyService | PacketFly | Packet manipulation flight, oscillation patterns, never-landing detection |
| AntiAirJumpService | AirJump | Mid-air jump packet detection, consecutive aerial jumps |
| AntiLongJump | LongJump | Extreme horizontal jump distance detection |
| AntiAntiHunger | AntiHunger | Zero hunger consumption under high activity detection |
| AntiFastFall | FastFall | Above-terminal-velocity falling detection |
| AntiVClip | VClip | Instant vertical block penetration (excluding legitimate teleport) |
| AntiElytraFlyService | ElytraFly | Elytra speed/altitude manipulation detection |
| AntiScaffoldService | Scaffold | Block placement frequency/angle/speed pattern analysis |
III. Anti-Cheat -- World/Player/Misc (19 modules)
| Module | Hack Detected | Detection Method |
|---|---|---|
| AntiNukerService | Nuker | Mining speed/range/pattern recognition |
| AntiAutoMineService | AutoMine | Automated mining behavior detection |
| AntiSpeedMineService | SpeedMine | Accelerated mining (InstaMine/PacketMine) detection |
| AntiFastBreakService | FastBreak | Block breaking speed anomaly detection |
| AntiFastUseService | FastUse | Item use acceleration detection |
| AntiNoInteractService | NoInteract | Interaction bypass detection |
| AntiVeinMinerService | VeinMiner | Automated vein mining pattern detection |
| AntiAutoTool | AutoTool | Instant tool switching detection |
| AntiAutoFishService | AutoFish | Fishing behavior timing/reaction speed analysis |
| AntiChestStealService | ChestSteal | Container open/loot speed pattern recognition |
| AntiInventoryManipulationService | InventoryManipulation | Inventory operation speed, illegal slot operation detection |
| AntiBaritoneService | Baritone | Path smoothness/behavior repetition analysis |
| AntiXrayDetectionService | Xray | Diamond ratio/straight-line mining/dark-precision detection |
| AntiGriefDetectionService | Grief | Block destruction rate/TNT/arson/chest theft detection |
| AntiFakePlayer | FakePlayer | Fake player entity detection |
| AntiPistonAura | PistonAura | Piston trap automation detection |
| AntiAnchor | Anchor | Hole anchor defense detection |
| AntiStashFinder | StashFinder | Automated storage cache scanning detection |
| AntiDupeDetectionService | AntiDupe | Item duplication detection (stack anomaly, 9 duplication methods) |
IV. Server Exploit Protection (12 modules)
| Module | Protection Target |
|---|---|
| AntiSignExploitService | Sign NBT exploits (oversized JSON, invalid components, NBT bombs) |
| AntiBookBanService | Book ban exploits (oversized pages, deep JSON nesting) |
| AntiResourcePackExploitService | Resource pack exploits (malicious URLs, oversized files, format validation) |
| AntiTabCompleteCrashService | Tab-complete crash (long text, deep nesting completion limits) |
| AntiOfflineModeSpoofService | Offline UUID spoofing (premium UUID conflicts, IP correlation) |
| CrashExploitProtectionService | Crash exploit protection (oversized packets, NBT bombs, book attacks) |
| CrashExploitSignatureDB | Crash exploit signature database (12 known signatures) |
| LagMachineDetectionService | Lag machine detection (observer chains, TNT stacks, redstone density) |
| ChunkLoadRateLimiter | Chunk load rate limiting (WARN/LIMIT/BLOCK 3-tier response) |
| EntityCountEnforcer | Entity count enforcement (per-chunk/player/type auto-removal) |
| RedstoneUpdateLimiter | Redstone update frequency limiting (degrade/freeze/exponential backoff) |
| PacketFloodProtectionService | Packet flood protection |
V. Chat & Social Security (5 modules)
| Module | Protection Target |
|---|---|
| ChatFloodProtectionService | Chat flood (frequency, similarity, length surges) |
| AntiAdvertisementService | Advertisement detection (IP/domain/group ID regex) |
| AntiPhishingLinkService | Phishing links (suspicious domains, short links, SSL verification) |
| AntiCommandAbuseService | Command abuse (rate limiting, sensitive command interception) |
| PlayerPrivacyService | Player privacy (IP anonymization, coordinate hiding, log anonymization) |
VI. Network Security (13 modules)
| Module | Protection Target |
|---|---|
| DDoSProtectionService | DDoS attacks (SYN/UDP/ICMP/HTTP/Slow connection/Amplification) |
| DDoSDefenseCoordinator | Multi-layer DDoS defense orchestration |
| ProtocolStateValidator | Protocol state machine (HANDSHAKE/STATUS/LOGIN/PLAY transitions) |
| BotFingerprintDetector | Bot fingerprint (login timing, naming patterns, movement entropy) |
| NBTExploitPrevention | NBT exploit prevention (depth/size limits) |
| ConnectionHandshakeValidator | Handshake validation (protocol version, hostname, ping flood, port scan) |
| PortScanDetectionService | Port scan detection |
| BruteForceProtectionService | Brute force protection (multi-window detection) |
| AntiVPNProxyService | VPN/proxy detection (known VPN IP database, hosting ASN matching) |
| DNSTunnelDetectionService | DNS tunnel detection (entropy, Base32 encoding, suspicious TLDs) |
| ReverseShellDetectionService | Reverse shell detection (50+ shell pattern matching) |
| ProcessInjectionDetectionService | Process injection detection |
| ARPSpoofDetectionService | ARP spoofing detection (MAC changes, gateway forgery) |
VII. Host & Access Control Security (6 modules)
| Module | Protection Target |
|---|---|
| FileIntegrityMonitorService | File integrity monitoring (hash baseline, real-time monitoring) |
| BackdoorPluginScannerService | Backdoor plugin scanning (known malicious class names, remote execution) |
| ConfigTamperDetectionService | Configuration tampering detection (ops/whitelist real-time monitoring) |
| OPPrivilegeMonitorService | OP privilege monitoring (privilege changes, sensitive command auditing) |
| AntiAltAccountService | Alt account detection (IP correlation, behavioral similarity, login patterns) |
| AntiNameSpoofService | Name spoofing detection (admin/famous player nickname forgery) |
VIII. Advanced Security Infrastructure (28 modules)
| Module | Function |
|---|---|
| PlayerSessionValidationService | Player session validation (UUID forgery, premium/offline detection) |
| PluginVerificationService | Plugin integrity verification (hash comparison, unauthorized modification) |
| BackupIntegrityService | Backup integrity verification (SHA-256, file count, size comparison) |
| ConnectionThrottleService | Connection rate limiting (IP/time window/incremental delay) |
| GeoBlockService | Geographic IP blocking (country/region filtering) |
| AntiSkinSpoofService | Skin spoofing detection (model data anomaly, skin URL detection) |
| JwtAuthService | JWT authentication and token management |
| AntiBotDetectionService | Anti-bot detection (name, join rate, IP correlation) |
| CSPEnforcementService | CSP security header enforcement (8 response headers) |
| SSRFProtectionService | SSRF protection (internal IP, cloud metadata, protocol restrictions) |
| XXEProtectionService | XXE protection (entity injection, Billion Laughs detection) |
| DatabaseFirewallService | Database firewall (SQL injection, UNION queries, time-based blind) |
| DataLossPreventionService | Data loss prevention (12 sensitive info rules, auto-masking) |
| MemoryProtectionService | JVM memory protection (heap/GC/memory leak detection) |
| SecureFileDeletionService | Secure file deletion (multi-pass overwrite, DoD standard) |
| ForensicsCollectorService | Forensic collection (process/network/log snapshots) |
| IncidentResponseService | Incident response (5 predefined response playbooks) |
| ThreatHuntingService | Threat hunting (10 hunt definitions, 5 categories) |
| ComplianceScannerService | Compliance scanning (7 categories, 20+ checks) |
| ExploitSignatureService | Exploit signature detection (Log4Shell, SQLi, RCE -- 15 types) |
| SecurityOrchestrationService | Multi-layer defense orchestration |
| SecurityAutomationScheduler | Security automation scheduling |
| HostEnforcementService | Host-level enforcement |
| HostIntrusionCountermeasureService | Host intrusion countermeasures |
| IntrusionDetectionService | Network intrusion detection |
| IntrusionPreventionSystem | Network intrusion prevention |
| WebApplicationFirewall | Web application firewall |
| ZeroTrustArchitectureService | Zero-trust architecture |
IX. Network & Traffic Analysis (10 modules)
| Module | Function |
|---|---|
| NetworkMonitorService | Network traffic monitoring |
| NetworkSnifferService | Network packet sniffing |
| NetworkThreatFusionService | Multi-source threat intelligence fusion |
| FlowAnalyzerService | Traffic behavior analysis |
| TrafficAnalysisService | Traffic pattern analysis |
| TrafficShapingService | Traffic shaping and QoS |
| PacketInspectionService | Deep packet inspection |
| ProtocolAnalysisService | Protocol anomaly analysis |
| TokenBucketRateLimiter | Reusable token bucket rate limiting primitive |
| FirewallService | System firewall management |
X. Infrastructure & Operations Security (8 modules)
| Module | Function |
|---|---|
| SIEMService | Security information and event management |
| LogAnalysisService | Log pattern analysis |
| LogCorrelationService | Cross-source log correlation |
| ThreatIntelligenceService | Threat intelligence aggregation |
| IPReputationService | IP reputation database queries |
| SSLTLSCertificateService | SSL/TLS certificate management |
| SecurityBaselineHardeningService | Security baseline hardening |
| ContainerSecurityService | Container runtime security |
XI. ML/AI Behavioral Analysis (4 modules)
| Module | Function |
|---|---|
| BehavioralProfilingEngine | Player behavioral profiling (statistical baseline modeling) |
| CombatPatternRecognizer | Combat pattern recognition (anomalous combat sequence detection) |
| MovementPatternAnalyzer | Movement pattern analysis (trajectory anomalies, path entropy) |
| ThreatScoreAggregator | Threat score aggregation (multi-dimensional threat fusion and escalation) |
Deployment Guide
Mode 1: Plugin Embedded Mode (Recommended)
ServerGuard runs directly inside the Minecraft server process as a Paper plugin, achieving zero network latency and maximum real-time performance.
Prerequisites:
- Minecraft PaperMC 1.21.1 server installed
- Java 21 runtime
- ServerGuard engine JAR compiled
Deployment Steps:
-
Build the plugin
cd /opt/AluerIII ./apache-maven-3.9.6/bin/mvn package -DskipTests -
Install plugin to Minecraft server
cp target/serverguard-4.0.0.jar /opt/minecraft/plugins/AluerServerGuard.jar -
Create plugin config at
plugins/AluerServerGuard/config.yml:server-url: ws://localhost:8080/agent -
Start ServerGuard engine (must start before Minecraft server)
java -jar target/serverguard-4.0.0.jar -
Start Minecraft server
cd /opt/minecraft java -Xms4G -Xmx4G -jar paper-1.21.11.jar
Upon startup, AluerPlugin will automatically connect to the ServerGuard engine via WebSocket and begin pushing Bukkit event data.
Mode 2: External Monitoring Mode
ServerGuard runs as an independent process, providing external protection via RCON and log monitoring. Suitable for scenarios where plugin installation is not desired.
Deployment Steps:
-
Build
./apache-maven-3.9.6/bin/mvn package -DskipTests -
Configure
application.ymlserverguard: mode: external minecraft: working-dir: /opt/minecraft rcon: enabled: true host: localhost port: 25575 password: "your_rcon_password_here" process-name: paper-1.21.11.jar -
Enable RCON in Minecraft
server.propertiesenable-rcon=true rcon.port=25575 rcon.password=your_rcon_password_here -
Start ServerGuard
java -jar target/serverguard-4.0.0.jar
Configuration Reference
Core Configuration (serverguard.*)
serverguard:
mode: ${SERVERGUARD_MODE:external} # plugin or external
minecraft:
service-name: minecraft
process-name: paper-1.21.11.jar
jar-file: paper-1.21.11.jar
working-dir: /opt/minecraft
java-opts: -Xms4G -Xmx4G
check-interval-seconds: 5
rcon:
enabled: true
host: localhost
port: 25575
password: ${RCON_PASSWORD:}
monitor:
tps-threshold: 15 # Alert when TPS falls below this value
cpu-threshold: 80.0 # Alert when CPU usage exceeds this value (%)
memory-threshold: 85.0 # Alert when memory usage exceeds this value (%)
connection-threshold: 50 # Alert when concurrent connections exceed this value
log-watch-lines: 100 # Number of log lines to monitor
log-path: /opt/minecraft/logs/latest.log
alert:
enabled: true
email:
smtp-host: smtp.qq.com
smtp-port: 587
username: ${ALUER_ALERT_SMTP_USERNAME:}
password: ${ALUER_ALERT_SMTP_PASSWORD:}
to:
- ${ALUER_ALERT_EMAIL_PRIMARY:}
- ${ALUER_ALERT_EMAIL_SECONDARY:}
rate-limit:
per-type-seconds: 300 # Minimum interval between same-type alerts (seconds)
max-emails-per-minute: 10 # Maximum emails per minute
AI Configuration (serverguard.ai.*)
ai:
enabled: true
use-isolation-forest: true # Enable Isolation Forest anomaly detection
use-prediction: true # Enable time series prediction
sliding-window-size: 100 # Analysis sliding window size
anomaly-threshold: 0.7 # Anomaly detection threshold (0-1)
prediction-horizon-minutes: 60 # Prediction horizon (minutes)
deepseek:
enabled: true
api-key: ${DEEPSEEK_API_KEY:}
base-url: ${DEEPSEEK_BASE_URL:https://api.deepseek.com}
model: ${DEEPSEEK_MODEL:deepseek-chat}
max-tokens: 1000
temperature: 0.35 # Analysis stability (0=precise, 1=creative)
auto-analyze-alerts: true # Automatically analyze alerts
analysis-interval-seconds: 45 # Analysis interval (seconds)
auto-execute:
enabled: true
ban-ip: true # Allow automatic IP banning
kill-entity: true # Allow automatic entity cleanup
clear-lag: true # Allow automatic lag clearing
set-spawn-rate: true # Allow automatic spawn rate adjustment
kick-player: true # Allow automatic player kicking
whitelist: true # Allow automatic whitelist enabling
min-confidence: 88 # Minimum confidence for auto-execution (%)
Security Configuration (serverguard.security.*)
security:
enabled: true
auto-ban-vpn: true
check-on-login: true
max-connections-per-ip: 3 # Maximum connections per IP
block-common-exploits: true
log-all-commands: true
minecraft-defense:
enabled: true
game-tcp-port: 25565
query-udp-port: 25565
rcon-tcp-port: 25575
status-ping-threshold: 25 # Status ping flood threshold
login-burst-threshold: 12 # Login burst threshold
bot-swarm-threshold: 15 # Bot swarm threshold
query-flood-threshold: 30 # Query flood threshold
rcon-brute-force-threshold: 5 # RCON brute force threshold
compression-payload-threshold: 8192 # Compression payload maximum
ddos-defense:
enabled: true
syn-flood-threshold: 100
udp-flood-threshold: 200
icmp-flood-threshold: 100
http-flood-threshold: 150
slow-connection-threshold: 150
amplification-threshold: 20
minecraft-status-threshold: 20
minecraft-login-threshold: 10
minecraft-rcon-threshold: 5
minecraft-query-threshold: 25
minecraft-bot-swarm-threshold: 12
anti-intrusion:
enabled: true
monitor-commands: true
monitor-processes: true
monitor-files: true
monitor-plugins: true
monitor-systemd: true
monitor-rcon: true
file-integrity:
enabled: true
max-depth: 5
monitored-paths:
- /opt/minecraft/plugins
- /opt/minecraft/server.properties
- /opt/minecraft/paper-1.21.11.jar
- /opt/minecraft/start.sh
- /etc/systemd/system/minecraft.service
host-enforcement:
enabled: true
dry-run: true # Dry-run mode (no actual blocking)
preferred-backend: auto # Backend: auto/iptables/nftables/firewalld
default-block-minutes: 60 # Default block duration (minutes)
default-rate-limit-per-minute: 120 # Default rate limit per minute
mirror-to-cloud-edge: true # Mirror to cloud edge
cloud-edge:
enabled: false
dry-run: true
provider: cloudflare
zone-id: ${ALUER_CLOUDFLARE_ZONE_ID:}
api-key: ${ALUER_CLOUDFLARE_API_KEY:}
api-email: ${ALUER_CLOUDFLARE_EMAIL:}
default-block-mode: block
default-challenge-mode: challenge
enable-under-attack-on-critical: true
orchestration:
enabled: true
allow-local-block: true
allow-edge-challenge: true
allow-minecraft-defense: true
notify-on-critical: true
automation:
enabled: true
feed-refresh-minutes: 15 # Threat intel refresh interval
posture-snapshot-minutes: 5 # Security posture snapshot interval
integrity-rescan-minutes: 30 # Integrity rescan interval
rule-sync-minutes: 10 # Rule sync interval
incident-retention-minutes: 120 # Incident retention period
autonomy:
enabled: true
deepseek-dominant: true # DeepSeek-dominant decision making
quiet-console: true # Quiet console mode
loop-interval-seconds: 45 # Autonomy loop interval
min-risk-score-for-action: 70 # Minimum risk score for action
critical-risk-score: 90 # Critical risk score
workflow-cooldown-seconds: 180 # Workflow cooldown
max-actions-per-hour: 12 # Maximum actions per hour
require-second-signal-for-containment: true # Require second signal for containment
shield:
enabled: true
auto-mode: true
auto-enable-under-attack: true
heat-trigger: 78 # Heat trigger threshold
resonance-trigger: 72 # Resonance trigger threshold
threat-score-trigger: 85 # Threat score trigger threshold
edge-challenge-offender-limit: 6 # Edge challenge offender limit
shelter-rate-limit-per-minute: 45 # Shelter rate limit per minute
attacker-notice-enabled: true
deterrence-message: "Your source has been identified, recorded, and isolated by Aluer."
kernel:
enabled: true
pulse-interval-seconds: 30 # Pulse interval
pulse-history-size: 180 # Pulse history size
journal-size: 300 # Journal size
echo-retention-minutes: 180 # Echo retention period
adaptive-weights: true # Adaptive weights
directive-heat-threshold: 60 # Directive heat threshold
lockdown-heat-threshold: 82 # Lockdown heat threshold
task-bus:
enabled: true
auto-dispatch: true
dispatch-interval-seconds: 10
queue-limit: 200
history-limit: 300
self-healing:
enabled: true
dry-run: true # Dry-run mode
loop-interval-seconds: 45
auto-backup-before-recovery: true # Auto-backup before recovery
auto-whitelist-on-swarm: true # Auto-whitelist on bot swarm
allow-soft-restart: true # Allow soft restart
tps-emergency-threshold: 12 # TPS emergency threshold
cpu-emergency-threshold: 92.0 # CPU emergency threshold (%)
memory-emergency-threshold: 95.0 # Memory emergency threshold (%)
max-recovery-actions-per-hour: 8 # Maximum recovery actions per hour
SuperEvolution Module Switches (serverguard.security.super-evolution.*)
super-evolution:
# === V4.0 Advanced Security Modules ===
jwt-auth: true # JWT authentication and token management
brute-force: true # Brute force protection (multi-window detection)
anti-bot: true # Anti-bot detection
reverse-shell: true # Reverse shell detection (50+ pattern matching)
arp-spoof: true # ARP spoofing detection
dns-tunnel: true # DNS tunnel detection (entropy/Base32/suspicious TLDs)
exploit-signature: true # Exploit signature detection (Log4Shell/SQLi/RCE -- 15 types)
ssrf: true # SSRF protection
xxe: true # XXE protection
csp: true # CSP security header enforcement
database-firewall: true # Database firewall
dlp: true # Data loss prevention (12 sensitive info rules)
memory-protection: true # JVM memory protection
process-injection: true # Process injection detection
secure-delete: true # Secure file deletion
forensics: true # Forensic collection
incident-response: true # Incident response (5 predefined playbooks)
threat-hunting: true # Threat hunting (10 hunt definitions)
compliance: true # Compliance scanning (7 categories, 20+ checks)
anti-grief: true # Anti-grief detection
# === Minecraft-Specific Protection ===
anti-xray: true # X-ray detection
anti-fly: true # Fly hack detection
anti-dupe: true # Item duplication detection (9 methods)
crash-exploit: true # Crash exploit protection
lag-machine: true # Lag machine detection
# === V4.0 New Modules ===
geo-block: true # Geographic IP blocking
session-validation: true # Player session validation
plugin-verification: true # Plugin integrity verification
connection-throttle: true # Connection rate limiting
backup-integrity: true # Backup integrity verification
anti-skin-spoof: true # Skin spoofing detection
# === V4.0 Anti-Cheat Extended ===
anti-kill-aura: true # KillAura detection
anti-reach: true # Reach detection
anti-speed: true # Speed detection
anti-jesus: true # Jesus detection
anti-no-fall: true # NoFall detection
anti-scaffold: true # Scaffold detection
anti-timer: true # Timer detection
anti-velocity: true # Velocity detection
anti-phase: true # Phase detection
anti-blink: true # Blink detection
anti-fast-break: true # FastBreak detection
anti-elytra-fly: true # ElytraFly detection
# === V4.0 Player Behavior ===
anti-nuker: true # Nuker detection
anti-auto-clicker: true # AutoClicker detection
anti-chest-steal: true # ChestSteal detection
anti-auto-fish: true # AutoFish detection
anti-inventory-manipulation: true # Inventory manipulation detection
anti-baritone: true # Baritone detection
# === V4.0 Server Protection ===
packet-flood-protection: true # Packet flood protection
anti-sign-exploit: true # Sign exploit protection
anti-book-ban: true # Book ban protection
anti-resource-pack-exploit: true # Resource pack exploit protection
anti-tab-complete-crash: true # Tab complete crash protection
anti-offline-mode-spoof: true # Offline mode spoof protection
# === V4.0 Access Control ===
op-privilege-monitor: true # OP privilege monitoring
config-tamper-detection: true # Config tamper detection
backdoor-plugin-scanner: true # Backdoor plugin scanner
anti-vpn-proxy: true # VPN/proxy detection
anti-alt-account: true # Alt account detection
anti-name-spoof: true # Name spoofing detection
# === V4.0 Chat & Social Security ===
chat-flood-protection: true # Chat flood protection
anti-advertisement: true # Advertisement detection
anti-phishing-link: true # Phishing link detection
anti-command-abuse: true # Command abuse detection
player-privacy: true # Player privacy protection
# === V5.0 Server Protection Extended ===
chunk-load-rate-limiter: true # Chunk load rate limiter
entity-count-enforcer: true # Entity count enforcer
redstone-update-limiter: true # Redstone update limiter
crash-exploit-signature-db: true # Crash exploit signature database
# === V4.0 Network Protocol Security ===
protocol-validator: true # Protocol state validator
token-bucket-rate-limiter: true # Token bucket rate limiter
bot-fingerprint: true # Bot fingerprint detection
nbt-exploit-prevention: true # NBT exploit prevention
handshake-validator: true # Connection handshake validator
# === V5.1 Anti-Cheat Combat (Meteor Client) ===
anti-criticals: true # Criticals detection
anti-auto-totem: true # AutoTotem detection
anti-surround: true # Surround detection
anti-auto-trap: true # AutoTrap detection
anti-auto-crystal: true # AutoCrystal detection
anti-auto-armor: true # AutoArmor detection
anti-chest-swap: true # ChestSwap detection
anti-auto-log: true # AutoLog detection
anti-hitboxes: true # Hitboxes detection
anti-bow-aimbot: true # BowAimbot detection
# === V5.2 Anti-Cheat Movement (Meteor Client) ===
anti-no-slow: true # NoSlow detection
anti-spider: true # Spider detection
anti-step: true # Step detection
anti-packet-fly: true # PacketFly detection
anti-air-jump: true # AirJump detection
anti-long-jump: true # LongJump detection
anti-anti-hunger: true # AntiHunger detection
anti-fast-fall: true # FastFall detection
anti-vclip: true # VClip detection
# === V5.3 Anti-Cheat World/Player/Misc (Meteor Client) ===
anti-speed-mine: true # SpeedMine detection
anti-fast-use: true # FastUse detection
anti-no-interact: true # NoInteract detection
anti-auto-mine: true # AutoMine detection
anti-vein-miner: true # VeinMiner detection
anti-auto-tool: true # AutoTool detection
anti-fake-player: true # FakePlayer detection
anti-piston-aura: true # PistonAura detection
anti-anchor: true # Anchor detection
anti-stash-finder: true # StashFinder detection
Other Configuration Sections
dashboard:
enabled: true
title: "Aluer Nebula Console"
subtitle: "PaperMC defense, recovery, and remote operations fabric"
refresh-interval-seconds: 6
compact-terminal: true
ssh-gateway:
enabled: true
session-timeout-minutes: 30
max-sessions: 6
command-timeout-seconds: 25
strict-host-key-checking: false
allow-private-key-paste: true
require-engine-handshake: true
handshake-ttl-seconds: 30
announcement:
enabled: false
interval-seconds: 300
messages:
- "Welcome to the server!"
afk:
enabled: false
afk-timeout-minutes: 5
max-afk-minutes: 30
teleport-to-afk-zone: false
afk-zone: "0,100,0"
auto-logout: false
chat-filter:
enabled: false
block-ip: true
block-profanity: true
block-advertising: true
block-spam: true
block-illegal: true
spam-threshold: 5
spam-window-seconds: 10
mute-on-violation: true
mute-duration-minutes: 5
kick-on-repeat: true
max-violations-before-kick: 3
backup:
enabled: false
backup-dir: /opt/minecraft/backups
world-dir: /opt/minecraft/world
plugin-dir: /opt/minecraft/plugins
config-dir: /opt/minecraft
interval-hours: 24
max-backups: 7
compress: true
backup-plugins: true
backup-config: false
notify-on-complete: true
schedule:
enabled: true
daily-restart: true
restart-time: "04:00"
save-before-restart: true
announce-restart: true
announce-message: "Server will restart in {minutes} minutes"
weekly-backup: true
backup-day: sunday
backup-time: "03:00"
clear-lag-daily: true
clear-lag-time: "02:00"
WebSocket Communication Protocol
Message Format
All messages are single-line JSON transmitted via WebSocket text frames.
Agent to Server event message:
{
"type": "EVENT",
"agentId": "agent-survival-01",
"timestamp": 1715000000000,
"payload": {
"eventType": "PLAYER_MOVE",
"playerName": "Steve",
"x": 100.5,
"y": 64.0,
"z": 200.3,
"yaw": 45.0,
"pitch": 0.0
}
}
Agent to Server heartbeat:
{
"type": "HEARTBEAT",
"agentId": "agent-survival-01",
"timestamp": 1715000005000,
"payload": {
"status": "alive"
}
}
Server to Agent command:
{
"type": "COMMAND",
"requestId": "550e8400-e29b-41d4-a716-446655440000",
"timestamp": 1715000001000,
"payload": {
"command": "KICK",
"target": "Hacker123",
"reason": "KillAura detected - confidence 94%"
}
}
Complete Event Types
| Event Constant | Value | Description |
|---|---|---|
| EVENT_PLAYER_JOIN | PLAYER_JOIN | Player joined server |
| EVENT_PLAYER_QUIT | PLAYER_QUIT | Player left server |
| EVENT_PLAYER_MOVE | PLAYER_MOVE | Player moved (x/y/z coordinates, yaw/pitch angles) |
| EVENT_PLAYER_TELEPORT | PLAYER_TELEPORT | Player teleported |
| EVENT_PLAYER_CHAT | PLAYER_CHAT | Chat message |
| EVENT_PLAYER_COMMAND | PLAYER_COMMAND | Command executed |
| EVENT_PLAYER_DAMAGE | PLAYER_DAMAGE | Player took damage |
| EVENT_COMBAT_ATTACK | COMBAT_ATTACK | Attack event (attacker/target/damage) |
| EVENT_COMBAT_DEATH | COMBAT_DEATH | Death event |
| EVENT_BLOCK_BREAK | BLOCK_BREAK | Block broken (block type/coordinates/tool) |
| EVENT_BLOCK_PLACE | BLOCK_PLACE | Block placed |
| EVENT_INVENTORY_CLICK | INVENTORY_CLICK | Inventory interaction (slot/item type) |
| EVENT_ENTITY_SPAWN | ENTITY_SPAWN | Entity spawned |
| EVENT_CHUNK_LOAD | CHUNK_LOAD | Chunk loaded |
Complete Command Types
| Command Constant | Value | Description |
|---|---|---|
| CMD_BAN_IP | BAN_IP | Ban IP address |
| CMD_BAN_PLAYER | BAN_PLAYER | Ban player account |
| CMD_KICK | KICK | Kick player from server |
| CMD_CLEAR_LAG | CLEAR_LAG | Remove all non-player entities |
| CMD_SET_SPAWN_RATE | SET_SPAWN_RATE | Dynamically adjust mob spawn rate |
| CMD_ENABLE_WHITELIST | ENABLE_WHITELIST | Enable server whitelist |
| CMD_DISABLE_WHITELIST | DISABLE_WHITELIST | Disable server whitelist |
| CMD_BROADCAST | BROADCAST | Broadcast message to all players |
| CMD_SAVE_ALL | SAVE_ALL | Force save all worlds |
| CMD_EXECUTE | EXECUTE | Execute arbitrary console command |
Alert Types
The system supports 75 alert types defined in AlertType.java:
System Monitoring (8): PROCESS_DEAD, TPS_LOW, CPU_HIGH, MEM_HIGH, CONNECTION_FLOOD, LOG_ATTACK, BACKUP_FAILED, AI_ANOMALY
V4.0 Anti-Cheat (10): SECURITY_KILL_AURA, SECURITY_REACH, SECURITY_SPEED, SECURITY_JESUS, SECURITY_NOFALL, SECURITY_SCAFFOLD, SECURITY_NUKER, SECURITY_AUTO_CLICKER, SECURITY_AUTO_FISH, SECURITY_FLY
V5.0 Anti-Cheat (6): SECURITY_TIMER, SECURITY_VELOCITY, SECURITY_PHASE, SECURITY_BLINK, SECURITY_FAST_BREAK, SECURITY_ELYTRA_FLY
V5.1 Combat (10): SECURITY_CRITICALS, SECURITY_AUTO_TOTEM, SECURITY_SURROUND, SECURITY_AUTO_TRAP, SECURITY_AUTO_CRYSTAL, SECURITY_AUTO_ARMOR, SECURITY_CHEST_SWAP, SECURITY_AUTO_LOG, SECURITY_HITBOXES, SECURITY_BOW_AIMBOT
V5.2 Movement (9): SECURITY_NO_SLOW, SECURITY_SPIDER, SECURITY_STEP, SECURITY_PACKET_FLY, SECURITY_AIR_JUMP, SECURITY_LONG_JUMP, SECURITY_ANTI_HUNGER, SECURITY_FAST_FALL, SECURITY_VCLIP
V5.3 World/Misc (10): SECURITY_SPEED_MINE, SECURITY_FAST_USE, SECURITY_NO_INTERACT, SECURITY_AUTO_MINE, SECURITY_VEIN_MINER, SECURITY_AUTO_TOOL, SECURITY_FAKE_PLAYER, SECURITY_PISTON_AURA, SECURITY_ANCHOR, SECURITY_STASH_FINDER
Player Behavior (6): SECURITY_CHEST_STEAL, SECURITY_INVENTORY_MANIPULATION, SECURITY_GRIEF, SECURITY_ALT_ACCOUNT, SECURITY_BARITONE, SECURITY_XRAY
Server Protection (9): SECURITY_SIGN_EXPLOIT, SECURITY_BOOK_BAN, SECURITY_RESOURCE_PACK_EXPLOIT, SECURITY_TAB_COMPLETE_CRASH, SECURITY_OFFLINE_MODE_SPOOF, SECURITY_CHUNK_RATE, SECURITY_ENTITY_LIMIT, SECURITY_REDSTONE_LAG, SECURITY_CRASH_EXPLOIT
Chat Security (4): CHAT_FLOOD, CHAT_ADVERTISEMENT, CHAT_PHISHING, COMMAND_ABUSE
Network Security (9): SECURITY_DDOS, SECURITY_PORT_SCAN, SECURITY_BRUTE_FORCE, SECURITY_VPN_PROXY, SECURITY_DNS_TUNNEL, SECURITY_PROTOCOL_VIOLATION, SECURITY_BOT_FINGERPRINT, SECURITY_NBT_EXPLOIT, SECURITY_HANDSHAKE_ANOMALY
Host Security (5): SECURITY_REVERSE_SHELL, SECURITY_PROCESS_INJECTION, SECURITY_FILE_TAMPER, SECURITY_BACKDOOR_PLUGIN, SECURITY_CONFIG_TAMPER
ML Analysis (4): ML_BEHAVIOR_ANOMALY, ML_THREAT_ESCALATION, ML_MOVEMENT_PATTERN, ML_COMBAT_PATTERN
General (1): SECURITY_OTHER
Testing Guide
Run Full Test Suite
cd /opt/AluerIII
./apache-maven-3.9.6/bin/mvn test
Testing Conventions
This project follows strict testing discipline:
- Live Fire Testing: Tests must simulate real Minecraft server environments
- Production Alignment: Test data and behavior must match actual production environments
- Dual Constructor Pattern: Each Service class provides both a no-arg constructor (for testing) and an @Autowired constructor (for production injection)
- Static Factory Methods: Detection results use
clean(),blocked(),flagged()static factory methods - Full Suite Validation: Full test suite must pass before and after every code change
Build Commands
# Compile
./apache-maven-3.9.6/bin/mvn compile
# Run full test suite
./apache-maven-3.9.6/bin/mvn test
# Package (skip tests for quick deployment)
./apache-maven-3.9.6/bin/mvn package -DskipTests
# Clean build artifacts
./apache-maven-3.9.6/bin/mvn clean
Project Structure
AluerIII/
├── pom.xml # Maven build configuration
├── application.yml # Spring Boot configuration (316 lines)
├── CLAUDE.md # Development guidelines
├── README.md # Project README (Chinese)
├── README_EN.md # Project README (English)
├── docs/
│ ├── DEVELOPER.md # Developer reference
│ ├── PROJECT_SUMMARY.md # Project overview and module breakdown
│ └── USER_MANUAL.md # User manual
├── apache-maven-3.9.6/ # Bundled Maven 3.9.6
├── src/
│ ├── main/java/com/aluer/
│ │ ├── ServerGuardApplication.java # Spring Boot entry point
│ │ ├── config/
│ │ │ └── ServerGuardConfig.java # Full configuration class (1273 lines, includes SuperEvolutionConfig)
│ │ ├── model/
│ │ │ └── AlertType.java # Alert type enum (75 alert types)
│ │ ├── agent/
│ │ │ └── AgentMessage.java # Agent communication protocol
│ │ ├── security/ # Security modules (123 Java files)
│ │ │ ├── AntiKillAuraService.java
│ │ │ ├── AntiReachService.java
│ │ │ ├── AntiAutoCrystalService.java
│ │ │ ├── ... (120+ more)
│ │ │ └── ZeroTrustArchitectureService.java
│ │ ├── ml/ # ML modules (4 files)
│ │ │ ├── BehavioralProfilingEngine.java
│ │ │ ├── CombatPatternRecognizer.java
│ │ │ ├── MovementPatternAnalyzer.java
│ │ │ └── ThreatScoreAggregator.java
│ │ ├── plugin/ # Paper plugin implementation
│ │ │ ├── AluerPlugin.java # Plugin main class (JavaPlugin)
│ │ │ ├── AluerCommandExecutor.java # Command registrar
│ │ │ ├── bridge/
│ │ │ │ ├── AgentWebSocketClient.java # WebSocket client
│ │ │ │ ├── DataBridge.java # Data format bridge
│ │ │ │ └── InternalCommandExecutor.java # Bukkit API command executor
│ │ │ └── listener/ # Bukkit event listeners (9)
│ │ │ ├── BlockEventListener.java # Block events (break/place)
│ │ │ ├── ChatEventListener.java # Chat/social events
│ │ │ ├── CombatEventListener.java # Combat events (attack/death)
│ │ │ ├── CommandEventListener.java # Command execution events
│ │ │ ├── EntityEventListener.java # Entity spawn/despawn events
│ │ │ ├── InventoryEventListener.java # Inventory/container events
│ │ │ ├── PacketEventListener.java # Raw packet events
│ │ │ ├── PlayerEventListener.java # Player join/quit/move events
│ │ │ └── WorldEventListener.java # World/chunk events
│ │ ├── controller/
│ │ │ └── TestController.java # Test controller
│ │ └── websocket/ # WebSocket server
│ └── main/resources/
│ └── application.yml # Default configuration file
└── src/test/ # Test code directory
Development Guide
Quick Start
# 1. Clone repository
git clone <repo-url>
cd AluerIII
# 2. Compile
./apache-maven-3.9.6/bin/mvn compile
# 3. Run tests
./apache-maven-3.9.6/bin/mvn test
# 4. Package
./apache-maven-3.9.6/bin/mvn package -DskipTests
Requirements
| Dependency | Version | Notes |
|---|---|---|
| Java JDK | 21+ | Compilation and runtime |
| Maven | 3.9.6 | Bundled with project |
| PaperMC | 1.21.1 | Minecraft server (Plugin mode only) |
Development Conventions
See CLAUDE.md in the project root. Core principles:
- YOLO Mode: Execute directly, do not wait for confirmation
- Chinese Comments: Detailed Chinese comments on every method and critical logic, explain WHY not WHAT
- Testing Discipline: Full test suite before and after every code change
- Frequent Commits: Each meaningful change gets its own Git commit with Chinese commit messages
- Zero Pseudocode: Every line of code must be compilable, runnable, and verifiable
Performance Characteristics
| Metric | Plugin Mode | External Mode |
|---|---|---|
| Communication Latency | < 1ms (same-machine WebSocket) | Depends on RCON response |
| Event Throughput | 50,000+ events/sec | 10,000+ events/sec |
| Online Player Capacity | 100+ (single agent) | 100+ |
| Memory Footprint | ~50MB (plugin portion) | ~200MB (full engine) |
| Module Hot-Switching | Supported | Supported |
| Automatic Recovery | Fully automatic (self-healing) | Fully automatic |
| DDoS Defense | Multi-layer coordinated | Multi-layer coordinated |
| AI Decision Latency | ~45s (DeepSeek analysis) | ~45s |
| Use Case | Production servers (recommended) | Monitoring/backup scenarios |
License
Proprietary. All rights reserved.