Security

Security Overview

The security features cover the connection itself: where it comes from, what client is on the other end, and whether the account behind it is somebody you already banned. 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

Setup

1. Create a free account at ipinfo.io and get your API token.
2. 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"

3. Reload with /xbans reload.

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.

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.

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

The alt-account detection weighs ten 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

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.

Client settings

The strongest signal of the lot, and the one an alt never thinks about. An address is shared by a household, a school and a VPN exit; skin layers, main hand, chat preferences and the answer to the resource pack come out of options.txt — they belong to the installation, not to the account. A second account is a new name and a new password; it is not a new options.txt.

Only a match on an unusual value scores. Almost everybody runs the defaults, so "both players use their right hand" describes most of the server and is worth nothing. "Both play left-handed with the cape hidden and coloured chat off" describes very few people.

The whole block is capped (max-score, default 35) so it can never trigger an action on its own, and a disagreement is never counted against a player: reconfiguring one install between two sessions is ordinary.

Address history

The addresses a player has connected from live in xbans_player_ips, one row per (player, address). They used to be a semicolon-separated VARCHAR(2048) column inside XCore's shared players table — two kilobytes carried on every player load and rewritten on every cache write, for every addon on the server.

The move happens by itself on the first start after updating, and writes a CSV backup next to the configuration before the old column is dropped. Looking a player up by address is now an exact match on an index: the old search matched 1.2.3.4 inside 11.2.3.40, and read every player row to do it.

Reviewing a case

/alts <player> opens the linked accounts straight away, each with its score and the evidence the engine actually weighed, rather than only the fact that an address was shared. Nothing is printed to chat. From the console, where there is no inventory to open, the same command prints the list instead.

A link recorded by hand outranks anything the engine scores afterwards, so a case you have already judged stays judged.

Weighting the evidence

Every weight lives in alt-detection.risk-scoring, and the risk levels follow the thresholds you set. A shared address is weighted by what it is: a VPN exit, a datacentre or a mobile carrier is not a household, and an address used by forty accounts is a school. Evidence also loses weight as it ages, on the half-life set in risk-scoring.decay.

Rank immunity

A moderator cannot sanction someone above them. Give each rank a level through xbans.immunity.<level> — the highest node a player holds is their level — and an attempt against an equal or higher level is refused with a message rather than silently working.

Console has no level and is never refused.