SerendiModGuarder

SerendiModGuarder 🛡️

English · 中文

English

SerendiModGuarder is a Fabric mod that detects and blocks players using forbidden client-side mods. Both server and client must install this mod.

How It Works

SerendiModGuarder uses a three-layer defense to catch cheat mods:

Features

• ✅ Three-layer defense — SHA256-signed login query + play-phase push + delayed channel scan
• ✅ Anti-tamper — Mod list is signed with SHA256 + server nonce; tampering is detected
• ✅ Configurable blacklist — Manage forbidden mod keywords via config/serendimodguarder.json
• ✅ Hot reload — /serendimodguarder reload applies config changes without restart
• ✅ Manual inspection — /serendimodguarder check <player> shows detailed verification state and plugin channels
• ✅ Configurable timeout — Login query timeout (default 10s); unresponsive clients are kicked
• ✅ Customizable messages — Separate messages for kick, "must install", and timeout

Requirements

• Minecraft 1.21.5 (26.2)
• Fabric Loader ≥0.19.3
• Fabric API (any version compatible with 1.21.5)
• Clients must also install SerendiModGuarder — otherwise they will be kicked

Installation

1. Place the JAR in the server's mods/ folder
2. All players must also install the mod on their client's mods/ folder
3. Restart the server (clients restart or reconnect)
4. Config file auto-generated at config/serendimodguarder.json
5. Customize the forbidden mod list to your needs
6. Run /serendimodguarder reload to apply changes

Commands

Configuration

Generated at config/serendimodguarder.json on first run:

{
  "enabled": true,
  "debugMode": false,
  "loginTimeoutSeconds": 10,
  "kickMessage": "§c检测到你正在使用违规Mod: §e%mod%\n§c请移除后重新加入服务器！\n§7若您未使用作弊Mod，请确保安装了 §eSerendiModGuarder §7后再进入。",
  "mustInstallMessage": "§c本服务器要求必须安装 §eSerendiModGuarder §c才能进入！\n§7请访问服务器官网或联系管理员获取 Mod 文件。",
  "timeoutMessage": "§c登录验证超时！\n§7请确保安装了 §eSerendiModGuarder §7，然后重新加入。",
  "forbiddenMods": [
    "meteor", "wurst", "aoba", "bthack", "catlean",
    "eternity", "minced", "pubdlc", "thunderhack",
    "liquidbounce", "augustus", "aristois", "future",
    "impact", "lambda", "novoline", "phobos",
    "rusherhack", "salhack", "seppuku", "sigtools",
    "weepcraft", "xray", "jello", "inertia",
    "bleach", "nightx", "youtube", "kami",
    "forgehax", "exeter", "crystallix"
  ]
}

Fields

Build

./gradlew build

Output: build/libs/SerendiModGuarder-<version>.jar

License

This project is licensed under the GNU General Public License v3.0 (GPL-3.0). See the LICENSE file for details.

Acknowledgements

This project references the design of InertiaAntiCheat (Copyright © 2023 DiffuseHyperion, GPL-3.0).

中文

SerendiModGuarder 是一款 Fabric Mod，用于检测并拦截使用了违规客户端 Mod 的玩家。服务端和客户端都必须安装本 Mod。

工作原理

SerendiModGuarder 采用 三道防线 来检测作弊 Mod：

功能特性

• ✅ 三道防线 — SHA256 签名登录查询 + 游戏阶段推送 + 延迟频道扫描
• ✅ 防篡改 — Mod 列表使用 SHA256 + 服务端随机数签名，篡改可被检测
• ✅ 可配置黑名单 — 通过 config/serendimodguarder.json 管理违禁 Mod 关键词
• ✅ 热重载 — /serendimodguarder reload 即时生效，无需重启
• ✅ 手动检查 — /serendimodguarder check <玩家> 查看详细验证状态和频道信息
• ✅ 超时控制 — 登录查询超时（默认 10 秒），未响应客户端自动踢出
• ✅ 自定义消息 — 踢出、强制安装、超时等消息均可自定义

运行环境

• Minecraft 1.21.5（26.2）
• Fabric Loader ≥0.19.3
• Fabric API（与 1.21.5 兼容的任意版本）
• 客户端必须同时安装 SerendiModGuarder，否则将被踢出

安装方法

1. 将 JAR 放入服务端的 mods/ 文件夹
2. 所有玩家也必须在客户端安装本 Mod，放入 mods/ 文件夹
3. 重启服务端（客户端重启或重新连接）
4. 配置文件自动生成在 config/serendimodguarder.json
5. 根据需要编辑配置文件中的违禁 Mod 列表
6. 在服务器中执行 /serendimodguarder reload 使配置生效

指令

配置说明

首次运行自动生成于 config/serendimodguarder.json：

{
  "enabled": true,
  "debugMode": false,
  "loginTimeoutSeconds": 10,
  "kickMessage": "§c检测到你正在使用违规Mod: §e%mod%\n§c请移除后重新加入服务器！\n§7若您未使用作弊Mod，请确保安装了 §eSerendiModGuarder §7后再进入。",
  "mustInstallMessage": "§c本服务器要求必须安装 §eSerendiModGuarder §c才能进入！\n§7请访问服务器官网或联系管理员获取 Mod 文件。",
  "timeoutMessage": "§c登录验证超时！\n§7请确保安装了 §eSerendiModGuarder §7，然后重新加入。",
  "forbiddenMods": [
    "meteor", "wurst", "aoba", "bthack", "catlean",
    "eternity", "minced", "pubdlc", "thunderhack",
    "liquidbounce", "augustus", "aristois", "future",
    "impact", "lambda", "novoline", "phobos",
    "rusherhack", "salhack", "seppuku", "sigtools",
    "weepcraft", "xray", "jello", "inertia",
    "bleach", "nightx", "youtube", "kami",
    "forgehax", "exeter", "crystallix"
  ]
}

配置项

防线详解

第 1 道防线 — 登录查询：

1. 玩家连接服务器时，服务端发送一个随机数（nonce）
2. 已安装本 Mod 的客户端返回完整 Mod 列表 + SHA256 签名
3. 服务端验证签名：若签名不匹配则判定为数据被篡改
4. 检查 Mod 列表中是否包含违禁 Mod
5. 若客户端未安装本 Mod（未响应），则踢出并提示强制安装

第 2 道防线 — 游戏阶段推送：

1. 玩家加入游戏后 2 秒，客户端主动推送 Mod 列表
2. 服务端再次检查违禁 Mod
3. 可捕获在登录完成后才加载的 Mod

第 3 道防线 — 延迟验证（T+60 秒）：

1. 玩家加入 60 秒后，服务端检查其注册的 Fabric 插件频道
2. 许多作弊 Mod 会在频道中暴露特征标识
3. 交叉比对登录阶段和游戏阶段的 Mod 列表
4. 对异常情况（如 Mod 多但频道少）记录日志

构建

./gradlew build

输出文件：build/libs/SerendiModGuarder-<version>.jar

开源许可证

本项目基于 GNU General Public License v3.0（GPL-3.0） 开源。详见 LICENSE 文件。

致谢

本项目参考了 InertiaAntiCheat（Copyright © 2023 DiffuseHyperion，GPL-3.0）的设计思路。