Advanced VPN & Proxy Detection System for Minecraft
VortexGuard is a professional-grade anti-VPN and anti-proxy solution designed for Minecraft server networks. It provides real-time detection of VPNs, proxies, and suspicious connections using multiple detection methods and API integrations.
- 🌐 Multi-Platform Support - Works seamlessly on Paper, Velocity, and BungeeCord
- 🔍 Hybrid Detection - Combines multiple API providers with local detection algorithms
- ⚡ High Performance - Intelligent caching system minimizes API calls
- 🎯 Flexible Actions - Configurable responses (kick, notify, log, whitelist)
- 📊 Advanced Scoring - Weighted scoring system for accurate detection
- 🔔 Discord Webhooks - Real-time notifications with detailed player information
- 🛡️ Whitelist System - Bypass detection for trusted players
- 📈 Metrics Integration - Built-in bStats support
- Java 17 or higher
- Minecraft server (Paper 1.20+, Velocity 3.0+, or BungeeCord)
-
Download the appropriate JAR file for your platform:
VortexGuard-Paper.jarfor Paper/Spigot serversVortexGuard-Velocity.jarfor Velocity proxiesVortexGuard-BungeeCord.jarfor BungeeCord proxies
-
Place the JAR file in your server's
pluginsfolder -
Restart your server
-
Configure the plugin by editing
plugins/VortexGuard/config.yml -
Reload configuration with
/vortexguard reload
Edit config.yml to configure detection settings:
detection:
enabled: true
threshold: 70
check-on-login: true
actions:
kick-player: true
notify-admins: true
log-to-console: true
cache:
enabled: true
duration: 3600VortexGuard supports multiple VPN detection APIs. Configure your API keys:
apis:
iphub:
enabled: true
key: "your-api-key-here"
weight: 30
proxycheck:
enabled: true
key: "your-api-key-here"
weight: 25
ipqualityscore:
enabled: true
key: "your-api-key-here"
weight: 25| Provider | Free Tier | Accuracy | Speed |
|---|---|---|---|
| IPHub | 1,000/day | ⭐⭐⭐⭐ | Fast |
| ProxyCheck.io | 1,000/day | ⭐⭐⭐⭐⭐ | Fast |
| GetIPIntel | Unlimited* | ⭐⭐⭐ | Medium |
| VPNApi.io | 1,000/day | ⭐⭐⭐⭐ | Fast |
| IPQualityScore | 5,000/month | ⭐⭐⭐⭐⭐ | Fast |
*Rate limited by contact email
Enable local detection for offline/backup detection:
local-detection:
enabled: true
check-hosting-providers: true
check-datacenter-ips: true
weight: 20Configure Discord notifications:
webhook:
enabled: true
url: "https://discord.com/api/webhooks/..."
notify-on-detection: true
notify-on-kick: trueWhitelist trusted players or IPs:
whitelist:
enabled: true
players:
- "PlayerName"
- "AnotherPlayer"
ips:
- "192.168.1.100"
- "10.0.0.0/8"| Command | Permission | Description |
|---|---|---|
/vortexguard |
vortexguard.admin |
Main command |
/vortexguard reload |
vortexguard.reload |
Reload configuration |
/vortexguard check <player> |
vortexguard.check |
Check a player's IP |
/vortexguard whitelist <player> |
vortexguard.whitelist |
Add player to whitelist |
/vortexguard stats |
vortexguard.stats |
View detection statistics |
| Permission | Description | Default |
|---|---|---|
vortexguard.admin |
Full access to all commands | OP |
vortexguard.bypass |
Bypass VPN detection | OP |
vortexguard.reload |
Reload configuration | OP |
vortexguard.check |
Check player IPs | OP |
vortexguard.whitelist |
Manage whitelist | OP |
vortexguard.notify |
Receive detection notifications | OP |
Player Connects
↓
Check Whitelist → Whitelisted? → Allow Connection
↓ No
Check Cache → Cached? → Use Cached Result
↓ No
Query APIs (Parallel)
↓
Local Detection (Backup)
↓
Calculate Weighted Score
↓
Score > Threshold? → Yes → Execute Actions (Kick/Notify/Log)
↓ No
Cache Result → Allow Connection
VortexGuard uses a weighted scoring system:
- Each API provider has a configurable weight (0-100)
- Positive detections contribute their weight to the total score
- Final score is compared against the threshold
- Default threshold: 70/100
Example:
- IPHub detects VPN (weight: 30) ✓
- ProxyCheck detects VPN (weight: 25) ✓
- Local detection positive (weight: 20) ✓
- Total Score: 75 → Player is kicked
- JDK 17 or higher
- Gradle 8.0+
# Clone the repository
git clone https://github.com/yourusername/VortexGuard.git
cd VortexGuard
# Build all platforms
./gradlew build
# Build specific platform
./gradlew :vortexguard-paper:build
./gradlew :vortexguard-velocity:build
./gradlew :vortexguard-bungeecord:build- Paper:
vortexguard-paper/build/libs/VortexGuard-Paper-*.jar - Velocity:
vortexguard-velocity/build/libs/VortexGuard-Velocity-*.jar - BungeeCord:
vortexguard-bungeecord/build/libs/VortexGuard-BungeeCord-*.jar
VortexGuard/
├── vortexguard-common/ # Shared code and detection logic
├── vortexguard-paper/ # Paper/Spigot implementation
├── vortexguard-velocity/ # Velocity proxy implementation
├── vortexguard-bungeecord/ # BungeeCord implementation
├── build.gradle # Main build configuration
└── settings.gradle # Project settings
- No Data Collection: VortexGuard does not collect or store player data
- API Privacy: IP addresses are only sent to configured API providers
- Local Processing: Detection logic runs entirely on your server
- Secure Storage: API keys are stored in local configuration files
Issue: Plugin not detecting VPNs
- Verify API keys are correct and active
- Check API rate limits haven't been exceeded
- Ensure
detection.enabledis set totrue - Lower the detection threshold temporarily for testing
Issue: False positives
- Increase the detection threshold (default: 70)
- Adjust API weights to favor more accurate providers
- Add legitimate players to the whitelist
- Disable less accurate APIs
Issue: High API usage
- Enable caching with longer duration
- Reduce the number of enabled APIs
- Use local detection as primary method
Issue: Slow connection times
- Enable caching to reduce API calls
- Increase cache duration
- Use faster API providers (IPHub, ProxyCheck)
This project is licensed under a custom license. See the LICENSE file for details.
For support, feature requests, or bug reports:
- 💬 Join our Discord Server
- 🐛 Open an issue on GitHub
- 📧 Contact via email
VortexGuard uses bStats to collect anonymous usage statistics. This helps us understand how the plugin is used and improve it.
You can opt-out by setting metrics.enabled: false in the configuration.
VortexGuard is a detection tool and may produce false positives. Always review detections before taking permanent action against players. The developers are not responsible for any bans or restrictions applied using this plugin.
Made with ❤️ for the Minecraft community