<?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-2009</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 - <IfModule mod_security.c> Apache 2.x -
<IfModule security_module></td>
<td><IfModule security2_module></td>
<td>The syntax of using IfModule has changed between Apache 1.x and
2.x</td>
<td>Make sure that any existing <IfModule> 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 “&” 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 -> Mod 2.x COOKIES ->
REQUEST_COOKIES COOKIES_COUNT -> &REQUEST_COOKIES
COOKIES_NAMES -> REQUEST_COOKIES_NAMES COOKIES_VALUES ->
REQUEST_COOKIES COOKIE_name -> 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>&ARGS &REQUEST_COOKIES &REQUEST_HEADERS
&FILES</td>
<td>In 2.x, prepending the “&” character will count the number
of variables. Example – 1.x – HEADERS_COUNT 2.x -
&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 -> Mod 2.x
SecFilterScanOutput -> SecResponseBodyAccess
SecFilterOutputMimeTypes -> SecResponseBodyMimeTypes OUTPUT ->
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>
distrib
>
Mandriva
>
2010.0
>
i586
>
media
>
contrib-release
>
by-pkgid
>
ec8d9d7e1251a670fddcb98de6880fe8
>
files
>
55
