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

Step 1: Fork the "ModSecurity" Repo

Step 2: Clone Your Fork

$ git clone https://github.com/username/ModSecurity.git

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

# 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

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

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

Include Licensing In File 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

void function(int parm, int error)      {
        /* variable declaration */

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

        }
}

Function Comments

/** \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

#define SOMEDEF 1 

Loops and Similar Constructs

while (condition)	{    
	
}    

for (i = 0; i 

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:

• The Apache Modules book by Nick Kew
• Apache Portable Runtime (APR)
• Apache Portable Runtime Utility (APR-Util)

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

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.

Building the Example Custom Modules

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

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

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:

• Reducing Web Application Attack Surface by SpiderLabs Team
• Implementing AppSensor Detection Points in ModSecurity by SpiderLabs Team
• OWASP Securing Webgoat with ModSecurity Project by Stephen Craig Evans
• OWASP Securing WebGoat with ModSecurity (LuLu Ebook) by Stephen Craig Evans
• Java Floating Point DoS Attack Mitigation by SpiderLabs Team
• Detecting Malice with ModSecurity: IP Forensics by SpiderLabs Team
• ModSecurity Advanced Topic of the Week: Passive Vulnerability Scanning Part 1 - OSVDB Checks by SpiderLabs Team
• ModSecurity Resource Profiling by Josh Zlatin of PureHacking
• Virus Detection in ModSecurity by Josh Zlatin of PureHacking
• Mitigating Password Recovery Weaknesses with ModSecurity and Lua by Josh Zlatin of PureHacking
• Protecting Hidden Fields with ModSecurity.