**简体中文** · [**English**](README.md)
---
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
|
## Table of Contents
- [System Architecture](#-system-architecture)
- [Three-Layer Decision Engine](#1-three-layer-decision-engine)
- [Kernel Signal Fusion Model](#2-kernel-signal-fusion-model)
- [Data Flow Overview](#3-data-flow-overview)
- [Quick Start](#-quick-start)
- [Requirements](#requirements)
- [Build](#build)
- [Environment Variables](#environment-variables)
- [First Launch](#first-launch)
- [One-Click Install](#one-click-install)
- [Deployment Guide](#-deployment-guide)
- [Systemd Services](#systemd-services)
- [sudo Configuration](#sudo-configuration)
- [Reverse Proxy](#reverse-proxy-optional)
- [Configuration Reference](#-configuration-reference)
- [Full Config Tree](#full-config-tree)
- [Environment Variable Injection](#environment-variable-injection-table)
- [Module Catalog](#-module-catalog)
- [AI Decision Layer](#ai-decision-layer-comaluerai)
- [Kernel Engine Layer](#kernel-engine-layer-comaluerkernel)
- [Security Defense Layer](#security-defense-layer-comaluersecurity)
- [Operations Control Layer](#operations-control-layer-comaluerconsole)
- [Monitoring Collection Layer](#monitoring-collection-layer-comaluermonitor)
- [Core Service Layer](#core-service-layer-comaluerservice)
- [Web Interaction Layer](#web-interaction-layer-comaluerweb)
- [Notification & Reporting Layer](#notification--reporting-layer-comaluernotification)
- [Auxiliary Modules](#auxiliary-modules)
- [Data Models](#data-models-comaluermodel)
- [Defense Levels & Auto Response](#️-defense-levels--auto-response)
- [API Reference](#-api-reference)
- [System Status API](#system-status-api)
- [Security Posture API](#security-posture-api)
- [Health Check API](#health-check-api)
- [Notification & Report API](#notification--report-api)
- [Console Operations API](#console-operations-api)
- [SSH Gateway API](#ssh-gateway-api)
- [Backup Management API](#backup-management-api)
- [Web Console](#-web-console)
- [Shell Command Reference](#-shell-command-reference)
- [Developer Guide](#-developer-guide)
- [FAQ](#-faq)
- [License](#-license)
- [Support](#-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
```bash
# 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):
```bash
# 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**:
```bash
# ──── 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
```bash
# 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 for AI assistant ║
╚══════════════════════════════════════════════════╝
aluer>
```
Verify everything is working:
```bash
# Test API
curl http://localhost:8080/api/status
# Expected response
{"status":"running","timestamp":1746883200000}
# Access Web Console
curl http://localhost:8080/
```
### One-Click Install
```bash
# Run with sudo
sudo bash install.sh
```
The script will:
1. Detect/install Java 17
2. Create `/opt/serverguard/` working directory
3. Wait for you to upload the jar (via `scp` or other)
4. Auto-create and enable systemd service
5. Start service and verify status
---
## 📦 Deployment Guide
### Systemd Services
The repo provides two systemd unit files:
**`systemd/minecraft.service`** — Minecraft server (Aluer's prerequisite):
```ini
[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:
```ini
[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:
```bash
# 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:
```bash
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:
```nginx
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 |
### 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**:
1. **Sovereign Handshake**: Connection requires handshake approval based on current heat and risk score
2. **Command Guard**: Every command is reviewed by `CommandExecutionGuardService`
3. **Session Timeout**: Auto-disconnect after 30 minutes of inactivity
4. **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
```bash
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
```bash
# 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
```bash
cd frontend
npm install
npm run dev # Dev server at http://localhost:4173
npm run build # Production build → ../src/main/resources/static/
```
### Running Tests
```bash
# 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:
1. Create a new class in `com.aluer.security`
2. Inject `ServerGuardConfig` via constructor
3. Implement `getPosture()` for Kernel consumption
4. Register in `NetworkThreatFusionService` (if network-related)
5. Aggregate in `AluerOperationsCenterService.buildOverview()` (if needed in console)
6. Add config node in `application.yml`
---
## ❓ FAQ
How do I verify AI is working?
```bash
aluer> ask Hello
```
If you get an AI response, DeepSeek is configured correctly. Or check logs:
```bash
tail -f /var/log/serverguard.log | grep DeepSeek
```
Not receiving email alerts?
1. Verify `username`/`password` in email config
2. QQ email requires **authorization code** not login password
3. Check spam folder
4. Run `alert test` to send a test email
Tips for first deployment?
Enable **dry-run mode** first:
```yaml
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](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
