README

Custom ModSecurity Modules
--------------------------

This directory contains three examples how you can extend
ModSecurity without having to touch it directly, simply
by creating custom Apache modules.

NOTE: ModSecurity must be compiled with API support
      to use this feature (the API is enabled by default,
      but it will have been disabled if you used -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 -I<MODSECURITY_SOURCE_CODE> -I/usr/include/libxml2 \
       -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.

  # Compile as a normal user
  apxs -I<MODSECURITY_SOURCE_CODE> -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.

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

  # Install as superuser
  sudo apxs -i mod_var_remote_addr_port.la


3) Example custom request body parser module

Module mod_reqbody_example.c creates a custom request body parser named
"EXAMPLE".  It does noting in particular, but shows the basic structure
of such a module.

  # Compile as a normal user
  apxs -I<MODSECURITY_SOURCE_CODE> -I/usr/include/libxml2 \
       -ca mod_reqbody_example.c

  # Install as superuser
  sudo apxs -i mod_var_remote_addr_port.la

  # Write a phase 1 rule to set the parser
  SecAction "phase:1,pass,nolog,ctl:requestBodyProcessor=EXAMPLE"


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 1.2.3.4:5678" "t:reverse"