Sentinel&ModGuard

🛡️ ModGuard + Sentinel — Client Verification System

A server plugin + client mod security system that verifies legitimate clients and detects malicious modifications using a secure encrypted handshake — far more reliable than client-brand checks or simple mod name detection.

Discord

Modrinth

GitHub

---

📦 Components

🔌 ModGuard — Server Plugin Sends encrypted challenges to connecting players, verifies responses, checks mod IDs against a blacklist, enforces a minimum Sentinel version, and optionally limits total installed mods. Supports cracked servers, Geyser/Floodgate auto-bypass, configurable kick messages, player whitelist, and persistent mod history.

🧩 Sentinel — Client Mod Installed by the player on their Fabric client. Receives the server challenge, collects the full mod list via FabricLoader, encrypts and returns it. Zero configuration. Zero performance impact.

---

⚙️ How It Works

``` Player joins → Server sends encrypted challenge (RSA-2048 + nonce + HMAC-SHA256 secret) → Sentinel collects mod list via FabricLoader → Sentinel encrypts response (AES-256-GCM, key wrapped with RSA/OAEP/SHA-256) → Server decrypts, verifies HMAC, checks protocol version + Sentinel version → Mod list checked against blacklist and optional count limit → Player approved or kicked with a configurable message ```

---

🚀 Installation

Server: 1. Drop `ModGuard.jar` into `plugins/` 2. Restart — `plugins/ModGuard/config.yml` and `modblacklist.json` are generated automatically

Client: 1. Drop the correct `Sentinel-<version>.jar` into `.minecraft/mods/` 2. Launch — no configuration needed

---

🔒 Security

- RSA-2048 keypair generated fresh per server session — never written to disk - AES-256-GCM authenticated encryption — ciphertext is tamper-proof - HMAC-SHA256 payload signing — server secret is never sent to the client - Nonce included in every challenge — replay attacks are not possible - Protocol version verified inside the encrypted payload — cannot be spoofed by a fake Sentinel - Minimum Sentinel version enforcement — kick players running outdated client mods

---

🚫 Default Blacklisted Mods

Pre-seeded in `modblacklist.json` on first run:

`meteor-client` · `impact` · `wurst` · `liquidbounce` · `aristois` · `sigma` · `thunderhack` · `wolfram` · `baritone` · `freecam` · `marlows-crystal-optimizer`

> Add or remove any mod ID via `/modguard blacklist add <modid>` or by editing `modblacklist.json` directly.

---

💻 Commands

Permission: `modguard.admin` (OP by default)

| Command | Description | |---|---| | `/modguard blacklist <add|remove|list>` | Manage mod blacklist | | `/modguard whitelist <add|remove|list>` | Manage player whitelist (bypasses verification) | | `/modguard mods <player>` | View a player's verified mod list and last seen time | | `/modguard check <player>` | Re-send a verification challenge to an online player | | `/modguard status` | Show online players, pending verifications, and plugin info | | `/modguard reload` | Reload configuration |

---

⚙️ Configuration

File: `plugins/ModGuard/config.yml`

```yaml offline-mode: false # set true for cracked servers allow-floodgate: true # Bedrock players via Geyser bypass verification

challenge-timeout-seconds: 15 # seconds client has to respond challenge-delay-ticks: 40 # delay before sending challenge after join

min-sentinel-version: "1.0.0" # kick players below this Sentinel version protocol-version: 1 # must match Sentinel — only change if you update both

enable-mod-count-limit: false max-mod-count: 50

show-mod-list-in-console: true highlight-banned-mods: true

kick-messages: missing-sentinel: "&cSentinel mod is required to join this server." banned-mod: "&cAccess denied." outdated-sentinel: "&cYour Sentinel mod is outdated. Please update to &ev{version}&c." protocol-mismatch: "&cSentinel version mismatch. Please update your Sentinel mod." timeout: "&cVerification timed out." mod-count-exceeded: "&cToo many mods installed. Maximum allowed: &e{max}" ```

---

📋 Compatibility

| Scenario | Behavior | |---|---| | Fabric client with Sentinel | Full verification | | Vanilla client (no mods) | Handled automatically — no Sentinel required | | Bedrock / Geyser | Bypassed automatically | | Cracked / offline server | Supported via `offline-mode: true` | | Forge / NeoForge | Not supported | | Whitelisted player | Skips verification |

---

🔧 Requirements

- Paper / Spigot 1.21.x · Java 21+ - Geyser + Floodgate *(optional, for Bedrock auto-bypass)*

---

💬 Join our Discord for support, downloads, and updates 🔗 More plugins by Treamhiler 🐙 GitHub