ModSecurity Version 3.0 Announcement

libModSecurity aka ModSecurity version 3.0 is out there. libModSecurity starts a new era in terms of ModSecurity extensibility. The modular architecture provides flexibility to extend ModSecurity core with scripting languages and from scripting languages. Facilitating work such as: UI integration, integration with other WAF products, other security products in general, including the ability to process the rules even without a web server.

A brief view of v3 internals

One of the most important differences from version 2 and 3 is the fact that version 3 no longer depends on Apache nor Apache Runhime (APR). The library is now something generic, not attached to any web server. A middleware - in our architecture called connector - is the one responsible to connect ModSecurity to the end web server. Originally a connector can be written in C or C++. By design, the connector should be a very minimal piece of software. Below you can find a hello world connector:

#include "modsecurity/modsecurity.h" #include "modsecurity/transaction.h" char main_rule_uri[] = "basic_rules.conf"; int main (int argc, char **argv) { ModSecurity *modsec = NULL; Transaction *transaction = NULL; Rules *rules = NULL; modsec = msc_init(); rules = msc_create_rules_set(); msc_rules_add_file(rules, main_rule_uri); transaction = msc_new_transaction(modsec, rules); msc_process_connection(transaction, "127.0.0.1"); msc_process_uri(transaction, "http://www.modsecurity.org/test?key1=value1&key2=value2&key3=value3&test=args&test=test"); msc_process_request_headers(transaction); msc_process_request_body(transaction); msc_process_response_headers(transaction); msc_process_response_body(transaction); return 0; }

Code: example of a Hello World connector. You can find more examples at our repository: https://github.com/SpiderLabs/ModSecurity/tree/v3/dev/v3.0.0/examples

The possibility to extend the collections

Sharing collection values within different instances of ModSecurity was always desirable. Depending on the logical distribution of your servers, information on clients can be shared among different server instances. On version 2 such approach was not possible. That is different from version 3 where collections can be extended to what fits you better. A collection on version 3 is an abstraction that can be implemented by different components such as: Memcache or REDIS. The logic on how to treat the variables is all handled by ModSecurity, the backend class is only responsible to save and read a key-pair value.

Have a look at our official supported backends to understand better how to create your own collection:

https://github.com/SpiderLabs/ModSecurity/tree/v3/dev/v3.0.0/src/collection/backend

Lua and other scripts

Although the SecRule language is very popular among ModSecurity users, it is known to have it its limitations. A more extensible and meaningful way to tell the core how to perform the inspections was always desired. To fulfill this requirement we had the support for Lua on ModSecurity version 2.x. Lua implementation on version 3 is quite different as it meant to be extensible to other languages as well. Lua is part of a script engine that open doors for other implementations such as Python and JavaScript. If you want to extend ModSecurity to support your favorite scripting language, you only have to implement a few methods, the rest is up to ModSecurity.

For further information check Lua implementation: https://github.com/SpiderLabs/ModSecurity/blob/v3/master/src/engine/lua.cc

The compilation dependencies and compilation flags

From a very minimal to full featured installation, the new ModSecurity has almost all the dependencies as optional. Depending on your setup you may not need JSON inspection or XML, in that case you don't need to compile it with such support. That is very convenient on minimal environments where meeting dependency criteria could be a nightmare and the resource of the dependency was not always used.

Along with the optional dependencies, this version counts with different compilation flags. From enable (and/or disable) the library examples, to complete removal of the support for logging (in compilation time). Those are examples of options that can be set using the configuration flags. In the end of the configuration stage you will find a summary of all items and its states.

Image 1. Configuration output

For the full list of the options, please refer to ./configure --help.

Stability and security test

Fuzzing tests is also part of version 3 implementation. At this point the fuzzer is running in our lab for months without any new crash :)

Image 2. Fuzzer running for months without crash so far.

For further information on ModSecurity fuzzer please check: https://www.trustwave.com/en-us/resources/blogs/spiderlabs-blog/modsecurity-version-3-fuzzing-as-part-of-the-qa/

Performance like you never measured

Although this version is not focused on performance improvements, it is all about methods to measure it. On version 2 understanding the amount of time/CPU consumed by each of the rules was a difficult task. Sometimes computing those values was already an impact on the performance. In version 3.0 there is the possibility to run stap scripts to grab the amount of time spent on every rule. Therefore, allowing the user to understand the amount of time consumed by phase and rule.

Image 3. Flamegraph Modsecurity rules in a production server.

The logging methods and delivery options

In ModSecurity version 2 we have the mlogc utility that we can use to send the logs to an external server. As of libModSecurity the logging delivery option can also be extended into different mechanisms. By default it supports the HTTP, Serial and Parallel logging. Apart from those you can also extend ModSecurity to support your own mechanism, having it easily integrated into your SIEM.

The connectors

Currently we officially support two connectors: Nginx and Apache.

NGINX

The nginx connector is also available in GitHub, as a matter of fact nginx connector for version 3 is our recommendation for the nginx platform. You can find further information about the nginx connector on the nginx GitHub page: https://github.com/SpiderLabs/ModSecurity-nginx

Apache

Apache connector is under development and is recommended for test environments and is also available on GitHub. We do appreciate feedback on it. The Apache connector still demands the rules to be specified under a ModSecurity configuration block. This is different and not as flexible as ModSecurity v2 and we plan to support the same rules configuration format in a near future.

Apache connector on GitHub: https://github.com/SpiderLabs/ModSecurity-apache

Core Rule Set and Commercial rules

libModSecurity is fully compatible with OWASP CRS and Trustwave Commercial rules. All the resources used on those rules sets are supported and well-tested on v3. Please note that ModSecurity v2.x versions will be maintained by Trustwave for some additional period of time.

Summary

This release represents a significant improvement to the ModSecurity WAF. It removes dependencies and improves performance. We'd like to thank to the community for helping with this release. For bug reports and future information about ModSecurity please check https://github.com/SpiderLabs/ModSecurity. For Trustwave Commercial Rules for Modsecurity please see: http://www.modsecurity.org/commercial-rules.html