apache2/api/README

   1 Custom ModSecurity Modules
   2 --------------------------
   3
   4 This directory contains three examples how you can extend
   5 ModSecurity without having to touch it directly, simply
   6 by creating custom Apache modules.
   7
   8 NOTE: ModSecurity must be compiled with API support
   9       to use this feature (do not use -DNO_MODSEC_API).
  10
  11
  12 Building the Example Custom Modules
  13 -----------------------------------
  14
  15 1) Example custom transformation function module
  16
  17 Module mod_tfn_reverse.c creates a custom transformation
  18 function "reverse" that reverses the content it receives
  19 on input.
  20
  21   # Compile as a normal user
  22   apxs -ca mod_tfn_reverse.c
  23
  24   # Install as superuser
  25   sudo apxs -i mod_tfn_reverse.la
  26
  27
  28 2) Example custom operator module
  29
  30 Module mod_op_strstr.c creates a custom operator "strstr"
  31 that implements fast matching using the Boyer-Moore-Horspool
  32 algorithm.
  33
  34 Compiling this module is more involved because it requires
  35 access to ModSecurity structures.
  36
  37   # Compile as a normal user
  38   apxs -I<MODSECURITY_SOURCE_CODE> -I/usr/include/libxml2 \
  39        -ca mod_op_strstr.c
  40
  41   # Install as superuser
  42   sudo apxs -i mod_op_strstr.la
  43
  44
  45 3) Example custom target variable module
  46
  47 Module mod_var_remote_addr_port.c creates a custom variable "REMOTE_ADDR_PORT"
  48 that combines the REMOTE_ADDR and REMOTE_PORT into a.b.c.d:port format.
  49
  50 Compiling this module is more involved because it requires
  51 access to ModSecurity structures.
  52
  53   # Compile as a normal user
  54   apxs -I<MODSECURITY_SOURCE_CODE> -I/usr/include/libxml2 \
  55        -ca mod_var_remote_addr_port.c
  56
  57   # Install as superuser
  58   sudo apxs -i mod_var_remote_addr_port.la
  59
  60
  61 Using the Modules
  62 -----------------
  63
  64 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.
  65
  66   # Load ModSecurity
  67   LoadModule security2_module modules/mod_security2.so
  68
  69   # Load ModSecurity custom modules
  70   LoadModule tfn_reverse_module modules/mod_tfn_reverse.so
  71   LoadModule op_strstr_module modules/mod_op_strstr.so
  72   LoadModule var_remote_addr_port_module modules/mod_var_remote_addr_port.so
  73
  74   # All three custom var/op/tfn used
  75   SecRule REMOTE_ADDR_PORT "@strstr 1.2.3.4:5678" "t:reverse"
  76