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: ["cool-mod:", "cool"] # Channel patterns (wildcards supported) brands: ["coolclient"] # 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> [punishment]` | 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. They see a chat message explaining what was restricted.

---

Troubleshooting

A clean player got flagged

Check the console logs for the `[DETECT]` line. If the detection looks wrong, report it with the full log output.

A mod isn't being detected

Most often the translation keys in your config don't match what the mod actually uses. Pull the real keys from the mod's JAR (`assets/<modid>/lang/en_us.json`) and paste them into the config under that mod's `keys:` list.

"Scan timeout" appears in logs

The player's client didn't respond to the verification check. This usually means they have a protection mod installed or there's severe network latency. Decide whether to treat this as suspicious or allow it based on your server's policy.

Sign placement failed

A protection plugin (WorldGuard, etc.) is blocking block placement at the player's location. Whitelist ModGuard in your region protection plugin, or add a bypass region near your spawn.

Player has stuck blindness

Shouldn't happen but if it does: `/effect clear <player>`.

`/mg reload` didn't apply a change

The `rescan-interval-ticks` setting requires a full server restart. Everything else reloads live.

---

Limitations to know about

- Some mods can't be detected. Pure texture-based X-ray mods and mods with no translation keys or plugin channels have no unique signature. No detection plugin can catch these without a client-side helper. - Xaero's World Map can still be opened with M even when "disable" is set — only cave mode and radar are restricted. This is a limitation of Xaero's compliance protocol. - Version mismatches through ViaVersion can occasionally affect detection accuracy. Most modern versions (1.20+) work fine. - Detection ≠ cheating. A player having Freecam installed doesn't mean they used it. Consider using `log` punishment for ambiguous mods during initial rollout so you can see what your players run before deciding on stricter action.

---

Tips

- Test with an alt account before deploying. Join with various mods and watch the logs. - Start with `log` punishment for new mod entries to see detection patterns before enabling `kick`/`ban`. - Watch the console — `[DETECT]` lines show exactly what was caught and why. - Keep keys updated — mod authors occasionally rename translation keys between versions. Re-pull keys from the JAR if detection stops working for a previously-caught mod.

Developed by waffleboiiiiii %%MD0%%