waf: A web application firewall module for NGINX

Debian/Ubuntu installation

These docs apply to the APT package nginx-module-waf provided by the GetPageSpeed Extras repository.

Configure the APT repository as described in APT repository setup.
Install the module:

sudo apt-get update
sudo apt-get install nginx-module-waf

Show suites and architectures

| Distro   | Suite             | Component   | Architectures   |
|----------|-------------------|-------------|-----------------|
| debian   | bookworm          | main        | amd64           |
| debian   | bookworm-mainline | main        | amd64           |
| debian   | trixie            | main        | amd64           |
| debian   | trixie-mainline   | main        | amd64           |
| ubuntu   | focal             | main        | amd64           |
| ubuntu   | focal-mainline    | main        | amd64           |
| ubuntu   | jammy             | main        | amd64           |
| ubuntu   | jammy-mainline    | main        | amd64           |
| ubuntu   | noble             | main        | amd64           |
| ubuntu   | noble-mainline    | main        | amd64           |

English | 简体中文

Handy, High performance Nginx firewall module.

Why ngx_waf

Basic protection: such as black and white list of IPs or IP range, uri black and white list, and request body black list, etc.
Easy to use: configuration files and rule files are easy to write and readable.
High performance: Efficient algorithms and caching.
Advanced protection: ModSecurity compatible, you can use OWASP(Open Web Application Security Project®) ModSecurity Core Rule Set.
Friendly crawler verification: Supports verifying Google, Bing, Baidu and Yandex crawlers and allowing them automatically to avoid false positives.
Captcha: Supports three kinds of captchas: hCaptcha, reCAPTCHAv2 and reCAPTCHAv3.

Features

ModSecurity compatible.
IPV4 and IPV6 support.
Support for enabling CAPTCHAs, including hCaptcha, reCAPTCHAv2 and reCAPTCHAv3.
Support authentication-friendly crawlers (based on user agent and IP identification) to avoid blocking of these crawlers (e.g. GoogleBot).
CC protection, if the request rate exceeds the limit, the IP will be automatically banned for a period of time, or use CAPTCHA to do human identification and allow it if successful.
Exceptional allow on specific IP address.
Block the specified IP address.
Block the specified request body.
Exceptional allow on specific URL.
Block the specified URL.
Block the specified query string.
Block the specified UserAgent.
Block the specified Cookie.
Exceptional allow on specific Referer.
Block the specified Referer.

Docs

Recommended link: https://docs.addesp.com/ngx_waf/
Alternate link 1: https://add-sp.github.io/ngx_waf-docs/
Alternate link 2: https://ngx-waf-docs.pages.dev/

Contact

Telegram Channel: https://t.me/ngx_waf
Telegram Group (English): https://t.me/group_ngx_waf
Telegram Group (Chinese): https://t.me/group_ngx_waf_cn

Hope you can help promote this project. The more stars got, the better this project is. :)

Test Suite

This module comes with a Perl-driven test suite. The test cases are declarative too. Thanks to the Test::Nginx module in the Perl world.

To run it on your side:

## It will take a lot of time, but it only needs to be run once.
cpan Test::Nginx

## You need to specify a temporary directory.
## If the directory does not exist it will be created automatically.
## If the directory already exists it will be **removed** first and then created.
export MODULE_TEST_PATH=/path/to/temp/dir

## You need to specify the absolute path to the dynamic module if you have it installed, 
## otherwise you do not need to run this line.
export MODULE_PATH=/path/to/ngx_http_waf_module.so

cd ./test/test-nginx
sh ./init.sh
sh ./start.sh ./t/*.t

Some parts of the test suite requires standard modules proxy, rewrite and SSI to be enabled as well when building Nginx.

Thanks

ModSecurity: An open source, cross platform web application firewall (WAF) engine.
uthash: C macros for hash tables and more.
libcurl: The multiprotocol file transfer library .
cJSON: Ultralightweight JSON parser in ANSI C.
libinjection: SQL / SQLI tokenizer parser analyzer.
libsodium: A modern, portable, easy to use crypto library.
test-nginx: Data-driven test scaffold for Nginx C module and OpenResty Lua library development.
lastversion: A command line tool that helps you download or install a specific version of a project.
ngx_lua_waf: A web application firewall based on the lua-nginx-module (openresty).
nginx-book: The Chinese language development guide for nginx.
nginx-development-guide: The Chinese language development guide for nginx.