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® Reference
2 Manual"><link rel="up" href="index.html" title="ModSecurity® 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> </td><td align="center" width="60%"> <a accesskey="h" href="index.html">Home</a></td><td align="right" width="20%"> <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 &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 &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
33 SecRule REMOTE_ADDR "@geoLookup" "pass,nolog"
34 SecRule &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 &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");
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.
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 &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 &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
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> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="ar01s10.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Actions </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> 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>