Skip to main content

Blacklist System

CocoAntiVPN features a persistent IP blacklist system that automatically blocks detected VPN/proxy users and provides custom ping responses.

How It Works​

When a VPN is detected:

  1. Detection - API confirms IP is using VPN/proxy or is from blocked country
  2. Kick - Player is immediately kicked with configured message
  3. Blacklist - IP is added to persistent SQLite database
  4. Custom Ping - Blacklisted IPs receive fake server status

Automatic Blacklisting​

Once an IP is detected as VPN/proxy, it's automatically blacklisted:

  • Stored in SQLite database (data.db)
  • Persists across server restarts
  • Immediate rejection on future connections
  • No API call needed for known bad IPs

Custom Ping Response​

Blacklisted IPs see a custom server status when pinging:

blacklist-ping:
  # Server version shown in client
  version-name: "IP Blacklisted"
  
  # Protocol version (-1 = incompatible)
  protocol-version: -1
  
  # MOTD message
  motd: "&cCould not connect to the server."
  
  # Max players shown
  max-players: 0
  
  # Online players shown
  online-players: 0
  
  # Player sample (hover text)
  player-sample: ""

What Blacklisted Users See​

With default settings:

  • Version: "IP Blacklisted" (or shows as incompatible)
  • MOTD: "Could not connect to the server."
  • Players: 0/0

This discourages reconnection attempts by making the server appear down or incompatible.

Configuration Examples​

Stealth Mode​

Make server appear completely offline:

blacklist-ping:
  version-name: ""
  protocol-version: -1
  motd: ""
  max-players: -1
  online-players: 0
  player-sample: ""

Warning Message​

Show clear warning to VPN users:

blacklist-ping:
  version-name: "VPN Blocked"
  protocol-version: -1
  motd: "&cYour IP is blacklisted.\n&7Disable VPN to connect."
  max-players: 0
  online-players: 0
  player-sample: "&cAccess Denied"

Fake Maintenance​

Disguise as maintenance:

blacklist-ping:
  version-name: "Maintenance"
  protocol-version: -1
  motd: "&6Server is under maintenance.\n&7Please try again later."
  max-players: 0
  online-players: 0
  player-sample: ""

Unban Command​

To remove an IP from the blacklist:

/antivpn unban <ip>

Permission: antivpn.command.unban

Examples:

/antivpn unban 192.168.1.100
> [CocoVPN] IP address 192.168.1.100 successfully removed from blacklist!

/antivpn unban 10.0.0.1
> [CocoVPN] IP address 10.0.0.1 is not on the blacklist!

Database Storage​

Blacklisted IPs are stored in SQLite:

Table Structure:

CREATE TABLE blacklist (
    ip TEXT PRIMARY KEY,
    blocked_at INTEGER
);

Fields:

  • ip - The blacklisted IP address
  • blocked_at - Unix timestamp when blocked

Location:

  • Bukkit: plugins/CocoAntiVPN/data.db
  • BungeeCord: plugins/CocoAntiVPN/data.db
  • Velocity: plugins/cocoantivpn/data.db

Use Cases​

Bot Attack Mitigation​

During bot attacks:

  1. VPN bots are detected and blacklisted
  2. Subsequent connections from same IP are instantly rejected
  3. No API calls needed for known attackers
  4. Custom ping discourages automated reconnects

False Positive Recovery​

If a legitimate player is incorrectly blacklisted:

  1. Player contacts support
  2. Admin runs /antivpn unban <ip>
  3. Player can immediately reconnect
  4. Consider adding to bypass list if recurring

ISP Proxy Issues​

Some ISPs route through proxy-like infrastructure:

  1. Identify affected players
  2. Unban their IP: /antivpn unban <ip>
  3. Add to bypass: /antivpn bypass add <player>

Best Practices​

Regular Monitoring​

Monitor blacklist activity via:

  • Staff notifications (antivpn.notify permission)
  • Discord webhooks
  • Database queries

Cleanup Old Entries​

For large databases, consider periodic cleanup:

-- Remove entries older than 30 days
DELETE FROM blacklist 
WHERE blocked_at < (strftime('%s', 'now') - 2592000);

Backup Database​

Regularly backup data.db to prevent data loss:

cp plugins/CocoAntiVPN/data.db backups/antivpn-backup.db

Troubleshooting​

Ping Response Not Working​

  1. Ensure Netty injector is active (check startup logs)
  2. Some proxy setups may interfere
  3. Paper/Spigot handle ping differently

IP Not Being Blacklisted​

  1. Check if VPN check is timing out
  2. Verify API key is valid
  3. Check database write permissions

Cannot Unban IP​

  1. Verify IP format is correct
  2. Check permission: antivpn.command.unban
  3. IP may not be in blacklist