NGINX Abuse Guard Module: Auto-Ban Scanners and Bots

Danila Vershinin — Sun, 19 Jul 2026 17:06:05 +0000

Open your NGINX error log on any public server and you will see the same thing: a steady drip of 404s probing for /wp-login.php, /.env, /phpmyadmin, and a thousand other paths that do not exist on your site. A vulnerability scanner walking your tree is a wall of 404s. A bot rattling locked admin endpoints is a wall of 403s. A credential-stuffing run is a wall of failed logins. Legitimate visitors almost never generate a burst of errors, but abusers generate little else. That asymmetry is the entire signal the NGINX abuse guard module acts on, and most servers throw it away.

The usual tools do not act on it cleanly. A rate limiter such as limit_req shapes load by request volume, so it slows everyone during a flood and lets the offender back in the instant the rate eases. Tools like fail2ban read the error pattern correctly, but they live outside NGINX: they tail a log file, parse it on a delay, and shell out to the firewall, so the ban lands seconds or minutes after the damage. What you actually want is to read the status codes your server is already returning and evict the clients whose traffic is mostly failure, immediately, inside the worker.

That is exactly what the NGINX abuse guard module does. It watches the final response status of every request, keeps a small per-client score in shared memory, and the moment a client crosses a threshold of errors it earns a timed ban enforced at the NGINX preaccess phase, before any handler, file lookup, or upstream runs. There is no sidecar, no log shipper, and no scripting layer. The decision happens in compiled C in a few microseconds. This guide shows you how it works, how to install and configure it, and how to roll it out safely against live traffic.

How the NGINX Abuse Guard Module Works

The module reduces abuse detection to three moving parts, all of which live inside the NGINX worker. Understanding them makes every configuration choice below obvious.

A leaky, decaying score per client

Every client identity carries a single small number in a shared-memory zone. Each matching error response adds to that score, and the score continuously bleeds away at a rate of threshold ÷ interval per second. A short, sharp burst of errors pushes the score over the line and trips a ban; a slow trickle of the occasional 404 spread across hours never accumulates. Crucially, that score is one fixed-size record no matter how high you set the threshold, so a single modest zone comfortably tracks the tens of thousands of distinct source addresses a botnet throws at you.

Counting at the header filter, deciding at preaccess

The module hooks two points in the request lifecycle. A header filter inspects the final response status of each request and updates the offending client's score. Separately, the preaccess phase checks whether the current client is already banned. Because preaccess runs before routing, static-file handling, and upstream proxying, a banned client is turned away at the cheapest possible point: NGINX never spends a cycle serving the request it is about to reject.

A privacy-correct refusal

When a banned client returns, it receives 429 Too Many Requests by default (you choose the code). The response carries a Retry-After header telling honest clients when to come back, and a Cache-Control: private, no-store header so that no shared cache or CDN can ever store one client's ban page and serve it to another. Identities are folded into a fixed-size digest before they are stored, so keying on something large like $request_uri or a header costs exactly as much memory as keying on a plain IP address.

Installation

Abuse Guard ships as a precompiled, signed dynamic module from the GetPageSpeed repository, so there is no build toolchain to install.

RHEL, CentOS, AlmaLinux, Rocky Linux, Amazon Linux

Install the NGINX abuse guard module from the GetPageSpeed RPM repository:

sudo dnf install https://extras.getpagespeed.com/release-latest.rpm
sudo dnf install nginx-module-abuse-guard

Then load the module by adding this line at the top of /etc/nginx/nginx.conf, in the main context before any http {} block:

load_module modules/ngx_http_abuse_guard_module.so;

Debian and Ubuntu

First, set up the GetPageSpeed APT repository, then install from the APT module page:

sudo apt-get update
sudo apt-get install nginx-module-abuse-guard

On Debian and Ubuntu, the package handles module loading automatically. No load_module directive is needed.

On either platform, confirm the configuration is valid before reloading:

sudo nginx -t

Quick Start

A working policy is two directives. Declare one shared-memory zone in the http context, then switch enforcement on wherever abuse arrives:

load_module modules/ngx_http_abuse_guard_module.so;

http {
    abuse_guard_zone zone=clients:10m;     # one shared-memory zone

server {
        location / {
            abuse_guard zone=clients;      # enforce here
        }
    }
}

sudo nginx -t && sudo systemctl reload nginx

With nothing but a zone name and size, those defaults ban any single IP that returns 100 403 or 404 responses inside a 5-minute window, and the ban holds for one hour. Every one of those numbers is tunable, as the reference below shows.

Directive Reference

The module is four directives: one declares a policy, the rest apply it, exempt trusted clients, and optionally share bans across machines. Everything documented here is verified against the module source, so you can rely on the contexts and defaults exactly as listed.

abuse_guard_zone

Context: http. Carves out one shared-memory zone and sets the policy that governs it. The zone name and size are the only required parameters; sensible defaults fill in the rest.

abuse_guard_zone zone=clients:10m
                 key=$binary_remote_addr
                 statuses=403,404
                 interval=300s
                 threshold=100
                 block=60m;

Parameter	Default	Description
`zone`	(required)	The policy name (referenced by `abuse_guard`) and the shared-memory size, e.g. `clients:10m`. About 10 MB tracks on the order of a hundred thousand live clients.
`key`	`$binary_remote_addr`	The expression that defines one client. Any NGINX variable. A request whose key resolves to an empty string is skipped entirely.
`statuses`	`403,404`	Which response codes count as errors. Individual codes, ranges, or a mix, e.g. `statuses=401,403,404,500-599`.
`interval`	`300s`	The window the score decays over. A burst inside it trips a ban; a slow trickle never accumulates.
`threshold`	`100`	How many errors within the window cross the line, up to 1024.
`block`	`60m`	How long a tripped client stays locked out.
`inactive`	`max(1h, interval, block)`	How long a dormant client lingers in memory before reclamation. Any explicit value must be at least as large as both `interval` and `block`.
`redis`	`off`	Set `on` to replicate this zone's bans across a fleet (see below).
`persist`	(none)	A file path to snapshot bans into so they survive a restart.
`persist_interval`	`5s`	How often the snapshot is rewritten.
`persist_secret`	(none)	A hex key that signs the snapshot with HMAC-SHA256, so a tampered file is rejected rather than loaded.

Why 5xx is left out by default: a server error is usually your side's doing, and counting it would let one flaky backend get innocent visitors banned. Add statuses=403,404,500-599 only when you deliberately want to act on clients that trigger server errors.

abuse_guard

Context: http, server, location. Applies a declared policy. Name the zone to switch enforcement on; write abuse_guard off; in a nested scope to switch it back off for that scope.

location /wp-login.php {
    abuse_guard zone=clients status=429 log_level=warn;
}

Parameter	Default	Description
`zone`	(required)	The zone (declared with `abuse_guard_zone`) whose policy applies here.
`status`	`429`	The code a banned client receives, anywhere in `400` to `599`.
`dry_run`	`off`	Set `on` to observe without enforcing: the verdict is logged but no ban is written.
`log_level`	`notice`	How loudly to log each decision: `info`, `notice`, `warn`, or `error`.

abuse_guard_allow

Context: http, server, location. Repeatable and inherited downward. Listed clients are never counted and never banned. Matching is on the true connection address, so it cooperates with realip.

abuse_guard_allow 127.0.0.0/8;
abuse_guard_allow 10.0.0.0/8 192.168.0.0/16;

abuse_guard_redis

Context: http. Points the server at one Redis or Valkey instance for fleet-wide ban replication. Pair it with redis=on on the zone you want shared.

abuse_guard_redis host=10.0.0.5 password=secret;   # tls://host for TLS
abuse_guard_zone  zone=clients:10m redis=on;

Parameter	Default	Description
`host`	(required)	The Redis or Valkey host. Prefix with `tls://` to connect over TLS.
`password`	(none)	Authentication password, if the server requires one.
`port`	`6379`	The server port.
`db`	`0`	The logical database number.
`prefix`	`ag_`	Key and channel prefix, so several services can share one Redis safely.
`timeout`	`100ms`	Connection and command timeout for the out-of-band replication path.

Variables

The module exposes exactly three variables, which you can write to your access log or use in a map:

Variable	Value
`$abuse_guard_status`	The verdict for this request: `BYPASSED`, `PASSED`, `COUNTED`, `BLOCKED`, or `DRY_RUN`.
`$abuse_guard_count`	The error count currently attributed to this client.
`$abuse_guard_blocked_until`	The Unix timestamp when the ban lifts, or `0` if the client is not banned.

A custom log format makes the module's decisions visible while you tune it:

log_format guard '$remote_addr "$request" $status '
                 'guard=$abuse_guard_status count=$abuse_guard_count';

access_log /var/log/nginx/access.log guard;

Security Hardening Use Cases

Blocking vulnerability scanners and 404 floods

This is the case the defaults are built for. An automated scanner requests hundreds of nonexistent paths in quick succession, and every miss is a 404. Enforce the default policy site-wide and the scanner bans itself within seconds of starting, while a real visitor who fat-fingers one URL never comes close to the threshold:

http {
    abuse_guard_zone zone=scanners:10m statuses=404 threshold=40 interval=60s block=30m;

server {
        location / {
            abuse_guard zone=scanners;
        }
    }
}

Brute-force protection on login and admin endpoints

Credential-stuffing and admin-probing bots produce 403s and failed logins. Scope a stricter policy to the endpoints they target, so a handful of failures is tolerated but a sustained run is locked out, without affecting the rest of the site:

location = /wp-login.php {
    abuse_guard zone=clients status=429 log_level=warn;
    # ... your usual fastcgi_pass / proxy_pass ...
}

Exempting authenticated users with a map

Because a request whose key resolves to an empty string is skipped, a map lets you track anonymous visitors by IP while leaving logged-in users untouched. Here, requests that carry a session cookie produce an empty key and are never scored:

map $cookie_sessionid $abuse_key {
    ""      $binary_remote_addr;   # anonymous: key on IP
    default "";                    # logged in: skip entirely
}

http {
    abuse_guard_zone zone=clients:10m key=$abuse_key;
}

Protecting verified search crawlers

A search-engine crawler grinding through stale URLs can rack up 404s through no fault of yours. Allowlist the published crawler ranges so they are never counted. Because matching is on the real connection address, this also cooperates with realip when you run behind a CDN:

abuse_guard_allow 66.249.64.0/19;   # example Googlebot range
abuse_guard_allow 157.55.0.0/16;    # example Bingbot range

Rolling out safely with dry_run

Never flip a new ban policy straight to enforcing on production traffic. Run it in observation mode first: dry_run=on records every ban it would issue, in the log, without writing any state. You can even run a dry-run location next to an enforcing one on the same zone, calibrate the threshold against real traffic, then flip it live once the numbers look right:

location / {
    abuse_guard zone=clients dry_run=on log_level=warn;
}

Watch the log for the bans it reports, confirm no legitimate client is caught, then remove dry_run=on.

Fleet-Wide Bans with Redis or Valkey

Behind a load balancer, a per-server ban is theatre: the attacker simply lands on a different node. Abuse Guard closes that gap without ever putting Redis in the request path. Point every node at one Redis or Valkey instance and set redis=on on the zone:

http {
    abuse_guard_redis host=10.0.0.5 password=secret;
    abuse_guard_zone  zone=clients:10m redis=on;

server {
        location / {
            abuse_guard zone=clients;
        }
    }
}

SELinux: on enforcing systems (RHEL, Rocky Linux, AlmaLinux) the kernel blocks NGINX from opening the connection to Redis until you permit it once with setsebool -P httpd_can_network_connect 1. Skip this and replication silently does nothing while local enforcement carries on as normal.

Each node still decides locally and counts locally. The instant a node issues a ban, it broadcasts that one fact to the cluster and records a durable copy; every other node imports it within milliseconds, and a node that was offline reconciles the moment it reconnects. Because enforcement is always served from each node's own in-memory state, a visitor's request never waits on a network round-trip. Redis here is a one-way alarm bell, not a shared ledger consulted per request, so a slow or missing Redis can never add latency to your traffic. Run it on a private network and treat write access as privileged: anything that can write to it can issue bans.

Bans That Survive a Restart

Point a zone at a file and active bans are snapshotted on an interval and restored at startup, so a reload or a reboot does not hand every attacker a fresh slate:

abuse_guard_zone zone=clients:10m
                 persist=/var/lib/nginx/abuse_guard/clients.state
                 persist_secret=00112233445566778899aabbccddeeff;

The snapshot is integrity-checked and written so that a crash can never leave a torn file. With persist_secret set, it is also signed with HMAC-SHA256, so a tampered file is rejected rather than trusted. Keep the directory readable only by the NGINX worker user.

Abuse Guard vs limit_req and fail2ban

NGINX already ships rate limiting, and most servers already run fail2ban, so it is worth being precise about where Abuse Guard fits rather than presenting it as a replacement for either.

	limit_req	fail2ban	Abuse Guard
Signal	Request rate	Log patterns	Response error rate
Action	Throttle / delay	Firewall ban	Timed in-worker ban
Where it runs	In NGINX	Out of process	In NGINX
Reaction time	Immediate	Log-tail delay	Immediate
Best at	Shaping load	Host-wide bans across services	Evicting error-heavy clients

Use a rate limiter to shape load and protect capacity. Use fail2ban for host-wide bans that span SSH, mail, and other services. Use Abuse Guard for the specific job neither does well: reading the errors NGINX is already returning and evicting the clients defined by them, in the same worker, on the request itself. The three layer cleanly. A common production stack runs limit_req for burst control and Abuse Guard for eviction in the same location.

Performance Considerations

Abuse Guard is engineered to make abuse cheap to reject and good traffic free to serve. Three properties matter in production:

Rejection is the cheapest outcome. A banned client is turned away at the preaccess phase, before routing, file lookups, or upstream connections, so the more an attacker hammers you the less each request costs.
Memory is fixed per client. Each tracked identity is one small, constant-size record regardless of threshold, so a single 10 MB zone tracks roughly a hundred thousand clients. That is what lets one zone absorb a botnet.
Optional dependencies fail open. Clustering and signed snapshots are best-effort by design. If Redis or the disk misbehaves, enforcement quietly carries on from local memory and your traffic is never held hostage to a dependency.

Troubleshooting

Symptom	Cause and fix
`nginx -t` reports "unknown directive abuse_guard_zone"	The module is not loaded. Confirm `load_module modules/ngx_http_abuse_guard_module.so;` is in the main context on RHEL-based systems, and that the package is installed: `ls /usr/lib64/nginx/modules/ngx_http_abuse_guard_module.so`.
Bans never trip	The score decays at `threshold ÷ interval` per second. If errors arrive slower than that, the score never builds. Lower `threshold` or shorten `interval` for the burst you want to catch.
A client is never counted	Its `key` may resolve to an empty string (skipped by design), or it may match an `abuse_guard_allow` range. Check both.
Wrong client is banned behind a CDN	You are keying on the proxy address. Resolve the real client with `realip` first, then key on `$binary_remote_addr`.
`dry_run` bans nothing	That is correct: `dry_run=on` logs the verdict but never writes a ban. Check the log for the bans it reports, then remove `dry_run=on` to enforce.
Redis replication does nothing on RHEL or Rocky Linux	SELinux is blocking the outbound connection. Allow it once with `setsebool -P httpd_can_network_connect 1`, then reload NGINX. Local enforcement is unaffected either way.
A `return` in the same location appears to bypass the guard	A `return` directive can short-circuit request processing. Place enforcement where it runs before any short-circuit, or in a parent scope.

When you run behind a CDN or reverse proxy, never trust a raw X-Forwarded-For. Let realip resolve the true client first:

set_real_ip_from 10.0.0.0/8;
real_ip_header   X-Forwarded-For;
real_ip_recursive on;

Conclusion

A tuned Abuse Guard policy only stays correct until someone touches the config. NGINX upgrades, module updates, and routine edits quietly reintroduce the very gaps you just closed, and a ban rule that silently stops matching is worse than none. GetPageSpeed Amplify runs scheduled gixy scans across every host and ties findings to live NGINX runtime metrics. Drop-in compatible with the deprecated nginx-amplify-agent (EOL January 2026).

The NGINX abuse guard module turns the errors your server already returns into an automatic, self-calibrating defense. It reads the one signal abusers cannot hide, decides in microseconds inside the worker, and evicts offenders with a real timed ban instead of a throttle that lets them straight back in. With dry_run for safe rollout, a map-driven key for surgical scoping, optional fleet-wide replication, and bans that survive a restart, it covers the timed-ban niche that neither limit_req nor fail2ban fills. Pair it with the NGINX delay module to tarpit slow probers, the NGINX WAF module for payload inspection, or ModSecurity for NGINX for full rule-based filtering.

Abuse Guard is available as a pre-built package from the GetPageSpeed RPM repository and the GetPageSpeed APT repository. For licensing, volume deployments, or a hand getting set up, contact us.

DEV Community: Danila Vershinin