Anti-VPN and anti-proxy protection with country filtering, Discord alerts, a silent mode and a dry-run mode.
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.logto 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
/proxyshieldcommand 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 <player|ip> |
Runs the full pipeline and explains the verdict |
/proxyshield lookup <player|ip> |
Fresh provider lookup, ignoring the cache |
/proxyshield whitelist <add|remove|list> [entry] |
Manage the never-block list |
/proxyshield blacklist <add|remove|list> [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.
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
Pinned Versions
- R1.21–1.21.111.213.3–3.5
Pages
Members
1Owner