Crowz Anti VPN

The only anti-VPN plugin that doesn't rely on a single point of failure.

---

Why Crowz Anti VPN?

Most anti-VPN plugins use one detection method — a single API call. If that API is down, rate-limited, or the VPN provider isn't in their database, the player walks right through.

Crowz Anti VPN runs 5 independent detection strategies in parallel on every connection. If one fails, the other four still catch the VPN. If all five are inconclusive, it fails closed — blocking the connection rather than letting it through.

Feature	Crowz Anti VPN	Other Plugins
Detection strategies	5 parallel	Usually 1
Fail-closed on API outage	✅	❌
Tor exit node detection	✅ (DNS-based, no API key)	Rarely
ASN/ISP hosting analysis	✅	Sometimes
ProxyCheck.io integration	✅	Common
IPQualityScore integration	✅	Rare
Discord webhook alerts	✅	Sometimes
Country whitelist	✅	Rare
Aggressive mode toggle	✅	Rare
Per-risk-level actions	✅	❌
Rate limiting & caching	✅	❌

---

How it works

Every time a player connects, Crowz Anti VPN runs all 5 strategies simultaneously:

1. ASN Check — Queries ip-api.com for ASN/ISP data. Compares against known hosting providers (AWS, DigitalOcean, OVH, Hetzner, etc.) and known VPN ASNs. Also checks ip-api.com's built-in proxy and hosting flags.

2. Hosting Provider Check — Same ip-api.com data, but analyzes ISP/org name keywords. Classifies IPs as hosting (datacenter/VPS) vs consumer (residential). Hosting IPs are flagged as potential VPNs.

3. Tor Exit Node Check — DNS-based Tor exit node lookup using the official Tor Project DNSBL. No API key needed, no HTTP calls. Works instantly.

4. ProxyCheck.io API — Queries proxycheck.io's database for VPN/proxy status, risk score, and type classification. (Requires free API key)

5. IPQualityScore API — Queries ipqualityscore.com for fraud scoring, VPN/proxy/Tor detection, and bot identification. (Requires free API key)

All results are aggregated: if any strategy confirms a VPN, the player is blocked. If most strategies can't get a result (API outage), the system escalates to MEDIUM risk — blocking the player rather than letting them through undetected.

Results are cached for 1 hour (configurable) so repeat join attempts are instant.

---

Features

Detection

• 5 parallel detection strategies
• Fail-closed aggregation
• Tor exit node detection (no API key)
• ASN/ISP hosting analysis
• ProxyCheck.io & IPQualityScore integration
• Aggressive mode for stricter flagging
• Configurable hosting ASN list
• Per-IP & per-player whitelist
• Country whitelist (allow only specific countries)
• Rate-limited API calls (avoids hitting free tier caps)

Actions

• Per-risk-level actions: none, notify, warn, kick, ban
• Customizable kick messages & ban reasons
• Console command execution on detection
• Discord webhook alerts with full player/IP/risk info

Commands

• /antivpn check <player|ip> — Check an IP
• /antivpn lookup <player|ip> — Detailed check
• /antivpn stats — Cache hit ratio, total checks, etc.
• /antivpn status — Active strategies & config state
• /antivpn whitelist add|remove|list <value> — Manage whitelist
• /antivpn reload — Reload config
• /antivpn clear — Clear cache

Performance

• Fully asynchronous (no main thread blocking)
• TTL cache with configurable expiry
• Automatic stale cache eviction
• Strategy-level timeouts (5s per API call)
• 8-second overall check timeout

---

Configuration

strategies:
  asn-check: true
  hosting-provider-check: true
  tor-node-check: true
  proxy-api-check: true
  ipquality-check: true

api-keys:
  proxycheck: "your-proxycheck-api-key"
  ipqualityscore: "your-ipqualityscore-api-key"

actions:
  risk-levels:
    TRUSTED: none
    LOW: none
    MEDIUM: kick
    HIGH: kick
    CERTAIN: kick

All 5 strategies are enabled by default. API-key strategies gracefully skip if no key is set. The config is fully documented inline.

---

Installation

1. Drop the JAR into your server's plugins/ folder
2. Restart or /reload
3. Configure API keys in plugins/CrowzAntiVPN/config.yml (optional)
4. Done — no setup required for basic operation

Requirements: Paper 1.21.3+, Java 21+

---

Permissions

Permission	Default	Purpose
crowz.antivpn.bypass	op	Bypass all VPN checks
crowz.antivpn.notify	op	Receive VPN alerts
crowz.antivpn.admin	op	Access admin commands
crowz.antivpn.reload	op	Reload configuration
crowz.antivpn.lookup	op	Check/lookup IPs
crowz.antivpn.whitelist	op	Manage whitelist

---

Built for Paper 1.21.3+ with Java 21.