X-SHIELD (anti-cheat)

Version 3.0.0 — Detection Overhaul

This is a substantial rewrite. Detection no longer relies on file names, and several serious issues in 1.x are fixed. Please read the two upgrade notes at the bottom before updating a live server.

🔐 Security fixes

• The config is no longer sent to clients. In 1.x the config was registered as a SERVER config, and NeoForge transmits those to every joining player as a complete file — including the Discord bot token, the channel IDs and the keyword list. It is now a COMMON config, which is never transmitted. If you ran 1.x with a bot token, regenerate it.
• Audit packets are now size-limited and rate-limited. Previously a modified client could send arbitrarily large packets arbitrarily often, filling server RAM and disk.
• Discord mentions are disabled on every message. A player could previously name a mod @everyone and make the bot ping the whole server.

🔍 Detection

• Files are now hashed (SHA-256, SHA-1 and the CurseForge fingerprint) instead of compared by name. Renaming a file no longer defeats detection.
• Resource packs are inspected for what they actually do. The scanner looks for blockstate redirection, hollow-shell block models, forced full brightness, retargeted ore models, core shaders inside a resource pack, and transparent filler textures. This catches x-ray packs that no blacklist has ever seen. Verified against 18 real packs: 10 of 10 x-ray packs detected, 0 of 8 legitimate packs flagged.
• Unpacked (folder) resource packs and the shaderpacks folder are scanned. Both were previously a free bypass.
• Reputation lookup against Modrinth and CurseForge. Files that are known public releases stay quiet, so an SMP where players install their own mods does not drown in alerts.
• Platform screening. Being a known release is not the same as being allowed — x-ray mods sit on both platforms like any other mod. The project title reported by the platform is now checked too, and that title cannot be forged by editing a local file.
• Project blacklist. Block a project by its Modrinth slug or CurseForge mod ID and every version of it is covered, including future ones.
• Integrity heartbeat. The server periodically challenges the client. A client that stops answering is reported, which closes the "install the mod only to get past the login" gap.

⚖ Evidence scoring

Findings are no longer treated as equally serious. Each signal carries a weight, and only the total decides what happens:

• A hash match or a blocked project is proof (100 points).
• The x-ray score scales — 3 of 9 blocks hidden is borderline, 9 of 9 is not.
• A keyword in a file name is worth almost nothing (10 points), because renaming defeats it.
• Weak signals are capped at 50 points combined and can never trigger an automatic action on their own. An automatic kick additionally requires at least one proof-level signal.

🛡 Bans that lift themselves

A ban now remembers the hashes of the files it was issued for. The player removes the file, rejoins, and the ban lifts itself — no admin, no ticket. Four modes are configurable: UNTIL_REMOVED, UNTIL_REMOVED_OR_EXPIRED (default), TIMED and PERMANENT. Repeat offenders can escalate automatically.

In 1.x the class was called TempBan but had no expiry at all — anyone added to it stayed banned forever.

⛏ Persistent ore logging

Ore mining is written to logs/X-Shield PlayerLogs/ore-history/<uuid>.csv with timestamp, session id, dimension and coordinates. It survives restarts and tracks every player by default, so the history exists before someone is flagged — which is when it is most useful. Retention is configurable.

💬 Discord

• One alert per player that is updated in place, instead of a new message on every rescan.
• Findings are paginated with navigation buttons, and the alert body uses the embed description (4096 characters) instead of a field (1024).
• Bot presence shows rotating, aggregated statistics.
• New buttons and commands: /clientaudit ores, /clientaudit stats, /clientaudit altstats, /clientaudit apistatus, /clientaudit bans list|lift.

👥 Alt account correlation (optional)

The server works out which files belong to the shared modpack and compares only what each player has beyond it. A player running nothing but the plain modpack produces no signal at all. Off-by-default IP correlation can be added as a secondary hint, but never triggers a flag on its own.

⚠ Upgrade notes

1. The config moved. It is now config/xshield-server.toml instead of saves/<world>/serverconfig/xshield-server.toml. Copy your settings across; the mod prints a warning on startup if it finds the old file. Regenerate your Discord bot token — the old one was transmitted to every player who joined while 1.x was running.

2. Set a CurseForge API key. Without one, only Modrinth is queried, which recognises roughly 73% of the files on a typical CurseForge modpack. Everything else is reported as an unknown file. A free key from console.curseforge.com cuts that from over 140 entries to a handful on a 280-mod pack.

📊 Data disclosure

With the reputation lookup enabled, the server sends file hashes to api.modrinth.com and api.curseforge.com to identify public releases. No player names, UUIDs or file contents are transmitted, and requests are cached and rate limited. Both lookups can be disabled in the config. If a Discord bot or webhook is configured, the server sends alerts containing player names, UUIDs and the names of flagged files to the Discord channel you configure.