Frequently Asked Questions

Who Leads the ModSecurity Project?

ModSecurity was created by Ivan Ristić and was later developed and sponsored by Trustwave (SpiderLabs). In January 2024 Trustwave transferred stewardship of the code to the OWASP ModSecurity project, which maintains both the v2 and the v3 code lines today. The current project leaders are listed on the OWASP project page; the active maintainers are visible on the GitHub organization.

Background and Support

What exactly is ModSecurity?

ModSecurity is an open source, free web application firewall (WAF) engine. WAFs establish an external security layer that detects and prevents attacks before they reach web applications. ModSecurity provides protection from a range of attacks against web applications and allows for HTTP traffic monitoring and real-time analysis with little or no changes to existing infrastructure. See the Introduction.

Which version of ModSecurity should I be using? v2.9.x or v3.0.x?

Both code lines are supported and actively maintained by OWASP (current releases: v2.9.15 and v3.0.17). The web server you run decides:

• Apache httpd: ModSecurity v2 (mod_security2, branch v2/master). The v3 Apache connector exists but is not production ready.
• Microsoft IIS: ModSecurity v2 (the IIS module is built from the same v2 tree).
• NGINX: libModSecurity v3 with the ModSecurity-nginx connector. NGINX support was removed from the v2 tree in 2.9.13.
• Your own application or another server: libModSecurity v3, through its C or C++ API.

Both versions run the OWASP CRS. The rule language is the same; the differences in behavior and the features v3 does not implement are listed in Migrating from v2 to v3.

Where do I get more help on ModSecurity?

• Issues and feature requests: https://github.com/owasp-modsecurity/ModSecurity/issues (use the connector repository, for example ModSecurity-nginx, when the problem is in the connector).
• Questions are welcome in the same issue tracker; label them as questions and search closed issues first.
• Security vulnerabilities: follow the security policy or email [email protected]. Do not open a public issue.
• OWASP CRS questions belong to the CRS project, which is run by a separate team.

Commercial support is not offered by the project itself. Several vendors package ModSecurity and the CRS and support them as part of their products.

Is there anything that I should do prior to creating a new issue?

Yes. There is a good chance that the issue you are facing has already been discussed and, in many cases, either a fix has been produced or a workaround or mitigation has been suggested. Search open and closed issues first. If you cannot find an answer, create a new issue, follow the issue template and supply as much pertinent information as possible: ModSecurity version, connector or web server version, the rule involved and a debug log excerpt.

Will I always get an immediate response to my issue?

GitHub issues are handled on a best-effort basis by volunteers. You may also get assistance from other members of the ModSecurity community.

How do I report a security vulnerability?

Do not open a public issue. Report it privately by creating a draft security advisory on GitHub for the affected repository, for example ModSecurity, ModSecurity-nginx or ModSecurity-apache. The maintainers triage the report there, coordinate a fix and publish the advisory together with the fixed release. Reporters are credited in the advisory.

If you cannot use GitHub, email [email protected] instead.

What about the mailing lists?

The SourceForge mailing lists that the project used in the past are no longer in use. Use GitHub issues instead. Release announcements are published on the GitHub releases pages of each repository.

Where can I find books about Web Application Firewalls and ModSecurity?

The books below predate the v3 code line, but the rule language and the concepts they explain still apply.

ModSecurity Handbook

ModSecurity Handbook is “The definitive guide to the popular open source web application firewall”, written by Ivan Ristić (original author of ModSecurity), later updated by Christian Folini. The book is available from Feisty Duck in hard copy or digital form.

Web Application Defender’s Cookbook: Battling Hackers and Defending Users

The Web Application Defender’s Cookbook: Battling Hackers and Protecting Users is a book written by the former ModSecurity Project Lead Ryan Barnett. The book outlines critical defensive techniques to protect web applications and includes example ModSecurity rules/scripts.

ModSecurity 2.5

ModSecurity 2.5 is “A complete guide to using ModSecurity”, written by Magnus Mischel. The book is available from Packt Publishing in both hard copy and digital forms.

Apache Security

Apache Security is a comprehensive Apache Security resource, written by Ivan Ristić for O’Reilly.

Preventing Web Attacks with Apache

Preventing Web Attacks with Apache. Building on his groundbreaking SANS presentations on Apache security, Ryan C. Barnett reveals why your Web servers represent such a compelling target, how significant exploits are performed, and how they can be defended against.

Getting Started

What type(s) of security models does ModSecurity support?

There is a common misconception that ModSecurity can only be used for negative policy enforcement. This is not the case. ModSecurity does not have any default security model “out-of-the-box.” It is up to the user to implement appropriate rules to achieve the desired security model. That being said, these are the security models which are most often employed:

Negative Security Model - looks for known bad, malicious requests. This method is effective at blocking a large number of automated attacks, however it is not the best approach for identifying new attack vectors. Using too many negative rules may also negatively impact performance.

Positive Security Model - When positive security model is deployed, only requests that are known to be valid are accepted, with everything else rejected. This approach works best with applications that are heavily used but rarely updated.

Virtual Patching - Its rule language makes ModSecurity an ideal external patching tool. External patching is all about reducing the window of opportunity. Time needed to patch application vulnerabilities often runs to weeks in many organizations. With ModSecurity, applications can be patched from the outside, without touching the application source code (and even without any access to it), making your systems secure until a proper patch is produced.

Extrusion Detection Model - ModSecurity can also monitor outbound data and identify and block information disclosure issues such as leaking detailed error messages or Social Security Numbers or Credit Card Numbers.

I hear that ModSecurity can be run in embedded-mode, what does that mean exactly?

The term “embedded” simply refers to the fact that ModSecurity is running inside the webserver process. Most WAFs function as totally separate hosts and sit in front of the web servers. Running in embedded-mode has some tradeoffs that should be considered:

Advantages

• Easy to add to an existing web server.
• Not a point of failure with respect to traffic.

Disadvantages

• ModSecurity can only protect the local web server.
• ModSecurity will consume local resources such as CPU and RAM.
• Management of log files and configurations can become difficult if you have multiple installations.

I hear that ModSecurity can be run in reverse-proxy mode. How does that differ from embedded-mode?

The only difference with this deployment vs. an embedded one is that the web server itself is configured to function as a reverse proxy.

Advantages

• Single point of access functions as a choke point so you consolidate applying security settings and makes management easier.
• Network topology is hidden from the outside world so it will be more difficult for attackers to enumerate your web platforms.
• Increased performance if SSL accelerators/caching used.
• You can implement vulnerability filters to protect any vulnerable web server or application on the back-end (IIS, ASP, PHP, etc.). See related section on Virtual Patching.

Disadvantages

• A potential traffic bottleneck if the reverse proxy can not handle the network load.
• A potential point of failure: if the reverse proxy goes down it may cause a denial of service to the web applications that are behind it.
• Requires changes to the network.

Configuring ModSecurity

Should I initially set the SecRuleEngine to On?

No. Every rule set can have false positives in new environments. A new installation should initially run with SecRuleEngine set to DetectionOnly (the setting shipped in modsecurity.conf-recommended). After running ModSecurity in detection-only mode for a while, review the events generated and decide if any modification to the rule set should be made before moving to blocking mode.

How do I get ModSecurity to inspect request and response bodies?

You need to set the following two directives:

SecRequestBodyAccess On

SecResponseBodyAccess On

How can I verify exactly how ModSecurity is processing rules and requests?

You need to enable the debug log with SecDebugLog and increase the log level with SecDebugLogLevel. If you set the debug log level to 9, it will tell you exactly what tasks it is completing along with what data it is acting upon. Do be aware that while the increased debug log level does help from a troubleshooting perspective, it does negatively impact performance. See Debugging.

ModSecurity Rules Language

What are the OWASP ModSecurity Core Rules (CRS) and should I use them?

Using ModSecurity requires rules. Installations commonly use one or more of the following:

• A generic rule set that provides generic protection from unknown vulnerabilities
• A rule set addressing known CVEs in specific applications
• Custom rules

The most widely used generic rule set is the OWASP CRS, which is managed by a separate OWASP project. It runs on both ModSecurity v2 and v3.

How do I allow an IP address to bypass ModSecurity?

The first issue to realize is that the allow action is only applied to the current phase. This means that if a rule matches in a subsequent phase it may still take a disruptive action. The recommended rule configuration to allow a remote IP address to bypass ModSecurity rules is to do the following (where 192.168.1.100 should be substituted with the desired IP address):

SecRule REMOTE_ADDR "@ipMatch 192.168.1.100" \
    "id:1000,\
    phase:1,\
    allow,\
    nolog,\
    ctl:ruleEngine=Off"

If you want to allow uninterrupted access to the remote IP address, however you still want to log rule alerts, then you can use this rule:

SecRule REMOTE_ADDR "@ipMatch 192.168.1.100" \
    "id:1000,\
    phase:1,\
    allow,\
    nolog,\
    ctl:ruleEngine=DetectionOnly"

If you want to disable both the rule and audit engines, then you can optionally add another ctl action:

SecRule REMOTE_ADDR "@ipMatch 192.168.1.100" \
    "id:1000,\
    phase:1,\
    allow,\
    nolog,\
    ctl:ruleEngine=Off,\
    ctl:auditEngine=Off"

How do I handle False Positives and creating Custom Rules?

It is inevitable; you will run into some False Positive hits when using web application firewalls. This is not something that is unique to ModSecurity. All web application firewalls will generate false positives from time to time. The directives SecRuleRemoveById, SecRuleUpdateTargetById and the ctl action are the tools for excluding rules or targets. If you use the OWASP CRS, follow the CRS documentation on false positives and tuning.

Will using a large amount of negative filtering rules impact performance?

Yes. Each and every rule that you implement will consume resources (RAM, CPU, etc…). The two most important factors to consider with creating ModSecurity rules are the total number of rules and the Regular Expression optimizations. A single rule with a complex regular expression is significantly faster than multiple rules with simple regular expressions. Unfortunately, it is quite easy to create inefficient RegEx patterns. Optimizing RegExs by utilizing Grouping Only/Non-Capturing Parentheses can cut the validation time by up to 50%. The OWASP CRS is optimized for performance.

What is a Virtual Patch and why should I care?

Fixing identified vulnerabilities in web applications always requires time. Organizations often do not have access to a commercial application’s source code and are at the vendor’s mercy while waiting for a patch. Even if they have access to the code, implementing a patch in development takes time. This leaves a window of opportunity for the attacker to exploit. External patching (also called “just-in-time patching” and “virtual patching”) is one of the biggest advantages of web application firewalls as they can fix this problem externally. A fix for a specific vulnerability is usually very easy to design and in most cases it can be done in less than 15 minutes.

https://cheatsheetseries.owasp.org/cheatsheets/Virtual_Patching_Cheat_Sheet.html

Managing Alerts

How do I manage ModSecurity logs if I have multiple installations?

If you have more than one ModSecurity installation, you have undoubtedly run into issues with consolidating, analyzing and responding to alert messages. The original “Serial” format of the audit log is multi-line with all records held within one file, which makes remote logging difficult. Two options exist:

• Both v2 and v3 can write the audit log in JSON format (SecAuditLogFormat JSON), one entry per line, which any log shipper can forward to a central system.
• ModSecurity v2 ships the ModSecurity Log Collector (mlogc), which sends individual audit log entries to a remote host in near real time. mlogc is not part of v3.

Can I send ModSecurity alert log data through Syslog?

Yes. If you already have a central Syslog infrastructure and/or a SIEM, you might want to forward the short ModSecurity alert messages that appear in the web server error log; both Apache and NGINX can send their error logs to syslog. However, the data being forwarded is a very small subset of the entire transaction. It is only a warning message and not enough information to conduct proper incident response to determine if there was a false positive or if it was a legitimate attack. In order to determine this information, you need access to the ModSecurity audit log files. See Logging and Data Formats.

Building libModSecurity v3 from source

libModSecurity is a C++17 library. On Unix-like systems it is built with autotools; Windows builds use CMake and Conan and are described in the Windows build README. The library does nothing on its own: after installing it, add a connector for your web server, see libModSecurity v3 with NGINX and libModSecurity v3 with Apache.

If you only need a working installation, your distribution most likely packages the library and the NGINX connector already; see Distribution packages for libModSecurity v3. Build from source when you need the current release before your distribution ships it, a build option the package does not enable (LMDB, Lua, ssdeep), or the development branch.

Dependencies

When an optional library is missing, the corresponding operator or directive is compiled out and a configuration using it fails to load. LMDB is special: even when the library is installed, it is not used unless you pass --with-lmdb explicitly.

The git tree also carries submodules under others/: libinjection (@detectSQLi, @detectXSS) and mbedtls (hashing and base64 helpers). Both are required for a source build and must be initialized after cloning; the release tarball bundles them.

Package names for the development headers, for the two most common families:

# Debian and Ubuntu
sudo apt install build-essential automake libtool pkg-config libyajl-dev libpcre2-dev libxml2-dev \
    libcurl4-openssl-dev liblua5.4-dev libmaxminddb-dev libfuzzy-dev liblmdb-dev
# Fedora, RHEL and EPEL
sudo dnf install gcc-c++ automake libtool pkgconf yajl-devel pcre2-devel libxml2-devel \
    libcurl-devel lua-devel libmaxminddb-devel ssdeep-devel lmdb-devel

Get the source

Stable release (recommended). The current release is v3.0.17. The release tarball already bundles the git submodules and is signed:

wget https://github.com/owasp-modsecurity/ModSecurity/releases/download/v3.0.17/modsecurity-v3.0.17.tar.gz
wget https://github.com/owasp-modsecurity/ModSecurity/releases/download/v3.0.17/modsecurity-v3.0.17.tar.gz.sha256
wget https://github.com/owasp-modsecurity/ModSecurity/releases/download/v3.0.17/modsecurity-v3.0.17.tar.gz.asc
sha256sum -c modsecurity-v3.0.17.tar.gz.sha256
gpg --verify modsecurity-v3.0.17.tar.gz.asc modsecurity-v3.0.17.tar.gz
tar xzf modsecurity-v3.0.17.tar.gz
cd modsecurity-v3.0.17

Development branch. For the latest code, clone v3/master and initialize the submodules:

git clone --branch v3/master https://github.com/owasp-modsecurity/ModSecurity
cd ModSecurity
git submodule update --init --recursive

Verify that every submodule shows a commit hash in git submodule status; a leading - means it was not initialized and the build will fail.

Build

./build.sh        # git checkout only: generates the configure script
./configure
make
sudo make install

The library is installed under /usr/local/modsecurity by default (--prefix changes that). Because it is a dynamic library, that location must be known to the dynamic linker: add /usr/local/modsecurity/lib to /etc/ld.so.conf.d/ and run ldconfig, or set LD_LIBRARY_PATH. The modsecurity.pc file installed under lib/pkgconfig lets other software find the library through pkg-config.

Run the unit and regression tests after building:

make check

Configure options

Every optional library has a --with-NAME=PATH option that points at an installation prefix, and a --without-NAME form that disables the feature even when the library is present:

Feature switches:

libModSecurity v3 with NGINX

The ModSecurity-nginx connector links libModSecurity into NGINX as a third-party module. Unlike the old (v2-era) standalone module, it is a thin layer between NGINX and the library: the rules engine, the body processors and the logging all live in libModSecurity. The current connector release is v1.0.4.

Distribution packages

Most distributions ship the connector as a dynamic NGINX module built against their own nginx and libmodsecurity packages, which is the easiest way to get a working setup. Versions as of October 2026:

Ubuntu 22.04 has no connector package in the main archive. Debian, Ubuntu and the Red Hat family also have the current development builds of both the connector and the library in the digitalwave repository, maintained by one of the ModSecurity project leaders.

On Debian and Ubuntu:

sudo apt install libnginx-mod-http-modsecurity modsecurity-crs

The package enables the module through /etc/nginx/modules-enabled/50-mod-http-modsecurity.conf and installs modsecurity.conf (the recommended base configuration, SecRuleEngine DetectionOnly), unicode.mapping and modsecurity_includes.conf into /etc/nginx/, plus a sample site at /etc/nginx/sites-available/default-modsecurity.conf. Turn it on per server or location with modsecurity on; and modsecurity_rules_file /etc/nginx/modsecurity_includes.conf;, and include the CRS from that file by uncommenting the owasp-crs.load line. libModSecurity has no IncludeOptional, so replace that directive by Include in the files the CRS package installs. NGINX reports most CRS events at error_log ... info;.

On Fedora and EPEL:

sudo dnf install nginx-mod-modsecurity

The module is loaded from /usr/share/nginx/modules/mod-modsecurity.conf, the base configuration is installed as /etc/nginx/modsecurity.conf, and /etc/nginx/nginx.conf.modsecurity is a sample server configuration; add the modsecurity directives to your own server blocks as shown below.

Compilation

Get the connector source:

wget https://github.com/owasp-modsecurity/ModSecurity-nginx/releases/download/v1.0.4/ModSecurity-nginx-v1.0.4.tar.gz
wget https://github.com/owasp-modsecurity/ModSecurity-nginx/releases/download/v1.0.4/ModSecurity-nginx-v1.0.4.tar.gz.sha256
wget https://github.com/owasp-modsecurity/ModSecurity-nginx/releases/download/v1.0.4/ModSecurity-nginx-v1.0.4.tar.gz.asc
sha256sum -c ModSecurity-nginx-v1.0.4.tar.gz.sha256
gpg --verify ModSecurity-nginx-v1.0.4.tar.gz.asc ModSecurity-nginx-v1.0.4.tar.gz
tar xzf ModSecurity-nginx-v1.0.4.tar.gz

or clone the development branch with git clone https://github.com/owasp-modsecurity/ModSecurity-nginx. Install libModSecurity first (see Building libModSecurity v3 from source or your distribution’s libmodsecurity-dev / libmodsecurity-devel package). The connector’s config script looks for the library under /usr/local/modsecurity; for any other location export MODSECURITY_INC (the directory holding modsecurity/modsecurity.h) and MODSECURITY_LIB (the directory holding libmodsecurity.so) before running NGINX’s configure.

From the NGINX source directory, add the connector as a static module:

./configure --add-module=/path/to/ModSecurity-nginx
make
sudo make install

Or build it as a dynamic module. The NGINX source version and configure arguments must then match the NGINX binary you load it into (nginx -V prints them):

./configure --add-dynamic-module=/path/to/ModSecurity-nginx --with-compat
make modules

and load it with load_module modules/ngx_http_modsecurity_module.so; at the top of nginx.conf.

The connector runs ModSecurity phase 1 in NGINX’s rewrite phase, phase 2 in the preaccess phase (the development branch has moved it to the access phase, after allow/deny and auth_*), phases 3 and 4 in the header and body filters, and phase 5 in the log phase.

Configuration directives

The connector adds the following directives, all valid in the http, server and location contexts. The modsecurity_rules* directives may be repeated and accumulate; a location inherits the rules of its server.

modsecurity

Turns ModSecurity on or off for the context. This flag only enables the module in NGINX; the rule engine state is controlled separately by SecRuleEngine.

modsecurity_rules_file

Loads ModSecurity configuration and rules from a file:

server {
    modsecurity on;
    location / {
        root /var/www/html;
        modsecurity_rules_file /etc/my_modsecurity_rules.conf;
    }
}

modsecurity_rules_remote

Downloads the configuration from a URL, authenticating with the given key, exactly like SecRemoteRules (libModSecurity must be built with libcurl):

server {
    modsecurity on;
    location / {
        root /var/www/html;
        modsecurity_rules_remote my-server-key https://my-own-server/rules/download;
    }
}

modsecurity_rules

Embeds rules directly in the NGINX configuration, which is handy for per-location overrides:

server {
    modsecurity on;
    location / {
        root /var/www/html;
        modsecurity_rules_file /etc/my_modsecurity_rules.conf;
    }
    location /ops {
        root /var/www/html/opts;
        modsecurity_rules '
          SecRuleEngine On
          SecDebugLog /tmp/modsec_debug.log
          SecDebugLogLevel 9
          SecRuleRemoveById 10
        ';
    }
}

modsecurity_transaction_id

Supplies the transaction ID from NGINX instead of letting the library generate one. The string may contain NGINX variables, so access-log and audit-log entries can be correlated:

log_format extended '$remote_addr - $remote_user [$time_local] '
                    '"$request" $status $body_bytes_sent '
                    '"$http_referer" "$http_user_agent" $request_id';

server {
    server_name host1;
    modsecurity on;
    modsecurity_transaction_id "host1-$request_id";
    access_log logs/host1-access.log extended;
    error_log logs/host1-error.log;
    location / {
        ...
    }
}

modsecurity_use_error_log

Controls whether ModSecurity alert messages are also written to the NGINX error log. This directive exists only on the connector’s master branch; the 1.0.4 release does not know it and refuses to start with it in the configuration. Distribution packages built from release tarballs do not have it either.

libModSecurity v3 with Apache

The ModSecurity-apache connector loads libModSecurity into Apache HTTP Server as the module mod_security3.

Compilation

Install libModSecurity first (see Building libModSecurity v3 from source), make sure apxs from the Apache development package is on the path, then:

git clone https://github.com/owasp-modsecurity/ModSecurity-apache
cd ModSecurity-apache
./autogen.sh
./configure
make
sudo make install

Usage

Load the module and point it at a rules file. The directives mirror the NGINX connector’s:

LoadModule security3_module modules/mod_security3.so

modsecurity on
modsecurity_rules_file /etc/my_modsecurity_rules.conf

modsecurity_rules_remote <key> <URL> and modsecurity_rules '<inline rules>' are also available, with the same meaning as in the NGINX connector. All of them are accepted in the server and virtual host configuration and in <Location> and <Directory> blocks.

Distribution packages for libModSecurity v3

Every major distribution packages libModSecurity, and most also package the NGINX connector built against it. The packaged versions lag behind the upstream release, sometimes by several minor versions, but the distributions backport security fixes to the version they ship. Versions in the package repositories as of October 2026:

The development headers are in libmodsecurity-dev (Debian, Ubuntu) or libmodsecurity-devel (Fedora, EPEL, openSUSE); install them when you build a connector yourself. The OWASP CRS rule set is packaged as modsecurity-crs on Debian and Ubuntu and mod_security_crs on Fedora and EPEL. Alpine Linux and Amazon Linux 2023 do not package libModSecurity; use the container images or build from source there.

See libModSecurity v3 with NGINX for how the Debian and Fedora connector packages are laid out and enabled.

The digitalwave repository

modsecurity.digitalwave.hu is an APT repository for Debian and Ubuntu maintained by Ervin Hegedüs, co-leader of the ModSecurity project and the Debian maintainer of these packages. It builds the current v2/master and v3/master branches, the NGINX connector and the latest OWASP CRS release for every supported Debian and Ubuntu version, as the same packages the distributions ship, so you get the engine fixes months before they reach a distribution release. Packages are for amd64 only. As of October 2026 it provides:

The packages live in the <release>-backports suite of the repository. Ubuntu 22.04 also needs the plain <release> suite, which carries the rebuilt nginx packages the connector is part of there. Add the key, the suite and an APT pin so that only the ModSecurity packages come from this repository:

sudo apt install apt-transport-https lsb-release ca-certificates curl
# Debian 12 and later
sudo wget -qO - https://modsecurity.digitalwave.hu/archive.key | sudo tee /etc/apt/trusted.gpg.d/modsecurity-digitalwave.asc
# Ubuntu 24.04 and later
sudo wget -qO - https://modsecurity.digitalwave.hu/dwmodsec.gpg | sudo tee /etc/apt/trusted.gpg.d/modsecurity-digitalwave.gpg

# Debian (use .../ubuntu/ on Ubuntu)
echo "deb http://modsecurity.digitalwave.hu/debian/ $(lsb_release -sc)-backports main" | sudo tee /etc/apt/sources.list.d/dwmodsec.list

cat << EOF2 | sudo tee /etc/apt/preferences.d/99modsecurity
Package: *libnginx-mod-http-modsecurity*
Pin: origin modsecurity.digitalwave.hu
Pin-Priority: 900

Package: *libapache2-mod-security2*
Pin: origin modsecurity.digitalwave.hu
Pin-Priority: 900

Package: *modsecurity-crs*
Pin: origin modsecurity.digitalwave.hu
Pin-Priority: 900

Package: *libmodsecurity*
Pin: origin modsecurity.digitalwave.hu
Pin-Priority: 900
EOF2
sudo apt update
sudo apt install libnginx-mod-http-modsecurity modsecurity-crs   # or libapache2-mod-security2

Debian 11 and Ubuntu 22.04 use apt-key add - for the key and need both the <release> and <release>-backports lines; the repository page has the exact commands for every release, the full version matrix and the configuration walkthrough. Run apt-cache policy libmodsecurity3 afterwards to confirm the candidate comes from modsecurity.digitalwave.hu. If you previously installed the distribution’s own package, run apt clean first.

Containers

The OWASP CRS project publishes images with NGINX and libModSecurity. owasp/modsecurity contains NGINX with the connector and no rules (tags nginx, 3-<timestamp>, with -alpine variants); owasp/modsecurity-crs bundles the OWASP CRS on top of it and is the image most deployments want. See https://github.com/coreruleset/modsecurity-crs-docker for the tags and the environment variables that configure the engine.

docker run -p 8080:8080 owasp/modsecurity-crs:nginx

Building packages

To build a newer version as a distribution package, rebuild the distribution’s own packaging against the new release rather than starting from scratch; see Building distribution packages.

ModSecurity v2 for Apache

ModSecurity v2 is an Apache httpd module (mod_security2). The current release is v2.9.15. You can install it from your distribution’s package repository, which is the quickest route and gets you security updates through the normal package channels, or build it from source to get the latest release.

Prerequisites

Apache httpd 2.x

ModSecurity 2.x works with Apache httpd 2.0.x or later (2.4.x is the version in common use today). To build from source you need the Apache development files (the apxs tool and headers), which distributions package as httpd-devel or apache2-dev.

mod_unique_id

Make sure you have mod_unique_id loaded. It is packaged with Apache httpd and ModSecurity uses it for the UNIQUE_ID variable and audit log entry identifiers.

libapr and libapr-util

Required. https://apr.apache.org/. APR-util must be compiled with crypto support if you intend to use the crypto parameter of SecRemoteRules; otherwise configure prints a warning and continues.

libpcre2 (or libpcre)

Required. ModSecurity 2.9.x uses PCRE2 by default (https://www.pcre.org/). The legacy PCRE 8.x library is still supported: pass --with-pcre=PATH to configure to use it, in which case the PCRE2 check is skipped.

libxml2

Required. https://gitlab.gnome.org/GNOME/libxml2. Used by the XML request body processor and the @validateDTD/@validateSchema operators.

libyajl

Needed for the JSON request body processor. Configure detects it automatically (--with-yajl=PATH to point at a custom location); without it ModSecurity builds without JSON support.

liblua 5.x

Optional; only needed for SecRuleScript and the exec action with Lua scripts. Lua 5.1 through 5.5 are supported (--with-lua=PATH). https://www.lua.org/download.html

libcurl

Optional. Needed for SecRemoteRules and for the ModSecurity Log Collector (mlogc), which sends audit logs to a central repository. Without libcurl, configure disables building mlogc. https://curl.se/libcurl/

libfuzzy (ssdeep)

Optional; only needed for the @fuzzyHash operator (--with-ssdeep=PATH).

Distribution Packages

Every major distribution packages ModSecurity v2 for Apache. Packaged versions lag behind the upstream release, sometimes by several minor versions, but the distributions backport security fixes to the version they ship, so an older version number does not by itself mean an unpatched module. If you need a feature from a newer release, build from source instead.

Versions in the distributions’ package repositories as of October 2026:

Alpine Linux, Arch Linux and Amazon Linux 2023 do not package ModSecurity v2; build from source or use the container image there. The OWASP CRS project separately packages the OWASP CRS rule set for most of these distributions (modsecurity-crs on Debian and Ubuntu, mod_security_crs on Fedora and EPEL).

Debian and Ubuntu

sudo apt install libapache2-mod-security2
sudo cp /etc/modsecurity/modsecurity.conf-recommended /etc/modsecurity/modsecurity.conf
sudo a2enmod security2
sudo systemctl restart apache2

The package enables the module through /etc/apache2/mods-available/security2.load and security2.conf. The latter sets SecDataDir /var/cache/modsecurity and includes every *.conf file in /etc/modsecurity/, so that directory is where your modsecurity.conf and any local rule files go; unicode.mapping is already installed there. The audit log goes to /var/log/apache2/modsec_audit.log by default. The shipped modsecurity.conf-recommended leaves the engine in DetectionOnly; switch SecRuleEngine to On once you have reviewed the logs.

Current builds from the digitalwave repository

For Debian 11 to 13 and Ubuntu 22.04 to 26.04, the digitalwave repository maintained by a ModSecurity project leader provides libapache2-mod-security2 built from the current v2/master branch (2.9.16 pre-release as of October 2026) together with the latest modsecurity-crs. It is the same package as the distribution’s, so the configuration layout above applies unchanged. Repository setup is described under Distribution packages for libModSecurity v3.

RHEL, AlmaLinux, Rocky Linux, CentOS Stream

The module comes from EPEL (Extra Packages for Enterprise Linux):

sudo dnf install epel-release        # on RHEL itself: dnf install https://dl.fedoraproject.org/pub/epel/epel-release-latest-$(rpm -E %rhel).noarch.rpm
sudo dnf install mod_security
sudo systemctl restart httpd

Fedora

sudo dnf install mod_security
sudo systemctl restart httpd

On Fedora and EPEL the module is loaded by /etc/httpd/conf.modules.d/10-mod_security.conf (which also loads mod_unique_id if needed) and configured by /etc/httpd/conf.d/mod_security.conf. That file carries the recommended base configuration with SecRuleEngine On already set, response body access off, logs under /var/log/httpd/, persistent data under /var/lib/mod_security, and it includes /etc/httpd/modsecurity.d/*.conf, modsecurity.d/activated_rules/*.conf and modsecurity.d/local_rules/*.conf. Put your own rules in local_rules/.

openSUSE

sudo zypper install apache2-mod_security2
sudo a2enmod security2
sudo systemctl restart apache2

Run rpm -ql apache2-mod_security2 to see where the package placed its configuration and the recommended configuration file.

FreeBSD

pkg install ap24-mod_security

Or build the port from www/mod_security. The port installs the module into the Apache modules directory and the sample configuration files under /usr/local/etc/modsecurity/; add the LoadModule security2_module libexec/apache24/mod_security2.so line to httpd.conf and include your configuration from there.

Gentoo

emerge www-apache/mod_security

Add -D SECURITY to APACHE2_OPTS in /etc/conf.d/apache2 to load the module.

Containers

The OWASP CRS project publishes ready-to-run images for Docker and compatible runtimes. owasp/modsecurity contains Apache httpd with ModSecurity v2 and no rules (tags apache, 2-<timestamp>, with -alpine variants); owasp/modsecurity-crs bundles the OWASP CRS on top of it and is the image most deployments want. See https://github.com/coreruleset/modsecurity-crs-docker for the tags and the environment variables that configure the engine.

docker run -p 8080:8080 owasp/modsecurity-crs:apache

Building from Source

From the release tarball

Releases are published on GitHub as a signed source tarball (no binaries). Install the prerequisites above with their development headers first (for example apt install apache2-dev libpcre2-dev libxml2-dev libyajl-dev liblua5.4-dev libcurl4-openssl-dev on Debian and Ubuntu, or dnf install httpd-devel pcre2-devel libxml2-devel yajl-devel lua-devel libcurl-devel on Fedora and RHEL), then:

wget https://github.com/owasp-modsecurity/ModSecurity/releases/download/v2.9.15/modsecurity-v2.9.15.tar.gz
wget https://github.com/owasp-modsecurity/ModSecurity/releases/download/v2.9.15/modsecurity-v2.9.15.tar.gz.sha256
wget https://github.com/owasp-modsecurity/ModSecurity/releases/download/v2.9.15/modsecurity-v2.9.15.tar.gz.asc
sha256sum -c modsecurity-v2.9.15.tar.gz.sha256
gpg --verify modsecurity-v2.9.15.tar.gz.asc modsecurity-v2.9.15.tar.gz
tar xzf modsecurity-v2.9.15.tar.gz
cd modsecurity-v2.9.15
./configure
make
make install

From git

The repository is hosted on GitHub: https://github.com/owasp-modsecurity/ModSecurity. The v2 code lives on the v2/master branch (the default branch is v3). The list of changes made since the last stable release is in the file CHANGES. A git checkout needs the autotools (autoconf, automake, libtool) in addition to the prerequisites above, and the libinjection submodule:

git clone --branch v2/master https://github.com/owasp-modsecurity/ModSecurity
cd ModSecurity
git submodule update --init --recursive
./autogen.sh
./configure
make
make install

Configure options

Run the configure script to generate a Makefile. Typically no options are needed (./configure --help lists them all); the one you are most likely to need is the location of the apxs command installed by Apache httpd:

./configure --with-apxs=/path/to/httpd-2.x.y/bin/apxs

Options worth knowing:

1. –enable-pcre-jit - Enables JIT support from PCRE >= 8.20 / PCRE2 that can improve regex performance.
2. –enable-pcre-study - Enables PCRE pattern studying (WITH_PCRE_STUDY), which can give a slight performance edge.
3. –enable-lua-cache - Enables Lua VM caching that can improve Lua script performance. The difference only appears if ModSecurity must run more than one script per transaction.
4. –enable-request-early - Since ModSecurity 2.6 phase 1 runs in Apache’s fixups hook; this option moves it back to the post-read-request hook (see Processing Phases).
5. –enable-htaccess-config - Allows the following directives to be used in .htaccess files when AllowOverride Options is set: SecAction, SecRule, SecRuleRemoveById, SecRuleRemoveByMsg, SecRuleRemoveByTag, SecRuleUpdateActionById, SecRuleUpdateTargetById, SecRuleUpdateTargetByMsg and SecRuleUpdateTargetByTag.

Testing and installing

Optionally run the unit and regression tests before installing:

make test

Optionally build the ModSecurity Log Collector with make mlogc; to install it, review the INSTALL file in the mlogc directory of the distribution. make install copies mod_security2.so into the Apache modules directory reported by apxs; if your layout differs, copy it by hand, for example cp /usr/local/modsecurity/lib/mod_security2.so /usr/local/apache/modules/.

Windows

ModSecurity for Apache httpd on Windows is built with CMake and Visual Studio. The steps and the tested dependency versions are described in README_WINDOWS.md in the v2 source tree; Apache must be built from source with the same compiler. For IIS see ModSecurity v2 for IIS.

Loading and Configuring the Module

Skip this section if you installed a distribution package: the package already loads the module and includes a configuration directory, as described above.

On UNIX (and on Windows if the DLLs are not in the Apache bin directory) you may need to load libxml2 and Lua before ModSecurity if they are not found automatically:

LoadFile /usr/lib/libxml2.so
LoadFile /usr/lib/liblua5.4.so

Load the ModSecurity module in httpd.conf with:

LoadModule security2_module modules/mod_security2.so

Copy modsecurity.conf-recommended from the source tree to your Apache configuration directory as modsecurity.conf, together with unicode.mapping, and include it from httpd.conf. See Recommended Base Configuration. Then add a rule set, typically the OWASP CRS, and restart Apache httpd. You should now have ModSecurity 2.x up and running.

Build Notes

You want to avoid Apache using the bundled PCRE library and ModSecurity linking against the one provided by the operating system. The easiest way to do this is to compile Apache against the PCRE library provided by the operating system (or against the latest PCRE2 version downloaded from the PCRE site) using Apache’s --with-pcre configure switch. If you are not in a position to recompile Apache, then, to compile ModSecurity successfully, you need access to the bundled PCRE headers (they are available only in the Apache source code) and must point ModSecurity at them via its --with-pcre or --with-pcre2 configure option.

Non-gcc compilers may have problems running out-of-the-box as the current build system was designed around the gcc compiler and some compiler/linker flags may differ. To use a non-gcc compiler you may need some manual Makefile tweaks if issues cannot be solved by exporting custom CFLAGS and CPPFLAGS environment variables.

If you are upgrading from ModSecurity 1.x, see Migrating from 1.x to 2.x.

ModSecurity v2 for Microsoft IIS

ModSecurity for IIS (ModSecurityIIS.dll) is an IIS native module built from the ModSecurity v2 source tree (v2/master, directory iis/). It shares the engine, the rule language and the configuration file format with the Apache module; only the way the module is loaded and configured differs.

Prerequisites

• Windows Server with IIS 7 or later.
• The Microsoft Visual C++ Redistributable matching the compiler the module was built with (the build scripts in the repository use Visual Studio 2019). Install the 32-bit or 64-bit version according to the application pool architecture.
• The dependency DLLs that ship alongside the module: APR and APR-util, PCRE, libxml2, Lua, libcurl, YAJL, zlib and libfuzzy. The build scripts produce them together with ModSecurityIIS.dll and mlogc.exe.

Obtaining the Module

The project publishes source releases only (https://github.com/owasp-modsecurity/ModSecurity/releases); no Windows binaries or MSI installers are attached to current releases. To build the module and, optionally, the MSI installer, use the scripts in the iis/ directory of the v2 tree (build_release.bat builds the dependencies and the module for x86 and amd64, build_msi.bat builds the WiX installer). The general Windows build notes are in README_WINDOWS.md.

If you use a third-party installer or binary package, make sure it comes from a source you trust and matches the version you expect.

Any installation errors or warning messages from the MSI installer are logged in the Application event log under the ModSecurityIIS Installer source. The installer does not install the OWASP CRS; download it from the CRS project and include it from your ModSecurity configuration file.

Manually Installing and Troubleshooting Setup of ModSecurity Module on IIS

Configuration

After the installation the module will be running in all websites by default. To remove it from a website add to web.config:

<modules>
    <remove name="ModSecurityIIS" />
</modules>

To configure the module in a website add to web.config:

<?xml version="1.0" encoding="UTF-8"?>
<configuration>
    <system.webServer>
        <ModSecurity enabled="true" configFile="c:\inetpub\wwwroot\modsecurity.conf" />
    </system.webServer>
</configuration>

where configFile is a standard ModSecurity configuration file (start from modsecurity.conf-recommended, see Recommended Base Configuration). A relative path can also be used. To load the OWASP CRS, add Include directives for crs-setup.conf and the rules\*.conf files to that configuration file.

Events from the module will show up in the “Application” Windows event log.

Common Problems

If after installation the protected website responds with HTTP 503 error and event ID 2280 keeps getting logged in the application event log:

Log Name:      Application
Source:        Microsoft-Windows-IIS-W3SVC-WP
Event ID:      2280
Task Category: None
Level:         Error
Keywords:      Classic
User:          N/A
Description:
The Module DLL C:\Windows\system32\inetsrv\modsecurityiis.dll failed to load.  The data is the error.

most likely it means that the installation process has failed and the ModSecurityIIS.dll module is missing one or more libraries that it depends on. Repeating installation of the prerequisites and the module files should fix the problem. A dependency walker tool such as Dependencies can be used to figure out which library is missing or cannot be loaded.

See also IIS Troubleshooting.

Building distribution packages

Distribution packages lag behind upstream releases, so it is common to need a package of a newer ModSecurity version, or one built with different options, for a distribution that does not ship it yet. The quickest way to get one is to rebuild the distribution’s own packaging against the newer source tarball rather than writing a spec or debian/ directory from scratch: the packaging already carries the configuration layout, the module loading snippets and the dependencies the distribution expects.

ModSecurity v2 (Apache)

Debian and Ubuntu

The packaging lives at https://salsa.debian.org/debian/modsecurity-apache (source package modsecurity-apache, binary libapache2-mod-security2). To rebuild it against a newer upstream release:

sudo apt install build-essential devscripts
sudo apt build-dep modsecurity-apache
apt source modsecurity-apache
cd modsecurity-apache-*/
uupdate --upstream-version 2.9.15 ../modsecurity-v2.9.15.tar.gz
cd ../modsecurity-apache-2.9.15/
dpkg-buildpackage -us -uc -b

The resulting libapache2-mod-security2_*.deb lands in the parent directory. Download the release tarball as described in ModSecurity v2 for Apache first; apt source needs a deb-src entry in your APT sources.

Fedora, RHEL and EPEL

The packaging lives at https://src.fedoraproject.org/rpms/mod_security (mod_security.spec, the mod_security.conf base configuration and the 10-mod_security.conf module snippet). To rebuild it against a newer upstream release:

sudo dnf install fedpkg rpm-build rpmdevtools
fedpkg clone -a rpms/mod_security
cd mod_security
sudo dnf builddep mod_security.spec
rpmdev-bumpspec --new 2.9.15 mod_security.spec
spectool -g -R mod_security.spec
fedpkg --release rawhide local      # or: rpmbuild -ba mod_security.spec

Use the branch that matches your target (epel9, epel10, f44, …). Check the spec’s %prep section for patches that no longer apply to the newer source; drop them if upstream already contains the fix.

Other systems

• FreeBSD: the port is www/mod_security; bump PORTVERSION in its Makefile, run make makesum and build with make package.
• openSUSE: the package is apache2-mod_security2 in the Apache:Modules project on the Open Build Service; branch it with osc branch and update the Version and source tarball in the spec.
• Gentoo: copy the www-apache/mod_security ebuild to a local overlay under the new version and run ebuild ... manifest.

libModSecurity v3

The same approach applies to the v3 library and the nginx connector: Debian and Ubuntu package libmodsecurity3 (source package modsecurity) and libnginx-mod-http-modsecurity; Fedora and EPEL package libmodsecurity and nginx-mod-modsecurity. Rebuild those packaging sources against the newer release with the commands above.

Processing Phases

ModSecurity, in both v2 and v3, allows rules to be placed in one of the following five phases of an HTTP transaction:

In ModSecurity v2 the phases are hooks in the Apache request cycle. In libModSecurity v3 the phases are the process*() calls the connector (for example ModSecurity-nginx) makes on a transaction: processConnection, processURI, processRequestHeaders, processRequestBody, processResponseHeaders, processResponseBody and processLogging. The rule semantics are the same; the differences are listed at the end of this page.

In order to select the phase a rule executes during, use the phase action either directly in the rule or in the SecDefaultAction directive:

SecDefaultAction "phase:2,pass,log"
SecRule REQUEST_HEADERS:Host "!@rx ^$" "id:5,phase:1,deny"

The phase can be given by number or by name: phase:request is phase 2, phase:response is phase 4 and phase:logging is phase 5.

Phase Request Headers

Rules in this phase are processed immediately after the request headers have been received. At this point the request body has not been read yet, meaning not all request arguments are available. Rules should be placed in this phase if you need to have them run early, to do something before the request body has been read, determine whether or not the request body should be buffered, or decide how you want the request body to be processed (e.g. whether to parse it as XML or JSON).

Phase Request Body

This is the general-purpose input analysis phase. Most of the application-oriented rules should go here. In this phase you are guaranteed to have received the request arguments (provided the request body has been read). Both versions support four request body processors:

• application/x-www-form-urlencoded - used to transfer form data
• multipart/form-data - used for file transfers
• XML - used for passing XML data (ctl:requestBodyProcessor=XML)
• JSON - used for passing JSON data (ctl:requestBodyProcessor=JSON, requires a build with YAJL)

Other encodings are not used by most web applications. The XML and JSON processors are not selected automatically; modsecurity.conf-recommended contains phase 1 rules that enable them based on the Content-Type header.

Phase Response Headers

This phase takes place just before response headers are sent back to the client. Run here if you want to observe the response before that happens, and if you want to use the response headers to determine if you want to buffer the response body.

Phase Response Body

This is the general-purpose output analysis phase. At this point you can run rules against the response body (provided it was buffered, of course). This is the phase where you would want to inspect the outbound HTML for information disclosure, error messages or failed authentication text.

Phase Logging

This phase is run just before logging takes place. The rules placed into this phase can only affect how the logging is performed. You cannot deny/block connections in this phase as it is too late. This phase also allows for inspection of other response headers that weren’t available during phase 3 or phase 4. In ModSecurity v2 this phase can also inspect the error messages logged by Apache (WEBSERVER_ERROR_LOG). Note that you must be careful not to inherit a disruptive action into a rule in this phase as this is a configuration error in ModSecurity 2.5.0 and later versions.

Differences between ModSecurity v2 and libModSecurity v3

• Default phase. v2: phase 2, or the phase of the preceding SecDefaultAction. v3: phase 1. Always write phase: explicitly.
• Phase 4 without body inspection. v2 runs phase 4 rules with an empty RESPONSE_BODY; v3 skips the phase entirely when SecResponseBodyAccess is not On or the MIME type is not inspected.
• Phase 0. v3 accepts phase:0 (connection phase, evaluated when the connector calls processConnection, when only REMOTE_ADDR, REMOTE_HOST, REMOTE_PORT, SERVER_ADDR, SERVER_PORT and UNIQUE_ID are known). v2 has no phase 0.
• skipAfter with a missing marker. In v2 a skip ends with the current phase. In v3 the pending marker persists across phases: if no SecMarker of that name exists, every remaining rule of every later phase is skipped. Always define the marker.
• ctl:ruleEngine=Off mid-phase. v2 stops evaluating the rest of the current phase immediately; v3 checks the engine state only when a phase starts, so the remaining rules of the current phase are still evaluated (none of them can interrupt). Place such a rule last in its phase.
• Web server scopes. In v2 rules can be placed in Apache <VirtualHost>, <Location>, <Directory> and (with --enable-htaccess-config) .htaccess contexts and are merged by Apache’s configuration inheritance. In v3 the connector decides the scopes: ModSecurity-nginx loads rules per http, server or location block via modsecurity_rules_file, modsecurity_rules_remote and modsecurity_rules.

Configuration Directives

The following section outlines all of the ModSecurity directives. Most of the ModSecurity directives can be used inside the various Apache Scope Directives such as VirtualHost, Location, LocationMatch, Directory, etc… There are others, however, that can only be used once in the main configuration file. This information is specified in the Scope sections below. The first version to use a given directive is given in the Version sections below.

These rules, along with the Core rules files, should be contained in files outside of the httpd.conf file and called up with Apache “Include” directives. This allows for easier updating/migration of the rules. If you create your own custom rules that you would like to use with the Core rules, you should create a file called - modsecurity_crs_15_customrules.conf and place it in the same directory as the Core rules files. By using this file name, your custom rules will be called up after the standard ModSecurity Core rules configuration file but before the other Core rules. This allows your rules to be evaluated first which can be useful if you need to implement specific “allow” rules or to correct any false positives in the Core rules as they are applied to your site.

Include

Loads another configuration file in place, as if its contents had been written at the position of the directive.

In ModSecurity v2 this is the Apache httpd core Include directive; ModSecurity itself does not define it, and the rules files it names are processed by Apache. libModSecurity v3 implements its own Include in the SecLang parser: the parameter may be quoted, may contain a * wildcard matching several files, and may be a relative path, which is tried against the current working directory first and then against the directory of the file that contains the Include. A file that cannot be opened is a configuration error. Nested includes are permitted.

Include modsecurity.conf
Include "/etc/modsecurity/crs/rules/*.conf"

SecAction

Unconditionally processes the action list it receives as the first and only parameter. The syntax of the parameter is identical to that of the third parameter of SecRule.

This directive is commonly used to set variables and initialize persistent collections using the initcol action. For example:

SecAction "phase:1,nolog,initcol:RESOURCE=%{REQUEST_FILENAME}"

SecArgumentSeparator

Specifies which character to use as the separator for application/x-www-form- urlencoded content.

This directive is needed if a backend web application is using a nonstandard argument separator. Applications are sometimes (very rarely) written to use a semicolon separator. You should not change the default setting unless you establish that the application you are working with requires a different separator. If this directive is not set properly for each web application, then ModSecurity will not be able to parse the arguments appropriately and the effectiveness of the rule matching will be significantly decreased.

The parameter must be a single character. Before 2.7.0 the directive was only accepted in the main server configuration; since 2.7.0 it can be used in any configuration context.

SecArgumentsLimit

Configures the maximum number of ARGS that will be accepted for processing.

Exceeding the limit will set the REQBODY_ERROR variable, and additional arguments beyond the limit will not be included. With JSON body processing, there is an additional short-circuit to halt parsing once the limit is breached. As with the enforcement of other issues that signal REQBODY_ERROR, a rule should be in place to test this value, like rule 200002 in modsecurity.conf-recommended.

In ModSecurity v2 the default is 1000. libModSecurity v3 applies no limit unless the directive is set.

When using this setting, it is recommended to accompany it with a rule that will test for that same integer value and deny the request if it is reached, like rule 200007 in modsecurity.conf-recommended:

SecRule &ARGS "@ge 1000" \
    "id:'200007',\
    phase:2,\
    deny,\
    status:400,\
    t:none,\
    log,\
    msg:'Failed to fully parse request body due to large argument count'"

Without such a matching rule, an attacker could potentially evade detection by placing the attack payload in a parameter occurring beyond the limit.

SecAuditEngine

Configures the audit logging engine.

The SecAuditEngine directive is used to configure the audit engine, which logs complete transactions. ModSecurity is currently able to log most, but not all transactions. Transactions involving errors (e.g., 400 and 404 transactions) use a different execution path, which ModSecurity does not support.

The possible values for the audit log engine are as follows:

• On: log all transactions
• Off: do not log any transactions
• RelevantOnly: only the log transactions that have triggered a warning or an error, or have a status code that is considered to be relevant (as determined by the SecAuditLogRelevantStatus directive)

The following example demonstrates how SecAuditEngine is used:

SecAuditEngine RelevantOnly
SecAuditLog logs/audit/audit.log
SecAuditLogParts ABCFHZ
SecAuditLogType concurrent
SecAuditLogStorageDir logs/audit
SecAuditLogRelevantStatus ^(?:5|4(?!04))

SecAuditLog

Defines the path to the main audit log file (serial logging format), the concurrent logging index file (concurrent logging format) or, in libModSecurity v3, the destination URL (HTTPS logging format). When used in combination with mlogc (only possible with concurrent logging), this directive defines the mlogc location and command line.

This file will be used to store the audit log entries if serial audit logging format is used. If concurrent audit logging format is used this file will be used as an index, and contain a record of all audit log files created. If you are planning to use concurrent audit logging to send your audit log data off to a remote server you will need to deploy the ModSecurity Log Collector (mlogc), like this:

SecAuditLog "|/path/to/mlogc /path/to/mlogc.conf"

libModSecurity v3 does not ship mlogc. When using SecAuditLogType HTTPS (v3 only), specify the destination URL instead of a path, e.g. SecAuditLog https://xxx.xxx.xxx.xxx:port/.

SecAuditLog2

Defines the path to the secondary audit log index file when concurrent logging is enabled. See SecAuditLog for more details.

The purpose of SecAuditLog2 is to make logging to two remote servers possible, which is typically achieved by running two instances of the mlogc tool, each with a different configuration (in addition, one of the instances will need to be instructed not to delete the files it submits). This directive can be used only if SecAuditLog was previously configured and only if concurrent logging format is used.

SecAuditLogDirMode

Configures the mode (permissions) of any directories created for the concurrent audit logs, using an octal mode value as parameter (as used in chmod).

The default mode for new audit log directories (0750) grants full access to the owner (typically the account under which Apache is running, for example apache) and read/search access to the group. If access from other accounts is needed (e.g., for use with mpm-itk), then you may use this directive to grant additional read and/or write privileges. You should use this directive with caution to avoid exposing potentially sensitive data to unauthorized users. Using the value default as parameter reverts the configuration back to the default setting. This feature is not available on operating systems not supporting octal file modes. libModSecurity v3 accepts only a numeric value here; the keyword default is a syntax error.

Example:

SecAuditLogDirMode 02750

SecAuditLogFormat

Select the output format of the AuditLogs. The format can be either the native AuditLogs format or JSON.

SecAuditLogFileMode

Configures the mode (permissions) of any files created for concurrent audit logs using an octal mode (as used in chmod). See SecAuditLogDirMode for controlling the mode of created audit log directories.

This feature is not available on operating systems not supporting octal file modes. The default mode (0640) grants read/write access to the account writing the file and read access to its group. If access from another account is needed (using mpm-itk is a good example), then this directive may be required. However, use this directive with caution to avoid exposing potentially sensitive data to unauthorized users. Using the value “default” will revert back to the default setting. libModSecurity v3 accepts only a numeric value here; the keyword default is a syntax error.

SecAuditLogParts

Defines which parts of each transaction are going to be recorded in the audit log. Each part is assigned a single letter; when a letter appears in the list then the equivalent part will be recorded. See below for the list of all parts.

The format of the audit log format is documented in detail in the Audit Log Data Format Documentation.

Available audit log parts:

• A: Audit log header (mandatory).
• B: Request headers.
• C: Request body (present only if the request body exists and ModSecurity is configured to intercept it. This would require SecRequestBodyAccess to be set to on).
• D: Reserved for intermediary response headers; not implemented yet.
• E: Intermediary response body (present only if ModSecurity is configured to intercept response bodies, and if the audit log engine is configured to record it. Intercepting response bodies requires SecResponseBodyAccess to be enabled). Intermediary response body is the same as the actual response body unless ModSecurity intercepts the intermediary response body, in which case the actual response body will contain the error message (either the Apache default error message, or the ErrorDocument page).
• F: Final response headers (excluding the Date and Server headers, which are always added by Apache in the late stage of content delivery).
• G: Reserved for the actual response body; not implemented yet.
• H: Audit log trailer.
• I: This part is a replacement for part C. It will log the same data as C in all cases except when multipart/form-data encoding in used. In this case, it will log a fake application/x-www-form-urlencoded body that contains the information about parameters but not about the files. This is handy if you don’t want to have (often large) files stored in your audit logs. Not implemented in libModSecurity v3.
• J: This part contains information about the files uploaded using multipart/form-data encoding.
• K: This part contains a full list of every rule that matched (one per line) in the order they were matched. The rules are fully qualified and will thus show inherited actions and default operators. Supported as of v2.5.0. Not implemented in libModSecurity v3.
• Z: Final boundary, signifies the end of the entry (mandatory).

SecAuditLogRelevantStatus

Configures which response status code is to be considered relevant for the purpose of audit logging.

Dependencies/Notes: Must have SecAuditEngine set to RelevantOnly. Additionally, the auditlog action is present by default in rules, this will make the engine bypass the ‘SecAuditLogRelevantStatus’ and send rule matches to the audit log regardless of status. You must specify noauditlog in the rules manually or set it in SecDefaultAction.

The main purpose of this directive is to allow you to configure audit logging for only the transactions that have the status code that matches the supplied regular expression. The example provided would log all 5xx and 4xx level status codes, except for 404s. Although you could achieve the same effect with a rule in phase 5, SecAuditLogRelevantStatus is sometimes better, because it continues to work even when SecRuleEngine is disabled.

SecAuditLogStorageDir

Configures the directory where concurrent audit log entries are to be stored.

This directive is only needed when concurrent audit logging is used. The directory must already exist and must be writable by the web server user. Audit log entries are created at runtime, after Apache switches to a non-root account. As with all logging mechanisms, ensure that you specify a file system location that has adequate disk space and is not on the main system partition.

SecAuditLogType

Configures the type of audit logging mechanism to be used.

The possible values are:

• Serial: Audit log entries will be stored in a single file, specified by SecAuditLog. This is convenient for casual use, but it can slow down the server, because only one audit log entry can be written to the file at any one time.
• Concurrent: One file per transaction is used for audit logging. This approach is more scalable when heavy logging is required (multiple transactions can be recorded in parallel). In ModSecurity v2 it is also the only choice if you need to use remote logging (with mlogc). libModSecurity v3 also accepts Parallel as an alias.
• HTTPS: Only available in libModSecurity v3, and still considered experimental. Each audit log entry is POSTed to the URL given in SecAuditLog instead of being written to a file. Depending on the amount of requests that you have, it may be suitable.

SecAuditLogPrefix

Configures a text that will be prepended to each audit log line. This directive only exists in libModSecurity v3; ModSecurity v2 does not know it.

This parameter is only used when audit log format is set to native. Intended to be used in situations where the log target receives entries from multiple log sources (for example when the audit log is written to stdout using SecAuditLog /dev/stdout).

Example:

SecAuditEngine RelevantOnly
SecAuditLog /dev/stdout
SecAuditLogParts ABHZ
SecAuditLogType Serial
SecAuditLogRelevantStatus ^(?:5|4(?!04))
SecAuditLogPrefix "[audit.log]: "

Audit log:

[audit.log]: ---Lm20Vggw---A--
[audit.log]: [07/Aug/2025:18:00:57 +0200] 17545824577.300397 200.249.12.31 2313 200.249.12.31 80
[audit.log]: ---Lm20Vggw---B--
[audit.log]: GET /test.pl?param1=   test   ¶m2=test2 HTTP/1.1
[audit.log]: Host: www.modsecurity.org
[audit.log]: User-Agent: Mozilla/5.0 (Windows; U; Windows NT 6.1; en-US; rv:1.9.1.5) Gecko/20091102 Firefox/3.5.5 (.NET CLR 3.5.30729)
[audit.log]: Accept-Charset: ISO-8859-1,utf-8;q=0.7,*;q=0.7
[audit.log]: Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8
[audit.log]: Accept-Language: en-us,en;q=0.5
[audit.log]: Accept-Encoding: gzip,deflate
[audit.log]: Keep-Alive: 300
[audit.log]: Connection: keep-alive
[audit.log]: Pragma: no-cache
[audit.log]: Cache-Control: no-cache
[audit.log]:
[audit.log]:
[audit.log]: ---Lm20Vggw---H--
[audit.log]: ModSecurity: Access denied with code 403 (phase 1). Matched "Operator `Contains' with parameter `test' against variable `ARGS:param2' (Value: `test2' ) [file "auditlog.json"] [line "2"] [id "1"] [rev ""] [msg ""] [data ""] [severity "0"] [ver ""] [maturity "0"] [accuracy "0"] [hostname "200.249.12.31"] [uri "/test.pl"] [unique_id "17545824577.300397"] [ref "o0,4v20,10t:trimo0,4v38,5t:trim"]
[audit.log]:
[audit.log]: ---Lm20Vggw---Z--

SecCacheTransformations

Controls the caching of transformations, which may speed up the processing of complex rule sets. Caching is off by default starting with 2.5.6, when it was deprecated and downgraded back to experimental.

The first directive parameter can be one of the following:

• On: Cache transformations (per transaction, per phase) allowing identical transforma- tions to be performed only once.
• Off: Do not cache any transformations, leaving all transformations to be performed every time they are needed.

libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

The following options are allowed (multiple options must be comma-separated):

• incremental:on|off: Enabling this option will cache every transformation instead of just the final transformation. The default is off.
• maxitems:N: Do not allow more than N transformations to be cached. Cache will be disabled once this number is reached. A zero value is interpreted as unlimited. This option may be useful to limit caching for a form with a large number of variables. The default value is 512.
• minlen:N: Do not cache the transformation if the variable’s length is less than N bytes. The default setting is 32.
• maxlen:N: Do not cache the transformation if the variable’s length is more than N bytes. A zero value is interpreted as unlimited. The default setting is 1024.

SecChrootDir

Configures the directory path that will be used to jail the web server process.

libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3. This feature is not available on Windows builds. The internal chroot functionality provided by ModSecurity works great for simple setups. One example of a simple setup is Apache serving only static files, or running applications using built-in modules. Some problems you might encounter with more complex setups:

1. DNS lookups do not work (this is because this feature requires a shared library that is loaded on demand, after chroot takes place).
2. You cannot send email from PHP, because it wants to use sendmail and sendmail re- sides outside the jail.
3. In some cases, when you separate Apache from its configuration, restarts and graceful reloads no longer work.

The best way to use SecChrootDir is the following:

1. Create /chroot to be your main jail directory.
2. Create /chroot/opt/apache inside jail.
3. Create a symlink from /opt/apache to /chroot/opt/apache.
4. Now install Apache into /chroot/opt/apache.

You should be aware that the internal chroot feature might not be 100% reliable. Due to the large number of default and third-party modules available for the Apache web server, it is not possible to verify the internal chroot works reliably with all of them. A module, working from within Apache, can do things that make it easy to break out of the jail. In particular, if you are using any of the modules that fork in the module initialization phase (e.g., mod_fastcgi, mod_fcgid, mod_cgid), you are advised to examine each Apache process and observe its current working directory, process root, and the list of open files. Consider what your options are and make your own decision.

SecCollectionTimeout

Specifies the collections timeout. Default is 3600 seconds. ModSecurity v2 accepts values from 0 to 2592000 seconds (30 days).

libModSecurity v3 accepts the directive (so that crs-setup.conf loads) but ignores it: v3 collections do not expire through this setting.

SecComponentSignature

Appends component signature to the ModSecurity signature.

This directive should be used to make the presence of significant rule sets known. The entire signature will be recorded in the transaction audit log.

SecConnEngine

Configures the connections engine. This directive affect the directives: SecConnReadStateLimit and SecConnWriteStateLimit.

Possible values are (Same as SecRuleEngine):

• On: process SecConn[Read|Write]StateLimit.
• Off: Ignore the directives SecConn[Read|Write]StateLimit
• DetectionOnly: process SecConn[Read|Write]StateLimit definitions in verbose mode but never executes any disruptive actions

libModSecurity v3 accepts only Off (and ignores it); On and DetectionOnly are rejected with a configuration error.

SecContentInjection

Enables content injection using actions append and prepend.

This directive provides an easy way to control content injection, no matter what the rules want to do. It is not necessary to have response body buffering enabled in order to use content injection. libModSecurity v3 accepts only Off (and ignores it); On is rejected with a configuration error.

SecCookieFormat

Selects the cookie format that will be used in the current configuration context.

The possible values are:

• 0: Use version 0 (Netscape) cookies. This is what most applications use. It is the default value.
• 1: Use version 1 cookies.

Since 2.7.0 the directive can be used in any configuration context; before that it was only accepted in the main server configuration.

SecCookieV0Separator

Specifies which character to use as the separator for cookie v0 content.

The parameter must be a single character. When the directive is not set, ModSecurity v2 splits version 0 cookies on ;, falling back to , when the Cookie header contains no semicolon but a comma followed by a space. The source registers the directive as SecCookiev0Separator; Apache matches directive names case-insensitively, so both spellings work. libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecDataDir

Path where persistent data (e.g., IP address data, session data, and so on) is to be stored.

This directive must be provided before initcol, setsid, and setuid can be used. The directory to which the directive points must be writable by the web server user.

libModSecurity v3 accepts the directive (so that modsecurity.conf-recommended loads) but ignores it: collections are kept in memory per process, or, when a backend such as LMDB is compiled in, the storage path is defined by the backend.

SecDebugLog

Path to the ModSecurity debug log file.

SecDebugLogLevel

Configures the verboseness of the debug log data.

In ModSecurity v2, messages at levels 1–3 are always copied to the Apache error log. Therefore you can always use level 0 as the default logging level in production if you are very concerned with performance. Having said that, the best value to use is 3. Higher logging levels are not recommended in production, because the heavy logging affects performance adversely. In libModSecurity v3, always having the debug log active in a production environment is typically not advised; even when investigating a specific issue be aware that using a value of 4 or higher can impact performance significantly.

The possible values for the debug log level are:

• 0: no logging
• 1: errors (intercepted requests) only
• 2: warnings
• 3: notices
• 4: details of how transactions are handled
• 5: as above, but including information about each piece of information handled
• 9: log everything, including very detailed debugging information

SecDefaultAction

Defines the default list of actions for a particular phase, which will be inherited by the rules in the same phase and in the same configuration context.

Every rule following a previous SecDefaultAction directive in the same configuration context will inherit its settings unless more specific actions are used. Every SecDefaultAction directive must specify a disruptive action and a processing phase and cannot contain metadata actions. In ModSecurity v2 it must not contain the chain, skip or skipAfter actions either, and using severity, logdata or transformations (t:) in it is deprecated and logs a warning at startup. In libModSecurity v3 the phase is optional (it defaults to phase 1), only one SecDefaultAction is allowed per phase, t:none is rejected, and block does not count as the required disruptive action.

SecDisableBackendCompression

Disables backend compression while leaving the frontend compression enabled.

libModSecurity v3 accepts only Off (and ignores it); On is rejected with a configuration error. This directive is necessary in reverse proxy mode when the backend servers support response compression, but you wish to inspect response bodies. Unless you disable backend compression, ModSecurity will only see compressed content, which is not very useful. This directive is not necessary in embedded mode, because ModSecurity performs inspection before response compression takes place.

SecHashEngine

Configures the hash engine.

The possible values are:

• On: Hash engine can process the request/response data.
• Off: Hash engine will not process any data.

libModSecurity v3 accepts only Off (and ignores it); On is rejected with a configuration error.

SecHashKey

Define the key that will be used by HMAC.

ModSecurity hash engine will append, if specified, the user’s session id or remote ip to the key before the MAC operation. If the first parameter is “rand” then a random key will be generated and used by the engine. libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecHashParam

Define the parameter name that will receive the MAC hash.

ModSecurity hash engine will add a new parameter to protected HTML elements containing the MAC hash. libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecHashMethodRx

Configures what kind of HTML data the hash engine should sign based on regular expression.

As a initial support is possible to protect HREF, FRAME, IFRAME and FORM ACTION html elements as well response Location header when http redirect code are sent. libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

The possible values for TYPE are:

• HashHref: Used to sign href= html elements
• HashFormAction: Used to sign form action= html elements
• HashIframeSrc: Used to sign iframe src= html elements
• HashFrameSrc: Used to sign frame src= html elements
• HashLocation: Used to sign Location response header

SecHashMethodPm

Configures what kind of HTML data the hash engine should sign based on string search algorithm.

As a initial support is possible to protect HREF, FRAME, IFRAME and FORM ACTION html elements as well response Location header when http redirect code are sent. libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

The possible values for TYPE are:

• HashHref: Used to sign href= html elements
• HashFormAction: Used to sign form action= html elements
• HashIframeSrc: Used to sign iframe src= html elements
• HashFrameSrc: Used to sign frame src= html elements
• HashLocation: Used to sign Location response header

SecGeoLookupDb

Defines the path to the database that will be used for geolocation lookups.

ModSecurity v2 relies on the free geolocation databases (GeoLite City and GeoLite Country) that can be obtained from MaxMind 1. ModSecurity v2 only supports the legacy GeoIP format; MaxMind’s newer GeoIP2 format is not supported there. The v2 source registers the directive as SecGeoLookupDB (Apache matches directive names case-insensitively). A relative path is resolved against the directory of the configuration file that contains the directive.

libModSecurity v3 supports the newer GeoIP2 (.mmdb) format through libmaxminddb (since 3.0.1), and the legacy GeoIP format when built with --with-geoip. The build must enable one of them, otherwise the directive fails to load.

SecGsbLookupDb

Defines the path to the database that will be used for Google Safe Browsing (GSB) lookups.

ModSecurity relies on the free Google Safe Browsing database that can be obtained from the Google GSB API 1. The source registers the directive as SecGsbLookupDB (Apache matches directive names case-insensitively). A relative path is resolved against the directory of the configuration file that contains the directive. libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecGuardianLog

Configures an external program that will receive the information about every transaction via piped logging.

libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3. Guardian logging is designed to send the information about every request to an external program. Because Apache is typically deployed in a multiprocess fashion, which makes information sharing between processes difficult, the idea is to deploy a single external process to observe all requests in a stateful manner, providing additional protection.

Currently the only tool known to work with guardian logging is httpd-guardian, which is part of the Apache httpd tools project 1. The httpd-guardian tool is designed to defend against denial of service attacks. It uses the blacklist tool (from the same project) to interact with an iptables-based (on a Linux system) or pf-based (on a BSD system) firewall, dynamically blacklisting the offending IP addresses. It can also interact with SnortSam 2. Assuming httpd-guardian is already configured (look into the source code for the detailed instructions), you only need to add one line to your Apache configuration to deploy it. The optional second parameter restricts guardian logging to requests for which the given environment variable is set (or, with the ! prefix, not set), as with Apache’s CustomLog:

SecGuardianLog |/path/to/httpd-guardian

SecHttpBlKey

Configures the user’s registered Honeypot Project HTTP BL API Key to use with @rbl.

If the @rbl operator uses the dnsbl.httpbl.org RBL (http://www.projecthoneypot.org/httpbl_api.php) you must provide an API key. This key is registered to individual users and is included within the RBL DNS requests.

SecInterceptOnError

Configures how to respond when rule processing fails.

When an operator execution fails, that is it returns greater than 0, this directive configures how to react. When set to “Off”, the rule is just ignored and the engine will continue executing the rules in phase. When set to “On”, the rule will be just dropped and no more rules will be executed in the same phase, also no interception is made. libModSecurity v3 accepts only Off (and ignores it); On is rejected with a configuration error.

SecMarker

Adds a fixed rule marker that can be used as a target in a skipAfter action. A SecMarker directive essentially creates a rule that does nothing and whose only purpose is to carry the given ID.

The value can be either a number or a text string. The SecMarker directive is available to allow you to choose the best way to implement a skip-over. Here is an example used from the OWASP CRS:

SecMarker BEGIN_HOST_CHECK

SecRule &REQUEST_HEADERS:Host "@eq 0" \
    "id:'960008',\
    phase:2,\
    block,\
    t:none,\
    msg:'Request Missing a Host Header',\
    tag:'PROTOCOL_VIOLATION/MISSING_HEADER_HOST',\
    tag:'WASCTC/WASC-21',\
    tag:'OWASP_TOP_10/A7',\
    tag:'PCI/6.5.10',\
    rev:'2.1.1',\
    severity:'5',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.notice_anomaly_score},\
    setvar:tx.protocol_violation_score=+%{tx.notice_anomaly_score},\
    setvar:tx.%{rule.id}-PROTOCOL_VIOLATION/MISSING_HEADER-%{matched_var_name}=%{matched_var},\
    skipAfter:END_HOST_CHECK"
SecRule REQUEST_HEADERS:Host "@rx ^$" \
    "id:'960008',\
    phase:2,\
    block,\
    t:none,\
    msg:'Request Missing a Host Header',\
    tag:'PROTOCOL_VIOLATION/MISSING_HEADER_HOST',\
    tag:'WASCTC/WASC-21',\
    tag:'OWASP_TOP_10/A7',\
    tag:'PCI/6.5.10',\
    rev:'2.1.1',\
    severity:'5',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.notice_anomaly_score},\
    setvar:tx.protocol_violation_score=+%{tx.notice_anomaly_score},\
    setvar:tx.%{rule.id}-PROTOCOL_VIOLATION/MISSING_HEADER-%{matched_var_name}=%{matched_var}"

SecMarker END_HOST_CHECK

SecPcreMatchLimit

Sets the match limit in the PCRE library.

In ModSecurity v2 the default can be changed when ModSecurity is prepared for compilation: the –enable-pcre-match-limit=val configure option will set a custom default and the –disable-pcre-match-limit option will revert back to the default of the PCRE library. For more information, refer to the pcre_extra field in the pcreapi man page.

libModSecurity v3 accepts the directive since 3.0.0 but only honors it since 3.0.10, where it sets the PCRE match limit for executions of the @rx and @rxGlobal operators. Unless the directive is set, the PCRE library default applies. If the configured limit is exceeded, the variable MSC_PCRE_LIMITS_EXCEEDED will be set.

SecPcreMatchLimitRecursion

Sets the match limit recursion in the PCRE library.

The default can be changed when ModSecurity is prepared for compilation: the –enable-pcre-match-limit-recursion=val configure option will set a custom default and the –disable-pcre-match-limit-recursion option will revert back to the default of the PCRE library. For more information, refer to the pcre_extra field in the pcreapi man page. libModSecurity v3 accepts the directive (so that modsecurity.conf-recommended loads) but ignores it; the PCRE library default applies.

SecReadStateLimit

Establishes a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_READ state.

Deprecated since 2.8.0: it is an alias of SecConnReadStateLimit, accepts the same parameters (including the optional IP match operator) and logs a deprecation warning at startup. libModSecurity v3 does not know this directive; a configuration containing it fails to load.

SecConnReadStateLimit

Establishes a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_READ state.

This measure is effective against Slowloris-style attacks from a single IP address, but it may not be as good against modified attacks that work by slowly sending request body content. This is because Apache to switches state to SERVER_BUSY_WRITE once request headers have been read. As an alternative, consider mod_reqtimeout (part of Apache as of 2.2.15), which is expected be effective against both attack types. See Blog post on mitigating slow DoS attacks - http://blog.spiderlabs.com/2010/11/advanced-topic-of-the-week-mitigating-slow-http-dos-attacks.html. v2.8.0 and newest supports the @ipMatch, @ipMatchF and @ipMatchFromFile operator along with the its negative (e.g. !@ipMatch) these were used to create suspicious or whitelist. When a suspicious list is informed, just the IPs that belongs to the list will be filtered. A combination of suspicious and whitelist is possible by using multiple definitions of SecConnReadStateLimit, note, however, that the limit will be always overwrite by its successor.

LIMIT must be greater than zero.

Note: This functionality is Apache only.

Note 2: Make sure SecConnEngine is on prior to use this feature.

libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecSensorId

Define a sensor ID that will be present into log part H.

libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecWriteStateLimit

Establishes a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_WRITE state.

Deprecated since 2.8.0: it is an alias of SecConnWriteStateLimit, accepts the same parameters (including the optional IP match operator) and logs a deprecation warning at startup. libModSecurity v3 does not know this directive; a configuration containing it fails to load.

SecConnWriteStateLimit

Establishes a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_WRITE state.

This measure is effective against Slow DoS request body attacks. v2.8.0 and newest supports the @ipMatch, @ipMatchF and @ipMatchFromFile operator along with the its negative (e.g. !@ipMatch) these were used to create suspicious or whitelist. When a suspicious list is informed, just the IPs that belongs to the list will be filtered. A combination of suspicious and whitelist is possible by using multiple definitions of SecConnReadStateLimit, note, however, that the limit will be always overwrite by its successor.

LIMIT must be greater than zero.

Note: This functionality is Apache only.

Note 2: Make sure SecConnEngine is on prior to use this feature.

libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecParseXmlIntoArgs

Controls how XML processing is done. If you turn it on with On or OnlyArgs, then XML nodes will appear in ARGS.

In these cases, the SecArgumentsLimit directive will set the limit to number of loadable arguments.

NOTE: You must enable this directive with On or OnlyArgs if you want to load XML nodes into ARGS.

This is an optional directive that allow the user to load XML payload’s nodes into ARGS (and XML tags into ARGS_NAMES). The default value is Off. If the user set it to On then XML nodes will appear in ARGS collection with key xml.tag.chain, but the XML target will fill too. If the value is OnlyArgs, then XML will be empty. Notice that in this case the @validateDTD and @validateSchema operators will return with false value (because the XML target is empty).

ctl:parseXmlIntoArgs action’s behavior is the same, you can control it during the transaction.

Example Consider the XML payload:

<?xml version="1.0" encoding="UTF-8"?>
<root>
    <level1>
        <level2>foo</level2>
        <level2>bar</level2>
    </level1>
</root>

This payload will generate value for XML target like this: foo bar.

If you turn on this feature, the nodes will apear under ARGS:

Adding XML argument 'xml.root.level1.level2' with value 'foo'
Adding XML argument 'xml.root.level1.level2' with value 'bar'

(These lines are from debug.log)

SecRemoteRules

Load rules from a given file hosted on a HTTPS site.

This is an optional directive that allow the user to load rules from a remote server. Notice that besides the URL the user also needs to supply a key, which could be used by the target server to provide different content for different keys.

Along with the key, supplied by the users, ModSecurity will also send its Unique ID and the `status call’ in the format of headers to the target web server. The following headers are used:

- ModSec-status
- ModSec-unique-id
- ModSec-key

The optional option “crypto” tells ModSecurity to expect some encrypted content from server. The utilization of SecRemoteRules is only allowed over TLS, thus, this option may not be necessary.

In ModSecurity v2 the directive can appear only once, the URL must begin with https, and the crypto option requires a build with APR crypto support. libModSecurity v3 takes exactly two parameters, the key and the URL (the crypto option is not accepted), downloads the file with libcurl requiring TLS 1.2 or newer and a verifiable certificate, and parses the content in place; a SecRemoteRulesFailAction must precede the directive to take effect.

SecRemoteRulesFailAction

Action that will be taken if SecRemoteRules specify an URL that ModSecurity was not able to download.

In ModSecurity v2 the default action is to Abort whenever there is a problem downloading a given URL. libModSecurity v3 only aborts when the directive is explicitly set to Abort before the SecRemoteRules directive; otherwise (unset or Warn) a failed download is ignored and the configuration loads without the remote rules, with nothing logged.

SecRequestBodyAccess

Configures whether request bodies will be buffered and processed by ModSecurity.

This directive is required if you want to inspect the data transported request bodies (e.g., POST parameters). Request buffering is also required in order to make reliable blocking possible. The possible values are:

• On: buffer request bodies
• Off: do not buffer request bodies

libModSecurity v3 skips request body processing only when the directive is explicitly set to Off; when it is unset, whatever body the connector hands over is processed. Set it explicitly.

SecRequestBodyInMemoryLimit

Configures the maximum request body size that ModSecurity will store in memory.

When a multipart/form-data request is being processed, once the in-memory limit is reached, the request body will start to be streamed into a temporary file on disk.

libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecRequestBodyJsonDepthLimit

Configures the maximum parsing depth that is allowed when parsing a JSON object.

During parsing of a JSON object, if nesting exceeds the configured depth limit then parsing will halt and REQBODY_ERROR will be set.

SecRequestBodyLimit

Configures the maximum request body size ModSecurity will accept for buffering.

Anything over the limit will be rejected with status code 413 (Request Entity Too Large). ModSecurity v2 enforces the 1 GB hard limit only on ctl:requestBodyLimit; the directive itself accepts any positive value.

In ModSecurity v2 the default is 134217728 bytes (128 MB). libModSecurity v3 applies no limit unless the directive is set; when the limit is exceeded it sets INBOUND_DATA_ERROR and, with SecRequestBodyLimitAction Reject and SecRuleEngine On, rejects the request with status 403.

SecRequestBodyNoFilesLimit

Configures the maximum request body size ModSecurity will accept for buffering, excluding the size of any files being transported in the request. This directive is useful to reduce susceptibility to DoS attacks when someone is sending request bodies of very large sizes. Web applications that require file uploads must configure SecRequestBodyLimit to a high value, but because large files are streamed to disk, file uploads will not increase memory consumption. However, it’s still possible for someone to take advantage of a large request body limit and send non-upload requests with large body sizes. This directive eliminates that loophole.

Generally speaking, the default value is not small enough. For most applications, you should be able to reduce it down to 128 KB or lower. Anything over the limit will be rejected with status code 413 (Request Entity Too Large). ModSecurity v2 accepts any positive value; no hard limit is enforced for this directive.

In ModSecurity v2 the default is 1048576 bytes (1 MB). libModSecurity v3 accepts the directive since 3.0.0 but only enforces it since 3.0.7, and applies no limit unless the directive is set.

SecRequestBodyLimitAction

Controls what happens once a request body limit, configured with SecRequestBodyLimit, is encountered

By default, ModSecurity will reject a request body that is longer than specified. This is problematic especially when ModSecurity is being run in DetectionOnly mode and the intent is to be totally passive and not take any disruptive actions against the transaction. With the ability to choose what happens once a limit is reached, site administrators can choose to inspect only the first part of the request, the part that can fit into the desired limit, and let the rest through. This is not ideal from a possible evasion issue perspective, however it may be acceptable under certain circumstances.

SecRequestEncoding

Declares the character encoding used in requests.

ModSecurity v2 accepts and stores the value but never uses it: the encoding is not validated and no request processing depends on it, so the directive has no effect. libModSecurity v3 does not accept it. It is documented only because it still appears in old configurations.

SecResponseBodyLimit

Configures the maximum response body size that will be accepted for buffering.

Anything over this limit will be rejected; ModSecurity v2 uses status code 500 (Internal Server Error), libModSecurity v3 uses 403 (only when SecRuleEngine is On and SecResponseBodyLimitAction is Reject; OUTBOUND_DATA_ERROR is set in any case). This setting will not affect the responses with MIME types that are not selected for buffering. There is a hard limit of 1 GB.

In ModSecurity v2 the default is 524288 bytes (512 KB). libModSecurity v3 applies no limit unless the directive is set.

SecResponseBodyLimitAction

Controls what happens once a response body limit, configured with SecResponseBodyLimit, is encountered.

By default, ModSecurity will reject a response body that is longer than specified. Some web sites, however, will produce very long responses, making it difficult to come up with a reasonable limit. Such sites would have to raise the limit significantly to function properly, defying the purpose of having the limit in the first place (to control memory consumption). With the ability to choose what happens once a limit is reached, site administrators can choose to inspect only the first part of the response, the part that can fit into the desired limit, and let the rest through. Some could argue that allowing parts of responses to go uninspected is a weakness. This is true in theory, but applies only to cases in which the attacker controls the output (e.g., can make it arbitrary long). In such cases, however, it is not possible to prevent leakage anyway. The attacker could compress, obfuscate, or even encrypt data before it is sent back, and therefore bypass any monitoring device.

SecResponseBodyMimeType

Configures which MIME types are to be considered for response body buffering.

Multiple SecResponseBodyMimeType directives can be used to add MIME types. Use SecResponseBodyMimeTypesClear to clear previously configured MIME types and start over.

In ModSecurity v2 the default list is text/plain text/html. libModSecurity v3 has no default list: when the directive is not set, every response type is considered for buffering. libModSecurity v3 compares the configured types verbatim against the lowercased response Content-Type (3.0.17; newer builds also lowercase the configured types), so write them in lowercase.

SecResponseBodyMimeTypesClear

Clears the list of MIME types considered for response body buffering, allowing you to start populating the list from scratch.

SecResponseBodyAccess

Configures whether response bodies are to be buffered.

This directive is required if you plan to inspect HTML responses and implement response blocking. Possible values are:

• On: buffer response bodies (but only if the response MIME type matches the list configured with SecResponseBodyMimeType).
• Off: do not buffer response bodies.

SecRule

Creates a rule that will analyze the selected variables using the selected operator.

Every rule must provide one or more variables along with the operator that should be used to inspect them. If no actions are provided, the default list will be used. (There is always a default list, even if one was not explicitly set with SecDefaultAction.) If there are actions specified in a rule, they will be merged with the default list to form the final actions that will be used. (The actions in the rule will overwrite those in the default list.) Refer to SecDefaultAction for more information.

SecRuleInheritance

Configures whether the current context will inherit the rules from the parent context.

Sometimes when you create a more specific configuration context (for example using the container), you may wish to use a different set of rules than those used in the parent context. By setting SecRuleInheritance to Off, you prevent the parent rules to be inherited, which allows you to start from scratch. In ModSecurity 2.5.x it is not possible to override phase 1 rules from a configuration context. There are no limitations in that respect in the current development version (and there won’t be in the next major version).

The possible values are:

• On: inherit rules from the parent context
• Off: do not inherit rules from the parent context

libModSecurity v3 accepts only Off (and ignores it); On is rejected with a configuration error.

SecRuleEngine

Configures the rules engine.

The possible values are:

• On: process rules
• Off: do not process rules
• DetectionOnly: process rules but never executes any disruptive actions (block, deny, drop, allow, proxy and redirect)

In ModSecurity v2 the default is Off. libModSecurity v3 leaves the value unset, in which state rules are evaluated and logged but never interrupt the transaction (equivalent to DetectionOnly). Always set it explicitly.

SecRulePerfTime

Set a performance threshold for rules. Rules that spend at least the time defined will be logged into audit log Part H as Rules-Performance-Info in the format id=usec, comma separated.

The rules hitting the threshold can be accessed via the collection PERF_RULES. libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecRuleRemoveById

Removes the matching rules from the current configuration context.

This directive supports multiple parameters, each of which can be a rule ID or a range. Parameters that contain spaces must be delimited using double quotes.

SecRuleRemoveByMsg

Removes the matching rules from the current configuration context.

Normally, you would use SecRuleRemoveById to remove rules, but that requires the rules to have IDs defined. If they don’t, then you can remove them with SecRuleRemoveByMsg, which matches a regular expression against rule messages.

SecRuleRemoveByTag

Removes the matching rules from the current configuration context.

Normally, you would use SecRuleRemoveById to remove rules, but that requires the rules to have IDs defined. If they don’t, then you can remove them with SecRuleRemoveByTag, which matches a regular expression against rule tag data. This is useful if you want to disable entire groups of rules based on tag data. Example tags used in the OWASP ModSecurity CRS include:

• AUTOMATION/MALICIOUS
• AUTOMATION/MISC
• AUTOMATION/SECURITY_SCANNER
• LEAKAGE/SOURCE_CODE_ASP_JSP
• LEAKAGE/SOURCE_CODE_CF
• LEAKAGE/SOURCE_CODE_PHP
• WEB_ATTACK/CF_INJECTION
• WEB_ATTACK/COMMAND_INJECTION
• WEB_ATTACK/FILE_INJECTION
• WEB_ATTACK/HTTP_RESPONSE_SPLITTING
• WEB_ATTACK/LDAP_INJECTION
• WEB_ATTACK/PHP_INJECTION
• WEB_ATTACK/REQUEST_SMUGGLING
• WEB_ATTACK/SESSION_FIXATION
• WEB_ATTACK/SQL_INJECTION
• WEB_ATTACK/SSI_INJECTION
• WEB_ATTACK/XSS

SecRuleScript

Description: This directive creates a special rule that executes a Lua script to decide whether to match or not. The main difference from SecRule is that there are no targets nor operators. The script can fetch any variable from the ModSecurity context and use any (Lua) operator to test them. The second optional parameter is the list of actions whose meaning is identical to that of SecRule. In ModSecurity v2 a relative script path is resolved against the directory of the configuration file that contains the directive, and a build without Lua support ignores the directive with a startup warning instead of failing. libModSecurity v3 resolves a relative path against the working directory, and a build without Lua support refuses to load the configuration (“Lua support was not enabled”).

Example script:

-- Your script must define the main entry
-- point, as below.
function main()
    -- Log something at level 1. Normally you shouldn't be
    -- logging anything, especially not at level 1, but this is
    -- just to show you can. Useful for debugging.
    m.log(1, "Hello world!");

    -- Retrieve one variable.
    local var1 = m.getvar("REMOTE_ADDR");

    -- Retrieve one variable, applying one transformation function.
    -- The second parameter is a string.
    local var2 = m.getvar("ARGS", "lowercase");

    -- Retrieve one variable, applying several transformation functions.
    -- The second parameter is now a list. You should note that m.getvar()
    -- requires the use of comma to separate collection names from
    -- variable names. This is because only one variable is returned.
    local var3 = m.getvar("ARGS.p", { "lowercase", "compressWhitespace" } );

    -- If you want this rule to match return a string
    -- containing the error message. The message must contain the name
    -- of the variable where the problem is located.
    -- return "Variable ARGS:p looks suspicious!"

    -- Otherwise, simply return nil.
    return nil;
end

In this first example we were only retrieving one variable at the time. In this case the name of the variable is known to you. In many cases, however, you will want to examine variables whose names you won’t know in advance, for example script parameters.

Example showing use of m.getvars() to retrieve many variables at once:

function main()
    -- Retrieve script parameters.
    local d = m.getvars("ARGS", { "lowercase", "htmlEntityDecode" } );

    -- Loop through the parameters.
    for i = 1, #d do
        -- Examine parameter value.
        if (string.find(d[i].value, "<script")) then
            -- Always specify the name of the variable where the
            -- problem is located in the error message.
            return ("Suspected XSS in variable " .. d[i].name .. ".");
        end
    end

    -- Nothing wrong found.
    return nil;
end

SecRuleUpdateActionById

Updates the action list of the specified rule.

This directive will overwrite the action list of the specified rule with the actions provided in the second parameter. It has two limitations: it cannot be used to change the ID or phase of a rule. Only the actions that can appear only once are overwritten. The actions that are allowed to appear multiple times in a list, will be appended to the end of the list.

SecRule ARGS "@rx attack" \
    "id:12345,\
    phase:2,\
    pass,\
    t:lowercase,\
    log,\
    msg:'Message text'"
SecRuleUpdateActionById 12345 \
    "t:none,\
    t:compressWhitespace,\
    deny,\
    status:403,\
    msg:'New message text'"

The effective resulting rule in the previous example will be as follows:

SecRule ARGS "@rx attack" \
    "id:12345,\
    phase:2,\
    deny,\
    status:403,\
    t:lowercase,\
    t:none,\
    t:compressWhitespace,\
    msg:'New Message text'"

The addition of t:none will neutralize any previous transformation functions specified (t:lowercase, in the example).

SecRuleUpdateTargetById

Updates the target (variable) list of the specified rule.

This directive will append (or replace) variables to the current target list of the specified rule with the targets provided in the second parameter. Starting with 2.7.0 this feature supports id range.

Explicitly Appending Targets

This is useful for implementing exceptions where you want to externally update a target list to exclude inspection of specific variable(s).

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}"

SecRuleUpdateTargetById 958895 !ARGS:email

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/*|!ARGS:email "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}""

Note that is is also possible to use regular expressions in the target specification:

SecRuleUpdateTargetById 981172 "!REQUEST_COOKIES:/^appl1_.*/"

Explicitly Replacing Targets

You can also entirely replace the target list to something more appropriate for your environment. For example, lets say you want to inspect REQUEST_URI instead of REQUEST_FILENAME, you could do this:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}"

SecRuleUpdateTargetById 958895 REQUEST_URI REQUEST_FILENAME

The effective resulting rule in the previous example replaces the target in the begin of the variable list as follows:

SecRule REQUEST_URI|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}""

SecRuleUpdateTargetById 981172 "!REQUEST_COOKIES:/^appl1_.*/"
SecRuleUpdateTargetById 981173 "!REQUEST_COOKIES:'/^(appl1_.*|foo_.*)/'"

SecRuleUpdateTargetByMsg

Updates the target (variable) list of the specified rule by rule message.

This directive will append (or replace) variables to the current target list of the specified rule with the targets provided in the second parameter.

Explicitly Appending Targets

This is useful for implementing exceptions where you want to externally update a target list to exclude inspection of specific variable(s).

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}"

SecRuleUpdateTargetByMsg "System Command Injection" !ARGS:email

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/*|!ARGS:email "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}""

Explicitly Replacing Targets

You can also entirely replace the target list to something more appropriate for your environment. For example, lets say you want to inspect REQUEST_URI instead of REQUEST_FILENAME, you could do this:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}"

SecRuleUpdateTargetByMsg "System Command Injection" REQUEST_URI REQUEST_FILENAME

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:

SecRule REQUEST_URI|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}""

SecRuleUpdateTargetByTag

Updates the target (variable) list of the specified rule by rule tag.

This directive will append (or replace) variables to the current target list of the specified rule with the targets provided in the second parameter.

Explicitly Appending Targets

This is useful for implementing exceptions where you want to externally update a target list to exclude inspection of specific variable(s).

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}"

SecRuleUpdateTargetByTag "WASCTC/WASC-31" !ARGS:email

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/*|!ARGS:email "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}""

Explicitly Replacing Targets

You can also entirely replace the target list to something more appropriate for your environment. For example, lets say you want to inspect REQUEST_URI instead of REQUEST_FILENAME, you could do this:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}"

SecRuleUpdateTargetByTag "WASCTC/WASC-31" REQUEST_URI REQUEST_FILENAME

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:

SecRule REQUEST_URI|ARGS_NAMES|ARGS|XML:/* "@rx [\;\|\`]\W*?\bmail\b" \
    "id:'958895',\
    phase:2,\
    block,\
    capture,\
    t:none,\
    t:htmlEntityDecode,\
    t:compressWhitespace,\
    t:lowercase,\
    msg:'System Command Injection',\
    logdata:'%{TX.0}',\
    tag:'WEB_ATTACK/COMMAND_INJECTION',\
    tag:'WASCTC/WASC-31',\
    tag:'OWASP_TOP_10/A1',\
    tag:'PCI/6.5.2',\
    ctl:auditLogParts=+E,\
    rev:'2.1.1',\
    severity:'2',\
    setvar:'tx.msg=%{rule.msg}',\
    setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},\
    setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},\
    setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%{tx.0}""

SecServerSignature

Instructs ModSecurity to change the data presented in the “Server:” response header token.

libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3. In order for this directive to work, you must set the Apache ServerTokens directive to Full. ModSecurity will overwrite the server signature data held in this memory space with the data set in this directive. If ServerTokens is not set to Full, then the memory space is most likely not large enough to hold the new data we are looking to insert.

SecStatusEngine

Controls Status Reporting functionality. Uses DNS-based reporting to send software version information to the ModSecurity Project team.

libModSecurity v3 accepts the directive (so that modsecurity.conf-recommended loads) but ignores it: nothing is ever sent. If SecStatusEngine directive is not present, it is disabled. If SecStatusEngine is marked as On, the following information will be shared with the ModSecurity project team when the web server is started:

• Anonymous unique id for the server
• Version of:
  • ModSecurity
  • Web Server Software (Apache, IIS, Nginx, Java)
  • APR
  • Libxml2
  • Lua
  • PCRE

[Mon Jan 20 10:55:22.001020 2014] [:notice] [pid 18231:tid 140735189168512] ModSecurity: StatusEngine call: "2.7.7,Apache/2.4.4 (Unix),1.4.6/1.4.6, 8.32 /8.32 2012-11-30,Lua 5.1/(null),2.7.8/(null),96ce9ba3c2fb71f7a8bb92a88d560d44dbe459b8"
[Mon Jan 20 10:55:22.089012 2014] [:notice] [pid 18231:tid 140735189168512] ModSecurity: StatusEngine call successfully submitted.

SecStreamInBodyInspection

Configures the ability to use stream inspection for inbound request data in a re-allocable buffer. For security reasons we are still buffering the stream.

This feature enables the creation of the STREAM_INPUT_BODY variable and is useful for data modification or to match data in raw data for any content-types.

SecStreamOutBodyInspection

Configures the ability to use stream inspection for outbound request data in a re-allocable buffer. For security reasons we are still buffering the stream.

This feature enables the creation of the STREAM_OUTPUT_BODY variable and is useful when you need to do data modification into response body. libModSecurity v3 rejects this directive with a configuration error, so a configuration containing it cannot be shared between v2 and v3.

SecTmpDir

Configures the directory where temporary files will be created.

The location specified needs to be writable by the Apache user process. This is the directory location where ModSecurity will swap data to disk if it runs out of memory (more data than what was specified in the SecRequestBodyInMemoryLimit directive) during inspection.

As of ModSecurity version 3.0, SecTmpDir is no longer supported. libModSecurity is able to deal with request body in a file or in a buffer (chunked or not). Web servers have properties which controls whenever a request should be saved to a file or used as a buffer (e.g. client_body_buffer_size https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size) . If it is a file, ModSecurity will use the file to perform the inspection. If not, the buffer will be used.

SecTmpSaveUploadedFiles

Configures whether or not files uploaded via a multipart POST request will be temporarily saved to the file system.

When set to On, uploaded files are extracted to the upload directory (SecUploadDir) while the transaction is processed, even when SecUploadKeepFiles is Off, so that operators such as @inspectFile can examine them. The files are automatically deleted after the transaction is complete. If you wish to retain the files, see SecUploadKeepFiles. Both ModSecurity v2 and libModSecurity v3 implement this directive.

SecUnicodeMapFile

Defines the path to the file that will be used by the urlDecodeUni transformation function to map Unicode code points during normalization and specifies the code page to use.

In ModSecurity v2 the code page parameter is optional (accepted since 2.7.5; before that it was set with SecUnicodeCodePage), and a relative path is resolved against the directory of the configuration file that contains the directive. In libModSecurity v3 the code page parameter is mandatory, and a relative path is tried against the working directory first and then against the directory of the configuration file.

SecUnicodeCodePage

Defines which Unicode code point will be used by the urlDecodeUni transformation function during normalization.

Deprecated in ModSecurity 2.7.5: SecUnicodeMapFile now accepts the code page as its second parameter. libModSecurity v3 does not accept this directive.

SecUploadDir

Configures the directory where intercepted files will be stored.

This directory must be on the same filesystem as the temporary directory defined with SecTmpDir. This directive is used with SecUploadKeepFiles. In ModSecurity v2 the value none unsets the directory (useful in a child configuration context).

SecUploadFileLimit

Configures the maximum number of file uploads processed in a multipart POST.

In ModSecurity v2 the default is set to 100 files, but you are encouraged to reduce this value; the value default reverts to it. libModSecurity v3 applies no limit unless the directive is set, accepts only a numeric value (the keyword default is a syntax error), and only counts files when they are being extracted (SecUploadKeepFiles or SecTmpSaveUploadedFiles On). Any file over the limit will not be extracted and the MULTIPART_FILE_LIMIT_EXCEEDED and MULTIPART_STRICT_ERROR flags will be set. To prevent bypassing any file checks, you must check for one of these flags.

SecUploadFileMode

Configures the mode (permissions) of any uploaded files using an octal mode (as used in chmod).

This feature is not available on operating systems not supporting octal file modes. The default mode (0600) only grants read/write access to the account writing the file. If access from another account is needed (using clamd is a good example), then this directive may be required. However, use this directive with caution to avoid exposing potentially sensitive data to unauthorized users. Using the value “default” will revert back to the default setting. libModSecurity v3 accepts only a numeric value (the keyword default is a syntax error); when unset, files are created with mode 0600. Releases 3.0.15 through 3.0.17 parse the value as a decimal number rather than octal, so 0640 is applied as mode 01200; earlier releases parse it as octal.

SecUploadKeepFiles

Configures whether or not the intercepted files will be kept after transaction is processed.

This directive requires the storage directory to be defined (using SecUploadDir).

Possible values are:

• On - Keep uploaded files.
• Off - Do not keep uploaded files.
• RelevantOnly - This will keep only those files that belong to requests that are deemed relevant.

SecWebAppId

Creates an application namespace, allowing for separate persistent session and user storage.