Nginx-Lua-Anti-DDoS: a Lua challenge page in front of your server block

It runs in the access phase, which decides everything

The mechanism is the Cloudflare I am under attack interstitial, rebuilt through `anti_ddos_challenge.lua`. When the script judges that a visitor is not worth passing through, it answers with an HTML page carrying a JavaScript puzzle that the browser solves in roughly five seconds, and only then does the request continue to your application.

Where that decision is made matters more than the puzzle. The file is invoked through `access_by_lua_file`, the Nginx access phase, which runs after routing but before content fetching. So the expensive part of an attack, your PHP or application backend, is never reached for challenged requests. The README describes the I/O as fully asynchronous and nonblocking, which is the second half of why this helps: the worker does not sit waiting while it judges traffic.

The scope is set by where you put the directive. In an `http` block it covers every site on the server. In a `server` block it covers one site. In a `location` block it covers one path, which is how you protect a login endpoint without adding a challenge to static assets.

Two lines of configuration and a 70 megabyte shared zone

Installation is manual. You edit the settings inside `anti_ddos_challenge.lua` to fit your setup, copy the file into your Nginx configuration folder under `nginx/conf/lua/`, and add two directives. The shared dictionary is not optional, because it is where per-user request tracking lives.

lua_shared_dict antiddos 70m; #Anti-DDoS shared memory zone to track requests per each unique user

access_by_lua_file anti_ddos_challenge.lua;

The README also shows the same pair inside an `http` block, which is how you apply it to every website on the server at once. The `70m` value is the size of the shared memory zone in megabytes, and the comment ties it directly to per unique user request tracking. Sizing is therefore a function of how many concurrent identities you expect to track, and the README does not document a rule for picking it.

That single directive pair is the whole integration. There is no package to build and nothing to register at startup, which also means the script inherits whatever Lua libraries your Nginx already has, rather than shipping its own.

The settings block is the configuration surface

Unlike most Nginx add-ons, this one has no separate config file. Everything is a Lua setting inside `anti_ddos_challenge.lua`, and the README points at a specific line in that file as the place to start. Two consequences follow.

The first is that configuration is code, so it can be reviewed and version controlled as such, but it also means a typo is a runtime error rather than a config parse failure. The second is that the project asks you to change it deliberately. The stated expectation is that you edit it for your own needs and share your changes back, which tells you the maintainer treats this file as the extension point rather than a finished product.

What lives in those settings spans a wide surface. For filtering there are IP address lists, IP subnet range lists and User-Agent lists in both whitelist and blacklist form. For authentication there is a protected area with a username and password box for restricting access to sites or paths. Logging of both successful and failed challenge solves can be enabled or disabled, and the README points Fail2Ban users at that log as a way to ban bots and addresses from it.

Range header filtering targets slowloris, not volumetric floods

One feature is worth separating from the rest because it addresses a different threat. Most download and video streaming sites use HTTP Range headers, and the Range header filtering option exists to filter and block slowhttp and slowloris style attacks.

This is the honest core of what the script can do. A JavaScript challenge costs the attacker a browser and a few seconds, which hurts high request rate floods of ordinary requests. It does nothing about a Layer 3 or Layer 4 volumetric attack, where packets never reach Nginx at all, or about a single determined client that solves the puzzle once and then holds a session. The README's claim of no limit on attack size and an uptime guarantee is a marketing line, and the mechanism described in the text does not support it.

The same applies to the WAF section. The README lists inspection of POST fields, URL content for SQL and XSS patterns, query strings, request headers and cookies. These request inspection options are not a substitute for an application-level review of what your endpoint accepts.

Caching, compression and output rewriting are in the same file

Beyond defence, the script adds a caching and output layer. Webpages can be cached, with rules to bypass the cache based on cookies or URLs, to cache only when cookies or URLs exist, and to cache only if the page is larger or smaller than a given size. Four storage backends are offered: Redis, Memcached, lrucache and Nginx `shared.DICT` memory.

Remote storage is possible, and the README states remote data and key storage as a feature, with encryption for data held in Redis or Memcached and a choice of compression algorithms including LZW, Brotli, Zstd, Zlib, GZip and Google Snappy.

On the output side, the script can minify and compress served files by removing whitespace and empty lines from JavaScript, CSS and HTML, sort or whitelist query strings, drop individual query arguments, replace content in responses, and intercept application error output. That last one has a clear purpose: the README describes hiding errors such as PHP and MySQL messages from visitors by substituting a custom error page, which is a real information disclosure fix rather than a feature for its own sake.

The risk to weigh is concentration. Filtering, caching, compression and rewriting in one file means a mistake in one area affects all of them, and the code runs before your application gets a chance to error out cleanly.

Two branches, dated releases, and packaging

The repository keeps a `master` branch for modern Nginx Lua builds and an `old-outdated-nginx-lua-builds` branch for older ones. That split is a maintenance signal worth taking seriously: the script depends on Nginx Lua libraries being current, and the README says so explicitly, advising that you use the latest Nginx and Lua builds and libraries to avoid issues.

Release naming embeds a timestamp, so recent tags read like 6.8-20261015_124048, 6.7-20261014_155937 and 6.6-20261009_085712. The last push was on 2026-10-16, one day after the newest listed release, and the three releases within one week indicate active iteration.

Packaging goes beyond the script. Alongside `lua/`, the repository carries `debian/` and `rpm/` directories and a GitHub Actions workflow named for building and publishing RPM and DEB packages. The licence is MIT, which is permissive and puts no conditions on your own configuration edits.

Editorial conclusion

Adopt this if you run Nginx with Lua bindings, can tolerate adding a shared memory zone of tens of megabytes, and want a challenge page plus a WAF in one file you can edit directly. Do not adopt it as your only defence, because the mechanism is a JavaScript interstitial that a determined client can skip, and the README itself tells you to keep Nginx and its libraries current. Verify first that your build supports `access_by_lua_file`, since a stock Nginx without Lua modules cannot load this at all.

Frequently asked questions

Official sources

1. C0nw0nk/Nginx-Lua-Anti-DDoS on GitHub
2. Issues
3. License: MIT
4. README
5. Releases