doc/html-multipage/operators.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Operators</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="actions.html" title="Actions"><link rel="next" href="ar01s10.html" title="Macro Expansion"></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">Operators</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="actions.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="ar01s10.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="operators"></a>Operators</h2></div></div><div></div></div><p>A number of operators can be used in rules, as documented below. The
   4     operator syntax uses the <code class="literal">@</code> symbol followed by the
   5     specific operator name.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11BC6"></a><code class="literal">beginsWith</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a string
   6       comparison and returns true if the parameter value is found at the
   7       beginning of the input. Macro expansion is performed so you may use
   8       variable names such as <code class="literal">%{TX.1}</code>, etc.</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_LINE "!<span class="emphasis"><em>@beginsWith GET</em></span>" t:none,deny,status:403
   9 SecRule REQUEST_ADDR "^(.*)\.\d+$" deny,status:403,capture,chain
  10 SecRule ARGS:gw "!<span class="emphasis"><em>@beginsWith %{TX.1}</em></span>"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11BDE"></a><code class="literal">contains</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a string
  11       comparison and returns true if the parameter value is found anywhere in
  12       the input. Macro expansion is performed so you may use variable names
  13       such as %{TX.1}, etc.</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_LINE "!<span class="emphasis"><em>@contains .php</em></span>" t:none,deny,status:403
  14 SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain
  15 SecRule ARGS:ip "!<span class="emphasis"><em>@contains %{TX.1}</em></span>"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11BF2"></a><code class="literal">endsWith</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a string
  16       comparison and returns true if the parameter value is found at the end
  17       of the input. Macro expansion is performed so you may use variable names
  18       such as %{TX.1}, etc.</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_LINE "!<span class="emphasis"><em>@endsWith HTTP/1.1</em></span>" t:none,deny,status:403
  19 SecRule ARGS:route "!<span class="emphasis"><em>@endsWith %{REQUEST_ADDR}</em></span>" t:none,deny,status:403</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C06"></a><code class="literal">eq</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a numerical
  20       comparison and stands for "equal to."</p><p>Example:</p><pre class="programlisting">SecRule &amp;REQUEST_HEADERS_NAMES "<span class="emphasis"><em>@eq</em></span> 15"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C17"></a><code class="literal">ge</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a numerical
  21       comparison and stands for "greater than or equal to."</p><p>Example:</p><pre class="programlisting">SecRule &amp;REQUEST_HEADERS_NAMES "<span class="emphasis"><em>@ge</em></span> 15"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C28"></a><code class="literal">geoLookup</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator looks up various
  22       data fields from an IP address or hostname in the target data. The
  23       results will be captured in the <code class="literal">GEO</code>
  24       collection.</p><p>You must provide a database via <code class="literal">SecGeoLookupDb</code> before this operator can be
  25       used.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This operator matches and the action is executed on a <span class="emphasis"><em>
  26         successful</em></span> lookup. For this reason, you probably want to
  27         use the <span class="emphasis"><em>pass,nolog</em></span> actions. This allows for
  28         <code class="literal">setvar</code> and other non-disruptive
  29         actions to be executed on a match. If you wish to block on a failed
  30         lookup, then do something like this (look for an empty GEO
  31         collection):</p><pre class="programlisting">SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat
  32 ...
  33 SecRule REMOTE_ADDR "@geoLookup" "pass,nolog"
  34 SecRule &amp;GEO "@eq 0" "deny,status:403,msg:'Failed to lookup IP'"</pre></div><p>See the <code class="literal">GEO</code> variable for an
  35       example and more information on various fields available.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C51"></a><code class="literal">gt</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a numerical
  36       comparison and stands for "greater than."</p><p>Example:</p><pre class="programlisting">SecRule &amp;REQUEST_HEADERS_NAMES "<span class="emphasis"><em>@gt</em></span> 15"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C62"></a><code class="literal">inspectFile</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Executes the external
  37       script/binary given as parameter to the operator against every file
  38       extracted from the request. As of v2.5.0, if the supplied filename is
  39       not absolute it is treated as relative to the directory in which the
  40       configuration file resides. Also as of v2.5.0, if the filename is
  41       determined to be a Lua script (based on its extension) the script will
  42       be processed by the internal engine. As such it will have full access to
  43       the ModSecurity context.</p><p>Example of using an external binary/script:</p><pre class="programlisting"># Execute external script to validate uploaded files.
  44 SecRule FILES_TMPNAMES "<span class="emphasis"><em>@inspectFile</em></span> /opt/apache/bin/inspect_script.pl"</pre><p>Example of using Lua script:</p><pre class="programlisting">SecRule FILES_TMPNANMES "@inspectFile <span class="emphasis"><em>inspect.lua</em></span>"</pre><p>Script <code class="filename">inspect.lua</code>:</p><pre class="programlisting">function main(filename)
  45     -- Do something to the file to verify it. In this example, we
  46     -- read up to 10 characters from the beginning of the file.
  47     local f = io.open(filename, "rb");
  48     local d = f:read(10);
  49     f:close();
  50
  51     -- Return null if there is no reason to believe there is ansything
  52     -- wrong with the file (no match). Returning any text will be taken
  53     -- to mean a match should be trigerred.
  54     return null;
  55 end</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C84"></a><code class="literal">le</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a numerical
  56       comparison and stands for "less than or equal to."</p><p>Example:</p><pre class="programlisting">SecRule &amp;REQUEST_HEADERS_NAMES "<span class="emphasis"><em>@le</em></span> 15"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C95"></a><code class="literal">lt</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a numerical
  57       comparison and stands for "less than."</p><p>Example:</p><pre class="programlisting">SecRule &amp;REQUEST_HEADERS_NAMES "<span class="emphasis"><em>@lt</em></span> 15"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11CA6"></a><code class="literal">pm</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Phrase Match operator. This
  58       operator uses a set based matching engine (Aho-Corasick) for faster
  59       matches of keyword lists. It will match any one of its arguments
  60       anywhere in the target value. The match is case insensitive.</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "<span class="emphasis"><em>@pm</em></span> WebZIP WebCopier Webster WebStripper SiteSnagger ProWebWalker CheeseBot" "deny,status:403</pre><p>The above would deny access with 403 if any of the words matched
  61       within the User-Agent HTTP header value.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11CB9"></a><code class="literal">pmFromFile</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Phrase Match operator. This
  62       operator uses a set based matching engine (Aho-Corasick) for faster
  63       matches of keyword lists. This operator is the same as
  64       <code class="literal">@pm</code> except that it takes a list of files as
  65       arguments. It will match any one of the phrases listed in the file(s)
  66       anywhere in the target value.</p><p>Notes:</p><div class="orderedlist"><ol type="1"><li><p>The contents of the files should be one phrase per line. End
  67           of line markers will be stripped from the phrases, however,
  68           whitespace will not be trimmed from phrases in the file. Empty lines
  69           and comment lines (beginning with a '#') are ignored.</p></li><li><p>To allow easier inclusion of phrase files with rulesets,
  70           relative paths may be used to the phrase files. In this case, the
  71           path of the file containing the rule is prepended to the phrase file
  72           path.</p></li></ol></div><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "<span class="emphasis"><em>@pm</em></span> /path/to/blacklist1 blacklist2" "deny,status:403</pre><p>The above would deny access with 403 if any of the patterns in the
  73       two files matched within the User-Agent HTTP header value. The
  74       <code class="literal">blacklist2</code> file would need to be placed in the same
  75       path as the file containing the rule.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11CDF"></a><code class="literal">rbl</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Look up the parameter in the RBL
  76       given as parameter. Parameter can be an IPv4 address, or a
  77       hostname.</p><p>Example:</p><pre class="programlisting">SecRule REMOTE_ADDR "<span class="emphasis"><em>@rbl</em></span> sc.surbl.org"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11CF0"></a><code class="literal">rx</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Regular expression operator.
  78       This is the default operator, so if the "@" operator is not defined, it
  79       is assumed to be rx.</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "<span class="emphasis"><em>@rx</em></span> nikto"</pre><p><span class="emphasis"><em>Note</em></span></p><p>Regular expressions are handled by the PCRE library (<a href="http://www.pcre.org" target="_top">http://www.pcre.org</a>). ModSecurity
  80       compiles its regular expressions with the following settings:</p><div class="orderedlist"><ol type="1"><li><p>The entire input is treated as a single line, even when there
  81           are newline characters present.</p></li><li><p>All matches are case-sensitive. If you do not care about case
  82           sensitivity you either need to implement the <code class="literal">lowercase</code> transformation function, or use
  83           the per-pattern<code class="literal">(?i)</code>modifier, as
  84           allowed by PCRE.</p></li><li><p>The <code class="literal">PCRE_DOTALL</code> and
  85           <code class="literal">PCRE_DOLLAR_ENDONLY</code> flags are set
  86           during compilation, meaning a single dot will match any character,
  87           including the newlines and a <code class="literal">$</code>
  88           end anchor will not match a trailing newline character.</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D2A"></a><code class="literal">streq</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a string
  89       comparison and returns true if the parameter value matches the input
  90       exactly. Macro expansion is performed so you may use variable names such
  91       as %{TX.1}, etc.</p><p>Example:</p><pre class="programlisting">SecRule ARGS:foo "!<span class="emphasis"><em>@streq bar</em></span>" t:none,deny,status:403
  92 SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain
  93 SecRule REQUEST_HEADERS:Ip-Address "!<span class="emphasis"><em>@streq %{TX.1}</em></span>"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D3E"></a><code class="literal">validateByteRange</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Validates the byte range used in
  94       the variable falls into the specified range.</p><p>Example:</p><pre class="programlisting">SecRule ARGS:text "<span class="emphasis"><em>@validateByteRange</em></span> 10, 13, 32-126"</pre><p><span class="emphasis"><em>Note</em></span></p><p>You can force requests to consist only of bytes from a certain
  95       byte range. This can be useful to avoid stack overflow attacks (since
  96       they usually contain "random" binary content). Default range values are
  97       0 and 255, i.e. all byte values are allowed. This directive does not
  98       check byte range in a POST payload when
  99       <code class="literal">multipart/form-data</code> encoding (file upload) is used.
 100       Doing so would prevent binary files from being uploaded. However, after
 101       the parameters are extracted from such request they are checked for a
 102       valid range.</p><p>validateByteRange is similar to the ModSecurity 1.X
 103       SecFilterForceByteRange Directive however since it works in a rule
 104       context, it has the following differences:</p><div class="itemizedlist"><ul type="disc"><li><p>You can specify a different range for different
 105           variables.</p></li><li><p>It has an "event" context (id, msg....)</p></li><li><p>It is executed in the flow of rules rather than being a built
 106           in pre-check.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D64"></a><code class="literal">validateDTD</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Validates the DOM tree generated
 107       by the XML request body processor against the supplied DTD.</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,status:403,phase:2
 108 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
 109     phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML
 110 SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345
 111 SecRule XML "<span class="emphasis"><em>@validateDTD /path/to/apache2/conf/xml.dtd</em></span>" "deny,id:12345"</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This operator requires request body to be processed as
 112         XML.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D78"></a><code class="literal">validateSchema</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Validates the DOM tree generated
 113       by the XML request body processor against the supplied XML
 114       Schema.</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,status:403,phase:2
 115 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
 116     phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML
 117 SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345
 118 SecRule XML "<span class="emphasis"><em>@validateSchema /path/to/apache2/conf/xml.xsd</em></span>" "deny,id:12345"</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This operator requires request body to be processed as
 119         XML.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D8C"></a><code class="literal">validateUrlEncoding</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Verifies the encodings used in
 120       the variable (if any) are valid.</p><p>Example:</p><pre class="programlisting">SecRule ARGS "<span class="emphasis"><em>@validateUrlEncoding</em></span>"</pre><p><span class="emphasis"><em>Note</em></span></p><p>URL encoding is an HTTP standard for encoding byte values within a
 121       URL. The byte is escaped with a % followed by two hexadecimal values
 122       (0-F). This directive does not check encoding in a POST payload when the
 123       <code class="literal">multipart/form-data</code> encoding (file upload) is used.
 124       It is not necessary to do so because URL encoding is not used for this
 125       encoding.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11DA6"></a><code class="literal">validateUtf8Encoding</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Verifies the variable is a valid
 126       UTF-8 encoded string.</p><p>Example:</p><pre class="programlisting">SecRule ARGS "<span class="emphasis"><em>@validateUtf8Encoding</em></span>"</pre><p><span class="emphasis"><em>Note</em></span></p><p>UTF-8 encoding is valid on most web servers. Integer values
 127       between 0-65535 are encoded in a UTF-8 byte sequence that is escaped by
 128       percents. The short form is two bytes in length.</p><p>check for three types of errors:</p><div class="itemizedlist"><ul type="disc"><li><p>Not enough bytes. UTF-8 supports two, three, four, five, and
 129           six byte encodings. ModSecurity will locate cases when a byte or
 130           more is missing.</p></li><li><p>Invalid encoding. The two most significant bits in most
 131           characters are supposed to be fixed to 0x80. Attackers can use this
 132           to subvert Unicode decoders.</p></li><li><p>Overlong characters. ASCII characters are mapped directly into
 133           the Unicode space and are thus represented with a single byte.
 134           However, most ASCII characters can also be encoded with two, three,
 135           four, five, and six characters thus tricking the decoder into
 136           thinking that the character is something else (and, presumably,
 137           avoiding the security check).</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11DC8"></a><code class="literal">verifyCC</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator verifies a given
 138       regular expression as a potential credit card number. It first matches
 139       with a single generic regular expression then runs the resulting match
 140       through a Luhn checksum algorithm to further verify it as a potential
 141       credit card number.</p><p>Example:</p><pre class="programlisting">SecRule ARGS "<span class="emphasis"><em>@verifyCC \d{13,16}</em></span>" \
 142               "phase:2,sanitiseMatched,log,auditlog,pass,msg:'Potential credit card number'"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11DD9"></a><code class="literal">within</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This operator is a string
 143       comparison and returns true if the input value is found anywhere within
 144       the parameter value. Note that this is similar to
 145       <code class="literal">@contains</code>, except that the target and match values
 146       are reversed. Macro expansion is performed so you may use variable names
 147       such as %{TX.1}, etc.</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_METHOD "!<span class="emphasis"><em>@within get,post,head</em></span>" t:lowercase,deny,status:403
 148
 149 SecAction "pass,setvar:'tx.allowed_methods=get,post,head'"
 150 SecRule REQUEST_METHOD "!<span class="emphasis"><em>@within %{tx.allowed_methods}</em></span>" t:lowercase,deny,status:403</pre></div></div><div id="navfooter"><hr size="1"><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="actions.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="ar01s10.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Actions&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Macro Expansion</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>