Operating System CentOS

Install ModSecurity 3 for Nginx on Debian 12, Ubuntu 24.04 and AlmaLinux 9

Install the ModSecurity v3 module for Nginx from distribution packages, add the OWASP Core Rule Set 4, test in detection mode and switch to blocking.

This guide sets up ModSecurity v3 as a web application firewall (WAF) in front of your sites on Nginx, loads the OWASP Core Rule Set (CRS) 4, and takes you from detection-only mode to blocking. It covers Debian 12, Ubuntu 24.04 LTS and the RHEL 9 family (AlmaLinux 9, Rocky Linux 9, CentOS Stream 9), using packaged modules, so there is no need to compile Nginx.

Older tutorials on this topic targeted CentOS 7, Debian 8 and Ubuntu 16.04, all of which are end-of-life, and built Nginx against the experimental nginx_refactoring branch of ModSecurity 2. That approach is obsolete. Today the supported combination is libmodsecurity (ModSecurity v3) plus the ModSecurity-nginx connector, a regular dynamic Nginx module.

Where ModSecurity stands today

  • Ownership: Trustwave ended its support for ModSecurity on 1 July 2024 and the project moved to OWASP in 2024. It is maintained as a community project at github.com/owasp-modsecurity, and both the 2.9 and 3.0 lines still receive releases and security fixes.
  • Engines: ModSecurity 2.9.x is the Apache module. ModSecurity 3.0.x is a standalone library used by Nginx through the connector. The CRS project supports exactly these pairings: v3 for Nginx, the latest v2 for Apache.
  • Rules: the OWASP Core Rule Set is a separate project. The current major version is CRS 4. The 3.3 line reached end of life in the third quarter of 2026, so new installations should use CRS 4.

Requirements

  • A server with one of the systems above and a user with sudo rights.
  • Nginx from the distribution's own repositories. The packaged ModSecurity module is built for that Nginx build; it will not load into Nginx from nginx.org or another third-party repository (see the FAQ).
  • A working site to protect. The examples use example.com.

Step 1: Install Nginx and the ModSecurity module

Debian 12 and Ubuntu 24.04

The connector is packaged as libnginx-mod-http-modsecurity and pulls in libmodsecurity3. On Ubuntu it lives in the universe component, which is enabled by default on standard server installations.

sudo apt update
sudo apt install nginx libnginx-mod-http-modsecurity

The package enables the module through /etc/nginx/modules-enabled/50-mod-http-modsecurity.conf and installs a base configuration in /etc/nginx/modsecurity.conf together with /etc/nginx/unicode.mapping.

AlmaLinux 9, Rocky Linux 9 and CentOS Stream 9

The base repositories only ship ModSecurity for Apache. The Nginx connector (nginx-mod-modsecurity) and libmodsecurity come from EPEL:

sudo dnf install epel-release
sudo dnf install nginx nginx-mod-modsecurity
sudo systemctl enable --now nginx

This package installs the module as /usr/lib64/nginx/modules/ngx_http_modsecurity_module.so, a loader snippet in /usr/share/nginx/modules/mod-modsecurity.conf, and the same two files as on Debian: /etc/nginx/modsecurity.conf and /etc/nginx/unicode.mapping.

Check that the module loads

sudo nginx -t
sudo nginx -T 2>/dev/null | grep ngx_http_modsecurity_module

The first command must report a successful test; the second should print a load_module line. If nothing is printed, add this line at the very top of /etc/nginx/nginx.conf, with the path adjusted to where your package installed the module:

load_module modules/ngx_http_modsecurity_module.so;

Step 2: Review the base configuration

/etc/nginx/modsecurity.conf is based on the project's recommended configuration. It controls the engine itself: whether it blocks, what it logs and where. Print the three settings that matter first:

grep -E '^\s*Sec(RuleEngine|AuditEngine|AuditLog)\s' /etc/nginx/modsecurity.conf

Keep SecRuleEngine DetectionOnly for now. In this mode ModSecurity evaluates every rule and logs matches but never rejects a request, which lets you find false positives before real visitors are affected. Note the SecAuditLog path; you will read that file in step 5. If it points outside /var/log/nginx, change it so the log sits with the other Nginx logs:

SecAuditLog /var/log/nginx/modsec_audit.log

Step 3: Install the OWASP Core Rule Set 4

Without rules the engine does nothing. Debian and Ubuntu offer a modsecurity-crs package, but in Debian 12 it contains the older 3.3 rule layout, so install CRS 4 from the project's release archive. This works the same on every distribution. Look up the current version on the CRS releases page and set it in the first line; 4.25 is the long-term support line, supported until the third quarter of 2027.

CRS_VERSION=4.25.2
cd /tmp
curl -LO https://github.com/coreruleset/coreruleset/archive/refs/tags/v${CRS_VERSION}.tar.gz
curl -LO https://github.com/coreruleset/coreruleset/releases/download/v${CRS_VERSION}/coreruleset-${CRS_VERSION}.tar.gz.asc

Verify the signature with the project's public key. The key's fingerprint is published in the CRS installation documentation; compare it with the one gpg prints.

gpg --fetch-key https://coreruleset.org/security.asc
gpg --verify coreruleset-${CRS_VERSION}.tar.gz.asc v${CRS_VERSION}.tar.gz

Unpack the rules to /etc/crs4 and create the setup file from the example:

sudo mkdir /etc/crs4
sudo tar -xzf v${CRS_VERSION}.tar.gz --strip-components 1 -C /etc/crs4
sudo cp /etc/crs4/crs-setup.conf.example /etc/crs4/crs-setup.conf

Step 4: Connect the rules to Nginx

ModSecurity reads one rules file, which in turn includes everything else. The order matters: engine settings, CRS setup, plugin configuration, the rules, then plugin post-processing. Create the file:

sudo nano /etc/nginx/modsec_includes.conf
Include /etc/nginx/modsecurity.conf
Include /etc/crs4/crs-setup.conf
Include /etc/crs4/plugins/*-config.conf
Include /etc/crs4/plugins/*-before.conf
Include /etc/crs4/rules/*.conf
Include /etc/crs4/plugins/*-after.conf

Use Include here, not Apache's IncludeOptional, which ModSecurity v3 does not support.

Now switch the firewall on for a site. The connector adds two directives you need, both valid in the http, server and location contexts. Add them to the server block of the site (on Debian and Ubuntu under /etc/nginx/sites-available/, on the RHEL family in /etc/nginx/conf.d/ or nginx.conf):

server {
    listen 80;
    server_name example.com;

    modsecurity on;
    modsecurity_rules_file /etc/nginx/modsec_includes.conf;

    # ... existing root / location / proxy_pass settings ...
}

Test and reload:

sudo nginx -t
sudo systemctl reload nginx

Loading several hundred rules makes nginx -t and reloads noticeably slower than before; that is normal.

Step 5: Test in detection mode

Send a request that looks like an attack. This is the test suggested by the CRS documentation:

curl -i 'http://example.com/?foo=/etc/passwd&bar=/bin/sh'

In detection mode the page is still delivered, but the request is recorded in the audit log:

sudo tail -n 60 /var/log/nginx/modsec_audit.log

You should see the request, the IDs of the rules that matched (for example rules in the 930xxx and 932xxx ranges for file access and command injection) and an inbound anomaly score. If the file stays empty, check /var/log/nginx/error.log and make sure the SecAuditLog path is writable for Nginx.

Leave detection mode running under real traffic for a few days and review what gets flagged, especially admin areas, file uploads and API endpoints.

Step 6: Switch to blocking

When the log is clean for legitimate traffic, enable blocking and reload:

sudo sed -i 's/^SecRuleEngine .*/SecRuleEngine On/' /etc/nginx/modsecurity.conf
sudo nginx -t && sudo systemctl reload nginx

Repeat the test request. The response is now 403 Forbidden.

Handling false positives

CRS adds up a score for every matching rule and blocks when the total reaches a threshold, so a single harmless match rarely blocks anything at the default paranoia level 1. When a legitimate request is blocked, find the rule ID in the audit log and exclude it as narrowly as possible. Put exclusions in their own file that is loaded after the rules, for example /etc/crs4/rules/RESPONSE-999-EXCLUSION-RULES-AFTER-CRS.conf:

# Example: rule 942100 misfires on this site
SecRuleRemoveById 942100

For popular applications such as WordPress or Nextcloud, CRS 4 provides ready-made exclusion plugins; download the plugin and place its files in /etc/crs4/plugins/, which the include file from step 4 already loads. Reload Nginx after every change.

Keeping it up to date

  • The engine and connector are updated with the system (sudo apt upgrade or sudo dnf upgrade).
  • CRS installed from the archive is not updated automatically. To upgrade, unpack the new release into a fresh directory, copy your crs-setup.conf, exclusion files and plugins across, point the include file at it, and run sudo nginx -t before reloading.

Frequently asked questions

Is ModSecurity discontinued?

No. Trustwave's commercial support ended in July 2024 and F5 retired its own ModSecurity module for NGINX Plus, which is why many articles call it end-of-life. The open source engine itself continues as an OWASP project with regular releases for both the v2 and v3 lines.

I use Nginx from nginx.org. Can I still use the packaged module?

No. A dynamic module only loads into the Nginx build it was compiled for. In that case build libmodsecurity and then compile the connector against the source of your exact Nginx version with ./configure --add-dynamic-module=/path/to/ModSecurity-nginx --with-compat, as described in the connector's README, and load the resulting ngx_http_modsecurity_module.so with load_module.

How much does the firewall slow Nginx down?

Every request is checked against several hundred regular expressions, so expect extra CPU time per request, most visibly on dynamic pages with large request bodies. You can limit the cost by enabling modsecurity on only in the location blocks that reach your application and leaving static assets unfiltered.

Can I enable it for one site and not another?

Yes. modsecurity and modsecurity_rules_file can be set per server or location. Put them in the sites you want to protect, or set modsecurity off; in a location that must bypass the firewall.

Share story:

Continue reading other guides on How VPS.