doc/migration-matrix.html

   1 <html><head>
   2       <meta http-equiv="Content-Type" content="text/html; charset=ISO-8859-1">
   3    <title>ModSecurity Migration Matrix</title><link rel="stylesheet" href="html.css" type="text/css"><meta name="generator" content="DocBook XSL Stylesheets V1.70.1"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="d0e1"></a>ModSecurity Migration Matrix</h2></div><div><p class="releaseinfo">Version 1.0 / (April 10, 2007)</p></div><div><p class="copyright">Copyright &copy; 2004-2007 Breach Security, Inc. (<a href="http://www.breach.com" target="_top">http://www.breach.com</a>)</p></div></div><hr></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="01-introduction"></a>Migration from 1.x to 2.x</h2></div></div></div><div class="section" lang="en"><div class="titlepage"></div><p>If you are already using an older version of ModSecurity and want to upgrade/migrate your existing custom rules, you will need to ensure that you properly translate all of your Directives to their corresponding 2.0 counterparts.  Some directives have simply changed names, however some directives actually behave differently so it is important that you also review the entire 2.0 Reference Manual.
   4 The migration matrix show below should help you to translate ModSecurity 1.X directives to the 2.0 values.  There are also some notes that provide additional information is a directive significantly changed how it operates.
   5 </p><table border="1" id="d0e21"><tr><td><span class="bold"><strong>Feature/Capability</strong></span></td><td><span class="bold"><strong>ModSecurity 1.x</strong></span></td><td><span class="bold"><strong>ModSecurity 2.x</strong></span></td><td><span class="bold"><strong>Notes</strong></span></td><td><span class="bold"><strong>How To Upgrade</strong></span></td></tr><tr><td><span class="bold"><strong>Apache Version Supported</strong></span></td><td>Apache 1.x/2.x</td><td>Apache 2.x Only</td><td>ModSecurity 2.0 will only work with Apache 2.x and not the older 1.3 version.</td><td>If you are mainly an Apache 1.3 shop and/or you have other web servers that you want to protect (such as IIS) an alternative solution is to deploy an Apache 2.x reverse proxy server and implement ModSecurity 2.x on it.</td></tr><tr><td><span class="bold"><strong>Installation</strong></span></td><td>Can be installed as either a DSO module or as a statically compiled module.</td><td>Can currently only be installed as a DSO module.</td><td>In 1.x, you could use apxs directly, while in 2.x you must use the provided Makefile.</td><td>If you can not use DSOs in your current Apache configs, you may look at implementing a front-end Apache reverse proxy server.</td></tr><tr><td><span class="bold"><strong>Configuration - IfModule</strong></span></td><td>Apache 1.x - &lt;IfModule mod_security.c&gt;
   6
   7 Apache 2.x - &lt;IfModule security_module&gt;</td><td>&lt;IfModule security2_module&gt;</td><td>The syntax of using IfModule has changed between Apache 1.x and 2.x</td><td>Make sure that any existing &lt;IfModule&gt; directives uses the correct syntax.</td></tr><tr><td><span class="bold"><strong>Processing Phases Supported</strong></span></td><td>2</td><td>5</td><td>ModSecurity 1.x supports:<div class="itemizedlist"><ul type="disc"><li><p>Inbound - which corresponds to current Mod 2.x Request Body phase and the Apache &#8220;fixups&#8221; phase.</p></li><li><p>Outbound - which corresponds to current Mod 2.x Response Body phase and just after the Apache &#8220;response&#8221; processing phase.</p></li></ul></div>ModSecurity 2.x supports: <div class="itemizedlist"><ul type="disc"><li><p>Request Headers &#8211; which corresponds with the Apache &#8220;post-read-request&#8221; phase.</p></li><li><p>Request Body &#8211; which corresponds with the Apache &#8220;fixups&#8221; phase.</p></li><li><p>Response Headers &#8211; which corresponds to the Apache &#8220;response&#8221; phase.</p></li><li><p>Response Body &#8211; which corresponds to just after the Apache &#8220;response&#8221; phase.</p></li><li><p>Logging - which is the Apache logging phase.</p></li></ul></div></td><td>If you are translating existing 1.x rules (SecFilter/SecFilterSelective) then you should use phase:2 in the new rule syntax.  Translate existing OUTPUT rules to run in phase:4.</td></tr><tr><td><span class="bold"><strong>Directive to turn On/Off the Rule Engine</strong></span></td><td>SecFilterEngine</td><td>SecRuleEngine
   8 ctl:ruleEngine=</td><td><div class="itemizedlist"><ul type="disc"><li><p>1.x &#8211; values were On, Off and DynamicOnly and was a Global directive.</p></li><li><p>2.x - values are On, Off or DetectionOnly.</p></li><li><p>2.x &#8211; the &#8220;ctl&#8221; action can control the RuleEngine dynamically for individual requests.</p></li></ul></div></td><td>Replace SecFilterEngine with SecRuleEngine. The DynamicOnly mode is not supported in ModSecurity 2.x because it was sometimes difficult for ModSecurity to determine if a particular request was dynamic in nature or not.  Use of AddType vs. AddHandler would cause problems.  Since this logic relies on the internal (and not entirely documented) workings of Apache and on the chosen configuration it also makes it somewhat unpredictable.</td></tr><tr><td><span class="bold"><strong>Directive to handle the Audit Engine</strong></span></td><td>SecAuditEngine On, Off, RelevantOnly, DynamicOrRelevant</td><td>SecAuditEngine On, Off, RelevantOnly</td><td>In 2.x, the DynamicOrRelevant option was discontinued.</td><td>If you are using DynamicOrRelevant then switch it to RelevantOnly.</td></tr><tr><td><span class="bold"><strong>Default Rule Action</strong></span></td><td>SecFilterDefaultAction</td><td>SecDefaultAction</td><td><div class="itemizedlist"><ul type="disc"><li><p>1.x &#8211; SecFilterDefaultAction could be used anywhere in the config and it would be picked up by all rules.</p></li><li><p>2.x &#8211; SecDefaultAction must come before rules and be specified in each context.  The default setting for this directive (if it is not specified otherwise) is &#8211;
   9 <code class="literal">SecDefaultAction phase:2,log,deny,status:403,\</code></p><p><code class="literal">t:lowercase,t:replaceNulls,\</code></p><p><code class="literal">t:compressWhitespace</code></p></li></ul></div></td><td>Replace SecFilterDefaultAction with SecDefaultAction.  Optionally, you can group rules together where you would like to use the same action and then specify a SecDefaultAction line before each group.
  10
  11 Also keep in mind that while most actions specified on individual rules will supersede those specified in SecDefaultAction, transformation functions are additive.  So, if you specify a &#8220;t:base64Decode&#8221; transformation function to a rule, it will be added after the lowercase, replaceNulls and compressWhitespace transformation functions.</td></tr><tr><td><span class="bold"><strong>Debug Logging</strong></span></td><td>SecFilterDebugLog
  12 SecFilterDebugLogLevel</td><td>SecDebugLog
  13 SecDebugLogLevel</td><td>Name change only.</td><td>Change the names of these directives to their 2.x counterparts.</td></tr><tr><td><span class="bold"><strong>Rule Directive(s)</strong></span></td><td>SecFilter
  14 SecFilterSelective</td><td>SecRule</td><td><div class="itemizedlist"><ul type="disc"><li><p>In Mod 1.x, SecFilter and SecFilterSelective were case insensitive. </p></li><li><p>In Mod 2.x, the case of data is not altered unless the lowercase transformation funce is used.
  15 SecRule has essentially the same rule syntax as SecFilterSelective.</p></li></ul></div></td><td>Replace SecFilterSelective with SecRule and make sure to translate the variable tested according to this list.
  16 Replace any SecFilter with a new SecRule directive.  You will need to specify a new Variable location and a phase.  You can optionally specify a disruptive action, otherwise it will be inherited from a previous SecDefaultAction.
  17 </td></tr><tr><td><span class="bold"><strong>Rule Exceptions</strong></span></td><td>Whitelist approach &#8211; use pass, allow actions
  18 False Positive Approach &#8211; use SecFilterRemove</td><td>Whitelist approach &#8211; use pass, allow and ctl actions.
  19 False Positive Approach &#8211; use SecRuleRemoveById and Apache Scope context</td><td>In Mod 2.x, using the &#8220;allow&#8221; action may not be enough to truly let a request through as &#8220;allow&#8221; only applies to the current processing phase.  This means that rules in subsequent phases may act on the request.  This is why you need to also use the &#8220;ctl:ruleEngine=Off&#8221; action if you really want to let a request through.</td><td>See Blog post on handling false positives and creating custom rules - http://www.modsecurity.org/blog/archives/2007/02/handling_false.html</td></tr><tr><td><span class="bold"><strong>Directive to control rule inheritance to Apache Scope locations (Virtual Hosts, Location, Directory)</strong></span></td><td>SecFilterInheritance</td><td>SecRuleInheritance</td><td>The best use of this directive is when you want to start with a &#8220;clean slate&#8221; so you can use SecRuleInheritance Off and then specify your new rule sets.
  20 Note &#8211; Rule Inheritance does not work across Apache Scope directives (such as Vhosts, Location and Directory directives).  This means that you can not use SecRuleInheritance On to inherit a SecDefaultAction directive within these new contexts.  This is an issue with the way that Apache inherits contexts.  It is for this reason that we recommend that you specify new SecDefaultAction directives within each Apache scope location that you create.</td><td>Translate any existing &#8220;SecFilterInheritance Off&#8221; rules directly to &#8220;SecRuleInheritance Off&#8221;.
  21 Then replace any &#8220;SecFilterInheritance On&#8221; directives inside Apache Scope context locations with a new SecDefaultAction directive and then import the rules that you want with standard Apache Include directives.</td></tr><tr><td><span class="bold"><strong>Ability to manage rules in Apache Scope locations</strong></span></td><td>SecFilterImport
  22 SecFilterRemove</td><td>SecRuleRemoveById
  23 SecRuleRemoveByMsg</td><td>SecFilterRemove is now SecRuleRemoveById or SecRuleRemoveByMsg.  SecFilterImport is no longer supported.</td><td>Change all of your existing SecFilterRemove rules to SecRuleRemoveById.  For any existing SecFilterImport rules, you will need to either copy the rule into the context or use an Apache Include Directive to include entire files (such as including the Core Rules files).</td></tr><tr><td><span class="bold"><strong>Ability to verify URL/UTF8 Encodings</strong></span></td><td>SecFilterCheckURLEncoding
  24 SecFilterCheckUnicodeEncoding </td><td>@validateUrlEncoding
  25 @validateUtf8Encoding </td><td>In Mod 1.x, these were Global Directives and in Mod 2.x they are Operators that can be applied selectively to each rule.</td><td>Add the rules that will do exactly the same as the directives</td></tr><tr><td><span class="bold"><strong>Ability to enforce a Byte Range (allowed character set)</strong></span></td><td>SecFilterForceByteRange</td><td>@validateByteRange</td><td>In Mod 1.x, this was a Global Directive and in Mod 2.x it is an Operator that can be applied selectively to each rule.
  26 In Mod 1.x, this directive did not check POST payloads when multipart/form-data encoding was used.</td><td>You can now add @validateByteRange operators to individual rules.  This helps if you have differences in allowed character sets for different portions of the web application.</td></tr><tr><td><span class="bold"><strong>Ability to Normalize/Transform Request Data</strong></span></td><td>ModSecurity 1.x automatically applied the following transformations:<div class="itemizedlist"><ul type="disc"><li><p>On Windows only, convert \ to /</p></li><li><p>Reduce /./ to /</p></li><li><p>Reduce // to /</p></li><li><p>Decode URL-encoded characters</p></li><li><p>Converts Null Bytes to Space character</p></li></ul></div></td><td><div class="itemizedlist"><ul type="disc"><li><p>base64Decode </p></li><li><p>base64Encode</p></li><li><p>compressWhitespace</p></li><li><p>escapeSeqDecode</p></li><li><p>hexDecode</p></li><li><p>hexEncode</p></li><li><p>htmlEntityDecode</p></li><li><p>lowercase</p></li><li><p>md5</p></li><li><p>none</p></li><li><p>normalisePath</p></li><li><p>normalisePathWin</p></li><li><p>removeNulls</p></li><li><p>removeWhitespace</p></li><li><p>replaceComments</p></li><li><p>replaceNulls</p></li><li><p>urlDecode</p></li><li><p>urlDecodeUni</p></li><li><p>urlEncode</p></li><li><p>sha1</p></li></ul></div></td><td>In Mod 1.x, the normalization functions were implicit and you could not control them.  In Mod 2.x, not normalization is done by default.  There are now &#8220;Transformation Functions&#8221; that allow you to selectively apply normalizations and other features.</td><td>You should add the appropriate transformation functions to either SecDefaultAction directive or each individual rule.  See the Core Rules files for examples.
  27 Keep in mind that transformation functions are inherited from parent SecDefaultAction directives.  Care should be taken to ensure that RegEx patterns match the data after transformation functions are applied.  In order to avoid possible unwanted inherited transformation functions, use &#8220;t:none&#8221; to either not apply any transformation functions or you can then specify specific transformation functions after &#8220;t:none&#8221;.</td></tr><tr><td><span class="bold"><strong>Ability to specify an arbitrary Request Header in a rule</strong></span></td><td>HEADER_headername
  28 HTTP_headername</td><td>REQUEST_HEADERS REQUEST_HEADERS:headername
  29 REQUEST_HEADERS:/RegEx/</td><td>The HTTP_headername syntax has been superseded by the new REQUEST_HEADERS:headername syntax and will not be supported in future releases.  The advantage to using the new syntax is that you can also use RegEx in the headername portion.</td><td>Translate any existing HTTP_headername directives to REQUEST_HEADERS:headername.  Also consider consolidating header checks by using Regular Expressions in the header name portion of the Variable.</td></tr><tr><td><span class="bold"><strong>Variable/Location for the entire URL Request Line</strong></span></td><td>THE_REQUEST</td><td>REQUEST_LINE</td><td>Functions the same.  The variable includes the Request Method, URI and HTTP version data.</td><td>Translate any existing THE_REQUEST directives to REQUEST_LINE directives.</td></tr><tr><td><span class="bold"><strong>Variable/Location for Arguments</strong></span></td><td>ARG_name</td><td>ARGS:name
  30 ARGS:/RegEx/</td><td>Similar to the HTTP_headername situation, the advantage of the new syntax is the ability to use RegEx in the argument name.</td><td>Translate any existing ARG_name directives to ARGS:name directives.</td></tr><tr><td><span class="bold"><strong>Accessing Request Bodies</strong></span></td><td>SecFilterScanPOST
  31 POST_PAYLOAD</td><td>SecRequestBodyAccess
  32 Phase:2
  33 REQUEST_BODY</td><td>In 2.x, the directive is now called SecRequestBodyAccess and it is more flexible than SecFilterScanPOST as it is able to inspect all request bodies (such as PUT and XML, etc&#8230;) and not just POST payloads.</td><td>Replace the existing SecFilterScanPOST directive with SecRequestBodyAccess.
  34 For individual rules where you want to inspect the request bodies, you must specify REQUEST_BODY as the variable and you also must ensure that it is running in phase:2 (by either an inherited SecDefaultAction setting or by explicitly specifying the phase within the rule action).</td></tr><tr><td><span class="bold"><strong>Ability to disable POST/Request buffering dynamically</strong></span></td><td>MODSEC_NOPOSTBUFFERING</td><td>ctl:requestBodyAccess=Off</td><td>In 2.x, you can use the ctl action to turn on/off request body access on a per rule basis.</td><td>Take any existing entries in the httpd.conf file that set the MODSEC_NOPOSTBUFFERING Env variable and translate them to Mod 2.x rules.</td></tr><tr><td><span class="bold"><strong>Accessing Cookies</strong></span></td><td>COOKIES
  35 COOKIES_COUNT
  36 COOKIES_NAMES
  37 COOKIES_VALUES
  38 COOKIE_name</td><td>REQUEST_HEADERS:Cookie
  39 REQUEST_COOKIES_NAMES REQUEST_COOKIES_NAMES:name
  40 REQUEST_COOKIES_NAMES:/RegEx/
  41 REQUEST_COOKIES
  42 REQUEST_COOKIES:name REQUEST_COOKIES:/RegEx/</td><td> In 2.x, you can use the &#8220;&amp;&#8221; character to &#8220;count&#8221; the number of variables.
  43 While there are different ways to access request cookies, the main difference between them are that REQUEST_HEADERS:Cookie will include all of the &#8220;raw&#8221; Cookie data while any of the REQUEST_COOKIES variable values are parsed.</td><td>Translate rules as follows &#8211;
  44 Mod 1.x -&gt; Mod 2.x
  45 COOKIES -&gt; REQUEST_COOKIES
  46 COOKIES_COUNT -&gt; &amp;REQUEST_COOKIES
  47 COOKIES_NAMES -&gt; REQUEST_COOKIES_NAMES COOKIES_VALUES -&gt; REQUEST_COOKIES
  48 COOKIE_name -&gt; REQUEST_COOKIES:name</td></tr><tr><td><span class="bold"><strong>Counting Variables</strong></span></td><td>ARGS_COUNT
  49 COOKIES_COUNT
  50 HEADERS_COUNT
  51 FILES_COUNT</td><td>&amp;ARGS
  52 &amp;REQUEST_COOKIES &amp;REQUEST_HEADERS
  53 &amp;FILES</td><td>In 2.x, prepending the &#8220;&amp;&#8221; character will count the number of variables.  Example &#8211;
  54 1.x &#8211; HEADERS_COUNT
  55 2.x - &amp;REQUEST_HEADERS</td><td>Translate existing 1.x rules as listed.</td></tr><tr><td><span class="bold"><strong>Accessing HTTP Status Code</strong></span></td><td>OUTPUT_STATUS</td><td>RESPONSE_STATUS
  56 Phase:3</td><td>In 2.x, you need to specify both the RESPONSE_STATUS variable and phase:3 with the rule.</td><td>Translate any existing 1.x OUTPUT STATUS rules to use RESPONSE_STATUS and phase:3.</td></tr><tr><td><span class="bold"><strong>Accessing Response Bodies/Post Payloads</strong></span></td><td>SecFilterScanOutput
  57 SecFilterOutputMimeTypes
  58 OUTPUT</td><td>SecResponseBodyAccess
  59 SecResponseBodyMimeTypes
  60 RESPONSE_BODY
  61 Phase:4</td><td>In 1.x, neither skipnext nor chain could be used on the OUTPUT location.
  62 In 2.x, both actions can be used on RESPONSE_BODY</td><td>Translate directives/rules as follows &#8211;
  63 Mod 1.x -&gt; Mod 2.x
  64 SecFilterScanOutput -&gt; SecResponseBodyAccess
  65 SecFilterOutputMimeTypes -&gt; SecResponseBodyMimeTypes
  66 OUTPUT -&gt; RESPONSE_BODY/Phase:4</td></tr><tr><td><span class="bold"><strong>Cookie Normalization</strong></span></td><td>SecFilterCookieFormat
  67 SecFilterNormalizeCookies</td><td>SecCookieFormat</td><td>SecFilterNormalizeCookies is no longer supported as Mod 2.x transformation functions can now be used to normalize all Variables including Cookie data.</td><td>Change SecFilterCookieFormat to SecCookieFormat.
  68 When specifying Cookie variables, then apply the applicable transformation functions in the action field of the rule.</td></tr><tr><td><span class="bold"><strong>Ability to skip rules</strong></span></td><td>skipnext</td><td>skip</td><td>In Mod 2.x &#8211; skip takes into account chained rulesets and treats them as 1 rule.
  69 In Mod 1.x &#8211; skipnext treated each rule directive as an individual rule regardless of whether or not they were tied together as a chained ruleset.</td><td>Translate all skipnext rules to skip, however make sure to factor in any chained rulesets that may follow and adjust the skip number accordingly.</td></tr><tr><td><span class="bold"><strong>Adding/Removing Audit Log Data on a per rule basis</strong></span></td><td>logparts</td><td>clt:auditLogParts=</td><td>The rules function the same.</td><td>Translate any existing logparts actions to the ctl:auditLogParts equivalent.</td></tr><tr><td><span class="bold"><strong>Inspecting uploaded files</strong></span></td><td>SecUploadApproveScript</td><td>@inspectFile
  70 FILES_TMPNAMES</td><td>The main difference here is that now @inspectFile is an Operator vs. a global Directive.  This means that you can apply @inspectFile to individual rules and use different scripts as appropriate.
  71 Also, the return codes are now reversed &#8211;
  72 In 1.x, a return code of &#8220;1&#8221; means that the file would be allowed.
  73 In 2.x, a return code of &#8220;1&#8221; means that the file would be denied. </td><td>In order to scan/inspect uploaded files in 2.x, you need to create specific rules that use the FILES_TMPNAMES variable (as these are the names of the files that are temporarily stored on disk) and then use the @inspectFile Operator on each rule.
  74 Also, make sure to swap your return codes in existing scripts as mentioned in the notes column.</td></tr><tr><td><span class="bold"><strong>Memory limits for uploaded files</strong></span></td><td>SecUploadInMemoryLimit</td><td>SecRequestBodyInMemoryLimit</td><td>These two directives function the same.</td><td>Change the SecUploadInMemoryLimit directive to SecRequestBodyInMemoryLimit.</td></tr></table></div></div></div></body></html>