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:
- Accept: the connection opens. Per-IP rate limits and your block lists apply here.
- Handshake: the client says which address and version it is using. NusaGate checks the domain, the timing and the shape of the data.
- Pre-login: the player name and login rate are checked, along with the player's history of failed attempts.
- 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.
| Module | Edition | In plain words |
|---|---|---|
attack-detector | Free | Notices bot, ping and spam floods and switches attack mode on and off. |
connection-login-speed | Free | Limits how many pings, connections and logins one IP address can make in a few seconds. |
slow-bot-detection | Free | Rejects 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-check | Free | Closes logins that never finish and limits half-open connections per IP. |
network-exhaustion-prevention | Free | Stops connections that send data byte by byte to tie up the proxy. |
chat-check | Free | Stops chat spam and floods of /register and /login commands. |
dns-check | Free | Requires your domain name instead of a raw IP address. |
light-verification | Free | Checks that the client sends a normal brand and client settings, and blocks known bot clients. |
protocol-attribute-guard | Free | Lets you block game versions or name and brand patterns, and checks ping stability during attacks. |
motd-minifier | Free | Keeps the server-list MOTD and icon small and cached, with an optional MOTD during ping attacks. |
adaptive-escalation | Free | Repeat offenders go from a challenge, to a short cooldown, to a temporary block that grows longer each time. |
bot-name-pattern | Free | Spots random-looking names and swarms of similar names. |
dynamic-heavy-unload | Free | Frees extra memory once an attack is over. |
fake-lobby-verification | PRO | Sentinel Limbo: a short virtual lobby that checks keep-alive replies, falling and collision like a real client. |
verified-player-cache | PRO | Remembers verified players so they skip heavy checks next time. A new IP address means a new check. |
interactive-captcha | PRO | A code, sum or number-in-words challenge in chat. Off by default. |
reconnect-check | PRO | Asks a first-time player to reconnect once. By default only during attacks. |
account-guard | PRO | Limits accounts online at once, and different accounts joining, from one IP address. |
nickname-guard | PRO | Locks staff names to their IP addresses and rejects look-alikes such as 0wner. |
attack-join-queue | PRO | During an attack, lets new players in at a steady pace. Verified players skip the queue. |
adaptive-dos-shield | PRO | Filters connection floods at the earliest point and switches itself off when traffic is calm. |
Anti-exploit modules
These live under anti-exploit-security.
| Module | Edition | In plain words |
|---|---|---|
exploit-fixes | Free | Closes connections that send malformed frames or abuse login and brand packets. |
backend-payload-shield | Free | Blocks oversized or dangerous plugin messages before they reach a backend. |
static-blacklist | Free | Permanent blocks for IP addresses, CIDR ranges and player names. |
packet-firewall | PRO | Packet and bandwidth limits per connection and per IP, stricter during attacks. |
anti-vpn | PRO | Detects VPN, proxy and hosting connections through the providers you configure. Can also block ASNs, ISP names and countries. |
proxy-blocklist-feeds | PRO | Blocks addresses from public proxy lists. Off by default. |
passthrough-mode | PRO | Screens new players before Mojang authentication. Off by default. |
native-tcp-check, kernel-country-block | PRO | Linux-only checks through the separate bridge helper. Skipped automatically elsewhere. |
Recommended settings
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:
- Set your domain. Add it to
anti-bot.dns-check.allowed-domains. Only switchblock-direct-ipoff while you test with an IP address. - 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-modeatONLY_UNDER_ATTACKand add such addresses toexempt-ips. - 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.
- CAPTCHA is optional (PRO). It is off by default. If you turn it on,
ONLY_UNDER_ATTACKkeeps it out of the way on normal days. - Tell players where to get help. Set
reliability-ux.localization.support-urlto your own Discord or website link. - Apply changes with
/ng reloadand 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:
| Module | Default message |
|---|---|
connection-login-speed | You are connecting too quickly. Please wait a few seconds and try again. |
dns-check | Please connect with the official server address instead of its IP address. |
light-verification | Client verification failed. Please join with the official Minecraft client. |
bot-name-pattern | Your username looks automated. Please join with a normal Minecraft account. |
adaptive-escalation | You are on a short security cooldown. Please rejoin in a few seconds. |
static-blacklist | Your 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
- Ask the player for the exact message on their screen. The message tells you which module blocked them.
- Check that module's settings in
nusagate.yml, especially per-IP limits for players on shared connections. - If needed, set that module's
enabledtofalse, run/ng reloadand ask the player to try again. If they get in, you have found the cause. - Switch the module back on with adjusted values, and report the case using Get support.
Next steps
- Module map: where every section lives in
nusagate.yml. - Known issues: shared IP addresses, Linux-only features and other limits.
- Commands and permissions:
/ng attack,/ng banand more.