ModSecurity & the OWASP Core Rule Set

This page describes the ModSecurity CRS plugins we write for the applications we host ourselves, and the APT packages that run them on NGINX and Angie. It is for Debian and Ubuntu admins who already run the OWASP Core Rule Set (CRS) on ModSecurity v3, or plan to, and want it to understand one specific application.

The engine and the rule set are generic by design. They do not know what normal traffic to your application looks like, so CRS either blocks legitimate requests or has to be tuned by hand. A CRS plugin closes that gap for one application: exclusions so real requests are not blocked, extra rules for attacks CRS does not model, and in two of the three plugins a positive-security allowlist that denies anything the application does not use.

All three are CRS 4 plugins, and each one runs the go-ftw regression suite in CI on Apache with mod_security2. The other test lanes differ per plugin. The ViMbAdmin plugin runs the same suite on Angie with libmodsecurity3 and on NGINX with the Coraza connector. The Vaultwarden plugin runs it on Angie with libmodsecurity3, and checks on Coraza only that every rule file loads. The WordPress plugin runs load, smoke and targeted checks on the official CRS NGINX image with libmodsecurity3, and a load check plus targeted runtime checks on Coraza. Each plugin page below has the details.

Our three ModSecurity CRS plugins

  • wordpress-hardening-plugin: more than 100 rules that add the WordPress-specific checks CRS lacks. They include typed-parameter checks (ORDER BY injection, non-integer values in WordPress’s numeric query variables), blocks for xmlrpc, user enumeration, the theme and plugin editor and sensitive files, plus optional GeoIP control for the login page. The aim is to stop many plugin SQL injection and XSS attempts before PHP runs. Use it alongside the CRS project’s WordPress rule exclusions plugin.
  • vaultwarden-crs-plugin: makes CRS work with Vaultwarden, the Rust Bitwarden-compatible server. It holds narrow exclusions for the encrypted JSON API and an opt-in path allowlist built from Vaultwarden’s real route map.
  • vimbadmin-crs-plugin: exclusions and an argument-name and route allowlist for the ViMbAdmin mailbox admin panel, so CRS can scan argument values without blocking passwords, CSRF tokens or alias lists.

What a CRS plugin actually does

Every CRS plugin is built from the same three rule files, which CRS loads in a fixed order:

  • <name>-config.conf holds the enable flag and the tunables. It loads first, before any CRS rule.
  • <name>-before.conf runs before the CRS rules. This is where the false-positive exclusions live, for example “do not run the base64 detector on this encrypted blob”.
  • <name>-after.conf runs after the CRS rules. It holds the positive-security layer: allow the application’s real paths and arguments, deny the rest.

The WordPress plugin adds two optional files on top of that: wordpress-hardening-ip.conf for client-IP and trusted-proxy handling, and wordpress-hardening-ratelimit.conf for login rate limiting, which works on Apache with mod_security2 only. CRS does not load either file automatically; you include them yourself.

The default state differs per plugin. The Vaultwarden and ViMbAdmin plugins are off by default, because they deliberately weaken CRS on their application’s routes. You switch each one on for its own vhost with a rule that sets the plugin’s enable variable. There is no Host check, so one CRS engine can serve many vhosts and only the vhost you flag gets the plugin. The WordPress plugin follows the standard CRS template instead: it is on as soon as CRS loads it, and you turn it off for a vhost by setting tx.wordpress-hardening-plugin_enabled=0 before the plugin’s own rules run (see below).

Install and enable a plugin

The modsecurity-crs package already contains the WordPress and ViMbAdmin plugins, in /etc/modsecurity/crs/plugins-available/. To enable one, link its directory into plugins-enabled/, for example ln -s ../plugins-available/vimbadmin-crs-plugin /etc/modsecurity/crs/plugins-enabled/vimbadmin-crs-plugin. The Vaultwarden plugin is not in the package yet: download its plugins/ directory from GitHub and place it the same way.

Then enable the plugin only on the matching vhost. Example on Angie or NGINX with libmodsecurity3:

server {
    server_name app.example.com;
    modsecurity on;
    modsecurity_rules '
        SecAction "id:9530001,phase:1,nolog,pass,setvar:tx.vaultwarden-plugin_enabled=1"
    ';
}

This works because the ModSecurity connector runs a server block’s own rules before the rules it inherits from http, so the flag is set before the plugin checks it. On Apache with mod_security2 it is different: a SecAction inside <VirtualHost> or <Location> runs after the inherited CRS rules and does not enable the plugin. Put a rule that matches the host name in the main configuration instead, before the CRS Include line, for example SecRule REQUEST_HEADERS:Host "@streq app.example.com" "id:9530002,phase:1,nolog,pass,setvar:tx.vaultwarden-plugin_enabled=1". The Vaultwarden plugin page describes how we tested both engines.

Turning the WordPress plugin off for one vhost uses the same placement with the value reversed. On Angie or NGINX, put a SecAction that sets tx.wordpress-hardening-plugin_enabled=0 in that server block’s modsecurity_rules. On Apache, use a Host-matching rule before the CRS Include. The plugin only sets the flag to 1 when it is still unset, so its kill switch (rule 9522099) sees the 0 and removes the plugin’s other rules for that request.

Always roll out a positive-security allowlist with CRS in DetectionOnly first. Watch the audit log for requests the allowlist would have denied, then switch back to blocking. In the ViMbAdmin plugin the allowlist is on once the plugin is enabled (set tx.vimbadmin-plugin_positive_security=0 to run without it). In the Vaultwarden plugin it is a separate opt-in.

Get the engine and rules

The whole WAF stack installs with APT once the repository is set up:

  • libmodsecurity3, the ModSecurity v3 engine, and its connector module: libnginx-mod-http-modsecurity for NGINX or angie-module-http-modsecurity for Angie. See the ModSecurity module page, the ModSecurity and CRS install guide and the full setup walkthrough.
  • modsecurity-crs, the OWASP Core Rule Set packaged from the current upstream branch, with 20 plugins in plugins-available/. It installs the rules under /etc/modsecurity/crs/ and ships /etc/modsecurity/modsecurity.conf-recommended with the CRS and plugin Include lines already appended in the right order. Copy that file to modsecurity.conf to use it; it starts in DetectionOnly mode. See the packages page.
  • The connector is a dynamic module for both servers; see the NGINX modules and Angie modules pages for the rest of the set.

The packages are built for Debian 13 trixie, 12 bookworm and 11 bullseye, and for Ubuntu 26.04 resolute, 24.04 noble and 22.04 jammy, on amd64 and arm64. On Debian 11 arm64 only the engine and the rule set are available, without the NGINX and Angie connector modules.

Related reading