doc/html-multipage/transformation-functions.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Transformation functions</title><link href="modsecurity-reference.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.69.1" name="generator"><link rel="start" href="index.html" title="ModSecurity&reg; Reference
   2   Manual"><link rel="up" href="index.html" title="ModSecurity&reg; Reference
   3   Manual"><link rel="prev" href="variables.html" title="Variables"><link rel="next" href="actions.html" title="Actions"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background:#F5F5F5;width:100%;border-top:1px solid #DDDDDD;border-bottom:1px solid #DDDDDD"><table width="100%" cellspacing="0" cellpadding="0"><tr><td><a href="http://www.modsecurity.org"><img style="margin:4px" src="modsecurity.gif" width="120" height="36" alt="ModSecurity" border="0"></a></td><td align="right"><a href="http://www.breach.com"><img style="margin:6px" src="breach-logo-small.gif" height="36" width="100" border="0"></a></td></tr></table></div><div id="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Transformation functions</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="variables.html">Prev</a>&nbsp;</td><td align="center" width="60%">&nbsp;<a accesskey="h" href="index.html">Home</a></td><td align="right" width="20%">&nbsp;<a accesskey="n" href="actions.html">Next</a></td></tr></table><hr size="1"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="transformation-functions"></a>Transformation functions</h2></div></div><div></div></div><p>When ModSecurity receives request or response information, it makes
   4     a copy of this data and places it into memory. It is on this data in
   5     memory that transformation functions are applied. The raw request/response
   6     data is never altered. Transformation functions are used to transform a
   7     variable before testing it in a rule.</p><p><span class="emphasis"><em>Note</em></span></p><p>There are no default transformation functions as there were in
   8     previous versions of ModSecurity.</p><p>The following rule will ensure that an attacker does not use mixed
   9     case in order to evade the ModSecurity rule:</p><p><pre class="programlisting">SecRule ARGS:p "xp_cmdshell" <span class="emphasis"><em>"t:lowercase"</em></span></pre>
  10     multiple transformation actions can be used in the same rule, for example
  11     the following rule also ensures that an attacker does not use URL encoding
  12     (%xx encoding) for evasion. Note the order of the transformation
  13     functions, which ensures that a URL encoded letter is first decoded and
  14     than translated to lower case.</p><p><pre class="programlisting">SecRule ARGS:p "xp_cmdshell" <span class="emphasis"><em>"t:urlDecode,t:lowercase"</em></span></pre></p><p>One can use the SecDefaultAction command to ensure the translation
  15     occurs for every rule until the next. Note that transformation actions are
  16     additive, so if a rule explicitly list actions, the translation actions
  17     set by SecDefaultAction are still performed.</p><p><pre class="programlisting">SecDefaultAction <span class="emphasis"><em>t:urlDecode,t:lowercase</em></span></pre></p><p>The following transformation functions are supported:</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1142D"></a><code class="literal">base64Decode</code></h3></div></div><div></div></div><p>This function decodes a base64-encoded string.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11434"></a><code class="literal">base64Encode</code></h3></div></div><div></div></div><p>This function encodes input string using base64 encoding.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1143B"></a><code class="literal">compressWhitespace</code></h3></div></div><div></div></div><p>It converts whitespace characters (32, \f, \t, \n, \r, \v, 160) to
  18       spaces (ASCII 32) and then compresses multiple consecutive space
  19       characters into one.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11442"></a>cssDecode</h3></div></div><div></div></div><p>Decodes CSS-encoded characters, as specified at <a href="http://www.w3.org/TR/REC-CSS2/syndata.html" target="_top">http://www.w3.org/TR/REC-CSS2/syndata.html</a>.
  20       This function uses only up to two bytes in the decoding process, meaning
  21       it is useful to uncover ASCII characters (that wouldn't normally be
  22       encoded) encoded using CSS encoding, or to counter evasion which is a
  23       combination of a backslash and non-hexadecimal characters (e.g.
  24       <code class="literal">ja\vascript</code> is equivalent to
  25       <code class="literal">javascript</code>).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11453"></a><code class="literal">escapeSeqDecode</code></h3></div></div><div></div></div><p>This function decode ANSI C escape sequences:<code class="literal"> \a</code>,<code class="literal"> \b</code>,
  26       <code class="literal">\f</code>, <code class="literal">\n</code>, <code class="literal">\r</code>,
  27       <code class="literal">\t</code>, <code class="literal">\v</code>, <code class="literal">\\</code>,
  28       <code class="literal">\?</code>, <code class="literal">\'</code>, <code class="literal">\"</code>,
  29       <code class="literal">\xHH</code> (hexadecimal), <code class="literal">\0OOO</code> (octal). Invalid encodings are left in
  30       the output.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1148E"></a><code class="literal">hexDecode</code></h3></div></div><div></div></div><p>This function decodes a hex-encoded string.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11495"></a><code class="literal">hexEncode</code></h3></div></div><div></div></div><p>This function encodes input as hex-encoded string.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1149C"></a><code class="literal">htmlEntityDecode</code></h3></div></div><div></div></div><p>This function decodes HTML entities present in input. The
  31       following variants are supported:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">&amp;#xHH</code> and <code class="literal">&amp;#xHH;</code> (where H is any hexadecimal
  32           number)</p></li><li><p><code class="literal">&amp;#DDD</code> and <code class="literal">&amp;#DDD;</code> (where D is any decimal
  33           number)</p></li><li><p><code class="literal">&amp;quot</code> and <code class="literal">&amp;quot;</code></p></li><li><p><code class="literal">&amp;nbsp</code> and <code class="literal">&amp;nbsp;</code></p></li><li><p><code class="literal">&amp;lt</code> and <code class="literal">&amp;lt;</code></p></li><li><p><code class="literal">&amp;gt</code> and <code class="literal">&amp;gt;</code></p></li></ul></div><p>This function will convert any entity into a single byte only,
  34       possibly resulting in a loss of information. It is thus useful to
  35       uncover bytes that would otherwise not need to be encoded, but it cannot
  36       do anything with the characters from the range above 255.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N114DE"></a><code class="literal">jsDecode</code></h3></div></div><div></div></div><p>Decodes JavaScript escape sequences. If a
  37       <code class="literal">\uHHHH</code> code is in the range of
  38       <code class="literal">FF01</code>-<code class="literal">FF5E</code> (the full width ASCII
  39       codes), then the higher byte is used to detect and adjust the lower
  40       byte. Otherwise, only the lower byte will be used and the higher byte
  41       zeroed.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N114F1"></a><code class="literal">length</code></h3></div></div><div></div></div><p>This function converts the input to its numeric length (count of
  42       bytes).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N114F8"></a><code class="literal">lowercase</code></h3></div></div><div></div></div><p>This function converts all characters to lowercase using the
  43       current C locale.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N114FF"></a><code class="literal">md5</code></h3></div></div><div></div></div><p>This function calculates an MD5 hash from input. Note that the
  44       computed hash is in a raw binary form and may need encoded into text to
  45       be usable (for example: <code class="literal">t:md5,t:hexEncode</code>).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1150A"></a><code class="literal"><code class="literal">none</code></code></h3></div></div><div></div></div><p>Not an actual transformation function, but an instruction to
  46       ModSecurity to remove all transformation functions associated with the
  47       current rule.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11513"></a><code class="literal">normalisePath</code></h3></div></div><div></div></div><p>This function will remove multiple slashes, self-references and
  48       directory back-references (except when they are at the beginning of the
  49       input).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1151A"></a><code class="literal">normalisePathWin</code></h3></div></div><div></div></div><p>Same as <code class="literal">normalisePath</code>, but will first convert
  50       backslash characters to forward slashes.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11525"></a><code class="literal">parityEven7bit</code></h3></div></div><div></div></div><p>This function calculates even parity of 7-bit data replacing the
  51       8th bit of each target byte with the calculated parity bit.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1152C"></a><code class="literal">parityOdd7bit</code></h3></div></div><div></div></div><p>This function calculates odd parity of 7-bit data replacing the
  52       8th bit of each target byte with the calculated parity bit.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11533"></a><code class="literal">parityZero7bit</code></h3></div></div><div></div></div><p>This function calculates zero parity of 7-bit data replacing the
  53       8th bit of each target byte with a zero parity bit which allows
  54       inspection of even/odd parity 7bit data as ASCII7 data.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1153A"></a><code class="literal">removeNulls</code></h3></div></div><div></div></div><p>This function removes NULL bytes from input.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11541"></a><code class="literal">removeWhitespace</code></h3></div></div><div></div></div><p>This function removes all whitespace characters from input.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11548"></a><code class="literal">replaceComments</code></h3></div></div><div></div></div><p>This function replaces each occurrence of a C-style comments
  55       (<code class="literal">/* ... */</code>) with a single space
  56       (multiple consecutive occurrences of a space will not be compressed).
  57       Unterminated comments will too be replaced with a space (ASCII 32).
  58       However, a standalone termination of a comment (<code class="literal">*/</code>) will not be acted upon.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11557"></a><code class="literal">replaceNulls</code></h3></div></div><div></div></div><p>This function is enabled by default. It replaces NULL bytes in
  59       input with spaces (ASCII 32).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1155E"></a><code class="literal">urlDecode</code></h3></div></div><div></div></div><p>This function decodes an URL-encoded input string. Invalid
  60       encodings (i.e. the ones that use non-hexadecimal characters, or the
  61       ones that are at the end of string and have one or two characters
  62       missing) will not be converted. If you want to detect invalid encodings
  63       use the <code class="literal">@validateUrlEncoding</code>
  64       operator. The transformation function should not be used against
  65       variables that have already been URL-decoded unless it is your intention
  66       to perform URL decoding twice!</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11569"></a><code class="literal">urlDecodeUni</code></h3></div></div><div></div></div><p>In addition to decoding <code class="literal">%xx</code> like <code class="literal">urlDecode, urlDecodeUni</code> also decodes <code class="literal">%uXXXX</code> encoding. If the code is in the range
  67       of <code class="literal">FF01</code>-<code class="literal">FF5E</code> (the full width ASCII
  68       codes), then the higher byte is used to detect and adjust the lower
  69       byte. Otherwise, only the lower byte will be used and the higher byte
  70       zeroed.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11584"></a><code class="literal">urlEncode</code></h3></div></div><div></div></div><p>This function encodes input using URL encoding.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1158B"></a><code class="literal">sha1</code></h3></div></div><div></div></div><p>This function calculates a SHA1 hash from input. Note that the
  71       computed hash is in a raw binary form and may need encoded to be usable
  72       (for example: <code class="literal">t:sha1,t:hexEncode</code>).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11596"></a><code class="literal">trimLeft</code></h3></div></div><div></div></div><p>This function removes whitespace from the left side of
  73       input.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1159D"></a><code class="literal">trimRight</code></h3></div></div><div></div></div><p>This function removes whitespace from the right side of
  74       input.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N115A4"></a><code class="literal">trim</code></h3></div></div><div></div></div><p>This function removes whitespace from both the left and right
  75       sides of input.</p></div></div><div id="navfooter"><hr size="1"><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="variables.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="actions.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Variables&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Actions</td></tr></table></div><div align="center" class="copyright">Copyright (C) 2004-2009 <a href="http://www.breach.com">Breach Security</a></div></body></html>