ModSecurity Trustwave

Developer Information

There are three main ways to extend ModSecurity functionality:

  1. Modify the ModSecurity Source Code
  2. Build Custom ModSecurity Modules
  3. Utilize the Lua API
We will outline all three methods below.

Community Developer Support

Community developer support for ModSecurity is available on the mod-security-developers mailing list. You must subscribe first in order to post. The list archives are available as Developer Archives,

Modify the ModSecurity Source Code

If you are planning to develop ModSecurity code, you should be familiar with the following:

If you would like to directly contribute source code patches/updates to the ModSecurity SVN Source Code Repository, please follow these steps:

  1. Register for an account on the ModSecurity Jira Ticketing System (link on the right-hand colum)
  2. Create a Jira ticket outlining the feature enhancement you are adding
  3. Attach a patch file to the ticket for review by the ModSecurity team
  4. If the patch is added to the source code, you will receive attribution in the CHANGES file

Cloning the SVN Repository

If you would like to test out new features that are available in development releases, just follow these steps to sync with the SourceForge SVN repository:

  1. Create a directory to clone the code: 
    mkdir /path/to/home/svn/modsecurity
cd /path/to/home/svn
  2. Clone the source code:
    SVN: 
    svn co https://mod-security.svn.sourceforge.net/svnroot/mod-security/m2/trunk modsecurity
    GIT: 
    git svn clone --prefix=svn/ https://mod-security.svn.sourceforge.net/svnroot/mod-security/m2/trunk modsecurity

Building Custom ModSecurity Modules

The ModSecurity archive includes some example module extensions in the apache2/api directory.

  • mod_tfn_reverse.c
  • mod_var_remote_addr_port.c
  • mod_op_strstr.c
These examples modules demonstrate how you can extend ModSecurity without having to touch it directly, simply by creating custom Apache modules.

You can also review a community contributed transformation function module from Marc Stern called t:cmdLine. This functionaliy has since been directly integrated into the ModSecurity v2.6 code but this module is a great example of extending ModSecurity using modules.

NOTE: ModSecurity must be compiled with API support to use this feature (do not use -DNO_MODSEC_API).

Building the Example Custom Modules

1) Example custom transformation function module

Module mod_tfn_reverse.c creates a custom transformation function "reverse" that reverses the content it receives on input. 

  # Compile as a normal user
  apxs -ca mod_tfn_reverse.c

  # Install as superuser
  sudo apxs -i mod_tfn_reverse.la
2) Example custom operator module

Module mod_op_strstr.c creates a custom operator "strstr" that implements fast matching using the Boyer-Moore-Horspool algorithm. Compiling this module is more involved because it requires access to ModSecurity structures. 

  # Compile as a normal user
  apxs -I -I/usr/include/libxml2 \
       -ca mod_op_strstr.c

  # Install as superuser
  sudo apxs -i mod_op_strstr.la
3) Example custom target variable module

Module mod_var_remote_addr_port.c creates a custom variable "REMOTE_ADDR_PORT" that combines the REMOTE_ADDR and REMOTE_PORT into a.b.c.d:port format. Compiling this module is more involved because it requires access to ModSecurity structures. 

  # Compile as a normal user
  apxs -I -I/usr/include/libxml2 \
       -ca mod_var_remote_addr_port.c

  # Install as superuser
  sudo apxs -i mod_var_remote_addr_port.la

Using the Modules

Once the modules are built and installed, you load them like any other Apache module, but they must be loaded *after* the mod_security2.so module. 

  # Load ModSecurity
  LoadModule security2_module modules/mod_security2.so

  # Load ModSecurity custom modules
  LoadModule tfn_reverse_module modules/mod_tfn_reverse.so
  LoadModule op_strstr_module modules/mod_op_strstr.so
  LoadModule var_remote_addr_port_module modules/mod_var_remote_addr_port.so

  # All three custom var/op/tfn used
  SecRule REMOTE_ADDR_PORT "@strstr 8765:4.3.2.1" "t:reverse"

Utilize the Lua API

If you find that the standard SecRule rules language is not adequate for your situation, you may look to utilize the Lua API by either using the SecRuleScript directive or by using the exec action with Lua script (.lua extension).

You should read the Lua Reference Manaul documentation.

Here are links to various community use-cases for ModSecurity+Lua:

ModSecurity Status
Stable: 2.6.3 (download)
CRS: 2.2.3 (download)