Aluer/README_EN.md

<div align="right">

**简体中文** · [**English**](README.md)

</div>

<div align="center">

<img src="https://raw.githubusercontent.com/tandpfun/skill-icons/main/icons/Java-Dark.svg" width="48" height="48" />
<img src="https://raw.githubusercontent.com/tandpfun/skill-icons/main/icons/Spring-Dark.svg" width="48" height="48" />
<img src="https://raw.githubusercontent.com/tandpfun/skill-icons/main/icons/React-Dark.svg" width="48" height="48" />

</div>

<p align="center">
  <img src="https://img.shields.io/badge/Java-17%2B-orange?logo=openjdk&logoColor=white&style=for-the-badge" alt="Java">
  <img src="https://img.shields.io/badge/Spring_Boot-3.2.0-6DB33F?logo=springboot&logoColor=white&style=for-the-badge" alt="Spring Boot">
  <img src="https://img.shields.io/badge/React-19.1-61DAFB?logo=react&logoColor=black&style=for-the-badge" alt="React">
  <img src="https://img.shields.io/badge/Vite-6.3-646CFF?logo=vite&logoColor=white&style=for-the-badge" alt="Vite">
  <img src="https://img.shields.io/badge/DeepSeek-AI-536DFE?logo=openai&logoColor=white&style=for-the-badge" alt="DeepSeek AI">
  <img src="https://img.shields.io/badge/License-Apache_2.0-blue?logo=apache&logoColor=white&style=for-the-badge" alt="License">
</p>

<p align="center">
  <a href="https://github.com/ZpjDev/Aluer/stargazers"><img src="https://img.shields.io/github/stars/ZpjDev/Aluer?style=for-the-badge&logo=github&color=f1c40f&labelColor=1a1a2e" alt="Stars"></a>
  <a href="https://github.com/ZpjDev/Aluer/network/members"><img src="https://img.shields.io/github/forks/ZpjDev/Aluer?style=for-the-badge&logo=github&color=3498db&labelColor=1a1a2e" alt="Forks"></a>
  <a href="https://github.com/ZpjDev/Aluer/issues"><img src="https://img.shields.io/github/issues/ZpjDev/Aluer?style=for-the-badge&logo=github&color=e74c3c&labelColor=1a1a2e" alt="Issues"></a>
  <a href="https://github.com/ZpjDev/Aluer/pulls"><img src="https://img.shields.io/github/issues-pr/ZpjDev/Aluer?style=for-the-badge&logo=github&color=2ecc71&labelColor=1a1a2e" alt="PRs"></a>
  <a href="https://github.com/ZpjDev/Aluer/commits/main"><img src="https://img.shields.io/github/last-commit/ZpjDev/Aluer?style=for-the-badge&logo=git&color=9b59b6&labelColor=1a1a2e" alt="Last Commit"></a>
</p>

---

<h1 align="center">
  <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Shield.png" width="36" height="36" />
  Aluer ServerGuard
  <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Shield.png" width="36" height="36" />
</h1>

<p align="center">
  <strong>🛡️ AI-Powered Minecraft PaperMC Server Security & Automation Platform</strong>
</p>

<p align="center">
  <sub>Built with ❤️ for Minecraft server operators who refuse to compromise on security</sub>
</p>

<blockquote align="center">
  <p>
    <i>"In a world where DDoS attacks, bot swarms, and zero-day exploits threaten your Minecraft community,<br>Aluer stands as the autonomous guardian — powered by DeepSeek AI and a multi-layer kernel fusion engine."</i>
  </p>
</blockquote>

<p align="center">
  <a href="#-system-architecture">🏗 Architecture</a> &nbsp;·&nbsp;
  <a href="#-quick-start">🚀 Quick Start</a> &nbsp;·&nbsp;
  <a href="#-configuration">⚙️ Config</a> &nbsp;·&nbsp;
  <a href="#-modules">📦 Modules</a> &nbsp;·&nbsp;
  <a href="#-api-reference">🌐 API</a> &nbsp;·&nbsp;
  <a href="#-web-console">🖥 Console</a> &nbsp;·&nbsp;
  <a href="#-commands">💻 Commands</a> &nbsp;·&nbsp;
  <a href="#-faq">❓ FAQ</a>
</p>

<hr>

<table align="center">
  <tr>
    <td align="center" width="140">
      <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Travel%20and%20places/Rocket.png" width="32" height="32" /><br>
      <strong>2-5s</strong><br>
      <sub>LLM Response</sub>
    </td>
    <td align="center" width="140">
      <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Electric%20Plug.png" width="32" height="32" /><br>
      <strong>&lt;1ms</strong><br>
      <sub>Kernel Latency</sub>
    </td>
    <td align="center" width="140">
      <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Locked%20with%20Key.png" width="32" height="32" /><br>
      <strong>4-Tier</strong><br>
      <sub>Defense Levels</sub>
    </td>
    <td align="center" width="140">
      <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Smilies/Alien%20Monster.png" width="32" height="32" /><br>
      <strong>30+</strong><br>
      <sub>Security Modules</sub>
    </td>
    <td align="center" width="140">
      <img src="https://raw.githubusercontent.com/Tarikul-Islam-Anik/Animated-Fluent-Emojis/master/Emojis/Objects/Bar%20Chart.png" width="32" height="32" /><br>
      <strong>~200MB</strong><br>
      <sub>Memory Footprint</sub>
    </td>
  </tr>
</table>

<hr>

## 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?

<table>
  <tr>
    <td width="50%">
      <h3>🧠 Dual-Engine Intelligence</h3>
      <p>LLM (DeepSeek) + Kernel Rule Engine working in tandem. Sovereign handles unknown threats; Kernel reacts in <1ms for known patterns. <b>No single point of decision failure.</b></p>
    </td>
    <td width="50%">
      <h3>🛡️ Full-Stack Defense</h3>
      <p>From Minecraft protocol layer → Application WAF → OS firewall → Cloudflare edge. <b>30+ security modules</b> covering L3-L7, zero-trust architecture, and honeypot deception.</p>
    </td>
  </tr>
  <tr>
    <td>
      <h3>📊 Real-Time Visualization</h3>
      <p>React 19 Nebula Console with SSE live streaming, performance sparklines, health probes, auto-refresh — designed for <b>incident commanders</b> who need instant clarity.</p>
    </td>
    <td>
      <h3>🔧 Autonomous Operations</h3>
      <p>Self-healing orchestration, auto-backup before recovery, scheduled tasks, Discord/Slack webhooks, and HTML attack reports. <b>Your server guards itself while you sleep.</b></p>
    </td>
  </tr>
</table>

---

## 🧬 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 <question> 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 65+ security services (with 25 Super Evolution v3.2 modules):

| 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%) |
| **Minecraft-Specific** | `AntiXrayDetectionService` | X-ray detection: diamond/stone ratio, straight-line mining, dark precision |
| | `AntiFlyDetectionService` | Fly/speed/teleport hack detection: vertical/horizontal limits, air time |
| | `AntiDupeDetectionService` | Item duplication detection: stack overflow, high-value item surges, 9 known methods |
| | `CrashExploitProtectionService` | Crash exploit protection: oversized packets, NBT bombs, book/sign exploits |
| | `LagMachineDetectionService` | Lag machine detection: observer chains, TNT stacks, entity spam, falling blocks |

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

<details>
<summary><strong>How do I verify AI is working?</strong></summary>

```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
```
</details>

<details>
<summary><strong>Not receiving email alerts?</strong></summary>

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
</details>

<details>
<summary><strong>Tips for first deployment?</strong></summary>

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

<details>
<summary><strong>Why two decision engines? Won't they conflict?</strong></summary>

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`.
</details>

<details>
<summary><strong>Performance overhead?</strong></summary>

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)
</details>

---

## 📄 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:

<p align="center">
  <a href="https://github.com/ZpjDev/Aluer"><img src="https://img.shields.io/badge/⭐_Star_this_repo-f1c40f?style=for-the-badge&logo=github" alt="Star"></a>
  &nbsp;
  <a href="https://github.com/ZpjDev/Aluer/fork"><img src="https://img.shields.io/badge/🍴_Fork-3498db?style=for-the-badge&logo=github" alt="Fork"></a>
  &nbsp;
  <a href="https://github.com/ZpjDev/Aluer/issues"><img src="https://img.shields.io/badge/🐛_Report_Bug-e74c3c?style=for-the-badge&logo=github" alt="Bug"></a>
  &nbsp;
  <a href="https://github.com/ZpjDev/Aluer/discussions"><img src="https://img.shields.io/badge/💬_Discussions-2ecc71?style=for-the-badge&logo=github" alt="Discuss"></a>
</p>

---

<h2 align="center">🏆 Contributors</h2>

<p align="center">
  <a href="https://github.com/ZpjDev/Aluer/graphs/contributors">
    <img src="https://contrib.rocks/image?repo=ZpjDev/Aluer&max=12" />
  </a>
</p>

<p align="center">
  <sub>Made with ❤️ by the Aluer community — defending Minecraft servers worldwide</sub>
</p>

---

<p align="center">
  <a href="https://github.com/ZpjDev/Aluer">
    <img src="https://img.shields.io/github/repo-size/ZpjDev/Aluer?style=flat-square&label=Repo%20Size&color=3498db" alt="Repo Size">
  </a>
  <a href="https://github.com/ZpjDev/Aluer/blob/main/LICENSE">
    <img src="https://img.shields.io/github/license/ZpjDev/Aluer?style=flat-square&label=License&color=2ecc71" alt="License">
  </a>
  <img src="https://img.shields.io/badge/Built%20With-Java%2017%20%7C%20Spring%20Boot%203.2%20%7C%20React%2019%20%7C%20DeepSeek%20AI-536DFE?style=flat-square" alt="Built With">
  <br>
  <sub>Aluer ServerGuard v1.0.0 — Autonomous protection for your Minecraft community</sub>
</p>