Bans & the CXA Network

When CXA Anticheat bans a player, it saves a ban record with its own ban ID and blocks every account and device it can link to that player. Your server can also share its automatic bans with the other servers on the CXA network and, if you choose, keep out players that were automatically banned somewhere else.

Global Bans Are Opt-In

Sharing your own automatic bans is on by default. Blocking players banned on other servers is off until you turn on Block globally banned players. Manual bans are never shared.

How It Works

  1. A detection with the ban punishment, a staff command, the web panel, the in-game panel or one of your scripts creates a ban.
  2. The ban gets an ID such as CXA-7KQ2MX. The record keeps the player's name, the reason, the detection, all identifiers (account IDs such as license: or discord:), the hardware tokens, who issued it, when it was made and when it ends.
  3. The player is dropped and sees the ban screen with the ban ID.
  4. Every time someone connects, CXA compares their identifiers and hardware tokens with the active bans. Active bans are kept in memory, so this check never waits for the database.
  5. If the ban came from a detection on your shared list, a hashed copy is sent to the CXA network as a global ban.

Ban IDs and Durations

Every ban gets a unique ID made of Config.Ban.IdPrefix (default CXA-) and Config.Ban.IdLength random characters (default 6). The characters are capital letters and digits without I, O, 0 and 1, so an ID is easy to read out, for example CXA-7KQ2MX. Changing the prefix or length only affects new bans.

Durations are always in hours. 0 means permanent. The web panel and the in-game panel accept up to 87600 hours. When a detection has no BanDuration, Config.Ban.DefaultDuration is used (default 0, permanent). Temporary bans end by themselves; you don't have to remove them.

Where Bans Are Stored

StorageWhereWhen to use it
oxmysql (default, recommended)Table cxa_bans in your database, created automaticallyAny server with MySQL. Unbanned records stay in the table with active = 0, so you keep the history.
jsondata/bans.json inside the resourceServers without MySQL. Unbanned records are deleted from the file.

[PERF] With json, every new ban or unban rewrites the whole file. Avoid it once you have thousands of bans.

If Storage is oxmysql but oxmysql is not started within 30 seconds, CXA switches to JSON and prints oxmysql is not started, bans will be stored in data/bans.json. Switching the storage does not move existing bans from one place to the other.

Because active bans are loaded into memory when the anticheat starts, a change you make directly in the database is not seen until you reload the ban list with Reload bans in the panel or cxareload in the console.

How Bans Are Matched

A connecting player is blocked when any of their identifiers or hardware tokens belongs to an active ban. Hardware tokens are IDs that FiveM creates from the player's PC. They stay the same when a cheater makes a new Rockstar, Steam or Discord account, which makes them the strongest protection against ban evasion.

Change these settings in the panel under Configuration → Ban system.

OptionKeyDefaultWhat it does
StorageBan.StorageoxmysqlWhere bans are saved, see above.
Table nameBan.TableNamecxa_bansMySQL table name. Letters, digits and _ only.
Ban ID prefixBan.IdPrefixCXA-Text in front of every ban ID.
Ban ID lengthBan.IdLength6Random characters after the prefix (4 to 16).
Default durationBan.DefaultDuration0Hours used when a detection has no ban duration. 0 = permanent.
Automatic ban issuerBan.BannedByCXA AnticheatName saved as the issuer of automatic bans.
Match identifiersBan.MatchIdentifierslicense, license2, steam, discord, xbl, live, fivemIdentifier types that count as a match.
Match hardware tokensBan.MatchTokenstrueAlso blocks the same PC on a new account.
Match IPBan.MatchIpfalseAlso blocks the same IP address.
Extend identifiersBan.ExtendIdentifierstrueWhen a banned player tries to join with a new account, its identifiers and tokens are added to the ban.

Match IP Can Ban Innocent Players

Players in the same home, dormitory or internet café, and many mobile internet users, share one IP address. With Match IP on, a ban on one of them blocks all of them. Leave it off unless you have a clear reason, and rely on hardware tokens instead.

Players listed in Config.Bypass.Identifiers skip the ban check when they connect. See Staff Bypass.

What Banned Players See

A banned player is dropped with this screen. A player who tries to join again sees the same screen.

Output
CXA Anticheat

You are banned from this server.

Ban ID: CXA-7KQ2MX
Reason: Blacklisted weapon
Expires: Never (permanent)
Appeal: discord.gg/yourserver

CodeXart Studios wishes you a safe flight..
  • The first line is your server name from Configuration → General → Server name (Config.ServerName).
  • A temporary ban shows its end date as YYYY-MM-DD HH:MM in your server's time zone.
  • The Appeal line comes from Configuration → General → Appeal URL (Config.AppealUrl). The default discord.gg/yourserver is a placeholder, so replace it with your own appeal link or leave it empty to hide the line.
  • The language follows Configuration → General → Language (Config.Locale).

Ask players to send you the ban ID when they appeal. With it you can look the ban up with cxabaninfo and remove it in one step.

Banning and Unbanning

From the Control Panel

To ban an online player:

  1. Open Players and stay on the Online view, or open the Live map tab (see 3D Map).
  2. Press the Ban icon on the player's row, or open the player and press Ban under Online now.
  3. In Ban player, set Duration (hours, 0 = permanent). The buttons Permanent, 1 day, 3 days, 1 week and 30 days fill it in for you.
  4. Enter a Reason and confirm.

Your server runs the ban within 30 seconds. The new ban ID appears under Recent panel actions on the Players page. Panel bans are manual bans and are saved with the issuer Panel: <your name>.

To unban:

  • Open Commands → Unban by ban ID, enter the ban ID and press Unban.
  • Or open the player's profile in Players. Under Detections on this server, press Unban next to the ban.

Banning and unbanning need a team role with the moderate permission (owner, admin or editor). See Team Access and Remote Actions.

From the Console and Chat

Console
# Ban online player 12 for 72 hours
cxaban 12 72 Using a mod menu

# Ban an identifier, even if the player is offline (0 = permanent)
cxabanoffline license:1234567890abcdef1234567890abcdef12345678 0 Ban evasion

# Show the details of a ban
cxabaninfo CXA-7KQ2MX

# Remove a ban
cxaunban CXA-7KQ2MX

# Reload the ban list from the database into memory
cxareload

Who may use each command in-game is set in Configuration → Staff roles & commands. See Console & Chat Commands and Staff Roles & Command Access.

From the In-Game Panel

Staff open the in-game panel with /cxa. Depending on their role, they can ban a player from the player list, browse all active bans and remove them. See In-Game Panel (/cxa).

From Your Scripts

Lua
-- Ban player 12 for 24 hours, the issuer is shown in the ban log
local banId = exports['cxa-anticheat']:BanPlayer(12, 'Money exploit', 24, 'my-shop')

-- Remove a ban, returns true when the ban existed
exports['cxa-anticheat']:UnbanPlayer('CXA-7KQ2MX')

-- Check one identifier, returns true and the ban ID when it is banned
local banned, id = exports['cxa-anticheat']:IsIdentifierBanned('discord:123456789012345678')

See Ban & Kick Exports for every parameter and return value.

Global Bans on the CXA Network

What the CXA Network Is

Every licensed server that runs CXA Anticheat is part of the CXA network. When a player connects, your server asks the network about them. The answer contains active global bans, the player's Account Trust score and their history, which you see on the Players page and in Network Lookup.

Identifiers and hardware tokens are stored on the network only as one-way hashes, so the network can recognise a player again without keeping their account IDs in plain text. IP addresses are never part of a global ban.

Sharing Your Automatic Bans

With Share my automatic bans on (default), your server shares an automatic ban when its detection is on the Shared detections list. These bans are never shared:

  • Manual bans from commands, the in-game panel and the web panel
  • Bans from the BanPlayer export
  • Automatic bans from detections that are not on the list

The default list only contains detections that a normal player cannot trigger:

Output
ResourceInjection, Injection, BlacklistedWeapons, BlacklistedCommands, DevTools,
DamageModifier, Explosion, ExplosionInvisible, BlacklistedEvent, GiveWeapon,
RemoveWeapon, WeaponDamage, BlacklistedProjectile, ImpossibleDamage, EventAbuse

Keep the list to high-confidence detections. A shared ban follows the player to every server that enforces global bans, so a false positive on your server would also lock an innocent player out of other servers.

Blocking Players Banned Elsewhere

Turn on Block globally banned players to check every connecting player against the network. A player is affected when at least Minimum banning servers different servers have an active global ban on one of their identifiers or tokens. Global bans older than Ignore bans older than are not counted.

Action decides what happens:

  • reject: the player cannot join.
  • log: the player joins and a Network check: global_ban entry is posted to the Connections channel, so your staff can keep an eye on them.

Configuration

Change these settings in the panel under Configuration → Network & trust.

OptionKeyDefaultWhat it does
Network check on connectNetworkCheck.EnabledtrueAsks the CXA network about every connecting player. Needed for global bans and account trust. [PERF]
TimeoutNetworkCheck.Timeout3000 msHow long a join waits for the network's answer.
Let players in when unreachableNetworkCheck.FailOpentruePlayers join normally when the network does not answer in time.
Block globally banned playersGlobalBans.EnforcefalseChecks players against global bans from other servers.
Share my automatic bansGlobalBans.SharetrueShares your automatic bans from the detections below.
ActionGlobalBans.Actionrejectreject the connection or only log it.
Ignore bans older thanGlobalBans.MaxAgeDays180 daysOlder global bans are not counted. 0 = never ignore.
Minimum banning serversGlobalBans.MinServers1How many different servers must have banned the player (1 to 10).
Shared detectionsGlobalBans.ShareDetections15 detections, see aboveOnly bans from these detection keys are shared.

[PERF] The network check is one HTTPS request per connecting player and can add up to the Timeout to each join.

What a Globally Banned Player Sees

With Action set to reject, the player sees:

Output
You are banned on the CXA Anticheat network and cannot join CXA Anticheat. If you believe this is a mistake, contact the server that banned you.

CXA Anticheat is replaced by your server name. If the network cannot be reached and Let players in when unreachable is off, every connecting player sees Security check could not be completed, please try again in a minute. instead.

Withdrawing a Shared Ban

When you remove a ban, CXA also withdraws its shared copy from the network. This works from every place you can unban: the panel, cxaunban, the in-game panel and the UnbanPlayer export. The Activity list then shows Global ban revoked after unban.

Only the server that issued a global ban can withdraw it. To let one player in despite a global ban from another server, add one of their identifiers to Always allowed identifiers (TrustScore.Whitelist). Identifiers on that list skip global ban and account trust checks.

Recommendations

Recommended:

  • Use oxmysql storage so bans survive file mistakes and keep a history.
  • Keep Match hardware tokens and Extend identifiers on. Together they catch most ban evasion.
  • Set your own Appeal URL and ask players for the ban ID.
  • Test a new detection with log for a few days before it bans, and before you add it to Shared detections.
  • Start global bans with Action log for a week, check the Connections channel, then switch to reject.

Avoid:

  • Turning on Match IP on a server with many players from the same city or mobile carrier.
  • Adding detections that can fire on legitimate players to Shared detections.
  • Editing cxa_bans while the server runs without running Reload bans afterwards.

Players and Network Lookup

  • The player profile in Players shows the number of global bans and the global ban history, marked "this server" for your own.
  • Network Lookup shows the automatic bans of any identifier on the whole network, active or withdrawn.

Account Trust

  • An active global ban pushes the player's trust score into the red band, even with Block globally banned players off.
  • See Account Trust.

Logging & Discord

  • New bans go to the Bans channel, unbans and staff bans to the Admin channel, blocked join attempts to the Connections channel.
  • See Logging & Discord.

Staff Bypass

  • Identifiers in Config.Bypass.Identifiers are not checked against local bans, global bans or account trust when they connect.
  • See Staff Bypass.

Limitations

  • Only an unban withdraws a shared ban. When a temporary automatic ban simply runs out, its shared copy stays on the network until it is older than the other servers' Ignore bans older than setting.
  • Global bans, sharing and withdrawing need an active license and a connection to codexart.net.
  • At join time, only identifiers in Config.Bypass.Identifiers count as bypass. txAdmin admins and players with the bypass ACE permission or framework group are checked for bans like everyone else when they connect.

Common Problems

A Banned Player Can Still Join

What you see: A player you banned joins again on the same or a new account.

How to fix it:

  • Check that the ban is still active with cxabaninfo <banId>. Temporary bans end on their own.
  • Make sure none of the player's identifiers are in Config.Bypass.Identifiers.
  • Keep Match hardware tokens on, so a new account on the same PC is blocked.
  • If you added or edited bans directly in the database, run Reload bans in Commands or cxareload in the console.
  • If you switched Storage, your old bans are still in the old place.

"Active ban CXA-... was not found."

What you see: cxaunban or cxabaninfo answers Active ban CXA-7KQ2MX was not found.

How to fix it:

  • Copy the ban ID from the ban log or the ban screen. IDs never contain I, O, 0 or 1.
  • The ban may have expired or been removed already.

Unban From the Panel Fails With ban_not_found

What you see: In Commands, the Results list shows failed with ban_not_found.

How to fix it:

  • Enter the ban ID in capital letters, exactly as it appears on the ban screen. Copying it from the ban log is the safest way.
  • Check that the ban still exists with cxabaninfo.

An Innocent Player Is Blocked by Someone Else's Ban

What you see: A new player gets the ban screen with a ban ID that belongs to another person.

How to fix it:

  • If Match IP is on, turn it off. The player probably shares an internet connection with the banned person.
  • Remove the ban with its ID if it was wrong, then ban the right person again.

Players See "You are banned on the CXA Anticheat network"

What you see: Players who were never banned on your server cannot join.

How to fix it:

  • Look the player up in Network Lookup to see the detections behind the global bans.
  • Raise Minimum banning servers so a single server is not enough.
  • Switch Action to log if you prefer to watch these players instead.
  • Add the identifier of a player you trust to Always allowed identifiers.

"Security check could not be completed, please try again in a minute."

What you see: Nobody can join while codexart.net is unreachable.

How to fix it:

  • Turn Let players in when unreachable back on (NetworkCheck.FailOpen = true).
  • Check that your host allows outgoing HTTPS connections.

"oxmysql is not started, bans will be stored in data/bans.json"

What you see: This warning in the console when the anticheat starts.

How to fix it:

  • Move ensure oxmysql above ensure cxa-anticheat in server.cfg and restart the server.
  • If you don't use MySQL, set Storage to JSON file and the warning goes away.

© 2026 CodeXart Studios · CXA Anticheat