WardenGuard

WardenGuard

WardenGuard is a cross-server ban enforcement plugin that connects your Minecraft server to the centralized WardenGuard. Keep banned players off your server automatically, detect alt accounts, and contribute to a shared ban database with your community.

---

Features

Ban Enforcement

- Checks players against the WardenGuard ban network on every join - 3-tier ban level system - configure which severity triggers an auto-kick - Local ban cache with configurable sync interval (default: every 5 minutes) - Fallback enforcement from cache if the API is temporarily unreachable - Retry queue for failed checks - no join goes unverified

Alt Account Detection

- Detects linked accounts via exact IP match or /24 subnet matching - Configurable action: kick or staff-warn only - Set a minimum ban level threshold to filter false positives - Logs all detected alts, even those without active bans

Ban Reporting

- `/wg report <player>` generates a direct report URL for any online or recently seen player - Automatic reporting when a ban is issued via LiteBans, AdvancedBan, or BanManager - Staff receive clickable report links in chat (Spigot/Paper only)

Staff Tools

- `/wg check <player>` - look up a player's ban cache status by name or UUID - `/wg scan` - scan all online players against the ban list - `/wg sync` - force an immediate ban list refresh - `/wg status` and `/wg ping` - monitor API connectivity and configuration - Recent player cache: commands work on players who left within the last 30 minutes

---

Platform Support

| Platform | Min Version | |----------|-------------| | Spigot / Paper | 1.21.4 |

Java 17 or newer is required.

---

Soft Dependencies (optional integrations)

- BanManager - auto-reports bans to WardenGuard on issue - BanManager - auto-reports bans to WardenGuard on issue - BanManager - auto-reports bans to WardenGuard on issue

---

Commands and Permissions

| Command | Permission | Description | |---------|------------|-------------| | `/wg report <player>` | `wardenguard.staff` | Generate a ban report URL | | `/wg check <player>` | `wardenguard.staff` | Check a player's ban status | | `/wg sync` | `wardenguard.admin` | Force ban list sync | | `/wg scan` | `wardenguard.admin` | Scan all online players | | `/wg status` | `wardenguard.admin` | Show API status and config | | `/wg ping` | `wardenguard.admin` | Test API connectivity | | `/wg reload` | `wardenguard.admin` | Reload config.yml |

Additional permission: `wardenguard.bypass` - exempt a player from automatic ban enforcement.

---

Configuration

WardenGuard is configured via `config.yml`. Key options:

```yaml wardenguard: api_key: "your_api_key_here" api_url: "https://wardenguard.com/api/v1" auto_ban_level: 2 # 1, 2, 3, or 0 to disable auto-ban sync_interval_seconds: 300 # how often to pull full ban list (default 5 min) check_on_join: true # check player via API on every join notify_staff_on_ban: true # send report URL to staff chat after ban staff_permission: "wardenguard.staff" alt_detection: enabled: true kick_enabled: true # kick on alt match (false = warn staff only) min_ban_level: 2 # only trigger for linked accounts at this level or higher include_subnet: false # also flag /24 subnet matches (higher false positive rate) log_all: true # also log alts with no active ban kick_message: "Your account is linked to a banned player ({linked}). Appeal at wardenguard.com/appeal" warn_staff: "{player} flagged as potential alt of {linked} (Level {level} ban: {reason})" warn_staff_all: "{player} shares an IP with {linked} (no active ban)" messages: banned_message: "You are banned from this network. Appeal at wardenguard.com/appeal" report_url_message: "Submit your ban report: {url}" not_banned: "{player} is not on the Warden Guard ban list." is_banned: "{player} is BANNED (Level {level}): {reason}" sync_complete: "Ban list synced. {count} bans loaded." warn_staff_on_join: "{player} joined with a Level {level} ban: {reason}" warn_staff_on_kick: "{player} tried to join but was blocked - Level {level} ban: {reason}" ```

All messages are fully customizable. Available placeholders: `{player}`, `{level}`, `{reason}`, `{linked}`, `{url}`, `{count}`.

---

Getting Started

1. Register your server at wardenguard.com to obtain an API key. 2. Drop the correct jar for your platform into your `plugins/` or `mods/` folder. 3. Start the server and add your `api_key` to `plugins/WardenGuard/config.yml`. 4. Reload with `/wg reload` or restart the server.

---

Links

- Website: wardenguard.com - Ban Feed: wardenguard.com/feed - Support: wardenguard.com