<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
Manual"><link rel="up" href="index.html" title="ModSecurity® Reference
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
operator syntax uses the <code class="literal">@</code> symbol followed by the
specific operator name.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C8A"></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
comparison and returns true if the parameter value is found at the
beginning of the input. Macro expansion is performed so you may use
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
SecRule REQUEST_ADDR "^(.*)\.\d+$" deny,status:403,capture,chain
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="N11CA2"></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
comparison and returns true if the parameter value is found anywhere in
the input. Macro expansion is performed so you may use variable names
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
SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain
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="N11CB6"></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
comparison and returns true if the parameter value is found at the end
of the input. Macro expansion is performed so you may use variable names
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
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="N11CCA"></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
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><p>Macro expansion is performed so you may use variable names such as
<code class="literal">%{TX.1}</code>, etc.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11CE1"></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
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><p>Macro expansion is performed so you may use variable names such as
<code class="literal">%{TX.1}</code>, etc.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11CF8"></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
data fields from an IP address or hostname in the target data. The
results will be captured in the <code class="literal">GEO</code>
collection.</p><p>You must provide a database via <code class="literal">SecGeoLookupDb</code> before this operator can be
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>
successful</em></span> lookup. For this reason, you probably want to
use the <span class="emphasis"><em>pass,nolog</em></span> actions. This allows for
<code class="literal">setvar</code> and other non-disruptive
actions to be executed on a match. If you wish to block on a failed
lookup, then do something like this (look for an empty GEO
collection):</p><pre class="programlisting">SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat
...
SecRule REMOTE_ADDR "@geoLookup" "pass,nolog"
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
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="N11D21"></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
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><p>Macro expansion is performed so you may use variable names such as
<code class="literal">%{TX.1}</code>, etc.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D38"></a><code class="literal">inspectFile</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Executes the external
script/binary given as parameter to the operator against every file
extracted from the request. As of v2.5.0, if the supplied filename is
not absolute it is treated as relative to the directory in which the
configuration file resides. Also as of v2.5.0, if the filename is
determined to be a Lua script (based on its extension) the script will
be processed by the internal engine. As such it will have full access to
the ModSecurity context.</p><p>Example of using an external binary/script:</p><pre class="programlisting"># Execute external script to validate uploaded files.
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)
-- Do something to the file to verify it. In this example, we
-- read up to 10 characters from the beginning of the file.
local f = io.open(filename, "rb");
local d = f:read(10);
f:close();
-- Return null if there is no reason to believe there is ansything
-- wrong with the file (no match). Returning any text will be taken
-- to mean a match should be trigerred.
return null;
end</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D5A"></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
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><p>Macro expansion is performed so you may use variable names such as
<code class="literal">%{TX.1}</code>, etc.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D71"></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
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><p>Macro expansion is performed so you may use variable names such as
<code class="literal">%{TX.1}</code>, etc.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D88"></a><code class="literal">pm</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Phrase Match operator. This
operator uses a set based matching engine (Aho-Corasick) for faster
matches of keyword lists. It will match any one of its arguments
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
within the User-Agent HTTP header value.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11D9B"></a><code class="literal">pmFromFile</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Phrase Match operator. This
operator uses a set based matching engine (Aho-Corasick) for faster
matches of keyword lists. This operator is the same as
<code class="literal">@pm</code> except that it takes a list of files as
arguments. It will match any one of the phrases listed in the file(s)
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
of line markers will be stripped from the phrases (LF and CRLF), and
whitespace is trimmed from both sides of the phrases. Empty lines
and comment lines (beginning with a '#') are ignored.</p></li><li><p>To allow easier inclusion of phrase files with rulesets,
relative paths may be used to the phrase files. In this case, the
path of the file containing the rule is prepended to the phrase file
path.</p></li><li><p>To allow easier matching of whole IP addresses, you can add
boundary characters to the phrases. For example, use "/1.2.3.4/"
instead of "1.2.3.4". You can then insert these characters into the
target prior to a match:</p><pre class="programlisting">SecAction "phase:1,pass,nolog,setvar:tx.remote_addr=/%{REMOTE_ADDR}/"
SecRule TX:REMOTE_ADDR "<span class="emphasis"><em>@pmFromFile ip-blacklist.txt</em></span>" "deny,status:403
# ip-blacklist.txt contents:
# NOTE: All IPs must be prefixed/suffixed with "/" as the rules
# will add in this character as a boundary to ensure
# the entire IP is matched.
# SecAction "phase:1,pass,nolog,setvar:tx.remote_addr='/%{REMOTE_ADDR}/'"
/1.2.3.4/
/5.6.7.8/</pre></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
two files matched within the User-Agent HTTP header value. The
<code class="literal">blacklist2</code> file would need to be placed in the same
path as the file containing the rule.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11DCA"></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
given as parameter. Parameter can be an IPv4 address, or a
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="N11DDB"></a><code class="literal">rx</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Regular expression operator.
This is the default operator, so if the "@" operator is not defined, it
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
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
are newline characters present.</p></li><li><p>All matches are case-sensitive. If you do not care about case
sensitivity you either need to implement the <code class="literal">lowercase</code> transformation function, or use
the per-pattern<code class="literal">(?i)</code>modifier, as
allowed by PCRE.</p></li><li><p>The <code class="literal">PCRE_DOTALL</code> and
<code class="literal">PCRE_DOLLAR_ENDONLY</code> flags are set
during compilation, meaning a single dot will match any character,
including the newlines and a <code class="literal">$</code>
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="N11E15"></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
comparison and returns true if the parameter value matches the input
exactly. Macro expansion is performed so you may use variable names such
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
SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain
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="N11E29"></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
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
byte range. This can be useful to avoid stack overflow attacks (since
they usually contain "random" binary content). Default range values are
0 and 255, i.e. all byte values are allowed. This directive does not
check byte range in a POST payload when
<code class="literal">multipart/form-data</code> encoding (file upload) is used.
Doing so would prevent binary files from being uploaded. However, after
the parameters are extracted from such request they are checked for a
valid range.</p><p>validateByteRange is similar to the ModSecurity 1.X
SecFilterForceByteRange Directive however since it works in a rule
context, it has the following differences:</p><div class="itemizedlist"><ul type="disc"><li><p>You can specify a different range for different
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
in pre-check.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11E4F"></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
by the XML request body processor against the supplied DTD.</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,status:403,phase:2
SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML
SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345
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
XML.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11E63"></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
by the XML request body processor against the supplied XML
Schema.</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,status:403,phase:2
SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML
SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345
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
XML.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11E77"></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
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
URL. The byte is escaped with a % followed by two hexadecimal values
(0-F). This directive does not check encoding in a POST payload when the
<code class="literal">multipart/form-data</code> encoding (file upload) is used.
It is not necessary to do so because URL encoding is not used for this
encoding.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11E91"></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
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
between 0-65535 are encoded in a UTF-8 byte sequence that is escaped by
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
six byte encodings. ModSecurity will locate cases when a byte or
more is missing.</p></li><li><p>Invalid encoding. The two most significant bits in most
characters are supposed to be fixed to 0x80. Attackers can use this
to subvert Unicode decoders.</p></li><li><p>Overlong characters. ASCII characters are mapped directly into
the Unicode space and are thus represented with a single byte.
However, most ASCII characters can also be encoded with two, three,
four, five, and six characters thus tricking the decoder into
thinking that the character is something else (and, presumably,
avoiding the security check).</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11EB3"></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
regular expression as a potential credit card number. It first matches
with a single generic regular expression then runs the resulting match
through a Luhn checksum algorithm to further verify it as a potential
credit card number.</p><p>Example:</p><pre class="programlisting">SecRule ARGS "<span class="emphasis"><em>@verifyCC \d{13,16}</em></span>" \
"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="N11EC4"></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
comparison and returns true if the input value is found anywhere within
the parameter value. Note that this is similar to
<code class="literal">@contains</code>, except that the target and match values
are reversed. Macro expansion is performed so you may use variable names
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
SecAction "pass,setvar:'tx.allowed_methods=get,post,head'"
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-2010 <a href="http://www.breach.com">Breach Security</a></div></body></html>
