ModGuard

# ModGuard **Server-side mod and hack-client detection for Paper/Spigot Minecraft servers. Detects disallowed client modifications and kicks, bans, logs, or restricts them based on your rules. No client-side companion mod required.** --- ## Requirements - Paper 1.21 or later - Java 21 or later - Optional: ViaVersion for cross-version client support --- ## Installation 1. Drop `ModGuard.jar` into your server's `plugins/` folder 2. Restart the server 3. Edit `plugins/ModGuard/config.yml` and `plugins/ModGuard/messages.yml` 4. Run `/mg reload` to apply changes --- ## Configuration `config.yml` ```yaml settings: punishment: kick # Default: kick, ban, log, disable log-detections: true # Log to console notify-admins: true # Alert players with modguard.notify scan-delay-ticks: 20 rescan-interval-ticks: 1200 bypass-uuids: detection: brand: true channels: true sign-scan: true scan-protection: blackout: true # Black screen during verification freeze-movement: true block-inputs: true prevent-damage: true prevent-falling: true minimap-control: enabled: false # Restrict minimaps for ALL players xaero-minimap: true xaero-worldmap: true journeymap: true voxelmap: true ``` ## Adding a blocked mod ### Minimum required: ```yaml mods: cool-mod: name: "Cool Mod" punishment: kick ``` ### Full options: ```yaml mods: cool-mod: name: "Cool Mod" channels: # Channel patterns (wildcards supported) brands: # Client brand strings keys: # Translation keys from the mod's lang file - "key.cool-mod.toggle" - "category.cool-mod" punishment: ban # kick / ban / log / disable ``` If you don't specify `channels:` or `keys:`, sensible defaults are auto-generated from the mod's ID. ## Punishment types | Type | Behavior | |------|----------| | `kick` | Disconnect with a kick message | | `ban` | Add to the server banlist | | `log` | Record the detection, take no action | | `disable` | Restrict the mod's features (Xaero, JourneyMap, VoxelMap only) | When multiple mods are detected with different punishments, the harshest applies: `ban` > `kick` > `disable` > `log`. ### Finding translation keys for a mod Some mods need specific translation keys that can't be auto-generated. To find them: 1. Open the mod's JAR file with any zip tool (7-Zip, WinRAR, or rename to `.zip`) 2. Navigate to `assets/<modid>/lang/en_us.json` 3. Copy the keys from that file into your config under `keys:` `messages.yml` All player-facing text is customizable. Supports MiniMessage formatting and these placeholders: - `{player}` — player name - `{mods}` — comma-separated detected mod names - `{count}` — number of detected mods - `{server}` — server name ```yaml kick: "<red><b>ModGuard</b></red> <dark_gray>»</dark_gray> <white>Blocked: <yellow>{mods}</yellow></white>" ban: "<red>You have been banned for using: <yellow>{mods}</yellow></red>" ``` --- ## Commands **All commands are aliased as `/mg` or `/modguard`.** | Command | Description | |---------|-------------| | `/mg reload` | Reload config.yml and messages.yml | | `/mg list` | List all configured mods | | `/mg info <mod-id>` | Details about a specific mod entry | | `/mg add <id> <name> ` | Add a mod to the blocklist | | `/mg remove <id>` | Remove a mod from the blocklist | | `/mg check <player>` | Check a player | | `/mg scan <player>` | Force a full scan on a player | --- ## Permissions | Permission | Default | Description | |------------|---------|-------------| | `modguard.admin` | op | Grants all permissions | | `modguard.reload` | op | `/mg reload` | | `modguard.list` | op | `/mg list` | | `modguard.info` | op | `/mg info` | | `modguard.add` | op | `/mg add` | | `modguard.remove` | op | `/mg remove` | | `modguard.check` | op | `/mg check` and `/mg scan` | | `modguard.notify` | false | Receive detection alerts | | `modguard.bypass` | false | Skip ALL checks | | `modguard.bypass.<modid>` | false | Skip checks for one specific mod | --- ## Included default detections - Wurst Client (ban) - Meteor Client (ban) - Advanced XRay (ban) - Baritone (kick) - Freecam — hashalite and Zergatul (kick) - Xaero's Minimap & World Map (disable → fair-play mode) - JourneyMap (disable) - VoxelMap (disable) Edit, remove, or add to any of these in `config.yml`. --- ## What players experience ### Clean players Brief "Verifying your client..." screen during the normal "Loading terrain" phase, then gameplay as usual. Most players won't notice any extra wait. ### Players with blocked mods Disconnected with the configured kick or ban message before they can load into the world. ### Players with "disable"-punished mods Join normally. Their minimap's cave mode and entity radar are disabled; their JourneyMap/VoxelMap are restricted.