ModSecurity Trustwave

Developer Information

  1. Contributing to the ModSecurity Project
  2. Code Writing Style Guidelines
  3. Modify the ModSecurity Source Code
  4. Build Custom ModSecurity Modules
  5. Utilize the Lua API

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,

Contributing to the ModSecurity Project

The ModSecurity source code is hosted on GitHub. Please follow these steps to contribute code updates to project.

Step 1: Fork the "ModSecurity" Repo

After logging into your GitHub account, browse to the ModSecurity Git Repo page and click the "Fork" button. This creates the fork of the repo under your own GitHub account username.

Step 2: Clone Your Fork

You've successfully forked the ModSecurity repo, but so far it only exists on GitHub. To be able to work on the project, you will need to clone it to your local machine. Run the following code:
$ git clone https://github.com/username/ModSecurity.git
Make sure to change username to your actual GitHub username. This command Clones your fork of the repo into the current directory in terminal on your computer.

Step 3: Checkout to trunk and make changes

# Changes the active directory in the prompt to the newly cloned "ModSecurity" directory
$ cd ModSecurity

# Checkout trunk
$ git checkout remotes/trunk

# Make any changes you want in the code.

Step 4: Create and Push Commits

Once you've made some commits to a forked repo and want to push it to your forked project, you do it the same way you would with a regular repo:
# Make some changes and Commits
$ git commit -a -m "My changes"

# Pushes commits to your remote repo stored on GitHub
$ git push origin remotes/trunk 

Step 5: Issue Pull Requests

If you are hoping to contribute back to the original fork, you can send the ModSecurity Team a pull request. Make sure you send Pull requests to remotes/trunk. Make sure base and head options are correct:
base repo: SpiderLabs/ModSecurity   base branch: remotes/trunk
head repo: Username/ModSecurity     head branch: remotes/trunk

Code Writing Style Guidelines

In order to help with code maintenance and readability, please follow these guidelines.

Recommended Vi Editor Settings

ModSecurity used the follow code style and for code indentation please use the follow vi configuration:
syntax on
set tabstop=4
set shiftwidth=4
set expandtab
set modeline
set list
set listchars=tab:»·,trail:@
au BufNewFile,BufRead *.cu set ft=cu
let g:load_doxygen_syntax=

Line Length

Should be 80 characater limit as much as possible

Include Licensing In File Header

Each ModSecurity source code file must contains the license notice in the header:
/*
* ModSecurity for Apache 2.x, http://www.modsecurity.org/
* Copyright (c) 2004-2013 Trustwave Holdings, Inc. (http://www.trustwave.com/)
*
* You may not use this file except in compliance with
* the License.  You may obtain a copy of the License at
*
*     http://www.apache.org/licenses/LICENSE-2.0
*
* If any of the files related to licensing are missing or if you have any
* other questions related to licensing please contact Trustwave Holdings, Inc.
* directly using the email address security@modsecurity.org.
*/

Function Definitions

Should be formatted like this:
void function(int parm, int error)      {
        /* variable declaration */

        if(error == 0)  {       /* shouldn’t be if (error) or if(!error)

        }
}

Function Comments

All functions must contains the follow comment style before it:
/** \brief This is a test functions
 *
 * \param parm User defined option
 * \param error The return error code
 *
 * \retval 1 On Success
 * \retval error On Fail
 */
int function(int parm, int error)      {
 
        if(parm == -1)
                return error;

        return 1
} 

Macro Definitions

All macro definitions should be uppercase:
#define SOMEDEF 1 

Loops and Similar Constructs

Please use the following style for the looping constructs:
while (condition)	{    
	
}    

for (i = 0; i < 10; i++) {       
	statement1;     
	statement2;   
}    

if (condition) {       
	statement1;
	statement2;
}    
If the "if" has a single statement, you can avoid the { } :
if (condition)
	statement1;    
But in the above "if", if the condition crosses multiple lines, please use { } even if the "if" block has a single statement in its block:
if (function() == 0 ||
	function1() == 1) {       
	statement1;   
}    
The same applies for "for" and "while".
switch (condition):       
	case x:            
	break;        
	case y:            
	break;   
}    
For if, else if, else, if the body of the if, else if, needs more than one physical line, if, else if, else should be wrapped in { }: For example:
if (condition)       
	printf("A\n");   
else       
	printf("B\n");    

if (condition) {       
	printf("A\n");   
} else {       
	printf("B\n");       
	printf("C\n");   
}

Modify the ModSecurity Source Code

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

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 Manual documentation.

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

ModSecurity Stable (v2.8.0)
Apache/Nginx: download (sha256)
IIS: 32b (sha256) | 64b (sha256)
Last development build status

Other builds...