Anti-bot and anti-exploit

Understand each NusaGate protection in plain language, apply the recommended settings, and know what players see when they are blocked.

On this page

This page explains how NusaGate tells real players apart from bots, which settings to check before you open your network, and what a player sees when a check stops them.

How the layers work together

Every new connection passes several checks before it reaches your lobby. Roughly in this order:

  1. Accept: the connection opens. Per-IP rate limits and your block lists apply here.
  2. Handshake: the client says which address and version it is using. NusaGate checks the domain, the timing and the shape of the data.
  3. Pre-login: the player name and login rate are checked, along with the player's history of failed attempts.
  4. Verify: the client has to behave like a real game, for example by sending its client brand and settings.

Once the player is in the game, chat, packet and plugin-message limits keep protecting your backends. A bot that fails early never costs your backend servers anything.

Attack mode

The attack detector watches three kinds of floods separately: bot (many logins), ping (many server-list pings) and spam (chat and connection spam). When one of them passes its limit, NusaGate switches that kind into attack mode for a short time.

While attack mode is active, NusaGate can use lighter compression to save CPU, show a special MOTD if you set one, and keep the console quiet with short summary messages instead of thousands of lines. Several PRO checks, such as Reconnect Check, only switch on during attack mode by default, so normal players are not slowed down on quiet days.

Use /ng attack to see the current state or to force attack mode on or off. See Commands and permissions.

Anti-bot modules

All of these live under anti-bot in nusagate.yml. Free modules are on by default.

ModuleEditionIn plain words
attack-detectorFreeNotices bot, ping and spam floods and switches attack mode on and off.
connection-login-speedFreeLimits how many pings, connections and logins one IP address can make in a few seconds.
slow-bot-detectionFreeRejects handshakes that are too slow, use an invalid address or name, or do not look like a Minecraft client. Bedrock names with a . prefix are allowed.
timeout-checkFreeCloses logins that never finish and limits half-open connections per IP.
network-exhaustion-preventionFreeStops connections that send data byte by byte to tie up the proxy.
chat-checkFreeStops chat spam and floods of /register and /login commands.
dns-checkFreeRequires your domain name instead of a raw IP address.
light-verificationFreeChecks that the client sends a normal brand and client settings, and blocks known bot clients.
protocol-attribute-guardFreeLets you block game versions or name and brand patterns, and checks ping stability during attacks.
motd-minifierFreeKeeps the server-list MOTD and icon small and cached, with an optional MOTD during ping attacks.
adaptive-escalationFreeRepeat offenders go from a challenge, to a short cooldown, to a temporary block that grows longer each time.
bot-name-patternFreeSpots random-looking names and swarms of similar names.
dynamic-heavy-unloadFreeFrees extra memory once an attack is over.
fake-lobby-verificationPROSentinel Limbo: a short virtual lobby that checks keep-alive replies, falling and collision like a real client.
verified-player-cachePRORemembers verified players so they skip heavy checks next time. A new IP address means a new check.
interactive-captchaPROA code, sum or number-in-words challenge in chat. Off by default.
reconnect-checkPROAsks a first-time player to reconnect once. By default only during attacks.
account-guardPROLimits accounts online at once, and different accounts joining, from one IP address.
nickname-guardPROLocks staff names to their IP addresses and rejects look-alikes such as 0wner.
attack-join-queuePRODuring an attack, lets new players in at a steady pace. Verified players skip the queue.
adaptive-dos-shieldPROFilters connection floods at the earliest point and switches itself off when traffic is calm.

Anti-exploit modules

These live under anti-exploit-security.

ModuleEditionIn plain words
exploit-fixesFreeCloses connections that send malformed frames or abuse login and brand packets.
backend-payload-shieldFreeBlocks oversized or dangerous plugin messages before they reach a backend.
static-blacklistFreePermanent blocks for IP addresses, CIDR ranges and player names.
packet-firewallPROPacket and bandwidth limits per connection and per IP, stricter during attacks.
anti-vpnPRODetects VPN, proxy and hosting connections through the providers you configure. Can also block ASNs, ISP names and countries.
proxy-blocklist-feedsPROBlocks addresses from public proxy lists. Off by default.
passthrough-modePROScreens new players before Mojang authentication. Off by default.
native-tcp-check, kernel-country-blockPROLinux-only checks through the separate bridge helper. Skipped automatically elsewhere.

The defaults are tuned for a busy public server: strict enough to stop floods, loose enough that real players do not notice. Start with them, then check these points:

  1. Set your domain. Add it to anti-bot.dns-check.allowed-domains. Only switch block-direct-ip off while you test with an IP address.
  2. Shared connections. The defaults allow several players behind one home or school connection. If many of your players share one public IP, for example in an internet cafe, review the per-IP limits first. In PRO, keep Account Guard's distinct-accounts-mode at ONLY_UNDER_ATTACK and add such addresses to exempt-ips.
  3. Anti-VPN needs a key (PRO). Without an API key for at least one provider (ProxyCheck, IP-API, IPHub or IPQualityScore), it cannot confirm a VPN and lets everyone through. Provider fees and quotas are separate.
  4. CAPTCHA is optional (PRO). It is off by default. If you turn it on, ONLY_UNDER_ATTACK keeps it out of the way on normal days.
  5. Tell players where to get help. Set reliability-ux.localization.support-url to your own Discord or website link.
  6. Apply changes with /ng reload and check the result with /ng stats.

What players see when blocked

NusaGate never drops a player silently. Each kick starts with NusaGate », gives a short reason and says what to do. Some default messages:

ModuleDefault message
connection-login-speedYou are connecting too quickly. Please wait a few seconds and try again.
dns-checkPlease connect with the official server address instead of its IP address.
light-verificationClient verification failed. Please join with the official Minecraft client.
bot-name-patternYour username looks automated. Please join with a normal Minecraft account.
adaptive-escalationYou are on a short security cooldown. Please rejoin in a few seconds.
static-blacklistYour IP address or account is blocked on this server.

You can change every message with that module's kick-message setting. During a heavy attack, repeated kicks to the same IP address get "(please wait a few seconds)" added to the end.

To show multi-line messages in the player's own language (English or Indonesian, based on the game language), with your support link underneath, turn on the localized cards:

reliability-ux:
  localization:
    use-localized-kick-cards: true
    support-url: "https://example.com/support"

If a real player is blocked

  1. Ask the player for the exact message on their screen. The message tells you which module blocked them.
  2. Check that module's settings in nusagate.yml, especially per-IP limits for players on shared connections.
  3. If needed, set that module's enabled to false, run /ng reload and ask the player to try again. If they get in, you have found the cause.
  4. Switch the module back on with adjusted values, and report the case using Get support.

Next steps

Nusa product documentation · NusaGateFree & PRO editions

Loading the index…