Libmodsecurity (ModSecurity v3)

Libmodsecurity is the core library component of the ModSecurity v3 project. It acts as an interface for 'Connectors' (such as Nginx or IIS connectors) to process web traffic. The library allows you to load and interpret rules written in the ModSecurity SecRules format and apply them to HTTP content provided by your application.

Unlike ModSecurity v2.x, this version is a complete rewrite that removes Apache dependencies, making it platform-independent and higher performing.

The test/benchmark/ directory contains a tool to measure library performance by simulating HTTP transactions.

By default, the benchmark uses a minimal configuration (basic_rules.conf) which only includes modsecurity.conf-recommended. To measure performance with real rules (like OWASP CRS), you must first download the rules and update your basic_rules.conf to include them.

# Run benchmark with default minimal rules
cd test/benchmark
$ ./benchmark 1000

# To measure with real OWASP rules:
$ ./download-owasp-v3-rules.sh
# Update basic_rules.conf to include the downloaded rules
$ cat basic_rules.conf

Include "../../modsecurity.conf-recommended"
Include "owasp-v3/crs-setup.conf.example"
Include "owasp-v3/rules/*.conf"

# Run benchmark again
$ ./benchmark 1000

On Unix-like systems, the project uses autotools. You must ensure all git submodules are initialized before starting the build process. After compilation, it is strongly recommended to run the unit and regression tests located in the tests/ subfolder.

# Clone the repository
git clone https://github.com/owasp-modsecurity/ModSecurity ModSecurity
cd ModSecurity

# Initialize and fetch all submodules (Required)
git submodule update --init --recursive

# Verify submodules
git submodule status

# Build process
./build.sh
./configure
make
sudo make install

To ensure your changes or implementations (like new operators) work correctly, use the native regression and unit test utilities. You must first initialize the required git submodules which contain the shared test cases.

Follow these steps to fetch submodules and run the tests:

$ cd /path/to/your/ModSecurity
$ git submodule update --init --recursive
$ make check

When debugging, it is recommended to disable compiler optimizations to ensure back traces contain readable data. Additionally, enabling assertions helps catch assumption violations early.

Use the CFLAGS environment variable to set -g -O0 and pass --enable-assertions=yes to the ./configure script.

$ export CFLAGS="-g -O0"
$ ./build.sh
$ ./configure --enable-assertions=yes
$ make
$ sudo make install

This repository relies on git submodules for critical components like libinjection and mbedtls. If submodules are not initialized, the project will not build successfully. You can verify the status using git submodule status; a leading - indicates a submodule has not been initialized or fetched.

git submodule update --init --recursive

# To verify:
git submodule status

The library provides a C++ interface for managing ModSecurity instances, rule sets, and transactions. This is the preferred interface for modern C++ applications.

using ModSecurity::ModSecurity;
using ModSecurity::Rules;
using ModSecurity::Transaction;

ModSecurity *modsec;
ModSecurity::Rules *rules;

modsec = new ModSecurity();

rules = new Rules();

rules->loadFromUri(rules_file);

Transaction *modsecTransaction = new Transaction(modsec, rules);

modsecTransaction->processConnection("127.0.0.1");
if (modsecTransaction->intervention()) {
   std::cout << "There is an intervention" << std::endl;
}

Libmodsecurity is written in C++17 and requires several dependencies depending on the features you need:

• Mandatory: Flex, Bison (Yacc), and YAJL (for JSON logging/testing).
• Regex Engine: Uses PCRE2 by default. You can fallback to legacy PCRE by providing the --with-pcre flag during configuration.
• Operator-specific:
  • libinjection: Required for @detectXSS and @detectSQL operators.
  • curl: Required for the SecRemoteRules directive.
• Optional Features:
  • libcurl: For SecRemoteRules.
  • LMDB: For persistent storage.
  • Lua: For scripting support.
  • libmaxminddb: Recommended for modern MaxMind DB support (replaces the deprecated legacy GeoIP C API).
  • libXML2: For parsing XML requests.