ModSecurity v3: The WAF engine behind Nginx and Apache, and who should compile it

What problem ModSecurity v3 solves, and who it is actually for

A web application firewall inspects HTTP requests and responses and decides whether to let them through. ModSecurity implements that decision layer. The repository describes libmodsecurity as an interface to ModSecurity Connectors, taking in web traffic and applying traditional ModSecurity processing, and it provides the capability to load and interpret rules written in the SecRules format and apply them to HTTP content supplied by your application through a connector.

That wording matters. The engine does not sit in front of your application by itself, and it does not ship a rule set. It is a C++ library that a connector calls. The connector is what talks to Nginx, Apache or IIS, normalises the request into a format the library understands, and hands back a verdict. The Nginx connector lives in a separate repository, ModSecurity-nginx, and the README states that each connector is maintained as its own GitHub project with its own release cycle, issues and development tree.

The intended audience is therefore narrower than the search volume suggests. It is for platform engineers who already terminate traffic in Nginx, Apache or IIS and want rule-based inspection at that layer, and for people building their own connector or embedding the library in a proxy or gateway written in C++. If you want a standalone reverse proxy with a WAF built in, this is the wrong shape of project. If you want a managed filtering service, it is also the wrong shape.

Why v3 dropped Apache: the library and connector split

ModSecurity began as an Apache module. The README is explicit that the project was extended over time to support other platforms, including Nginx and IIS, and that supporting more platforms required removing the Apache dependencies. In v3, all Apache dependencies have been removed, both at compilation and at runtime.

The consequence is architectural. The v3 branch no longer contains the traditional module logic for Nginx, Apache and IIS. It contains only libmodsecurity. That library is consumed by connectors, which interface with the web server and present the library with a common format it understands. The stated benefit is that installing ModSecurity v3 gives you exactly what you need and no extras, and that each connector can move on its own schedule.

The trade-off is visible the moment you try to install it. There is no single artefact called ModSecurity that you install and then point at a server. You build or install the library, then separately obtain the connector for your web server, then separately obtain a rule set. Three moving parts, three release cycles. The README frames the split as a feature, and for maintainers it is, but it moves coordination work onto the operator.

ModSecurity v2.x, the Apache module, still exists on the v2/master branch and the README says it is still under maintenance. So the split is not a forced migration; both lines are present in the same repository under different branches.

How SecRules are parsed and evaluated

The engine's core job is to read rules in the SecRules language and apply them to HTTP content. The README states that the library is written in C++ using the C++17 standard, and that Flex and Bison are used to produce the Sec Rules Language parser. That is the mechanism: rules are not interpreted by a hand-written evaluator, they are parsed by a generated lexer and parser, which is why Flex and Bison are build dependencies rather than optional extras.

Regular expressions inside rules are handled by a dedicated utility in src/utils/regex.*, and the README notes that operators such as @rx, @rxGlobal and @verifyCC use it. By default ModSecurity uses PCRE2. Legacy PCRE is only used if you explicitly pass --with-pcre at configure time, which sets WITH_PCRE. In practice that means current builds expect PCRE2 unless you deliberately configure otherwise, and a build environment with only the older PCRE will not do what you expect.

Other dependencies are tied to specific operators and directives rather than to compilation as a whole. libinjection is required for the @detectXSS and @detectSQL operators. curl is required for the SecRemoteRules directive. The README states plainly that if those libraries are missing, ModSecurity is compiled without support for the respective operators or directives. That is a silent capability loss: the build succeeds, and the rule that relied on @detectSQL simply has no engine behind it. Checking the configure output for those libraries is worth the minute it takes.

YAJL is mandatory, because ModSecurity uses JSON for logging and for its testing framework. libXML2 is optional and only relevant if you parse XML requests. The repository also carries a unicode.mapping file at the top level, which is a data file the engine needs rather than source code.

Building ModSecurity v3 from source on Linux or macOS

On Unix-like systems the project uses autotools. The README warns that if you are working from a git checkout you must clone recursively or initialise all submodules before building. The repository uses git submodules, and the top-level .gitmodules file is present, so a plain clone leaves you with an incomplete tree. Clone and then fetch the submodules:

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

Before building, check that the submodules actually landed. The README gives this command for that purpose:

git submodule status

A correctly initialised submodule shows a commit hash. A leading hyphen means it has not been initialised. If you see hyphens, the build will fail later in a less obvious way, so fix it here.

With the tree complete, the README's build sequence is four commands:

./build.sh
./configure
make
sudo make install

The README notes that libmodsecurity is a dynamic library and must be installed somewhere the operating system can find dynamic libraries. That is the step that catches people out: make install puts the library on disk, but a connector loading it at runtime still needs the dynamic linker to resolve it. The README also recommends running the unit and regression tests under tests/ after compilation to confirm there are no issues on your build and platform, and points to a Compilation Recipes page in the wiki for distribution-specific builds.

Nothing in the README describes configuring a web server to use the library. That work belongs to the connector's own documentation, which is a separate repository.

What the engine does not give you: rules, defaults and rollback

The repository ships modsecurity.conf-recommended at the top level. The name is accurate: it is a recommended configuration for the engine, not a rule set. Loading it tells ModSecurity how to behave. It does not tell ModSecurity what to block. For actual detection you need a rule set, and the README does not bundle one.

This is the most common source of confusion around the project, and it is worth stating without hedging. If you install the library, install a connector, and start your server, you have an engine with no rules and therefore no protection. The engine's job is to parse and evaluate SecRules; supplying SecRules is your job.

Two other gaps are worth knowing before you plan a deployment. First, the README does not document rollback. There is no described procedure for reverting to a previous library version or undoing a configuration change, so you should treat version pinning and configuration backup as your own responsibility. Second, the README does not document how to run the engine in a blocking mode versus a detection-only mode; that behaviour lives in the rule set and the configuration file, not in the library documentation reproduced here.

A practical failure mode follows from the build-time dependency behaviour described earlier. If libinjection is absent at compile time, the build completes and @detectSQL and @detectXSS are unavailable. A rule set that relies on them will load but not detect. On a system where the build was done by someone else, this is invisible unless you check.

ModSecurity v3 compared with ModSecurity v2.x and with a reverse proxy WAF

The most direct alternative is ModSecurity v2.x, which lives on the v2/master branch of the same repository and which the README says is still under maintenance. The difference is not a feature list, it is a dependency model. v2 is an Apache module and carries Apache dependencies at compile and run time. v3 has removed all Apache dependencies and is a standalone library driven by connectors. If your traffic is Apache and you want the shortest path to a working module, v2 is the smaller job. If you need Nginx or IIS, or you want to embed inspection in your own C++ service, v2 is not the right branch.

The README lists the v3 differences as removal of Apache dependencies, higher performance, new features and a new architecture. It also describes groundwork for features users have asked for, naming native support for audit logs in JSON format as an example. That is stated as intent for future versions, not as shipped behaviour today.

A second alternative is a WAF that ships as its own proxy rather than as a library for your existing server. The difference is where the request path changes. With ModSecurity v3, traffic keeps flowing into the Nginx or Apache you already run, and the connector inserts inspection into that existing path. With a standalone proxy WAF, you add a hop and point your upstream at it. The library approach avoids the extra network hop and keeps your existing server configuration as the source of truth; the proxy approach avoids compiling C++ and managing dynamic library paths, at the cost of another process in the request path. Neither is universally better, and the README does not make a claim either way.

Maintenance, licensing and what to check before upgrading

The repository is not archived, and the last push was on 2026-09-20, so the project is being worked on. Release cadence is visible in the tags: v3.0.15 on 2026-04-28, v3.0.16 on 2026-06-29, and v2.9.14 on 2026-07-02. The v2 and v3 lines are both receiving releases, which is consistent with the README's statement that v2.x is still under maintenance. Both lines are live, so a team on v2 is not being pushed off it by abandonment.

The upgrade cost is dominated by the connector split rather than by the library. Upgrading libmodsecurity does not upgrade the Nginx or Apache connector, because those are separate projects with separate release cycles. A version bump therefore has at least two coordinates to track, and the connector's own compatibility expectations are documented in its repository, not in this one. The README does not describe a compatibility matrix between library versions and connector versions, so that is something to establish from the connector side before you upgrade in production.

Licensing is Apache-2.0, per the repository's LICENSE file and the project metadata. Apache-2.0 is a permissive licence that includes an explicit patent grant, and it does not impose copyleft obligations on your own application code the way a strong copyleft licence would. What it does require is preservation of notices and inclusion of the licence text when you redistribute the library. This is a description of the licence, not legal advice; if you are redistributing ModSecurity inside a product, have counsel read the actual text rather than a summary.

Editorial conclusion

Adopt ModSecurity v3 if you run Nginx or Apache at the edge of an application you cannot fix quickly, and you are willing to build the library and manage a rule set separately. Do not adopt it if you expect a single package that filters traffic after installation: v3 is a library with no rules, and the connector is a separate project. Before committing, verify that your web server has a maintained connector, that PCRE2 and YAJL are present or can be built, and that you have a plan for the rule set, since modsecurity.conf-recommended configures the engine but does not defend anything by itself.

Frequently asked questions

Official sources

1. License: Apache-2.0
2. owasp-modsecurity/ModSecurity on GitHub
3. Project website
4. README
5. Releases