<picture> <source media="(prefers-color-scheme: dark)" srcset="./others/modsec_white_bg.png"> <source media="(prefers-color-scheme: light)" srcset="./others/modsec.png"> <img src="./others/modsec.png" width="50%"> </picture>

Libmodsecurity is one component of the ModSecurity v3 project. The library codebase serves as an interface to ModSecurity Connectors taking in web traffic and applying traditional ModSecurity processing. In general, it provides the capability to load/interpret rules written in the ModSecurity SecRules format and apply them to HTTP content provided by your application via Connectors.

If you are looking for ModSecurity for Apache (aka ModSecurity v2.x), it is still under maintenance and available: here.

What is the difference between this project and the old ModSecurity (v2.x.x)?

• All Apache dependencies have been removed
• Higher performance
• New features
• New architecture

Libmodsecurity is a complete rewrite of the ModSecurity platform. When it was first devised the ModSecurity project started as just an Apache module. Over time the project has been extended, due to popular demand, to support other platforms including (but not limited to) Nginx and IIS. In order to provide for the growing demand for additional platform support, it has became necessary to remove the Apache dependencies underlying this project, making it more platform independent.

As a result of this goal we have rearchitected Libmodsecurity such that it is no longer dependent on the Apache web server (both at compilation and during runtime). One side effect of this is that across all platforms users can expect increased performance. Additionally, we have taken this opportunity to lay the groundwork for some new features that users have been long seeking. For example we are looking to natively support auditlogs in the JSON format, along with a host of other functionality in future versions.

It is no longer just a module.

The 'ModSecurity' branch no longer contains the traditional module logic (for Nginx, Apache, and IIS) that has traditionally been packaged all together. Instead, this branch only contains the library portion (libmodsecurity) for this project. This library is consumed by what we have termed 'Connectors' these connectors will interface with your webserver and provide the library with a common format that it understands. Each of these connectors is maintained as a separate GitHub project. For instance, the Nginx connector is supplied by the ModSecurity-nginx project (https://github.com/owasp-modsecurity/ModSecurity-nginx).

Keeping these connectors separated allows each project to have different release cycles, issues and development trees. Additionally, it means that when you install ModSecurity v3 you only get exactly what you need, no extras you won't be using.

Compilation

Before starting the compilation process, make sure that all required dependencies are installed.
See the Dependencies and Git submodules section for further information.

After compilation, make sure that there are no issues on your build/platform.
We strongly recommend running the unit tests and regression tests. These test utilities are located in the tests/ subfolder.

As a dynamic library, libmodsecurity must be installed in a location where your operating system can find dynamic libraries.

Unix (Linux, macOS, FreeBSD, …)

On Unix-like systems, the project uses autotools for the compilation process.

If you are working with a git checkout, make sure to clone the repository recursively or initialize all submodules before building.
See also the Git submodules section.

git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity
cd ModSecurity

This repository uses git submodules. After cloning, make sure to initialize and fetch all submodules:

git submodule update --init --recursive

You can verify that all submodules are properly initialized with:

git submodule status

Submodules that are correctly initialized show a commit hash. A leading - indicates that the submodule has not been initialized.

You can then start the build process:

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

Details on distribution-specific builds can be found in our Wiki: Compilation Recipes

Windows

Windows build information can be found here.

Dependencies

• This library is written in C++ using the C++17 standard.
• It uses Flex and Bison (Yacc) to produce the “Sec Rules Language” parser.
• Mandatory dependencies include YAJL, as ModSecurity uses JSON for logging and its testing framework.
• libXML2 (optional) is used for parsing XML requests.

Regular expression engine (PCRE2 / PCRE)

• Regular expression processing in SecRules is implemented via the Regex utility (src/utils/regex.*).

• By default, ModSecurity uses PCRE2 for regex handling.

• This is used by operators such as @rx, @rxGlobal, and @verifyCC.

• Build-time behavior:

  • Default: PCRE2 is detected and used.
  • Fallback: legacy PCRE can be used if --with-pcre is explicitly provided (WITH_PCRE).

• In other words, current builds expect PCRE2 unless explicitly configured otherwise.

All other dependencies are related to operators specified within SecRules or configuration directives and may not be required for compilation.

Operator-related dependencies

• libinjection is required for the operators @detectXSS and @detectSQL.
• curl is required for the directive SecRemoteRules.

If those libraries are missing, ModSecurity will be compiled without support for the respective operators or directives.

Git-submodules

The repository includes the following submodules:

• others/libinjection – used by @detectSQLi and @detectXSS operators.

• others/mbedtls (TF-PSA-Crypto subset) – used for cryptographic functions and helpers (e.g. hashing, base64).

  Note: The newer mbedTLS v4 layout is not compatible with the older v3 structure. The internal structure has changed significantly, and many components have been moved into submodules (e.g. TF-PSA-Crypto).

  After merging PR #3532, it is required to run:

  git submodule update --init --recursive
  

  This ensures that all required submodules are fetched. Without this step, the project will not build successfully.

  You can verify that all submodules are properly initialized with:

  git submodule status
  

  Example output:

  bc625d5... bindings/python
  2117822... others/libinjection (v4.0.0)
  0fe989b... others/mbedtls (v4.1.0)
  a3d4405... test/test-cases/secrules-language-tests
  

  If a submodule is missing, it will be shown with a leading -, for example:

  -bc625d5... bindings/python
  

  A leading - indicates that the submodule has not been initialized or fetched.

• test/test-cases/secrules-language-tests – shared SecRules conformance and regression test suite used by make check.

• bindings/python – Python bindings for ModSecurity (not required for core library compilation).

others/libinjection and others/mbedtls are effectively required for source builds and must be initialized before building.

Optional external dependencies

Several external libraries are optional and enable additional features, including:

• libcurl – required for SecRemoteRules

• LMDB – persistent storage support

• Lua – scripting support

• XML libraries – extended XML processing

• GeoIP (legacy) / MaxMind

  The legacy GeoIP C API (libGeoIP) is deprecated and no longer maintained by MaxMind. The upstream repository has been archived and should not be used for new deployments.

  Instead, ModSecurity supports the modern MaxMind DB API (libmaxminddb), which is actively maintained.

  During configuration you may see something like:

  + GeoIP/MaxMind                                 ....found
      * (MaxMind) v1.12.2
         -lmaxminddb , -I/usr/include/x86_64-linux-gnu
  

  This indicates that libmaxminddb is being used (recommended).

  It is strongly recommended to use MaxMind DB instead of the legacy GeoIP library.

Library documentation

The library documentation is written within the code in Doxygen format. To generate this documentation, please use the doxygen utility with the provided configuration file, “doxygen.cfg”, located with the "doc/" subfolder. This will generate HTML formatted documentation including usage examples.

Library utilization

The library provides a C++ and C interface. Some resources are currently only available via the C++ interface, for instance, the capability to create custom logging mechanism (s