Announcing ModSecurity v2.8.0

Screen Shot 2014-04-15 at 6.41.27 PM

The ModSecurity Project team is pleased to announce the availability of v2.8.0. To see the full release notes or download the the source packages, see the ModSecurity GitHub project release tab:

New Features

Version 2.8.0 comes with five important new features:

  • Status Reporting
  • JSON Request body Parser
  • @detectXSS Operator
  • SecConnReadStateLimit and SecConnWriteStateLimit Directives

In addition to great new functionality, we have also improved the following:

  • Debug and Troubleshooting Documentation
  • Testing Platforms
  • Project Development Metrics

ModSecurity Status

See our previous blog post entitled "Introducing ModSecurity Status Reporting". Status Reporting simply provides the project team with some basic community usage data including the # of users, OS and web server platforms and software versions in use. This functionality is not enabled by default in ModSecurity, however we have activated it as part of our Recommended Base config file.

Screen Shot 2014-04-15 at 6.36.48 PM

The information that will be sent to the server is also shared with the community through the website:

Screen Shot 2014-04-15 at 6.12.19 PM

For the full list information that is sent to the ModSecurity website, check the ModSecurity Reference Manual.

JSON Parser

ModSecurity will automatically parse request body content when the Content-Type headers are:

  • www-x-form-urlencoded, or
  • multipart/form-data

If the request body Content-Type is something else, such as XML, then a SecRule is used to dynamically trigger libxml2 using the "requestBodyProcessor" parser.

Screen Shot 2014-04-15 at 6.29.47 PM

Similarly, we have extended the request body parser support to now handle JSON content using yajl (Yet Another JSON Library).

Screen Shot 2014-04-15 at 6.34.05 PM

When this configuration is used, ModSecurity will parse the JSON contents and populate the standard ARGS collection. We will be releasing a full blog post soon outlining the new JSON request body parsing feature. More information on the JSON Parser is available at: ModSecurity Reference Manual.

@detectXSS Operator

The new @detectXSS operator uses the most recent libinjection code that identifies possible XSS attacks. The new operator is active within both of our live demos:

More information about libinjection XSS detection:

SecConnReadStateLimit and SecConnWriteStateLimit Directives

In previous versions of ModSecurity we introduced two directives to help combat Slow HTTP DoS Attacks:

  • SecReadStateLimit
  • SecWriteStateLimit

While these directives are helpful to mitigate attacks, they lacked the capability to correlate client IP address data. With ModSecurity v2.8.0, we have deprecated the previous directives for two new ones:

These directives establish a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_READ or SERVER_BUSY_WRITE state. The big difference is that they are now able to accept optional parameters: @ipMatch, @ipMatchFromFile and @ipMatchF to allow for white-listing exceptions of these thresholds.

Note: This functionality is only available to Apache users.


As a ModSecurity rule writer, I have found occasions where I would like to analyze the entire HTTP request content all within one single variable, rather than parsed into separate individual variables. This is now possible with FULL_REQUEST which contains the full request content including: request URI, headers and the request body. The format is essentially the same as what the browser sends across the wire with headers and the request body separated by a "blank line". In this release there is also available the FULL_REQUEST_LENGTH, which contains the amount of bytes that will be used when FULL_REQUEST is requested.

Debug and Trouble-Shooting Documentation

We have published documentation to aid the community in reporting bugs and steps for troubleshooting problems. Sometimes due to very specific configurations and/or dependency versions it is not possible for our development team to reproduce, in a timely manner way, an error reported by our users. In order to reduce the time to respond to these kinds of problems, we created the following documentation: Debugging ModSecurity. This is not a developer guide or debugging utility, but rather simple documentation that can provide enough information to the users to eventually debug and report (with rich and detailed information) a problem whenever a crash is detected. In addition, we have published the IIS-Troubleshooting guide. It provides very important information those who are facing problems with the ModSecurity for IIS version.

Testing Platforms

We have updated our continuous integration platform to use ARM. Besides the support for Linux (32 and 64 bits), Windows with different versions of Visual Studio - our Buildbots - can now compile our code inside a BeagleBone Black.


Our BeagleBone black is running Ubuntu 13.10 for ARM with all the developer tools installed, a build with all the regression tests is taking about 16 minutes for Apache and 14 minutes for Nginx. So far our Beagle made 182 builds of a total of 1610 made by all the slaves combined.

Screen Shot 2014-04-15 at 7.38.41 PM

Project Development Metrics

A useful site for analyzing open source projects is Ohlo. There is a bunch useful tools and analysis graphs that show the health of the project. Here is an overview of the ModSecurity project:

Screen Shot 2014-04-15 at 8.25.45 PM

GitHub also provides many interesting project development tools including "Graphs". With Graphs it is possible to figure out project metrics such as: what time of day or day of week does the project receive commits from the community? This question can be answered by reviewing the GitHub ModSecurity punch card.

Screen Shot 2014-04-15 at 7.46.38 PM

The balls diameter represents the amount of commits. The time is represented in the "X" axis and the day of the week on the "Y" axis.

Bug Fixes

In this release, 18 bugs were also fixed. The complete list of bug is listed below:

  • Correctly handling inet_pton in IIS version;
  • Nginx was missing a terminator while the charset string was mounted (Ref: #148);
  • Added mod_extract_forwarded.c to run before mod_security2.c (Ref: #594);
  • Added missing environment variables to regression tests;
  • Build system is now more flexible by looking at liblua at: /usr/local/lib;
  • Fixed typo in README file;
  • Removed the non standard compliant HTTP response status code 44 from modsecurity recommended file (Ref: #665);
  • Fixed segmentation fault if it fails to write on the audit log (Ref: #668);
  • Not rejecting a larger request with ProcessPartial. Regression tests were also added (Ref: #597);
  • Fixed UF8 to unicode conversion. Regression tests were also added (Ref: #672);
  • Avoiding segmentation fault by checking if a structure is null before access its members;
  • Removed double charset-header that used to happen due a hardcoded charset in Nginx implementation (Ref: #650);
  • Now alerting the users that there is no memory to proceed loading the configuration instead of just die;
  • If SecRuleEngine is set to Off and SecRequestBodyAccess On Nginx returns error 500. Standalone is now capable to identify whenever ModSecurity is enabled or disabled, independently of ModSecurity core (Ref: #645);
  • Fixed missing headers on Nginx whenever SecResponseBodyAccess was set to On and happens to be a filter on phase equals or over 3. (Ref #634);
  • IIS is now picking the correct version of AppCmd while uninstalling or installing ModSecurityISS. (Ref#632).

What's next?

Besides new features, for the next release we are aiming to do the following:

  • Solaris and FreeBSD Support on our regression test platform.
  • Better documentation on how to build ModSecurity in different platforms.
  • Documentation on how to contribute to the project including: how to use git, how to request a merge, how to edit and test our code, how to create new regression tests.

Submitted by Felipe Costa and Ryan Barnett

Trustwave reserves the right to review all comments in the discussion below. Please note that for security and other reasons, we may not approve comments containing links.