Security

Security Overview

XBans includes a comprehensive security suite designed to protect your server from malicious connections, ban evasion, and unauthorized clients. These features work together to create multiple layers of defense.

VPN / Proxy / Datacenter Blocking

XBans can detect and block connections from VPNs, proxies, datacenters, and mobile/carrier networks using the IPInfo API. When a player connects, their IP is checked against IPInfo's database to determine the connection type.

Connection types

Type	Description	Example
VPN	Virtual Private Network services	NordVPN, ExpressVPN, Surfshark
Proxy	HTTP/SOCKS proxy servers	Public proxy lists, residential proxies
Datacenter	Hosted/cloud server IPs	AWS, OVH, Hetzner
Mobile	Carrier/mobile network IPs	Cellular data connections

Setup

Create a free account at ipinfo.io and get your API token.

Set the token in config.yml under the ipinfo section and configure blocking in the consolidated ip-security section:

ipinfo:
  enabled: true
  token: "your-api-token-here"

ip-security:
  vpn:
    enabled: true
    bypass-permission: "xbans.bypass.vpn"
  hosting:
    enabled: true
    bypass-permission: "xbans.bypass.hosting"
  mobile:
    enabled: false
    bypass-permission: "xbans.bypass.mobile"

Reload with /xbans reload.

IPInfo's free tier provides 50,000 requests/month, which is sufficient for most servers. Results are cached to minimize API calls.

Be careful with block-mobile: true. Many legitimate players connect from mobile data, especially in regions where mobile internet is the primary connection type.

ISP Blocking

ISP blocking allows you to deny connections from specific Internet Service Providers. This is useful for blocking hosting providers commonly used for bot attacks or specific ISPs known for abuse.

ISP blocking is configured under the consolidated ip-security section:

ip-security:
  isp:
    enabled: true
    blocked-isps:
      - "OVH SAS"
      - "Hetzner Online GmbH"
      - "DigitalOcean LLC"

The ISP name is resolved via the IPInfo API, so the IPInfo integration must also be enabled. ISP names must match exactly as returned by the API.

CIDR Range Blocking

CIDR blocking lets you block entire IP ranges using standard CIDR notation. This is a powerful tool for blocking known malicious networks at the network level.

IP range blocking is configured under the consolidated ip-security section:

ip-security:
  ip-range:
    enabled: true
    blocked-ranges:
      - "192.168.0.0/16"
      - "10.0.0.0/8"
      - "203.0.113.0/24"

CIDR checks are performed before any API calls, making them very fast. Use this for known bot networks or hosting ranges you want to block without consuming API quota.

CIDR notation works as follows: 203.0.113.0/24 blocks all IPs from 203.0.113.0 to 203.0.113.255. The number after the slash indicates how many bits of the IP are fixed.

Client Brand Control

Minecraft clients send a "brand" string on connection (e.g., "vanilla", "fabric", "forge", "lunar"). XBans can block or whitelist specific client brands to prevent unauthorized clients from joining.

client-brand:
  enabled: true
  mode: "blacklist"  # or "whitelist"
  list:
    - "wurst"
    - "meteor"
    - "impact"

In blacklist mode, brands in the list are denied. In whitelist mode, only brands in the list are allowed.

Client brand strings are sent by the client and can be spoofed. This feature is a deterrent, not a guarantee. Sophisticated cheat clients may report themselves as "vanilla". Use this alongside other security measures.

Protocol Version Control

Protocol version control allows you to restrict which Minecraft client versions can connect to your server. Each Minecraft version has a unique protocol number, and XBans can enforce minimum and maximum protocol versions.

protocol-version:
  enabled: true
  min-version: 767   # 1.21.1
  max-version: 769   # 1.21.4

Players connecting with a client version outside the allowed range are kicked with a configurable message. This prevents outdated or unreleased client versions from joining.

Alt-Account Detection

XBans features a sophisticated alt-account detection system that uses 10 risk factors to score how likely it is that a new player is an alternate account of a banned player. This goes far beyond simple IP matching.

Risk Factors

#	Factor	Description
1	IP history	Matches the connecting IP against IPs used by banned players
2	IP subnet	Checks if the IP is in the same /24 subnet as a banned player's IP
3	Name patterns	Analyzes username similarity (character sequences, prefixes, suffixes)
4	Name length	Compares username length patterns with banned accounts
5	Join timing	Detects suspicious timing (joining shortly after a ban)
6	First join	Brand new accounts joining soon after a ban are flagged
7	Client brand	Same client brand as the banned player
8	Protocol version	Same protocol version as the banned player
9	Locale/Language	Same client language settings
10	Connection pattern	Similar connection frequency and play time patterns

Each factor contributes a weighted score. When the total score exceeds the configured threshold, staff are notified and the account can be automatically blocked or flagged for review.

Alt-detection runs asynchronously on player join to avoid impacting connection times. Results are cached and available in the player's profile GUI.