🛡️ 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.

---

📦 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

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