Files

T

Peijun Zhao 939d257ce6 docs: update all documentation for super evolution v3.1

- PROJECT_SUMMARY: add Section 9 with all 20 new security modules
- USER_MANUAL: add super evolution API endpoints table (20+ new endpoints)
- README.md: update security table to 60+ services with new module entries
- README_EN.md: update security table to 60+ services with new module entries

2026-05-10 20:41:04 +08:00

53 KiB

Raw Blame History

简体中文 · English

Aluer ServerGuard

🛡️ AI-Powered Minecraft PaperMC Server Security & Automation Platform

_{Built with ❤️ for Minecraft server operators who refuse to compromise on security}

"In a world where DDoS attacks, bot swarms, and zero-day exploits threaten your Minecraft community,
Aluer stands as the autonomous guardian — powered by DeepSeek AI and a multi-layer kernel fusion engine."

🏗 Architecture · 🚀 Quick Start · ⚙️ Config · 📦 Modules · 🌐 API · 🖥 Console · 💻 Commands · ❓ FAQ

2-5s
_{LLM Response}

<1ms
_{Kernel Latency}

4-Tier
_{Defense Levels}

30+
_{Security Modules}

~200MB
_{Memory Footprint}

System Architecture
Quick Start
Deployment Guide
Configuration Reference
- Full Config Tree
- Environment Variable Injection
Module Catalog
Defense Levels & Auto Response
API Reference
Web Console
Shell Command Reference
Developer Guide
FAQ
License
Support

✨ Why Aluer?

🧠 Dual-Engine Intelligence

LLM (DeepSeek) + Kernel Rule Engine working in tandem. Sovereign handles unknown threats; Kernel reacts in <1ms for known patterns. No single point of decision failure.

🛡️ Full-Stack Defense

From Minecraft protocol layer → Application WAF → OS firewall → Cloudflare edge. 30+ security modules covering L3-L7, zero-trust architecture, and honeypot deception.

📊 Real-Time Visualization

React 19 Nebula Console with SSE live streaming, performance sparklines, health probes, auto-refresh — designed for incident commanders who need instant clarity.

🔧 Autonomous Operations

Self-healing orchestration, auto-backup before recovery, scheduled tasks, Discord/Slack webhooks, and HTML attack reports. Your server guards itself while you sleep.

🧬 System Architecture

Aluer ServerGuard deploys on the same host as your Minecraft server, communicating with PaperMC via the RCON protocol while managing OS-level firewalls (iptables/ufw) and Cloudflare edge protection.

1. Three-Layer Decision Engine

This is the core design — L1 handles strategic decisions, L2 handles signal-level tactical judgment, and L3 handles execution.

┌──────────────────────────────────────────────────────────────┐
│                    L1: AluerSovereignEngine                  │
│  Input:  Full-network posture JSON (compressed context)     │
│  Process: Send to DeepSeek LLM for structured directives    │
│  Output: workflow (1 of 8) + defenseLevel + reason          │
│  Cycle:  Every 45 seconds                                   │
│  Trait:  LLM-driven, natural language reasoning, handles    │
│          novel/ambiguous threat patterns                    │
├──────────────────────────────────────────────────────────────┤
│                    L2: AluerKernelEngine                      │
│  Input:  Real-time signals from 5 virtual modules           │
│  Process: Weighted aggregation → 3D pressure → directives   │
│  Output: heat / resonance / control + KernelDirective       │
│  Cycle:  Every 30 seconds (Pulse)                            │
│  Trait:  Deterministic rules, explainable, immune to        │
│          LLM latency/hallucination                          │
├──────────────────────────────────────────────────────────────┤
│                    L3: AIAutonomousService                    │
│  Input:  L1 macro directive + L2 Kernel directive           │
│  Process: Conflict arbitration → cooldown → rate-limit      │
│  Output: ban-ip / kick / whitelist / clear-lag              │
│  Guard:  Max 12 actions/hour, dual-signal for high-risk ops │
└──────────────────────────────────────────────────────────────┘

Why two decision layers? Sovereign (DeepSeek) excels at understanding novel threats but has API latency (~2-5s) and occasional unstructured output. Kernel is a pure rule engine with <1ms latency, capable of instant reaction to known threat patterns. The two layers intersect and back each other up.

2. Kernel Signal Fusion Model

The Kernel runs 5 virtual modules (KernelModule interface), each collecting pressure signals from specific security subsystems:

Module	Name	Data Source	Vector	Baseline Weight
`ThreatMeshModule`	Threat Mesh	DDoS / Firewall / IDS / Port Scan / DPI	`network`	1.12
`CommandLatticeModule`	Command Lattice	Command Guard (dangerous cmd + RCON brute force)	`command`	1.18
`HardeningMatrixModule`	Hardening Matrix	Security baseline audit (vuln × severity)	`integrity`	1.05
`PerimeterWardModule`	Perimeter Ward	WAF (blocked/suspicious + active clients)	`perimeter`	0.92
`EchoGridModule`	Echo Grid	Historical IP pressure memory decay	`memory`	0.84

Each Pulse cycle (default 30s), 5 modules produce 0~N KernelSignal objects. Aggregation algorithm:

For each signal:
  weighted = clamp(pressure × adaptiveWeight[module], 0, 100)
  vectorScores[vector] += weighted
  moduleScores[module] += weighted

heat     = clamp(peak_vector × 0.68 + avg_vector × 0.32, 0, 100)
resonance = clamp(heat × 0.45 + second_vector × 0.18 + energized × 14 + count × 2.2, 0, 100)
control  = clamp(100 - heat × 0.62 - resonance × 0.28, 0, 100)

Adaptive weights via exponential moving average:

target = baseline + (pressure ≥ 80 ? 0.18 : pressure ≥ 55 ? 0.08 : 0)
active = current × 0.82 + target × 0.18
active = clamp(active, 0.72, 1.45)

EchoGrid (attacker memory) decay:

cell.pressure = cell.pressure × 0.55 + pulse.heat × 0.75
// Cells exceeding retention time are auto-purged

3. Data Flow Overview

                      ┌──────────────┐
                      │  Minecraft    │
                      │  PaperMC      │
                      │  (RCON 25575) │
                      └──┬───────┬──┘
                         │       │
            RCON commands │       │ latest.log
            (ban-ip /     │       │ /proc metrics
             kick /       │       │ netstat
             whitelist)   │       │
                         │       │
    ┌────────────────────┴───────┴──────────────────────┐
    │                 Aluer ServerGuard                  │
    │                                                    │
    │  ┌──────────┐  ┌──────────┐  ┌──────────┐         │
    │  │ Monitor  │  │ Security │  │   AI     │         │
    │  │ Process  │  │ DDoS/IDS │  │ DeepSeek │         │
    │  │ Resource │  │ WAF/Honey│  │ Anomaly  │         │
    │  │ Connect  │  │ ZeroTrust│  │ Predict  │         │
    │  │ Log      │  │ 30+ svc  │  │ Adaptive │         │
    │  └────┬─────┘  └────┬─────┘  └────┬─────┘         │
    │       │             │             │                │
    │       └─────────┬───┴─────────────┘                │
    │                 │                                  │
    │    ┌────────────┴────────────┐                     │
    │    │  Kernel + Sovereign     │                     │
    │    │  Signal Fusion → Output │                     │
    │    └────────────┬────────────┘                     │
    │                 │                                  │
    │    ┌────────────┴────────────┐                     │
    │    │  AutoExecutor / RCON   │                      │
    │    │  Execute + Audit Log    │                      │
    │    └────────────────────────┘                      │
    │                                                    │
    │    ┌────────────────────────┐                      │
    │    │  Web Dashboard :8080   │  ← Admin Browser     │
    │    │  Spring Shell Terminal │  ← Admin Terminal    │
    │    └────────────────────────┘                      │
    └────────────────────────────────────────────────────┘
                         │
                  Cloudflare API
                  (Edge Challenge / Block / Under Attack)

🚀 Quick Start

Requirements

Dependency	Version	Notes
JDK	17+	Compile and runtime
Maven	3.9+ (bundled)	`apache-maven-3.9.6/` included in repo
OS	Ubuntu / Debian	Recommended for production; other Linux works but some security modules need iptables/ufw
Memory	2 GB+ free	On top of Minecraft server's own memory
Disk	10 GB+	Logs + backups + jar
Minecraft	PaperMC 1.21+	RCON must be enabled (`enable-rcon=true` in `server.properties`)
DeepSeek	API Key	Required for AI decision and natural language Q&A
Node.js	18+ (dev only)	Production uses pre-built static assets

Build

# 1. Clone the repository
git clone https://github.com/ZpjDev/Aluer.git
cd Aluer

# 2. Build with bundled Maven
./apache-maven-3.9.6/bin/mvn clean package -DskipTests

# 3. Output location
ls -lh target/serverguard.jar

The build process also compiles the React frontend via Vite, outputting to src/main/resources/static/ and embedding into the jar.

Environment Variables

Minimum viable config (only 2 env vars required):

# Required: DeepSeek API Key (get from https://platform.deepseek.com)
export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

# Required: RCON password (must match rcon.password in server.properties)
export RCON_PASSWORD=your-strong-rcon-password

Full production config:

# ──── Core Credentials ────
export DEEPSEEK_API_KEY=sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
export DEEPSEEK_BASE_URL=https://api.deepseek.com
export DEEPSEEK_MODEL=deepseek-chat
export RCON_PASSWORD=your-strong-rcon-password

# ──── Email Alerts (QQ email example) ────
export ALUER_ALERT_SMTP_USERNAME=your-email@qq.com
export ALUER_ALERT_SMTP_PASSWORD=your-smtp-auth-code
export ALUER_ALERT_EMAIL_PRIMARY=admin@example.com
export ALUER_ALERT_EMAIL_SECONDARY=backup@example.com

# ──── Cloudflare Edge Protection (optional) ────
export ALUER_CLOUDFLARE_ZONE_ID=your-zone-id
export ALUER_CLOUDFLARE_API_KEY=your-api-key
export ALUER_CLOUDFLARE_EMAIL=your-cloudflare-email

# ──── Discord/Slack Webhooks (optional) ────
export ALUER_WEBHOOK_DISCORD=https://discord.com/api/webhooks/xxx/yyy
export ALUER_WEBHOOK_SLACK=https://hooks.slack.com/services/xxx/yyy/zzz

Security note: Never hardcode API keys or passwords in application.yml. All sensitive values use ${VAR_NAME:} placeholder syntax, defaulting to empty string when not set.

First Launch

# Foreground (shows Spring Shell interactive terminal)
java -jar target/serverguard.jar

# Background (using provided script)
./start.sh

# Using systemd (recommended for production)
sudo systemctl start serverguard

On startup you'll see the Spring Shell terminal:

╔══════════════════════════════════════════════════╗
║       Welcome to Aluer ServerGuard                ║
╠══════════════════════════════════════════════════╣
║  Type help for available commands                 ║
║  Type ai <question> for AI assistant              ║
╚══════════════════════════════════════════════════╝
aluer>

Verify everything is working:

# Test API
curl http://localhost:8080/api/status

# Expected response
{"status":"running","timestamp":1746883200000}

# Access Web Console
curl http://localhost:8080/

One-Click Install

# Run with sudo
sudo bash install.sh

The script will:

Detect/install Java 17
Create /opt/serverguard/ working directory
Wait for you to upload the jar (via scp or other)
Auto-create and enable systemd service
Start service and verify status

📦 Deployment Guide

Systemd Services

The repo provides two systemd unit files:

systemd/minecraft.service — Minecraft server (Aluer's prerequisite):

[Unit]
Description=Minecraft PaperMC Server
After=network.target

[Service]
Type=simple
User=minecraft
WorkingDirectory=/opt/minecraft
ExecStart=/usr/bin/java -Xms4G -Xmx4G -jar paper-1.21.11.jar nogui
Restart=on-failure
RestartSec=10
StartLimitBurst=3

[Install]
WantedBy=multi-user.target

systemd/serverguard.service — Aluer protection system:

[Unit]
Description=Aluer ServerGuard Protection System
After=network.target minecraft.service
Requires=minecraft.service

[Service]
Type=simple
User=root
WorkingDirectory=/opt/serverguard
ExecStart=/usr/bin/java -jar serverguard.jar
Restart=always
RestartSec=5

[Install]
WantedBy=multi-user.target

Deployment steps:

# 1. Copy service files
sudo cp systemd/minecraft.service /etc/systemd/system/
sudo cp systemd/serverguard.service /etc/systemd/system/

# 2. Create minecraft user
sudo useradd -r -m -d /opt/minecraft minecraft

# 3. Reload systemd
sudo systemctl daemon-reload

# 4. Start Minecraft first, then Aluer
sudo systemctl enable --now minecraft
sudo systemctl enable --now serverguard

# 5. Check status
sudo systemctl status minecraft serverguard

# 6. Watch Aluer logs
sudo journalctl -u serverguard -f

sudo Configuration

Aluer needs permission to run systemctl restart minecraft. Copy the sudoers file:

sudo cp systemd/sudoers.serverguard /etc/sudoers.d/serverguard
sudo chmod 440 /etc/sudoers.d/serverguard

Reverse Proxy (Optional)

When exposing the web console publicly, place Nginx in front:

server {
    listen 443 ssl;
    server_name console.your-server.com;

    auth_basic "Aluer Console";
    auth_basic_user_file /etc/nginx/.htpasswd;

    location / {
        proxy_pass http://127.0.0.1:8080;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
    }
}

Warning

: Never expose Aluer's port 8080 directly to the internet. The WAF module provides basic protection only and is not a substitute for a proper reverse proxy.

⚙️ Configuration Reference

Full Config Tree

All top-level configuration nodes in application.yml and their purposes:

serverguard
├── minecraft                     # Minecraft server connection
│   ├── service-name              # systemd service name (default: minecraft)
│   ├── process-name              # Process name for liveness detection
│   ├── jar-file                  # PaperMC jar filename
│   ├── working-dir               # Minecraft working directory
│   ├── java-opts                 # JVM startup args
│   ├── check-interval-seconds    # Monitor check interval (default: 5s)
│   └── rcon
│       ├── enabled
│       ├── host                  # RCON host (default: localhost)
│       ├── port                  # RCON port (default: 25575)
│       └── password              # RCON password (${RCON_PASSWORD})
│
├── monitor                       # Monitoring thresholds
│   ├── tps-threshold             # TPS alert threshold (default: 15)
│   ├── cpu-threshold             # CPU usage alert % (default: 80)
│   ├── memory-threshold          # Memory usage alert % (default: 85)
│   ├── connection-threshold      # Connection anomaly threshold
│   ├── log-watch-lines           # Log tail lines
│   └── log-path                  # Minecraft log file path
│
├── alert                         # Alert notification config
│   ├── enabled
│   └── email
│       ├── smtp-host
│       ├── smtp-port             # (default: 587)
│       ├── username              # (${ALUER_ALERT_SMTP_USERNAME})
│       ├── password              # (${ALUER_ALERT_SMTP_PASSWORD})
│       ├── to                    # Recipient list (env var injected)
│       └── rate-limit
│           ├── per-type-seconds  # Cooldown per alert type (default: 300s)
│           └── max-emails-per-minute
│
├── ai                            # AI engine config
│   ├── enabled
│   ├── use-isolation-forest
│   ├── use-prediction
│   ├── sliding-window-size
│   ├── anomaly-threshold         # (0-1)
│   ├── prediction-horizon-minutes
│   └── deepseek
│       ├── enabled
│       ├── api-key               # (${DEEPSEEK_API_KEY})
│       ├── base-url              # (default: https://api.deepseek.com)
│       ├── model                 # (default: deepseek-chat)
│       ├── max-tokens
│       ├── temperature           # (0-1, recommended 0.35)
│       ├── auto-analyze-alerts
│       ├── analysis-interval-seconds
│       └── auto-execute
│           ├── enabled
│           ├── ban-ip / kill-entity / clear-lag
│           ├── set-spawn-rate / kick-player / whitelist
│           └── min-confidence    # (default: 88)
│
├── security                      # Security module config
│   ├── enabled                   # Master switch
│   ├── auto-ban-vpn
│   ├── check-on-login
│   ├── max-connections-per-ip
│   ├── block-common-exploits
│   ├── log-all-commands
│   │
│   ├── minecraft-defense         # Minecraft protocol defense
│   ├── ddos-defense              # DDoS multi-layer detection
│   ├── anti-intrusion            # Intrusion detection config
│   ├── host-enforcement          # Host firewall enforcement
│   ├── cloud-edge                # Cloudflare edge protection
│   ├── orchestration             # Orchestration policies
│   ├── autonomy                  # Autonomous defense policies
│   ├── shield                    # Mirage Shield config
│   ├── kernel                    # Kernel engine config
│   ├── task-bus                  # Task bus config
│   └── self-healing              # Self-healing orchestration
│
├── webhook                       # Discord/Slack notifications
│   ├── enabled
│   ├── discord-url               # (${ALUER_WEBHOOK_DISCORD})
│   └── slack-url                 # (${ALUER_WEBHOOK_SLACK})
│
├── dashboard                     # Web console config
├── backup                        # Backup config
├── schedule                      # Scheduled tasks
├── chat-filter                   # Chat filtering
├── announcement                  # Timed announcements
└── afk                           # AFK management

Environment Variable Injection Table

Env Variable	Config Path	Default
`RCON_PASSWORD`	`serverguard.minecraft.rcon.password`	(empty)
`DEEPSEEK_API_KEY`	`serverguard.ai.deepseek.api-key`	(empty)
`DEEPSEEK_BASE_URL`	`serverguard.ai.deepseek.base-url`	`https://api.deepseek.com`
`DEEPSEEK_MODEL`	`serverguard.ai.deepseek.model`	`deepseek-chat`
`ALUER_ALERT_SMTP_USERNAME`	`serverguard.alert.email.username`	(empty)
`ALUER_ALERT_SMTP_PASSWORD`	`serverguard.alert.email.password`	(empty)
`ALUER_ALERT_EMAIL_PRIMARY`	`serverguard.alert.email.to[0]`	(empty)
`ALUER_ALERT_EMAIL_SECONDARY`	`serverguard.alert.email.to[1]`	(empty)
`ALUER_CLOUDFLARE_ZONE_ID`	`serverguard.security.cloud-edge.zone-id`	(empty)
`ALUER_CLOUDFLARE_API_KEY`	`serverguard.security.cloud-edge.api-key`	(empty)
`ALUER_CLOUDFLARE_EMAIL`	`serverguard.security.cloud-edge.api-email`	(empty)
`ALUER_WEBHOOK_DISCORD`	`serverguard.webhook.discord-url`	(empty)
`ALUER_WEBHOOK_SLACK`	`serverguard.webhook.slack-url`	(empty)

📋 Module Catalog

AI Decision Layer (`com.aluer.ai`)

Class	File	Description
`AluerSovereignEngine`	`ai/AluerSovereignEngine.java`	L1 Sovereign Engine. Collects network posture → DeepSeek generates `AutonomyDirective` (workflow + defenseLevel + riskScore). Built-in workflow whitelist prevents LLM hallucination.
`DeepSeekClient`	`ai/DeepSeekClient.java`	DeepSeek API Client. Native `HttpURLConnection`. Supports 4 call modes: alert analysis, health report, free-form Q&A, and autonomous defense planning. Built-in JSON extraction from markdown/text.
`AIAutonomousService`	`ai/AIAutonomousService.java`	L3 Execution Layer. Reads L1 + L2 directives, conflict arbitration, cooldown, rate limiting, dual-signal confirmation. Translates decisions into RCON commands.
`AIStrategyEngine`	`ai/AIStrategyEngine.java`	Strategy Matching Engine. Maps threat types to optimal defense strategies (brute force → temp ban+captcha, DDoS → traffic scrubbing+rate limit).
`AnomalyDetector`	`ai/AnomalyDetector.java`	Isolation Forest. Based on Apache Commons Math3. Unsupervised anomaly detection on CPU/memory/TPS/connections.
`TimeSeriesPredictor`	`ai/TimeSeriesPredictor.java`	Time Series Predictor. Sliding window historical data → predict TPS trends 60min ahead.
`AdaptiveThreshold`	`ai/AdaptiveThreshold.java`	Adaptive Thresholds. Learns server load patterns, dynamically adjusts alert thresholds to reduce false positives during low-load hours.

Kernel Engine Layer (`com.aluer.kernel`)

Class	File	Description
`AluerKernelEngine`	`kernel/AluerKernelEngine.java`	L2 Kernel Engine. 30s Pulse loop. 5 virtual modules (ThreatMesh / CommandLattice / HardeningMatrix / PerimeterWard / EchoGrid), weighted signal fusion, heat/resonance/control 3D pressure, adaptive weights, EchoGrid attacker memory decay.
`AluerKernelTaskBus`	`kernel/AluerKernelTaskBus.java`	Task Bus. Plugin-based task execution framework. 4 built-in Plugins (Insight / Stability / Defense / Recovery) dispatched by priority.
`AluerSelfHealingOrchestrator`	`kernel/AluerSelfHealingOrchestrator.java`	Self-Healing Orchestrator. 45s recovery check. Detects TPS/CPU/memory emergency thresholds. Recovery actions: soft restart, clear entities, adjust spawn rate, whitelist (bot swarm). Max 8 recovery actions/hour.

Security Defense Layer (`com.aluer.security`)

The largest package in the system, containing 30+ security services:

Category	Key Classes	Description
DDoS Defense	`DDoSProtectionService`, `DDoSDefenseCoordinator`, `DistributedAttackMitigationService`, `MinecraftProtocolSecurityService`	SYN/HTTP/UDP/ICMP Flood detection, Minecraft-specific Status/Login/Rcon/Query Flood
Firewall	`FirewallService`, `HostEnforcementService`, `NetworkMonitorService`, `NetworkSegmentationService`	iptables/ufw rule management, auto/iptables/ufw/nftables backend support
Intrusion Detection	`IntrusionDetectionService`, `IntrusionPreventionSystem`, `HostIntrusionCountermeasureService`, `LogAnalysisService`, `LogCorrelationService`	Signature-based IDS, auto-blocking, multi-source log correlation
Application Security	`WebApplicationFirewall`, `WafRequestFilter`, `APIRateLimitService`, `RateLimitService`	SQLi/XSS/path traversal/header injection protection, client reputation scoring
Advanced Defense	`HoneypotService`, `ZeroTrustArchitectureService`, `AdvancedMalwareDetectionService`, `EndpointDetectionResponseService`, `ContainerSecurityService`	Honeypot decoys, continuous auth verification, malware scanning, EDR
Network Analysis	`TrafficAnalysisService`, `PacketInspectionService`, `FlowAnalyzerService`, `PortScanDetectionService`, `ProtocolAnalysisService`	Traffic pattern analysis, DPI, NetFlow/sFlow, port scan detection
IP Intelligence	`IPReputationService`, `GeoIPService`, `ThreatIntelligenceService`, `VPNDetectionService`	IP reputation scoring, geolocation filtering, threat feed integration, VPN/proxy detection
SSL/TLS	`SSLMonitorService`, `SSLTLSCertificateService`	Certificate expiry monitoring, cert management
Security Operations	`SIEMService`, `SecurityOrchestrationService`, `SecurityAutomationScheduler`, `SecurityBaselineHardeningService`, `BackupSecurityService`	SIEM correlation, security orchestration, baseline hardening
Command Security	`CommandExecutionGuardService`	Dangerous command interception (rm -rf / wget \| sh / privilege escalation)
Execution Layer	`CloudflareIntegrationService`, `DNSSecurityService`, `SessionManagementService`, `LoadBalancerService`, `TrafficShapingService`, `EncryptionService`	Cloudflare API integration, DNS security, session management, load balancing, traffic shaping
Super Evolution v3.1	`JwtAuthService`	JWT HMAC-SHA256 auth with constant-time comparison
	`BruteForceProtectionService`	Three-layer time window (60s/600s/3600s) brute force defense
	`AntiBotDetectionService`	Minecraft bot detection: name patterns/join velocity/multi-account
	`AntiGriefDetectionService`	Block break/place rate monitoring, dangerous block detection
	`ReverseShellDetectionService`	50+ reverse shell pattern matching + obfuscated command detection
	`ARPSpoofDetectionService`	ARP table baseline diff, MAC/Gateway spoof detection
	`DNSTunnelDetectionService`	Subdomain entropy analysis, Base64 encoding detection
	`ExploitSignatureService`	15+ exploit signatures (Log4Shell/SQLi/XSS/Deserialization)
	`SSRFProtectionService`	Internal IP/Cloud metadata/DNS rebinding protection
	`XXEProtectionService`	XML entity injection + Billion Laughs attack detection
	`CSPEnforcementService`	Content-Security-Policy + 8 security headers auto-generation
	`DatabaseFirewallService`	SQL injection detection (UNION/sleep/stacked queries)
	`DataLossPreventionService`	12 sensitive data patterns (email/API key/SSH key/JWT/card)
	`MemoryProtectionService`	JVM heap/GC overload/memory leak pattern detection
	`ProcessInjectionDetectionService`	Thread spike/memory mapping/non-standard native lib detection
	`SecureFileDeletionService`	DoD multi-pass overwrite (0x00/random/0xFF/0xAA) secure delete
	`ForensicsCollectorService`	6 evidence types (process/network/files/logs) case management
	`IncidentResponseService`	5 playbooks (DDoS/brute force/intrusion/MC exploit/data breach)
	`ThreatHuntingService`	10 proactive hunt rules (persistence/lateral/privilege/crypto/webshell)
	`ComplianceScannerService`	7 categories 20+ checks, auto compliance scoring (0-100%)

Operations Control Layer (`com.aluer.console`)

Class	Description
`AluerOperationsCenterService`	Operations Center. Aggregates all subsystem status, outputs to `/api/console/overview`
`AluerMirageShieldService`	Mirage Shield. 4-mode adaptive protection (OBSERVE → FORTIFY → MIRAGE → SHELTER), attacker deterrence, auto mode switching
`RemoteSshGatewayService`	Remote SSH Gateway. Built-in terminal, Sovereign Handshake approval + command guard integration
`ConsoleStreamController`	SSE Stream. Server-Sent Events push of real-time overview data to frontend

Monitoring Collection Layer (`com.aluer.monitor`)

Class	Description
`ProcessMonitor`	Process liveness detection, auto-restart Minecraft on crash
`ResourceMonitor`	System resource collection (CPU/memory/disk I/O) via `/proc` and JMX
`ConnectionMonitor`	Network connection statistics, Connection Flood detection
`LogMonitor`	Minecraft `latest.log` real-time tracking, crash stack and anomaly detection

Core Service Layer (`com.aluer.service`)

Class	Description
`ServerGuardService`	System Controller. `CommandLineRunner` entry point, schedules all monitoring and AI analysis loops
`RconClient`	Minecraft RCON protocol client, native NIO SocketChannel implementation with fallback
`AutoExecutor`	Translates AI decisions into RCON commands (e.g., "ban IP" → `/ban-ip 1.2.3.4`)

Web Interaction Layer (`com.aluer.web`)

Class	Description
`DashboardController`	REST API (`/api/*`): status, commands, backups, health checks, attack reports
`OperationsConsoleController`	Console API (`/api/console/*`): overview, shield control, quick actions
`ConsoleStreamController`	SSE stream (`/api/console/stream/overview`)
`HealthService`	Component-level health checks (RCON/AI/email/security/self-healing), system resources
`RequestLoggingFilter`	HTTP request logging, slow request and 500 error alerts

Notification & Reporting Layer (`com.aluer.notification`)

Class	Description
`WebhookService`	Discord/Slack dual-channel webhook push. Auto-sends embed messages on security alerts with color-coded severity
`AttackReportService`	Records last 500 attack events in memory ring buffer. Generates timestamped HTML security reports

Auxiliary Modules

Package	Class	Description
`com.aluer.alert`	`EmailAlertService`	Email alerts with QQ/Gmail/custom SMTP, built-in rate limiting
`com.aluer.backup`	`BackupService`	World/plugin/config scheduled backup, compression, auto-cleanup
`com.aluer.anticheat`	`AntiCheatService`	Anti-cheat integration, aggregated violation data
`com.aluer.vpn`	`VPNDetectionService`	VPN/proxy IP detection
`com.aluer.chat`	`ChatFilterService`	In-game chat filtering (profanity/ads/phishing/spam)
`com.aluer.punishment`	`PunishmentService`	Unified punishment management (ban/kick/mute)
`com.aluer.audit`	`SecurityAuditService`	Security audit logs for all admin operations
`com.aluer.world`	`WorldManagementService`	Minecraft world management (load/unload/list)
`com.aluer.metrics`	`MetricsCollectionService`	Unified metrics aggregation
`com.aluer.profiler`	`PerformanceProfiler`	CPU/memory/tick performance analyzer
`com.aluer.schedule`	`ScheduledTaskService`	Task scheduling engine (restart/backup/clear lag/announce)
`com.aluer.export`	`DataExportService`	Security data export (audit/attack/performance reports)
`com.aluer.command`	`AdminCommands` / `TestCommands`	Spring Shell management and test commands

Data Models (`com.aluer.model`)

Class	Fields	Description
`AlertEvent`	type, message, rootCause, timestamp, confidence, suggestedAction	Standardized alert event
`AlertType`	PROCESS_DEAD / TPS_LOW / CPU_HIGH / MEM_HIGH / CONNECTION_FLOOD / LOG_ATTACK / BACKUP_FAILED / AI_ANOMALY	Alert type enum
`MetricsData`	tps, cpuUsage, memoryUsage, onlinePlayers, connections, tickTime	Server performance snapshot

🛡️ Defense Levels & Auto Response

Four-Tier Defense System

The system auto-switches defense levels based on Kernel heat and Sovereign assessment:

Level	Heat Range	Trigger	Auto Actions
`NORMAL`	< 45	Normal operation	Routine monitoring, anomalies logged only
`ELEVATED`	45–69	Single module pressure rise	Increased detection frequency, IP reputation queries enabled
`HIGH`	70–81	Multiple modules alerting	Auto-block high-risk IPs, rate limiting, edge challenges
`LOCKDOWN`	≥ 82	Severe compound attack	Whitelist mode, Cloudflare Under Attack, reject new connections, emergency email

Mirage Shield Modes

Mirage Shield is the attacker deflection shield with 4 operating modes:

Mode	Meaning	Auto Trigger
`OBSERVE`	Observe only, no intervention	Default mode
`FORTIFY`	Harden defenses	heat ≥ 78 or threat_score ≥ 85
`MIRAGE`	Mirror deflection	resonance ≥ 72 with high-confidence attacker
`SHELTER`	Shelter mode	heat ≥ 82 and resonance ≥ 80, strict rate limiting

In MIRAGE and SHELTER modes, deterrence messages are sent to detected attacker IPs.

Self-Healing Triggers

AluerSelfHealingOrchestrator triggers recovery when:

Condition	Threshold	Recovery Actions
TPS emergency	< 12 TPS	`clear-lag` + `kill-entity` + low spawn rate
CPU emergency	> 92%	`clear-lag` first, soft restart if ineffective
Memory emergency	> 95%	`save-all` → notify players → soft restart
Bot Swarm	≥ 15 concurrent fake players	`whitelist on` + block source IPs

All recovery actions are log-only when dry-run=true.

🌐 API Reference

System Status API

Method	Path	Description
`GET`	`/api/status`	System running status
`GET`	`/api/server/info`	Minecraft server info
`GET`	`/api/performance`	TPS / CPU / Memory metrics
`POST`	`/api/command/execute`	Execute RCON command (param: `command`)

Security Posture API

Method	Path	Description
`GET`	`/api/security/stats`	Security overview
`GET`	`/api/security/network/posture`	Network posture details
`GET`	`/api/security/network/offenders?limit=10`	High-risk IP list
`GET`	`/api/security/network/incidents?limit=20`	Security incident list
`GET`	`/api/security/network/ip?ip=1.2.3.4`	Single IP deep inspection
`POST`	`/api/security/network/quarantine`	Quarantine IP (`ip`, `actor`, `reason`)
`POST`	`/api/security/network/release`	Release IP (`ip`, `actor`, `reason`)

Health Check API

Method	Path	Description
`GET`	`/api/health`	Full health report (component status + system resources)
`GET`	`/api/health/live`	Liveness probe (K8s compatible)
`GET`	`/api/health/ready`	Readiness probe (RCON availability check)

Notification & Report API

Method	Path	Description
`GET`	`/api/attacks/recent?limit=20`	Recent attack records
`POST`	`/api/attacks/report`	Generate HTML attack report
`POST`	`/api/webhook/test`	Test Discord/Slack webhook

Console Operations API

Method	Path	Description
`GET`	`/api/console/overview`	Full operations overview
`GET`	`/api/console/stream/overview`	SSE real-time stream
`POST`	`/api/console/shield/engage`	Manual shield mode switch (`mode`, `reason`)
`POST`	`/api/console/quick-action`	Quick action (`backup-now` / `shield-mirage` / `shield-shelter`)

SSH Gateway API

Method	Path	Description
`POST`	`/api/console/ssh/handshake`	Sovereign handshake approval
`POST`	`/api/console/ssh/connect`	Establish SSH connection
`POST`	`/api/console/ssh/execute`	Execute remote command
`DELETE`	`/api/console/ssh/{sessionId}`	Disconnect SSH session

SSH Gateway security design:

Sovereign Handshake: Connection requires handshake approval based on current heat and risk score
Command Guard: Every command is reviewed by CommandExecutionGuardService
Session Timeout: Auto-disconnect after 30 minutes of inactivity
Audit Sync: All SSH operations logged to SecurityAuditService

Backup Management API

Method	Path	Description
`GET`	`/api/backup/list`	Backup list
`POST`	`/api/backup/create`	Create backup (param: `name`)

🖥️ Web Console

Aluer ships with a React 19 + Vite 6 SPA console (Nebula Console).

Features

Feature	Description
Shield Control	One-click FORTIFY / MIRAGE / SHELTER / RECOVERY mode switching
Performance Trend	TPS / CPU / Memory / Players SparkBar visualization
Auto Refresh	Toggle + configurable interval (3s / 6s / 10s / 30s)
Health Panel	Collapsible, shows RCON/AI/Email/Security/Self-Healing UP/DOWN status
SSH Terminal	Remote node connection with command guard review
Module Monitor	Real-time status and signal values for 9 modules
Threat View	High-risk IP list with score, riskLevel, and details (up to 10)
Audit Filter	Real-time filtering of audit events, network incidents, shield transitions (up to 24)

Real-Time Data Flow

Frontend receives data via SSE (Server-Sent Events) with automatic polling fallback:

Browser ──EventSource──→ /api/console/stream/overview
                            │
                  Pushes full overview JSON every 6s
                  (aggregated by AluerOperationsCenterService)
                            │
                  SSE fails → auto-fallback to setInterval
                              polling /api/console/overview
                            │
                  Auto-refresh toggle: 3s / 6s / 10s / 30s

🖧 Shell Command Reference

Aluer provides a Spring Shell interactive terminal with natural language support.

AI Conversation

aluer> ai test server               # Run full server test
aluer> ai enable defense            # Enable AI autonomous defense
aluer> ai check security status     # Get security posture overview
aluer> ai analyze the lag           # DeepSeek deep analysis
aluer> ask how to improve security  # Free-form Q&A

Basic Commands

Command	Example	Description
`help`	`help`	Show all available commands
`status`	`status`	Server status (process/CPU/memory/connections)
`test`	`test` / `test cpu` / `test memory`	Run tests
`metrics`	`metrics` / `metrics counters`	Performance metrics

Security Management

Command	Example	Description
`security`	`security` / `security ddos` / `security firewall`	Security module status
`defense`	`defense` / `defense on` / `defense level high`	AI defense control
`network`	`network` / `network geoip 1.2.3.4`	Network analysis

Player Management

Command	Example	Description
`kick`	`kick PlayerName`	Kick player
`ban`	`ban PlayerName` / `ban PlayerName cheating`	Ban player
`unban`	`unban PlayerName`	Unban player

Operations

Command	Example	Description
`backup`	`backup create` / `backup status`	Backup management
`world`	`world load world_nether`	World management
`alert`	`alert test` / `alert send server anomaly`	Email alerts
`audit`	`audit recent 20` / `audit summary`	Security audit
`tasks`	`tasks start`	Scheduled task management

🔧 Developer Guide

Project Structure

Aluer/
├── src/main/java/com/aluer/
│   ├── ai/                    # AI Decision Engine (7 classes)
│   ├── kernel/                # Kernel Engine (3 classes)
│   ├── security/              # Security Modules (33 classes)
│   ├── console/               # Operations Control (4 classes)
│   ├── monitor/               # Monitoring Collection (4 classes)
│   ├── service/               # Core Services (4 classes)
│   ├── web/                   # Web Layer (5 classes)
│   ├── notification/          # Notification & Reports (2 classes)
│   ├── config/                # Configuration
│   ├── model/                 # Data Models
│   ├── terminal/              # Shell Terminal
│   ├── command/               # Shell Commands
│   ├── alert/                 # Alerts
│   ├── backup/                # Backup
│   ├── anticheat/             # Anti-Cheat
│   ├── vpn/                   # VPN Detection
│   ├── chat/                  # Chat Filter
│   ├── punishment/            # Punishment
│   ├── audit/                 # Security Audit
│   ├── world/                 # World Management
│   ├── metrics/               # Metrics Collection
│   ├── profiler/              # Performance Profiler
│   ├── schedule/              # Scheduled Tasks
│   ├── export/                # Data Export
│   └── ServerGuardApplication.java
│
├── src/main/resources/
│   ├── application.yml
│   ├── banner.txt
│   ├── logback.xml
│   └── static/
│
├── src/test/java/com/aluer/   # Tests (9 files)
├── frontend/                  # React Frontend
├── systemd/                   # Systemd Service Files
├── docs/                      # Documentation
├── apache-maven-3.9.6/        # Bundled Maven
└── pom.xml

Build & Run

# Full build (includes frontend)
./apache-maven-3.9.6/bin/mvn clean package -DskipTests

# Compile only
./apache-maven-3.9.6/bin/mvn compile

# Run
java -jar target/serverguard.jar

Frontend Development

cd frontend
npm install
npm run dev          # Dev server at http://localhost:4173
npm run build        # Production build → ../src/main/resources/static/

Running Tests

# All tests
./apache-maven-3.9.6/bin/mvn test

# Specific test class
./apache-maven-3.9.6/bin/mvn test -Dtest=AluerKernelEngineTest

Adding a New Security Module

Each security module follows a consistent convention:

Create a new class in com.aluer.security
Inject ServerGuardConfig via constructor
Implement getPosture() for Kernel consumption
Register in NetworkThreatFusionService (if network-related)
Aggregate in AluerOperationsCenterService.buildOverview() (if needed in console)
Add config node in application.yml

❓ FAQ

How do I verify AI is working?

aluer> ask Hello

If you get an AI response, DeepSeek is configured correctly. Or check logs:

tail -f /var/log/serverguard.log | grep DeepSeek

Not receiving email alerts?

Verify username/password in email config
QQ email requires authorization code not login password
Check spam folder
Run alert test to send a test email

Tips for first deployment?

Enable dry-run mode first:

serverguard:
  security:
    host-enforcement:
      dry-run: true
    cloud-edge:
      dry-run: true
    self-healing:
      dry-run: true

Observe for 1-2 days before disabling dry-run.

Why two decision engines? Won't they conflict?

No, they're complementary:

Sovereign (DeepSeek): excels at complex, never-seen attack patterns; 2-5s latency
Kernel (rule engine): <1ms response, 100% predictable, but can't handle unknown patterns

When outputs disagree, AIAutonomousService (L3) resolves based on autonomy.deepseek-dominant config. SecurityOrchestrationService provides final safety net — no operation exceeds max-actions-per-hour.

Performance overhead?

Tested on 2-core 4GB VPS:

JVM resident memory: ~180-250 MB (Spring Boot + all services)
CPU idle: <2% (monitoring and Pulse loops)
DeepSeek API call CPU: ~5% (mainly network I/O wait)
No impact on Minecraft server performance (async RCON communication)

📄 License

This project is open-sourced under Apache License 2.0. See LICENSE for full text.

Clause	Description
✅ Permitted	Commercial use, modification, distribution, patent use, private use
⚠️ Required	Include license and copyright notice, mark changed files
❌ Limited	No warranty, authors not liable for damages

🌟 Support the Project

If Aluer ServerGuard helps you, please consider:

🏆 Contributors

_{Made with ❤️ by the Aluer community — defending Minecraft servers worldwide}

_{Aluer ServerGuard v1.0.0 — Autonomous protection for your Minecraft community}

53 KiB Raw Blame History Unescape Escape