Connection Guard

Connection Guard

Connection rules. Your control.

Free, open-source VPN/proxy checks and country rules for Spigot, BungeeCord and Velocity. Choose your detection providers and what happens when a rule matches.

Download · Set up your server · Get help

MIT licensed. No Connection Guard account or GitHub star is required. External providers have their own quotas and terms; free software does not mean unlimited free lookups.

What you can control

• VPN/proxy checks: select supported providers or configure a custom REST API provider.
• Actions: reject a flagged connection, notify staff, execute a configured command or send a Discord webhook.
• Country rules: use a country allowlist or blocklist and choose the response.
• Multiple-provider voting: choose how many enabled providers must return a positive result.
• Caching: reuse lookup results to reduce repeated requests.
• Connection details: inspect provider-supplied information with /cg info <IP>.

Choose your setup

Download the combined JAR, stop your test server/proxy and install it in the appropriate plugins directory. Confirm successful initialization, choose providers and rules, and test the expected decisions before accepting live players.

Review the defaults: 0.4.10 enables VPN and geo kicks, with CN/RU in its country blocklist. Start with notifications to evaluate your policy before blocking.

Core/Spigot/BungeeCord bytecode targets Java 8; your server may require newer Java. The Velocity adapter targets the 3.3 API and requires Java 17 or newer. Follow your server software's requirements. Folia support is unverified.

Free plugin, provider limits

The default VPN provider is ProxyCheck; the default geo provider is IP-API. The free IP-API endpoint is for non-commercial use, is rate-limited and uses HTTP. Choose providers whose terms permit your use. Provider selection and quota guide links to their official documentation.

VPN and geo lookups may consume separate requests. Caching reduces repeated lookups; it does not remove provider quotas.

Reliability you can inspect

0.4.10 includes 48 passing regression tests and a controlled runtime check on Velocity 3.4.0 / Java 21 for startup, HTTP detection, pre-login rejection, SQLite caching, provider recovery and commands. Read the release checks and compatibility limits.

Tests do not establish real-world VPN detection accuracy. The fixture does not cover full backend joins, every Spigot/BungeeCord/server version, Redis runtime or LuckPerms/Floodgate integration.

If the configured positive VPN vote threshold is not met, the connection proceeds, subject to geo rules and other plugins. An unavailable geo lookup provides no geo verdict. Provider outages and caching.

Connection Guard does not replace an anticheat, a complete antibot system or network-level DDoS protection.

A legitimate player is flagged?

Check the rule, client IP, cached verdict and exemptions. A provider flag is not proof of malicious behavior. Permission exemptions require LuckPerms and the corresponding configuration switch.

Open an issue or use project Discord. Include plugin, platform and Java versions and reproduction steps. Remove keys, webhook URLs and personal connection data from shared settings/logs.

Open source

Source and contribution guide · MIT license. Stars and honest reviews are optional.