<?xml version="1.0" encoding="UTF-8"?>
<article>
  <title>ModSecurity Migration Matrix</title>

  <articleinfo>
    <releaseinfo>Version 1.0 / (April 10, 2007)</releaseinfo>

    <copyright>
      <year>2004-2010</year>

      <holder>Breach Security, Inc. (<ulink
      url="http://www.breach.com">http://www.breach.com</ulink>)</holder>
    </copyright>
  </articleinfo>

  <section id="01-introduction">
    <title>Migration from 1.x to 2.x</title>

    <section>
      <para>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. 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. </para>

      <table border="1">
        <tr>
          <td>
            <emphasis role="bold">Feature/Capability</emphasis>
          </td>

          <td>
            <emphasis role="bold">ModSecurity 1.x</emphasis>
          </td>

          <td>
            <emphasis role="bold">ModSecurity 2.x</emphasis>
          </td>

          <td>
            <emphasis role="bold">Notes</emphasis>
          </td>

          <td>
            <emphasis role="bold">How To Upgrade</emphasis>
          </td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Apache Version Supported</emphasis>
          </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>
            <emphasis role="bold">Installation</emphasis>
          </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>
            <emphasis role="bold">Configuration - IfModule</emphasis>
          </td>

          <td>Apache 1.x - &lt;IfModule mod_security.c&gt; 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>
            <emphasis role="bold">Processing Phases Supported</emphasis>
          </td>

          <td>2</td>

          <td>5</td>

          <td>ModSecurity 1.x supports:<itemizedlist>
              <listitem>
                <para>Inbound - which corresponds to current Mod 2.x Request
                Body phase and the Apache “fixups” phase.</para>
              </listitem>

              <listitem>
                <para>Outbound - which corresponds to current Mod 2.x Response
                Body phase and just after the Apache “response” processing
                phase.</para>
              </listitem>
            </itemizedlist>ModSecurity 2.x supports: <itemizedlist>
              <listitem>
                <para>Request Headers – which corresponds with the Apache
                “post-read-request” phase.</para>
              </listitem>

              <listitem>
                <para>Request Body – which corresponds with the Apache
                “fixups” phase.</para>
              </listitem>

              <listitem>
                <para>Response Headers – which corresponds to the Apache
                “response” phase.</para>
              </listitem>

              <listitem>
                <para>Response Body – which corresponds to just after the
                Apache “response” phase.</para>
              </listitem>

              <listitem>
                <para>Logging - which is the Apache logging phase.</para>
              </listitem>
            </itemizedlist></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>
            <emphasis role="bold">Directive to turn On/Off the Rule
            Engine</emphasis>
          </td>

          <td>SecFilterEngine</td>

          <td>SecRuleEngine ctl:ruleEngine=</td>

          <td>
            <itemizedlist>
              <listitem>
                <para>1.x – values were On, Off and DynamicOnly and was a
                Global directive.</para>
              </listitem>

              <listitem>
                <para>2.x - values are On, Off or DetectionOnly.</para>
              </listitem>

              <listitem>
                <para>2.x – the “ctl” action can control the RuleEngine
                dynamically for individual requests.</para>
              </listitem>
            </itemizedlist>

            
          </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>
            <emphasis role="bold">Directive to handle the Audit
            Engine</emphasis>
          </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>
            <emphasis role="bold">Default Rule Action</emphasis>
          </td>

          <td>SecFilterDefaultAction</td>

          <td>SecDefaultAction</td>

          <td>
            <itemizedlist>
              <listitem>
                <para>1.x – SecFilterDefaultAction could be used anywhere in
                the config and it would be picked up by all rules.</para>
              </listitem>

              <listitem>
                <para>2.x – SecDefaultAction must come before rules and be
                specified in each context. The default setting for this
                directive (if it is not specified otherwise) is –
                <literal>SecDefaultAction
                phase:2,log,deny,status:403,\</literal></para>

                <para>
                  <literal>t:lowercase,t:replaceNulls,\</literal>
                </para>

                <para>
                  <literal>t:compressWhitespace</literal>
                </para>
              </listitem>
            </itemizedlist>

            
          </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. 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
          “t:base64Decode” transformation function to a rule, it will be added
          after the lowercase, replaceNulls and compressWhitespace
          transformation functions.</td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Debug Logging</emphasis>
          </td>

          <td>SecFilterDebugLog SecFilterDebugLogLevel</td>

          <td>SecDebugLog SecDebugLogLevel</td>

          <td>Name change only.</td>

          <td>Change the names of these directives to their 2.x
          counterparts.</td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Rule Directive(s)</emphasis>
          </td>

          <td>SecFilter SecFilterSelective</td>

          <td>SecRule</td>

          <td>
            <itemizedlist>
              <listitem>
                <para>In Mod 1.x, SecFilter and SecFilterSelective were case
                insensitive. </para>
              </listitem>

              <listitem>
                <para>In Mod 2.x, the case of data is not altered unless the
                lowercase transformation funce is used. SecRule has
                essentially the same rule syntax as SecFilterSelective.</para>
              </listitem>
            </itemizedlist>
          </td>

          <td>Replace SecFilterSelective with SecRule and make sure to
          translate the variable tested according to this list. 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. </td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Rule Exceptions</emphasis>
          </td>

          <td>Whitelist approach – use pass, allow actions False Positive
          Approach – use SecFilterRemove</td>

          <td>Whitelist approach – use pass, allow and ctl actions. False
          Positive Approach – use SecRuleRemoveById and Apache Scope
          context</td>

          <td>In Mod 2.x, using the “allow” action may not be enough to truly
          let a request through as “allow” 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
          “ctl:ruleEngine=Off” 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>
            <emphasis role="bold">Directive to control rule inheritance to
            Apache Scope locations (Virtual Hosts, Location,
            Directory)</emphasis>
          </td>

          <td>SecFilterInheritance</td>

          <td>SecRuleInheritance</td>

          <td>The best use of this directive is when you want to start with a
          “clean slate” so you can use SecRuleInheritance Off and then specify
          your new rule sets. Note – 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 “SecFilterInheritance Off” rules directly
          to “SecRuleInheritance Off”. Then replace any “SecFilterInheritance
          On” 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>
            <emphasis role="bold">Ability to manage rules in Apache Scope
            locations</emphasis>
          </td>

          <td>SecFilterImport SecFilterRemove</td>

          <td>SecRuleRemoveById 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>
            <emphasis role="bold">Ability to verify URL/UTF8
            Encodings</emphasis>
          </td>

          <td>SecFilterCheckURLEncoding SecFilterCheckUnicodeEncoding </td>

          <td>@validateUrlEncoding @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>
            <emphasis role="bold">Ability to enforce a Byte Range (allowed
            character set)</emphasis>
          </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. 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>
            <emphasis role="bold">Ability to Normalize/Transform Request
            Data</emphasis>
          </td>

          <td>ModSecurity 1.x automatically applied the following
          transformations:<itemizedlist>
              <listitem>
                <para>On Windows only, convert \ to /</para>
              </listitem>

              <listitem>
                <para>Reduce /./ to /</para>
              </listitem>

              <listitem>
                <para>Reduce // to /</para>
              </listitem>

              <listitem>
                <para>Decode URL-encoded characters</para>
              </listitem>

              <listitem>
                <para>Converts Null Bytes to Space character</para>
              </listitem>
            </itemizedlist></td>

          <td>
            <itemizedlist>
              <listitem>
                <para>base64Decode </para>
              </listitem>

              <listitem>
                <para>base64Encode</para>
              </listitem>

              <listitem>
                <para>compressWhitespace</para>
              </listitem>

              <listitem>
                <para>escapeSeqDecode</para>
              </listitem>

              <listitem>
                <para>hexDecode</para>
              </listitem>

              <listitem>
                <para>hexEncode</para>
              </listitem>

              <listitem>
                <para>htmlEntityDecode</para>
              </listitem>

              <listitem>
                <para>lowercase</para>
              </listitem>

              <listitem>
                <para>md5</para>
              </listitem>

              <listitem>
                <para>none</para>
              </listitem>

              <listitem>
                <para>normalisePath</para>
              </listitem>

              <listitem>
                <para>normalisePathWin</para>
              </listitem>

              <listitem>
                <para>removeNulls</para>
              </listitem>

              <listitem>
                <para>removeWhitespace</para>
              </listitem>

              <listitem>
                <para>replaceComments</para>
              </listitem>

              <listitem>
                <para>replaceNulls</para>
              </listitem>

              <listitem>
                <para>urlDecode</para>
              </listitem>

              <listitem>
                <para>urlDecodeUni</para>
              </listitem>

              <listitem>
                <para>urlEncode</para>
              </listitem>

              <listitem>
                <para>sha1</para>
              </listitem>
            </itemizedlist>

            
          </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 “Transformation Functions” 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. 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 “t:none”
          to either not apply any transformation functions or you can then
          specify specific transformation functions after “t:none”.</td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Ability to specify an arbitrary Request
            Header in a rule</emphasis>
          </td>

          <td>HEADER_headername HTTP_headername</td>

          <td>REQUEST_HEADERS REQUEST_HEADERS:headername
          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>
            <emphasis role="bold">Variable/Location for the entire URL Request
            Line</emphasis>
          </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>
            <emphasis role="bold">Variable/Location for Arguments</emphasis>
          </td>

          <td>ARG_name</td>

          <td>ARGS:name 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>
            <emphasis role="bold">Accessing Request Bodies</emphasis>
          </td>

          <td>SecFilterScanPOST POST_PAYLOAD</td>

          <td>SecRequestBodyAccess Phase:2 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…) and not just POST
          payloads.</td>

          <td>Replace the existing SecFilterScanPOST directive with
          SecRequestBodyAccess. 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>
            <emphasis role="bold">Ability to disable POST/Request buffering
            dynamically</emphasis>
          </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>
            <emphasis role="bold">Accessing Cookies</emphasis>
          </td>

          <td>COOKIES COOKIES_COUNT COOKIES_NAMES COOKIES_VALUES
          COOKIE_name</td>

          <td>REQUEST_HEADERS:Cookie REQUEST_COOKIES_NAMES
          REQUEST_COOKIES_NAMES:name REQUEST_COOKIES_NAMES:/RegEx/
          REQUEST_COOKIES REQUEST_COOKIES:name REQUEST_COOKIES:/RegEx/</td>

          <td> In 2.x, you can use the “&amp;” character to “count” the number
          of variables. While there are different ways to access request
          cookies, the main difference between them are that
          REQUEST_HEADERS:Cookie will include all of the “raw” Cookie data
          while any of the REQUEST_COOKIES variable values are parsed.</td>

          <td>Translate rules as follows – Mod 1.x -&gt; Mod 2.x COOKIES -&gt;
          REQUEST_COOKIES COOKIES_COUNT -&gt; &amp;REQUEST_COOKIES
          COOKIES_NAMES -&gt; REQUEST_COOKIES_NAMES COOKIES_VALUES -&gt;
          REQUEST_COOKIES COOKIE_name -&gt; REQUEST_COOKIES:name</td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Counting Variables</emphasis>
          </td>

          <td>ARGS_COUNT COOKIES_COUNT HEADERS_COUNT FILES_COUNT</td>

          <td>&amp;ARGS &amp;REQUEST_COOKIES &amp;REQUEST_HEADERS
          &amp;FILES</td>

          <td>In 2.x, prepending the “&amp;” character will count the number
          of variables. Example – 1.x – HEADERS_COUNT 2.x -
          &amp;REQUEST_HEADERS</td>

          <td>Translate existing 1.x rules as listed.</td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Accessing HTTP Status Code</emphasis>
          </td>

          <td>OUTPUT_STATUS</td>

          <td>RESPONSE_STATUS 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>
            <emphasis role="bold">Accessing Response Bodies/Post
            Payloads</emphasis>
          </td>

          <td>SecFilterScanOutput SecFilterOutputMimeTypes OUTPUT</td>

          <td>SecResponseBodyAccess SecResponseBodyMimeTypes RESPONSE_BODY
          Phase:4</td>

          <td>In 1.x, neither skipnext nor chain could be used on the OUTPUT
          location. In 2.x, both actions can be used on RESPONSE_BODY</td>

          <td>Translate directives/rules as follows – Mod 1.x -&gt; Mod 2.x
          SecFilterScanOutput -&gt; SecResponseBodyAccess
          SecFilterOutputMimeTypes -&gt; SecResponseBodyMimeTypes OUTPUT -&gt;
          RESPONSE_BODY/Phase:4</td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Cookie Normalization</emphasis>
          </td>

          <td>SecFilterCookieFormat 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. When specifying
          Cookie variables, then apply the applicable transformation functions
          in the action field of the rule.</td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Ability to skip rules</emphasis>
          </td>

          <td>skipnext</td>

          <td>skip</td>

          <td>In Mod 2.x – skip takes into account chained rulesets and treats
          them as 1 rule. In Mod 1.x – 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>
            <emphasis role="bold">Adding/Removing Audit Log Data on a per rule
            basis</emphasis>
          </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>
            <emphasis role="bold">Inspecting uploaded files</emphasis>
          </td>

          <td>SecUploadApproveScript</td>

          <td>@inspectFile 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. Also,
          the return codes are now reversed – In 1.x, a return code of “1”
          means that the file would be allowed. In 2.x, a return code of “1”
          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. Also, make sure to
          swap your return codes in existing scripts as mentioned in the notes
          column.</td>
        </tr>

        <tr>
          <td>
            <emphasis role="bold">Memory limits for uploaded files</emphasis>
          </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>
    </section>
  </section>
</article>