ProxyShield

# ProxyShield Anti-VPN and anti-proxy protection for Minecraft servers. Country filtering, Discord webhook alerts, a silent mode and a dry-run mode — one shared detection core with a native build for every platform. | Build | Runs on | |---|---| | `ProxyShield-Paper-2.0.jar` | Paper 1.21+ and forks (Purpur, Pufferfish) | | `ProxyShield-Folia-2.0.jar` | Folia | | `ProxyShield-Bungee-2.0.jar` | BungeeCord / Waterfall | | `ProxyShield-Velocity-2.0.jar` | Velocity 3.3+ | | `ProxyShield-Sponge-2.0.jar` | SpongeAPI 17 | Install **one** jar, on the machine that accepts the connection. On a network that is the proxy — the Paper build behind a proxy would only ever see the proxy's own address. Plain Spigot and CraftBukkit are not supported: scheduling uses `AsyncScheduler` and the per-entity scheduler, which only exist on Paper and its forks. That is the same API that makes Folia work. ## Features **Detection** - Public VPN and proxy IP feeds with correct CIDR matching, IPv4 and IPv6 - Live provider lookup for proxy, VPN, Tor and datacenter flags - Country filtering, blacklist or whitelist mode - Manual blacklist, checked before the feeds and the provider - Choose whether a failed check lets players in or keeps them out **Exemptions** - IP whitelist accepting single addresses, CIDR blocks and ranges - Player name whitelist and a bypass permission - Loopback and private addresses are never checked, and never cost lookup quota **Operations** - **Dry-run mode** — detect and report without disconnecting anybody. Run it for a day first and read `blocks.log` to find false positives before they hit real players. - **Silent mode** — no staff or console alerts, while the log file and the webhook keep recording. Watch the filter without announcing every detection to everyone online. - Discord webhook with queueing, retry and rate-limit handling - Block log at `plugins/ProxyShield/blocks.log` - Full `/proxyshield` command set with tab completion - English and German included; any language by copying one file ## Commands All need `proxyshield.admin`. Aliases: `/ps`, `/antivpn`. | Command | Does | |---|---| | `/proxyshield info` | Version, active mode and list status | | `/proxyshield stats` | Detection counters, cache and webhook state | | `/proxyshield check ` | Runs the full pipeline and explains the verdict | | `/proxyshield lookup ` | Fresh provider lookup, ignoring the cache | | `/proxyshield whitelist [entry]` | Manage the never-block list | | `/proxyshield blacklist [entry]` | Manage the always-block list | | `/proxyshield refresh` | Re-download the feeds | | `/proxyshield recheck` | Re-check everyone online, disconnect whoever fails | | `/proxyshield clearcache` | Drop cached lookup results | | `/proxyshield reload` | Re-read the config and the message file | `/proxyshield check` is the tool for a false-positive report: it walks the whole pipeline and prints what each stage decided, so you can see exactly which rule fired. ## Permissions | Node | Default | Grants | |---|---|---| | `proxyshield.bypass` | op | Skip every check | | `proxyshield.notify` | op | Receive live block alerts | | `proxyshield.admin` | op | Use `/proxyshield` | On Paper, BungeeCord and Sponge no permission data exists yet during the login handshake, so `proxyshield.bypass` only resolves for operators there. For reliable exemptions on those platforms use the name or IP whitelist. On Velocity the permission works normally. ## How a connection is decided Strictly top to bottom, first match wins. Everything that can *allow* a player is evaluated before anything that can block one, so you can always whitelist your way out of a false positive. | # | Check | Result | Cost | |---|---|---|---| | 1 | Bypass permission | allow | none | | 2 | Name on the player whitelist | allow | none | | 3 | IP on the whitelist | allow | none | | 4 | Loopback or private address | allow | none | | 5 | IP on the blacklist | **block** | none | | 6 | IP in a downloaded feed | **block** | ~0.6 µs | | 7 | Provider reports a proxy | **block** | one request per uncached IP | | 8 | Provider reports hosting | **block** | same request | | 9 | Country not permitted | **block** | same request | Steps 1 to 6 never touch the network. ## Performance Measured with the four default feeds, 62,555 entries compiled into 35,161 merged ranges: | | | |---|---| | Memory held | 1.3 MB | | Startup parse | 259 ms, on a background thread | | Feed check per login | 589 ns | | 1000 logins | 0.59 ms total, about 1/85th of one tick | The provider lookup is the only part with real latency, typically 50–200 ms. It runs off the main thread on every platform, so it delays that one player's login and never the server tick. Set `use-api: false` for a feed-only setup with zero network traffic per login. ## Configuration Everything behaves identically on all five platforms and lives in one `config.yml`. Player facing text is separate, in `messages_en.yml` / `messages_de.yml`, so you can translate or reword anything without touching the jar. ```yaml detection: dry-run: false # detect and report, never kick block-proxy: true block-hosting: true country: enabled: true mode: whitelist # only these countries may connect codes: ["DE", "AT", "CH"] notifications: silent: false # true = log and webhook only, no live alerts ``` ## Support Questions and bug reports: [dc.gg/paperstream](https://dc.gg/paperstream)