doc/modsecurity2-apache-reference.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>ModSecurity&reg; Reference
   2   Manual</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="#N10001" title="ModSecurity&reg; Reference
   3   Manual"><link rel="next" href="#introduction" title="Introduction"></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 class="article" lang="en"><div class="titlepage"><div><div><h2 class="title"><a name="N10001"></a><span class="trademark">ModSecurity</span>&reg; Reference
   4   Manual</h2></div><div><p class="releaseinfo">Version 2.5.11 (Nov 4, 2009)</p></div><div><p class="copyright">Copyright &copy; 2004-2009 Breach Security, Inc. (<a href="http://www.breach.com" target="_top">http://www.breach.com</a>)</p></div></div><div></div><hr size="1"></div><div class="toc"><p><b>Table of Contents</b></p><dl><dt><span class="section"><a href="#introduction">Introduction</a></span></dt><dd><dl><dt><span class="section"><a href="#N1001D">HTTP Traffic Logging</a></span></dt><dt><span class="section"><a href="#N10022">Real-Time Monitoring and Attack Detection</a></span></dt><dt><span class="section"><a href="#N10027">Attack Prevention and Just-in-time Patching</a></span></dt><dt><span class="section"><a href="#N10038">Flexible Rule Engine</a></span></dt><dt><span class="section"><a href="#N1003D">Embedded-mode Deployment</a></span></dt><dt><span class="section"><a href="#N10054">Network-based Deployment</a></span></dt><dt><span class="section"><a href="#N10059">Portability</a></span></dt><dt><span class="section"><a href="#licensing">Licensing</a></span></dt></dl></dd><dt><span class="section"><a href="#N10067"><span class="trademark">ModSecurity Core Rules</span>&trade;</a></span></dt><dd><dl><dt><span class="section"><a href="#N1006C">Overview</a></span></dt><dt><span class="section"><a href="#N10075">Core Rules Content</a></span></dt></dl></dd><dt><span class="section"><a href="#installation">Installation</a></span></dt><dt><span class="section"><a href="#configuration-directives">Configuration Directives</a></span></dt><dd><dl><dt><span class="section"><a href="#N101B0"><code class="literal">SecAction</code></a></span></dt><dt><span class="section"><a href="#N101E1"><code class="literal">SecArgumentSeparator</code></a></span></dt><dt><span class="section"><a href="#N10216"><code class="literal">SecAuditEngine</code></a></span></dt><dt><span class="section"><a href="#N10263"><code class="literal">SecAuditLog</code></a></span></dt><dt><span class="section"><a href="#N10293"><code class="literal">SecAuditLog2</code></a></span></dt><dt><span class="section"><a href="#N102C5"><code class="literal">SecAuditLogDirMode</code></a></span></dt><dt><span class="section"><a href="#N102F3"><code class="literal">SecAuditLogFileMode</code></a></span></dt><dt><span class="section"><a href="#N10321"><code class="literal">SecAuditLogParts</code></a></span></dt><dt><span class="section"><a href="#N103B4"><code class="literal">SecAuditLogRelevantStatus</code></a></span></dt><dt><span class="section"><a href="#N103E5"><code class="literal">SecAuditLogStorageDir</code></a></span></dt><dt><span class="section"><a href="#N1040E"><code class="literal">SecAuditLogType</code></a></span></dt><dt><span class="section"><a href="#N1044A"><code class="literal">SecCacheTransformations</code>
   5       (Deprecated/Experimental)</a></span></dt><dt><span class="section"><a href="#N1049C"><code class="literal">SecChrootDir</code></a></span></dt><dt><span class="section"><a href="#N104DD"><code class="literal">SecComponentSignature</code></a></span></dt><dt><span class="section"><a href="#N10504"><code class="literal">SecContentInjection</code></a></span></dt><dt><span class="section"><a href="#N10533"><code class="literal">SecCookieFormat</code></a></span></dt><dt><span class="section"><a href="#N10569"><code class="literal">SecDataDir</code></a></span></dt><dt><span class="section"><a href="#N1058C"><code class="literal">SecDebugLog</code></a></span></dt><dt><span class="section"><a href="#N105B3"><code class="literal">SecDebugLogLevel</code></a></span></dt><dt><span class="section"><a href="#N10613"><code class="literal">SecDefaultAction</code></a></span></dt><dt><span class="section"><a href="#N1065E"><code class="literal">SecGeoLookupDb</code></a></span></dt><dt><span class="section"><a href="#N10689"><code class="literal">SecGuardianLog</code></a></span></dt><dt><span class="section"><a href="#N106BC"><code class="literal">SecMarker</code></a></span></dt><dt><span class="section"><a href="#N106F4"><code class="literal">SecPdfProtect</code></a></span></dt><dt><span class="section"><a href="#N1071F"><code class="literal">SecPdfProtectMethod</code></a></span></dt><dt><span class="section"><a href="#N10755"><code class="literal">SecPdfProtectSecret</code></a></span></dt><dt><span class="section"><a href="#N1077C"><code class="literal">SecPdfProtectTimeout</code></a></span></dt><dt><span class="section"><a href="#N107AA"><code class="literal">SecPdfProtectTokenName</code></a></span></dt><dt><span class="section"><a href="#N107D8"><code class="literal">SecRequestBodyAccess</code></a></span></dt><dt><span class="section"><a href="#N10816"><code class="literal">SecRequestBodyLimit</code></a></span></dt><dt><span class="section"><a href="#N10839"><code class="literal">SecRequestBodyNoFilesLimit</code></a></span></dt><dt><span class="section"><a href="#N10864"><code class="literal">SecRequestBodyInMemoryLimit</code></a></span></dt><dt><span class="section"><a href="#N10890"><code class="literal">SecResponseBodyLimit</code></a></span></dt><dt><span class="section"><a href="#N108BC"><code class="literal">SecResponseBodyLimitAction</code></a></span></dt><dt><span class="section"><a href="#N108E7"><code class="literal">SecResponseBodyMimeType</code></a></span></dt><dt><span class="section"><a href="#N10923"><code class="literal">SecResponseBodyMimeTypesClear</code></a></span></dt><dt><span class="section"><a href="#N1094E"><code class="literal">SecResponseBodyAccess</code></a></span></dt><dt><span class="section"><a href="#N10984"><code class="literal">SecRule</code></a></span></dt><dt><span class="section"><a href="#N10A74"><code class="literal">SecRuleInheritance</code></a></span></dt><dt><span class="section"><a href="#N10AD7"><code class="literal">SecRuleEngine</code></a></span></dt><dt><span class="section"><a href="#N10B13"><code class="literal">SecRuleRemoveById</code></a></span></dt><dt><span class="section"><a href="#N10B3D"><code class="literal">SecRuleRemoveByMsg</code></a></span></dt><dt><span class="section"><a href="#N10B68"><code class="literal">SecRuleScript</code> (Experimental)</a></span></dt><dt><span class="section"><a href="#N10BC2"><code class="literal">SecRuleUpdateActionById</code></a></span></dt><dt><span class="section"><a href="#N10BF1"><code class="literal">SecServerSignature</code></a></span></dt><dt><span class="section"><a href="#N10C18"><code class="literal">SecTmpDir</code></a></span></dt><dt><span class="section"><a href="#N10C3F"><code class="literal">SecUploadDir</code></a></span></dt><dt><span class="section"><a href="#N10C6E"><code class="literal">SecUploadFileMode</code></a></span></dt><dt><span class="section"><a href="#N10C98"><code class="literal">SecUploadKeepFiles</code></a></span></dt><dt><span class="section"><a href="#N10CD8"><code class="literal">SecWebAppId</code></a></span></dt></dl></dd><dt><span class="section"><a href="#processing-phases">Processing Phases</a></span></dt><dd><dl><dt><span class="section"><a href="#N10D73">Phase Request Headers</a></span></dt><dt><span class="section"><a href="#N10D7D">Phase Request Body</a></span></dt><dt><span class="section"><a href="#N10D97">Phase Response Headers</a></span></dt><dt><span class="section"><a href="#N10D9C">Phase Response Body</a></span></dt><dt><span class="section"><a href="#N10DA1">Phase Logging</a></span></dt></dl></dd><dt><span class="section"><a href="#variables">Variables</a></span></dt><dd><dl><dt><span class="section"><a href="#N10DAC"><code class="literal">ARGS</code></a></span></dt><dt><span class="section"><a href="#N10DFE"><code class="literal">ARGS_COMBINED_SIZE</code></a></span></dt><dt><span class="section"><a href="#N10E0B"><code class="literal">ARGS_NAMES</code></a></span></dt><dt><span class="section"><a href="#N10E18"><code class="literal">ARGS_GET</code></a></span></dt><dt><span class="section"><a href="#N10E26"><code class="literal">ARGS_GET_NAMES</code></a></span></dt><dt><span class="section"><a href="#N10E34"><code class="literal">ARGS_POST</code></a></span></dt><dt><span class="section"><a href="#N10E42"><code class="literal">ARGS_POST_NAMES</code></a></span></dt><dt><span class="section"><a href="#N10E50"><code class="literal">AUTH_TYPE</code></a></span></dt><dt><span class="section"><a href="#N10E66"><code class="literal">ENV</code></a></span></dt><dt><span class="section"><a href="#N10E7A"><code class="literal">FILES</code></a></span></dt><dt><span class="section"><a href="#N10E87"><code class="literal">FILES_COMBINED_SIZE</code></a></span></dt><dt><span class="section"><a href="#N10E94"><code class="literal">FILES_NAMES</code></a></span></dt><dt><span class="section"><a href="#N10EA1"><code class="literal">FILES_SIZES</code></a></span></dt><dt><span class="section"><a href="#N10EAE"><code class="literal">FILES_TMPNAMES</code></a></span></dt><dt><span class="section"><a href="#N10EBF"><code class="literal">GEO</code></a></span></dt><dt><span class="section"><a href="#N10F11"><code class="literal">HIGHEST_SEVERITY</code></a></span></dt><dt><span class="section"><a href="#N10F24"><code class="literal">MATCHED_VAR</code></a></span></dt><dt><span class="section"><a href="#N10F35"><code class="literal">MATCHED_VAR_NAME</code></a></span></dt><dt><span class="section"><a href="#N10F42"><code class="literal">MODSEC_BUILD</code></a></span></dt><dt><span class="section"><a href="#N10F4F"><code class="literal">MULTIPART_CRLF_LF_LINES</code></a></span></dt><dt><span class="section"><a href="#N10F7A"><code class="literal">MULTIPART_STRICT_ERROR</code></a></span></dt><dt><span class="section"><a href="#N10FC6"><code class="literal">MULTIPART_UNMATCHED_BOUNDARY</code></a></span></dt><dt><span class="section"><a href="#N10FDC"><code class="literal">PATH_INFO</code></a></span></dt><dt><span class="section"><a href="#N10FE9"><code class="literal">QUERY_STRING</code></a></span></dt><dt><span class="section"><a href="#N10FF6"><code class="literal">REMOTE_ADDR</code></a></span></dt><dt><span class="section"><a href="#N11003"><code class="literal">REMOTE_HOST</code></a></span></dt><dt><span class="section"><a href="#N11010"><code class="literal">REMOTE_PORT</code></a></span></dt><dt><span class="section"><a href="#N11021"><code class="literal">REMOTE_USER</code></a></span></dt><dt><span class="section"><a href="#N11033"><code class="literal">REQBODY_PROCESSOR</code></a></span></dt><dt><span class="section"><a href="#N1104C"><code class="literal">REQBODY_PROCESSOR_ERROR</code></a></span></dt><dt><span class="section"><a href="#N11064"><code class="literal">REQBODY_PROCESSOR_ERROR_MSG</code></a></span></dt><dt><span class="section"><a href="#N11071"><code class="literal">REQUEST_BASENAME</code></a></span></dt><dt><span class="section"><a href="#N11093"><code class="literal">REQUEST_BODY</code></a></span></dt><dt><span class="section"><a href="#N110C7"><code class="literal">REQUEST_COOKIES</code></a></span></dt><dt><span class="section"><a href="#N110D4"><code class="literal">REQUEST_COOKIES_NAMES</code></a></span></dt><dt><span class="section"><a href="#N110E1"><code class="literal">REQUEST_FILENAME</code></a></span></dt><dt><span class="section"><a href="#N110FD"><code class="literal">REQUEST_HEADERS</code></a></span></dt><dt><span class="section"><a href="#N11121"><code class="literal">REQUEST_HEADERS_NAMES</code></a></span></dt><dt><span class="section"><a href="#N1112E"><code class="literal">REQUEST_LINE</code></a></span></dt><dt><span class="section"><a href="#N1113B"><code class="literal">REQUEST_METHOD</code></a></span></dt><dt><span class="section"><a href="#N1114E"><code class="literal">REQUEST_PROTOCOL</code></a></span></dt><dt><span class="section"><a href="#N1115B"><code class="literal">REQUEST_URI</code></a></span></dt><dt><span class="section"><a href="#N11179"><code class="literal">REQUEST_URI_RAW</code></a></span></dt><dt><span class="section"><a href="#N11193"><code class="literal">RESPONSE_BODY</code></a></span></dt><dt><span class="section"><a href="#N111A2"><code class="literal">RESPONSE_CONTENT_LENGTH</code></a></span></dt><dt><span class="section"><a href="#N111B3"><code class="literal">RESPONSE_CONTENT_TYPE</code></a></span></dt><dt><span class="section"><a href="#N111BA"><code class="literal">RESPONSE_HEADERS</code></a></span></dt><dt><span class="section"><a href="#N111CE"><code class="literal">RESPONSE_HEADERS_NAMES</code></a></span></dt><dt><span class="section"><a href="#N111E0"><code class="literal">RESPONSE_PROTOCOL</code></a></span></dt><dt><span class="section"><a href="#N111ED"><code class="literal">RESPONSE_STATUS</code></a></span></dt><dt><span class="section"><a href="#N111FF"><code class="literal">RULE</code></a></span></dt><dt><span class="section"><a href="#N11224"><code class="literal">SCRIPT_BASENAME</code></a></span></dt><dt><span class="section"><a href="#N11236"><code class="literal">SCRIPT_FILENAME</code></a></span></dt><dt><span class="section"><a href="#N11248"><code class="literal">SCRIPT_GID</code></a></span></dt><dt><span class="section"><a href="#N1125A"><code class="literal">SCRIPT_GROUPNAME</code></a></span></dt><dt><span class="section"><a href="#N1126C"><code class="literal">SCRIPT_MODE</code></a></span></dt><dt><span class="section"><a href="#N1127E"><code class="literal">SCRIPT_UID</code></a></span></dt><dt><span class="section"><a href="#N11290"><code class="literal">SCRIPT_USERNAME</code></a></span></dt><dt><span class="section"><a href="#N112A2"><code class="literal">SERVER_ADDR</code></a></span></dt><dt><span class="section"><a href="#N112AF"><code class="literal">SERVER_NAME</code></a></span></dt><dt><span class="section"><a href="#N112C1"><code class="literal">SERVER_PORT</code></a></span></dt><dt><span class="section"><a href="#N112CE"><code class="literal">SESSION</code></a></span></dt><dt><span class="section"><a href="#N112E8"><code class="literal">SESSIONID</code></a></span></dt><dt><span class="section"><a href="#N112F9"><code class="literal">TIME</code></a></span></dt><dt><span class="section"><a href="#N11306"><code class="literal">TIME_DAY</code></a></span></dt><dt><span class="section"><a href="#N11313"><code class="literal">TIME_EPOCH</code></a></span></dt><dt><span class="section"><a href="#N11320"><code class="literal">TIME_HOUR</code></a></span></dt><dt><span class="section"><a href="#N1132D"><code class="literal">TIME_MIN</code></a></span></dt><dt><span class="section"><a href="#N1133A"><code class="literal">TIME_MON</code></a></span></dt><dt><span class="section"><a href="#N11347"><code class="literal">TIME_SEC</code></a></span></dt><dt><span class="section"><a href="#N11354"><code class="literal">TIME_WDAY</code></a></span></dt><dt><span class="section"><a href="#N11361"><code class="literal">TIME_YEAR</code></a></span></dt><dt><span class="section"><a href="#N1136E"><code class="literal">TX</code></a></span></dt><dt><span class="section"><a href="#N113A1"><code class="literal">USERID</code></a></span></dt><dt><span class="section"><a href="#N113B2"><code class="literal">WEBAPPID</code></a></span></dt><dt><span class="section"><a href="#N113C3"><code class="literal">WEBSERVER_ERROR_LOG</code></a></span></dt><dt><span class="section"><a href="#N113D0"><code class="literal">XML</code></a></span></dt></dl></dd><dt><span class="section"><a href="#transformation-functions">Transformation functions</a></span></dt><dd><dl><dt><span class="section"><a href="#N1142D"><code class="literal">base64Decode</code></a></span></dt><dt><span class="section"><a href="#N11434"><code class="literal">base64Encode</code></a></span></dt><dt><span class="section"><a href="#N1143B"><code class="literal">compressWhitespace</code></a></span></dt><dt><span class="section"><a href="#N11442">cssDecode</a></span></dt><dt><span class="section"><a href="#N11453"><code class="literal">escapeSeqDecode</code></a></span></dt><dt><span class="section"><a href="#N1148E"><code class="literal">hexDecode</code></a></span></dt><dt><span class="section"><a href="#N11495"><code class="literal">hexEncode</code></a></span></dt><dt><span class="section"><a href="#N1149C"><code class="literal">htmlEntityDecode</code></a></span></dt><dt><span class="section"><a href="#N114DE"><code class="literal">jsDecode</code></a></span></dt><dt><span class="section"><a href="#N114F1"><code class="literal">length</code></a></span></dt><dt><span class="section"><a href="#N114F8"><code class="literal">lowercase</code></a></span></dt><dt><span class="section"><a href="#N114FF"><code class="literal">md5</code></a></span></dt><dt><span class="section"><a href="#N1150A"><code class="literal"><code class="literal">none</code></code></a></span></dt><dt><span class="section"><a href="#N11513"><code class="literal">normalisePath</code></a></span></dt><dt><span class="section"><a href="#N1151A"><code class="literal">normalisePathWin</code></a></span></dt><dt><span class="section"><a href="#N11525"><code class="literal">parityEven7bit</code></a></span></dt><dt><span class="section"><a href="#N1152C"><code class="literal">parityOdd7bit</code></a></span></dt><dt><span class="section"><a href="#N11533"><code class="literal">parityZero7bit</code></a></span></dt><dt><span class="section"><a href="#N1153A"><code class="literal">removeNulls</code></a></span></dt><dt><span class="section"><a href="#N11541"><code class="literal">removeWhitespace</code></a></span></dt><dt><span class="section"><a href="#N11548"><code class="literal">replaceComments</code></a></span></dt><dt><span class="section"><a href="#N11557"><code class="literal">replaceNulls</code></a></span></dt><dt><span class="section"><a href="#N1155E"><code class="literal">urlDecode</code></a></span></dt><dt><span class="section"><a href="#N11569"><code class="literal">urlDecodeUni</code></a></span></dt><dt><span class="section"><a href="#N11584"><code class="literal">urlEncode</code></a></span></dt><dt><span class="section"><a href="#N1158B"><code class="literal">sha1</code></a></span></dt><dt><span class="section"><a href="#N11596"><code class="literal">trimLeft</code></a></span></dt><dt><span class="section"><a href="#N1159D"><code class="literal">trimRight</code></a></span></dt><dt><span class="section"><a href="#N115A4"><code class="literal">trim</code></a></span></dt></dl></dd><dt><span class="section"><a href="#actions">Actions</a></span></dt><dd><dl><dt><span class="section"><a href="#N115EC"><code class="literal">allow</code></a></span></dt><dt><span class="section"><a href="#N1163C">append</a></span></dt><dt><span class="section"><a href="#N1165E"><code class="literal">auditlog</code></a></span></dt><dt><span class="section"><a href="#N11678"><code class="literal">block</code></a></span></dt><dt><span class="section"><a href="#N116BD"><code class="literal">capture</code></a></span></dt><dt><span class="section"><a href="#N116D7"><code class="literal">chain</code></a></span></dt><dt><span class="section"><a href="#N116F2"><code class="literal">ctl</code></a></span></dt><dt><span class="section"><a href="#N11786"><code class="literal">deny</code></a></span></dt><dt><span class="section"><a href="#N1179B"><code class="literal">deprecatevar</code></a></span></dt><dt><span class="section"><a href="#N117B2"><code class="literal">drop</code></a></span></dt><dt><span class="section"><a href="#N117CC"><code class="literal">exec</code></a></span></dt><dt><span class="section"><a href="#N117F5"><code class="literal">expirevar</code></a></span></dt><dt><span class="section"><a href="#N1180F"><code class="literal">id</code></a></span></dt><dt><span class="section"><a href="#N1184E"><code class="literal">initcol</code></a></span></dt><dt><span class="section"><a href="#N11875"><code class="literal">log</code></a></span></dt><dt><span class="section"><a href="#N1188E"><code class="literal">logdata</code></a></span></dt><dt><span class="section"><a href="#N118A7"><code class="literal">msg</code></a></span></dt><dt><span class="section"><a href="#N118C3"><code class="literal">multiMatch</code></a></span></dt><dt><span class="section"><a href="#N118DC"><code class="literal">noauditlog</code></a></span></dt><dt><span class="section"><a href="#N118F9"><code class="literal">nolog</code></a></span></dt><dt><span class="section"><a href="#N11912"><code class="literal">pass</code></a></span></dt><dt><span class="section"><a href="#N11941"><code class="literal">pause</code></a></span></dt><dt><span class="section"><a href="#N1195A"><code class="literal">phase</code></a></span></dt><dt><span class="section"><a href="#N11974">prepend</a></span></dt><dt><span class="section"><a href="#N11996"><code class="literal">proxy</code></a></span></dt><dt><span class="section"><a href="#N119AF"><code class="literal">redirect</code></a></span></dt><dt><span class="section"><a href="#N119CC"><code class="literal">rev</code></a></span></dt><dt><span class="section"><a href="#N119EA"><code class="literal">sanitiseArg</code></a></span></dt><dt><span class="section"><a href="#N11A03"><code class="literal">sanitiseMatched</code></a></span></dt><dt><span class="section"><a href="#N11A1F"><code class="literal">sanitiseRequestHeader</code></a></span></dt><dt><span class="section"><a href="#N11A38"><code class="literal">sanitiseResponseHeader</code></a></span></dt><dt><span class="section"><a href="#N11A51"><code class="literal">severity</code></a></span></dt><dt><span class="section"><a href="#N11A86"><code class="literal">setuid</code></a></span></dt><dt><span class="section"><a href="#N11AA8"><code class="literal">setsid</code></a></span></dt><dt><span class="section"><a href="#N11ACD"><code class="literal">setenv</code></a></span></dt><dt><span class="section"><a href="#N11AEF"><code class="literal">setvar</code></a></span></dt><dt><span class="section"><a href="#N11B15"><code class="literal">skip</code></a></span></dt><dt><span class="section"><a href="#N11B30"><code class="literal">skipAfter</code></a></span></dt><dt><span class="section"><a href="#N11B52"><code class="literal">status</code></a></span></dt><dt><span class="section"><a href="#N11B74"><code class="literal">t</code></a></span></dt><dt><span class="section"><a href="#N11B8D"><code class="literal">tag</code></a></span></dt><dt><span class="section"><a href="#N11BA7"><code class="literal">xmlns</code></a></span></dt></dl></dd><dt><span class="section"><a href="#operators">Operators</a></span></dt><dd><dl><dt><span class="section"><a href="#N11BC6"><code class="literal">beginsWith</code></a></span></dt><dt><span class="section"><a href="#N11BDE"><code class="literal">contains</code></a></span></dt><dt><span class="section"><a href="#N11BF2"><code class="literal">endsWith</code></a></span></dt><dt><span class="section"><a href="#N11C06"><code class="literal">eq</code></a></span></dt><dt><span class="section"><a href="#N11C17"><code class="literal">ge</code></a></span></dt><dt><span class="section"><a href="#N11C28"><code class="literal">geoLookup</code></a></span></dt><dt><span class="section"><a href="#N11C51"><code class="literal">gt</code></a></span></dt><dt><span class="section"><a href="#N11C62"><code class="literal">inspectFile</code></a></span></dt><dt><span class="section"><a href="#N11C84"><code class="literal">le</code></a></span></dt><dt><span class="section"><a href="#N11C95"><code class="literal">lt</code></a></span></dt><dt><span class="section"><a href="#N11CA6"><code class="literal">pm</code></a></span></dt><dt><span class="section"><a href="#N11CB9"><code class="literal">pmFromFile</code></a></span></dt><dt><span class="section"><a href="#N11CDF"><code class="literal">rbl</code></a></span></dt><dt><span class="section"><a href="#N11CF0"><code class="literal">rx</code></a></span></dt><dt><span class="section"><a href="#N11D2A"><code class="literal">streq</code></a></span></dt><dt><span class="section"><a href="#N11D3E"><code class="literal">validateByteRange</code></a></span></dt><dt><span class="section"><a href="#N11D64"><code class="literal">validateDTD</code></a></span></dt><dt><span class="section"><a href="#N11D78"><code class="literal">validateSchema</code></a></span></dt><dt><span class="section"><a href="#N11D8C"><code class="literal">validateUrlEncoding</code></a></span></dt><dt><span class="section"><a href="#N11DA6"><code class="literal">validateUtf8Encoding</code></a></span></dt><dt><span class="section"><a href="#N11DC8"><code class="literal">verifyCC</code></a></span></dt><dt><span class="section"><a href="#N11DD9"><code class="literal">within</code></a></span></dt></dl></dd><dt><span class="section"><a href="#N11DF1">Macro Expansion</a></span></dt><dt><span class="section"><a href="#N11DFF">Persistant Storage</a></span></dt><dt><span class="section"><a href="#N11E63">Miscellaneous Topics</a></span></dt><dd><dl><dt><span class="section"><a href="#N11E67">Impedance Mismatch</a></span></dt></dl></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="introduction"></a>Introduction</h2></div></div><div></div></div><p>ModSecurity is a web application firewall (WAF). With over 70% of
   6     attacks now carried out over the web application level, organisations need
   7     all the help they can get in making their systems secure. WAFs are
   8     deployed to establish an increased external security layer to detect
   9     and/or prevent attacks before they reach web applications. ModSecurity
  10     provides protection from a range of attacks against web applications and
  11     allows for HTTP traffic monitoring and real-time analysis with little or
  12     no changes to existing infrastructure.</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1001D"></a>HTTP Traffic Logging</h3></div></div><div></div></div><p>Web servers are typically well-equipped to log traffic in a form
  13       useful for marketing analyses, but fall short logging traffic to web
  14       applications. In particular, most are not capable of logging the request
  15       bodies. Your adversaries know this, and that is why most attacks are now
  16       carried out via POST requests, rendering your systems blind. ModSecurity
  17       makes full HTTP transaction logging possible, allowing complete requests
  18       and responses to be logged. Its logging facilities also allow
  19       fine-grained decisions to be made about exactly what is logged and when,
  20       ensuring only the relevant data is recorded. As some of the request
  21       and/or response may contain sensitive data in certain fields,
  22       ModSecurity can be configured to mask these fields before they are
  23       written to the audit log.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10022"></a>Real-Time Monitoring and Attack Detection</h3></div></div><div></div></div><p>In addition to providing logging facilities, ModSecurity can
  24       monitor the HTTP traffic in real time in order to detect attacks. In
  25       this case, ModSecurity operates as a web intrusion detection tool,
  26       allowing you to react to suspicious events that take place at your web
  27       systems.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10027"></a>Attack Prevention and Just-in-time Patching</h3></div></div><div></div></div><p>ModSecurity can also act immediately to prevent attacks from
  28       reaching your web applications. There are three commonly used
  29       approaches:</p><div class="orderedlist"><ol type="1"><li><p>Negative security model. A negative security model monitors
  30           requests for anomalies, unusual behaviour, and common web
  31           application attacks. It keeps anomaly scores for each request, IP
  32           addresses, application sessions, and user accounts. Requests with
  33           high anomaly scores are either logged or rejected altogether.</p></li><li><p>Positive security model. When a positive security model is
  34           deployed, only requests that are known to be valid are accepted,
  35           with everything else rejected. This model requires knownledge of the
  36           web applications you are protecting. Therefore a positive security
  37           model works best with applications that are heavily used but rarely
  38           updated so that maintenance of the model is minimized.</p></li><li><p>Known weaknesses and vulnerabilities. Its rule language makes
  39           ModSecurity an ideal external patching tool. External patching
  40           (sometimes referred to as Virtual Patching) is about reducing the
  41           window of opportunity. Time needed to patch application
  42           vulnerabilities often runs to weeks in many organisations. With
  43           ModSecurity, applications can be patched from the outside, without
  44           touching the application source code (and even without any access to
  45           it), making your systems secure until a proper patch is applied to
  46           the application.</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10038"></a>Flexible Rule Engine</h3></div></div><div></div></div><p>A flexible rule engine sits in the heart of ModSecurity. It
  47       implements the ModSecurity Rule Language, which is a specialised
  48       programming language designed to work with HTTP transaction data. The
  49       ModSecurity Rule Language is designed to be easy to use, yet flexible:
  50       common operations are simple while complex operations are possible.
  51       Certified ModSecurity Rules, included with ModSecurity, contain a
  52       comprehensive set of rules that implement general-purpose hardening,
  53       protocol validation and detection of common web application security
  54       issues. Heavily commented, these rules can be used as a learning
  55       tool.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1003D"></a>Embedded-mode Deployment</h3></div></div><div></div></div><p>ModSecurity is an embeddable web application firewall, which means
  56       it can be deployed as part of your existing web server infrastructure
  57       provided your web servers are Apache-based. This deployment method has
  58       certain advantages:</p><div class="orderedlist"><ol type="1"><li><p>No changes to existing network. It only takes a few minutes to
  59           add ModSecurity to your existing web servers. And because it was
  60           designed to be completely passive by default, you are free to deploy
  61           it incrementally and only use the features you need. It is equally
  62           easy to remove or deactivate it if required.</p></li><li><p>No single point of failure. Unlike with network-based
  63           deployments, you will not be introducing a new point of failure to
  64           your system.</p></li><li><p>Implicit load balancing and scaling. Because it works embedded
  65           in web servers, ModSecurity will automatically take advantage of the
  66           additional load balancing and scalability features. You will not
  67           need to think of load balancing and scaling unless your existing
  68           system needs them.</p></li><li><p>Minimal overhead. Because it works from inside the web server
  69           process there is no overhead for network communication and minimal
  70           overhead in parsing and data exchange.</p></li><li><p>No problem with encrypted or compressed content. Many IDS
  71           systems have difficulties analysing SSL traffic. This is not a
  72           problem for ModSecurity because it is positioned to work when the
  73           traffic is decrypted and decompressed.</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10054"></a>Network-based Deployment</h3></div></div><div></div></div><p>ModSecurity works equally well when deployed as part of an
  74       Apache-based reverse proxy server, and many of our customers choose to
  75       do so. In this scenario, one installation of ModSecurity can protect any
  76       number of web servers (even the non-Apache ones).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10059"></a>Portability</h3></div></div><div></div></div><p>ModSecurity is known to work well on a wide range of operating
  77       systems. Our customers are successfully running it on Linux, Windows,
  78       Solaris, FreeBSD, OpenBSD, NetBSD, AIX, Mac OS X, and HP-UX.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="licensing"></a>Licensing</h3></div></div><div></div></div><p>ModSecurity is available under two licenses. Users can choose to
  79       use the software under the terms of the GNU General Public License
  80       version 2 (licence text is included with the distribution), as an Open
  81       Source / Free Software product. A range of commercial licenses is also
  82       available, together with a range of commercial support contracts. For
  83       more information on commercial licensing please contact Breach
  84       Security.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>ModSecurity, mod_security, ModSecurity Pro, and ModSecurity Core
  85         Rules are trademarks or registered trademarks of Breach Security,
  86         Inc.</p></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N10067"></a><span class="trademark">ModSecurity Core Rules</span>&trade;</h2></div></div><div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1006C"></a>Overview</h3></div></div><div></div></div><p>ModSecurity is a web application firewall engine that provides
  87       very little protection on its own. In order to become useful,
  88       ModSecurity must be configured with rules. In order to enable users to
  89       take full advantage of ModSecurity out of the box, Breach Security, Inc.
  90       is providing a free certified rule set for ModSecurity 2.x. Unlike
  91       intrusion detection and prevention systems, which rely on signatures
  92       specific to known vulnerabilities, the Core Rules provide generic
  93       protection from unknown vulnerabilities often found in web applications,
  94       which are in most cases custom coded. The Core Rules are heavily
  95       commented to allow it to be used as a step-by-step deployment guide for
  96       ModSecurity. The latest Core Rules can be found at the ModSecurity
  97       website - <a href="http://www.modsecurity.org/projects/rules/" target="_top">http://www.modsecurity.org/projects/rules/</a>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10075"></a>Core Rules Content</h3></div></div><div></div></div><p>In order to provide generic web applications protection, the Core
  98       Rules use the following techniques:</p><div class="itemizedlist"><ul type="disc"><li><p>HTTP protection - detecting violations of the HTTP protocol
  99           and a locally defined usage policy.</p></li><li><p>Common Web Attacks Protection - detecting common web
 100           application security attack.</p></li><li><p>Automation detection - Detecting bots, crawlers, scanners and
 101           other surface malicious activity.</p></li><li><p>Trojan Protection - Detecting access to Trojans horses.</p></li><li><p>Error Hiding - Disguising error messages sent by the
 102           server.</p></li></ul></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="installation"></a>Installation</h2></div></div><div></div></div><p>ModSecurity installation requirements:</p><div class="orderedlist"><ol type="1"><li><p>ModSecurity 2.x works only with Apache 2.0.x or higher. Version
 103         2.2.x is highly recommended.</p></li><li><p>Make sure you have <code class="literal">mod_unique_id</code> installed.</p><p>mod_unique_id is packaged with Apache httpd.</p></li><li><p>libapr and libapr-util</p><p><a href="http://apr.apache.org/" target="_top">http://apr.apache.org/</a></p></li><li><p>libpcre</p><p><a href="http://www.pcre.org/" target="_top">http://www.pcre.org/</a></p></li><li><p>libxml2</p><p><a href="http://xmlsoft.org/downloads.html" target="_top">http://xmlsoft.org/downloads.html</a></p></li><li><p>liblua v5.1.x</p><p>This library is optional and only needed if you will be using
 104         the new Lua engine.</p><p><a href="http://www.lua.org/download.html" target="_top">http://www.lua.org/download.html</a></p><p>Note that ModSecurity requires the dynamic libraries. These are
 105         not built by default in the source distribution, so the binary
 106         distribution is recommended.</p></li><li><p>libcurl v7.15.1 or higher</p><p>If you will be using the ModSecurity Log Collector (mlogc) to
 107         send audit logs to a central repository, then you will also need the
 108         curl library.</p><p><a href="http://curl.haxx.se/libcurl/" target="_top">http://curl.haxx.se/libcurl/</a></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Many have had issues with libcurl linked with the GnuTLS
 109           library for SSL/TLS support.  It is recommended that the
 110           openssl library be used for SSL/TLS support in libcurl.</p></div></li></ol></div><p>ModSecurity installation consists of the following steps:</p><div class="orderedlist"><ol type="1"><li><p>Stop Apache httpd</p></li><li><p>Unpack the ModSecurity archive</p></li><li><p>Building differs for UNIX (or UNIX-like) operating systems and
 111         Windows.</p><div class="itemizedlist"><ul type="disc"><li><p>UNIX</p><div class="orderedlist"><ol type="a"><li><p>Run the configure script to generate a Makefile.
 112                 Typically no options are needed.</p><p><code class="literal">./configure</code></p><p>Options are available for more customization (use
 113                 <code class="literal">./configure --help</code> for a full list), but
 114                 typically you will only need to specify the location of the
 115                 <code class="literal">apxs</code> command installed by Apache httpd with
 116                 the <code class="literal">--with-apxs</code> option.</p><p><code class="literal">./configure
 117                 --with-apxs=/path/to/httpd-2.x.y/bin/apxs</code></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>There are certain configure options that are meant for
 118                   debugging an other development use. If enabled, these
 119                   options can substantially impact performance. These options
 120                   include all <code class="literal">--debug-*</code> options as well as
 121                   the <code class="literal">--enable-performance-measurements</code>
 122                   options.</p></div></li><li><p>Compile with: <code class="literal">make</code></p></li><li><p>Optionally test with: <code class="literal">make
 123                 test</code></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This is step is still a bit experimental. If you have
 124                   problems, please send the full output and error from the
 125                   build to the support list. Most common issues are related to
 126                   not finding the required headers and/or libraries.</p></div></li><li><p>Optionally build the ModSecurity Log Collector with:
 127                 <code class="literal">make mlogc</code></p></li><li><p>Optionally install <code class="literal">mlogc</code>: Review the
 128                 <code class="literal">INSTALL</code> file included in the
 129                 apache2/mlogc-src directory in the distribution.</p></li><li><p>Install the ModSecurity module with: <code class="literal">make
 130                 install</code></p></li></ol></div></li><li><p>Windows (MS VC++ 8)</p><div class="orderedlist"><ol type="a"><li><p>Edit <code class="literal">Makefile.win</code> to configure the
 131                 Apache base and library paths.</p></li><li><p>Compile with: <code class="literal">nmake -f
 132                 Makefile.win</code></p></li><li><p>Install the ModSecurity module with: <code class="literal">nmake -f
 133                 Makefile.win install</code></p></li><li><p>Copy the <code class="literal">libxml2.dll</code> and
 134                 <code class="literal">lua5.1.dll</code> to the Apache
 135                 <code class="literal">bin</code> directory. Alternatively you can follow
 136                 the step below for using LoadFile to load these
 137                 libraries.</p></li></ol></div></li></ul></div></li><li><p>Edit the main Apache httpd config file (usually
 138         <code class="literal">httpd.conf</code>)</p><p>On UNIX (and Windows if you did not copy the DLLs as stated
 139         above) you must load libxml2 and lua5.1 before ModSecurity with
 140         something like this:</p><p><pre class="programlisting">LoadFile /usr/lib/libxml2.so
 141 LoadFile /usr/lib/liblua5.1.so</pre></p><p>Load the ModSecurity module with:<pre class="programlisting">LoadModule security2_module modules/mod_security2.so</pre></p></li><li><p>Configure ModSecurity</p></li><li><p>Start Apache httpd</p></li><li><p>You should now have ModSecurity 2.x up and running.</p></li></ol></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>If you have compiled Apache yourself you might experience problems
 142       compiling ModSecurity against PCRE. This is because Apache bundles PCRE
 143       but this library is also typically provided by the operating system. I
 144       would expect most (all) vendor-packaged Apache distributions to be
 145       configured to use an external PCRE library (so this should not be a
 146       problem).</p><p>You want to avoid Apache using the bundled PCRE library and
 147       ModSecurity linking against the one provided by the operating system.
 148       The easiest way to do this is to compile Apache against the PCRE library
 149       provided by the operating system (or you can compile it against the
 150       latest PCRE version you downloaded from the main PCRE distribution
 151       site). You can do this at configure time using the<code class="literal"> --with-pcre</code> switch. If you are not in a
 152       position to recompile Apache, then, to compile ModSecurity successfully,
 153       you'd still need to have access to the bundled PCRE headers (they are
 154       available only in the Apache source code) and change the include path
 155       for ModSecurity (as you did in step 7 above) to point to them (via the
 156       <code class="literal">--with-pcre</code> ModSecurity configure option).</p><p>Do note that if your Apache is using an external PCRE library you
 157       can compile ModSecurity with <code class="literal">WITH_PCRE_STUDY</code> defined,which would possibly
 158       give you a slight performance edge in regular expression
 159       processing.</p><p>Non-gcc compilers may have problems running out-of-the-box as the
 160       current build system was designed around the gcc compiler and some
 161       compiler/linker flags may differ. To use a non-gcc compiler you may need
 162       some manual Makefile tweaks if issues cannot be solved by exporting
 163       custom CFLAGS and CPPFLAGS environment variables.</p><p>If you are upgrading from ModSecurity 1.x, please refer to the
 164       migration matrix at <a href="http://www.modsecurity.org/documentation/ModSecurity-Migration-Matrix.pdf" target="_top">http://www.modsecurity.org/documentation/ModSecurity-Migration-Matrix.pdf</a></p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="configuration-directives"></a>Configuration Directives</h2></div></div><div></div></div><p>The following section outlines all of the ModSecurity directives.
 165     Most of the ModSecurity directives can be used inside the various Apache
 166     Scope Directives such as <code class="literal">VirtualHost</code>,
 167     <code class="literal">Location</code>, <code class="literal">LocationMatch</code>,
 168     <code class="literal">Directory</code>, etc... There are others, however, that can
 169     only be used once in the main configuration file. This information is
 170     specified in the Scope sections below. The first version to use a given
 171     directive is given in the Version sections below.</p><p>These rules, along with the Core rules files, should be contained is
 172     files outside of the httpd.conf file and called up with Apache "Include"
 173     directives. This allows for easier updating/migration of the rules. If you
 174     create your own custom rules that you would like to use with the Core
 175     rules, you should create a file called -
 176     <code class="filename">modsecurity_crs_15_customrules.conf</code> and place it in
 177     the same directory as the Core rules files. By using this file name, your
 178     custom rules will be called up after the standard ModSecurity Core rules
 179     configuration file but before the other Core rules. This allows your rules
 180     to be evaluated first which can be useful if you need to implement
 181     specific "allow" rules or to correct any false positives in the Core rules
 182     as they are applied to your site.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>It is highly encouraged that you do not edit the Core rules files
 183       themselves but rather place all changes (such as
 184       <code class="literal">SecRuleRemoveByID</code>, etc...) in your custom rules file.
 185       This will allow for easier upgrading as newer Core rules are released by
 186       Breach Security on the ModSecurity website.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N101B0"></a><code class="literal">SecAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Unconditionally processes the
 187       action list it receives as the first and only parameter. It accepts one
 188       parameter, the syntax of which is identical to the third parameter
 189       of<code class="literal"> SecRule</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAction
 190       action1,action2,action3</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAction
 191       nolog,phase:1,initcol:RESOURCE=%{REQUEST_FILENAME}</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>SecAction is best used when you unconditionally execute an action.
 192       This is explicit triggering whereas the normal Actions are conditional
 193       based on data inspection of the request/response. This is a useful
 194       directive when you want to run certain actions such as
 195       <code class="literal">initcol</code> to initialize collections.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N101E1"></a><code class="literal">SecArgumentSeparator</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Specifies which character to use
 196       as separator for<code class="literal">
 197       application/x-www-form-urlencoded</code> content. Defaults to
 198       <code class="literal">&amp;</code>. Applications are sometimes
 199       (very rarely) written to use a semicolon (<code class="literal">;</code>).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecArgumentSeparator character</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecArgumentSeparator ;</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>This directive is needed if a backend web application is using a
 200       non-standard argument separator. If this directive is not set properly
 201       for each web application, then ModSecurity will not be able to parse the
 202       arguments appropriately and the effectiveness of the rule matching will
 203       be significantly decreased.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10216"></a><code class="literal">SecAuditEngine</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the audit logging
 204       engine.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditEngine On|Off|RelevantOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditEngine On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Can be set/changed with
 205       the "<code class="literal">ctl</code>" action for the current transaction.</p><p>Example: The following example shows the various audit directives
 206       used together.</p><pre class="programlisting"><span class="emphasis"><em>SecAuditEngine RelevantOnly</em></span>
 207 SecAuditLog logs/audit/audit.log
 208 SecAuditLogParts ABCFHZ
 209 SecAuditLogType concurrent
 210 SecAuditLogStorageDir logs/audit
 211 <span class="emphasis"><em>SecAuditLogRelevantStatus ^(?:5|4\d[^4])</em></span></pre><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - log all transactions
 212           by default.</p></li><li><p><code class="literal">Off</code> - do not log
 213           transactions by default.</p></li><li><p><code class="literal">RelevantOnly</code> - by default
 214           only log transactions that have triggered a warning or an error, or
 215           have a status code that is considered to be relevant (see<code class="literal"> SecAuditLogRelevantStatus</code>).</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10263"></a><code class="literal">SecAuditLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the main
 216       audit log file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLog
 217       /path/to/auditlog</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLog
 218       /usr/local/apache/logs/audit.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This file is open on
 219       startup when the server typically still runs as<span class="emphasis"><em>
 220       root</em></span>. You should not allow non-root users to have write
 221       privileges for this file or for the directory it is stored in..</p><p>This file will be used to store the audit log entries if serial
 222       audit logging format is used. If concurrent audit logging format is used
 223       this file will be used as an index, and contain a record of all audit
 224       log files created. If you are planning to use Concurrent audit logging
 225       and sending your audit log data off to a remote Console host or
 226       commercial ModSecurity Management Appliance, then you will need to
 227       configure and use the ModSecurity Log Collector (mlogc) and use the
 228       following format for the audit log:</p><p><pre class="programlisting">SecAuditLog "|/path/to/mlogc /path/to/mlogc.conf"</pre></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10293"></a><code class="literal">SecAuditLog2</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the
 229       secondary audit log index file when concurrent logging is enabled. See
 230       <code class="literal">SecAuditLog2</code> for more details.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLog2
 231       /path/to/auditlog2</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLog2
 232       /usr/local/apache/logs/audit2.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.1.2</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> A main audit log must be
 233       defined via <code class="literal">SecAuditLog</code> before this
 234       directive may be used. Additionally, this log is only used for
 235       replicating the main audit log index file when concurrent audit logging
 236       is used. It will <span class="emphasis"><em>not</em></span> be used for non-concurrent
 237       audit logging.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102C5"></a><code class="literal">SecAuditLogDirMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
 238       (permissions) of any directories created for concurrent audit logs using
 239       an octal mode (as used in chmod). See <code class="literal">SecAuditLogFileMode</code> for controlling the mode
 240       of audit log files.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogDirMode octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogDirMode 02750</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.10</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
 241       available on operating systems not supporting octal file modes. The
 242       default mode (0600) only grants read/write access to the account writing
 243       the file. If access from another account is needed (using mpm-itk is a
 244       good example), then this directive may be required. However, use this
 245       directive with caution to avoid exposing potentially sensitive data to
 246       unauthorized users. Using the value "default" will revert back to the
 247       default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
 248         restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N102F3"></a><code class="literal">SecAuditLogFileMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
 249       (permissions) of any files created for concurrent audit logs using an
 250       octal mode (as used in chmod). See <code class="literal">SecAuditLogDirMode</code> for controlling the mode of
 251       created audit log directories.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogFileMode
 252       octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogFileMode 00640</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.10</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
 253       available on operating systems not supporting octal file modes. The
 254       default mode (0600) only grants read/write access to the account writing
 255       the file. If access from another account is needed (using mpm-itk is a
 256       good example), then this directive may be required. However, use this
 257       directive with caution to avoid exposing potentially sensitive data to
 258       unauthorized users. Using the value "default" will revert back to the
 259       default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
 260         restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10321"></a><code class="literal">SecAuditLogParts</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines which part of each
 261       transaction are going to be recorded in audit log. Each part is assigned
 262       a single letter. If a letter appears in the list then the equivalent
 263       part of each transactions will be recorded. See below for the list of
 264       all parts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogParts PARTS</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogParts ABCFHZ</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> At this time ModSecurity
 265       does not log response bodies of stock Apache responses (e.g. <code class="literal">404</code>), or the <code class="literal">Server</code> and <code class="literal">Date</code> response headers.</p><p>Default:<code class="literal"> ABCFHZ</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please refer to the ModSecurity Data Formats document for a
 266         detailed description of every available part.</p></div><p>Available audit log parts:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">A</code> - audit log header
 267           (mandatory)</p></li><li><p><code class="literal">B</code> - request headers</p></li><li><p><code class="literal">C</code> - request body (present
 268           only if the request body exists and ModSecurity is configured to
 269           intercept it)</p></li><li><p><code class="literal">D</code> - RESERVED for
 270           intermediary response headers, not implemented yet.</p></li><li><p><code class="literal">E</code> - intermediary response
 271           body (present only if ModSecurity is configured to intercept
 272           response bodies, and if the audit log engine is configured to record
 273           it). Intermediary response body is the same as the actual response
 274           body unless ModSecurity intercepts the intermediary response body,
 275           in which case the actual response body will contain the error
 276           message (either the Apache default error message, or the
 277           ErrorDocument page).</p></li><li><p><code class="literal">F</code> - final response headers
 278           (excluding the Date and Server headers, which are always added by
 279           Apache in the late stage of content delivery).</p></li><li><p><code class="literal">G</code> - RESERVED for the actual
 280           response body, not implemented yet.</p></li><li><p><code class="literal">H</code> - audit log
 281           trailer</p></li><li><p><code class="literal">I</code> - This part is a
 282           replacement for part C. It will log the same data as C in all cases
 283           except when <code class="literal">multipart/form-data</code>
 284           encoding in used. In this case it will log a fake <code class="literal">application/x-www-form-urlencoded</code> body
 285           that contains the information about parameters but not about the
 286           files. This is handy if you don't want to have (often large) files
 287           stored in your audit logs.</p></li><li><p><code class="literal">J</code> - RESERVED. This part,
 288           when implemented, will contain information about the files uploaded
 289           using <code class="literal">multipart/form-data</code> encoding.</p></li><li><p><code class="literal">K</code> - This part contains a
 290           full list of every rule that matched (one per line) in the order
 291           they were matched. The rules are fully qualified and will thus show
 292           inherited actions and default operators. Supported as of
 293           v2.5.0</p></li><li><p><code class="literal">Z</code> - final boundary,
 294           signifies the end of the entry (mandatory)</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N103B4"></a><code class="literal">SecAuditLogRelevantStatus</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures which response status
 295       code is to be considered relevant for the purpose of audit
 296       logging.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogRelevantStatus REGEX</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogRelevantStatus
 297       ^(?:5|4\d[^4])</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Must have the
 298       <code class="literal">SecAuditEngine</code> set to
 299       <code class="literal">RelevantOnly</code>. The parameter is a regular
 300       expression.</p><p>The main purpose of this directive is to allow you to configure
 301       audit logging for only transactions that generate the specified HTTP
 302       Response Status Code. This directive is often used to the decrease the
 303       total size of the audit log file. Keep in mind that if this parameter is
 304       used, then successful attacks that result in a 200 OK status code will
 305       not be logged.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N103E5"></a><code class="literal">SecAuditLogStorageDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the storage directory
 306       where concurrent audit log entries are to be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogStorageDir
 307       /path/to/storage/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogStorageDir
 308       /usr/local/apache/logs/audit</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> SecAuditLogType must be
 309       set to Concurrent. The directory must already be created before starting
 310       Apache and it must be writable by the web server user as new files are
 311       generated at runtime.</p><p>As with all logging mechanisms, ensure that you specify a file
 312       system location that has adequate disk space and is not on the root
 313       partition.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1040E"></a><code class="literal">SecAuditLogType</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the type of audit
 314       logging mechanism to be used.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecAuditLogType Serial|Concurrent</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecAuditLogType Serial</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Must specify
 315       <code class="literal">SecAuditLogStorageDir</code> if you use concurrent
 316       logging.</p><p>Possible values are:</p><div class="orderedlist"><ol type="1"><li><p><code class="literal">Serial</code> - all audit log
 317           entries will be stored in the main audit logging file. This is more
 318           convenient for casual use but it is slower as only one audit log
 319           entry can be written to the file at any one file.</p></li><li><p><code class="literal">Concurrent</code> - audit log
 320           entries will be stored in separate files, one for each transaction.
 321           Concurrent logging is the mode to use if you are going to send the
 322           audit log data off to a remote ModSecurity Console host.</p></li></ol></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1044A"></a><code class="literal">SecCacheTransformations</code>
 323       (Deprecated/Experimental)</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Controls caching of
 324       transformations. Caching is off by default starting with 2.5.6, when it
 325       was deprecated and downgraded back to experimental.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecCacheTransformations On|Off
 326       [options]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecCacheTransformations On
 327       "minlen:64,maxlen:0"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> N/A</p><p>First parameter:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - cache transformations
 328           (per transaction, per phase) allowing identical transformations to
 329           be performed only once. (default)</p></li><li><p><code class="literal">Off</code> - do not cache any
 330           transformations, forcing all transformations to be performed for
 331           each rule executed.</p></li></ul></div><p>The following options are allowed (comma separated):</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">incremental:on|off</code> -
 332           enabling this option will cache every transformation instead of just
 333           the final transformation. (default: off)</p></li><li><p><code class="literal">maxitems:N</code> - do not allow
 334           more than N transformations to be cached. The cache will then be
 335           disabled. A zero value is interpreted as "unlimited". This option
 336           may be useful to limit caching for a form with a large number of
 337           ARGS. (default: 512)</p></li><li><p><code class="literal">minlen:N</code> - do not cache the
 338           transformation if the value's length is less than N bytes. (default:
 339           32)</p></li><li><p><code class="literal">maxlen:N</code> - do not cache the
 340           transformation if the value's length is more than N bytes. A zero
 341           value is interpreted as "unlimited". (default: 1024)</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1049C"></a><code class="literal">SecChrootDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory path
 342       that will be used to jail the web server process.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecChrootDir
 343       /path/to/chroot/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecChrootDir /chroot</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
 344       available on Windows builds. The internal chroot functionality provided
 345       by ModSecurity works great for simple setups. One example of a simple
 346       setup is Apache serving static files only, or running scripts using
 347       modules.builds. Some problems you might encounter with more complex
 348       setups:</p><div class="orderedlist"><ol type="1"><li><p>DNS lookups do not work (this is because this feature requires
 349           a shared library that is loaded on demand, after chroot takes
 350           place).</p></li><li><p>You cannot send email from PHP because it uses sendmail and
 351           sendmail is outside the jail.</p></li><li><p>In some cases Apache graceful (reload) no longer works.</p></li></ol></div><p>You should be aware that the internal chroot feature might not be
 352       100% reliable. Due to the large number of default and third-party
 353       modules available for the Apache web server, it is not possible to
 354       verify the internal chroot works reliably with all of them. A module,
 355       working from within Apache, can do things that make it easy to break out
 356       of the jail. In particular, if you are using any of the modules that
 357       fork in the module initialisation phase (e.g.
 358       <code class="literal">mod_fastcgi</code>, <code class="literal">mod_fcgid</code>,
 359       <code class="literal">mod_cgid</code>), you are advised to examine each Apache
 360       process and observe its current working directory, process root, and the
 361       list of open files. Consider what your options are and make your own
 362       decision.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N104DD"></a><code class="literal">SecComponentSignature</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description</em></span>: Appends component signature to
 363       the ModSecurity signature.</p><p><span class="emphasis"><em>Syntax</em></span>: <code class="literal">SecComponentSignature
 364       "COMPONENT_NAME/X.Y.Z (COMMENT)"</code></p><p><span class="emphasis"><em>Example usage</em></span>: <code class="literal">SecComponentSignature
 365       "Core Rules/1.2.3"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope</em></span>: Main</p><p><span class="emphasis"><em>Version</em></span>: 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes</em></span>: This directive should be
 366       used to make the presence of significant ModSecurity components known.
 367       The entire signature will be recorded in transaction audit log. It
 368       should be used by ModSecurity module and rule set writers to make
 369       debugging easier.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10504"></a><code class="literal">SecContentInjection</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Enables content injection using
 370       actions <code class="literal">append</code> and <code class="literal">prepend</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecContentInjection
 371       (On|Off)</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecContentInjection
 372       On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope</em></span>: Any</p><p><span class="emphasis"><em>Version</em></span>: 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> N/A</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10533"></a><code class="literal">SecCookieFormat</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Selects the cookie format that
 373       will be used in the current configuration context.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecCookieFormat 0|1</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecCookieFormat 0</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">0</code> - use version 0
 374           (Netscape) cookies. This is what most applications use. It is the
 375           default value.</p></li><li><p><code class="literal">1</code> - use version 1
 376           cookies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10569"></a><code class="literal">SecDataDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Path where persistent data (e.g.
 377       IP address data, session data, etc) is to be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDataDir
 378       /path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDataDir /usr/local/apache/logs/data</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Dependencies/Notes: </em></span> This directive is needed
 379       when initcol, setsid an setuid are used. Must be writable by the web
 380       server user.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1058C"></a><code class="literal">SecDebugLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Path to the ModSecurity debug
 381       log file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDebugLog
 382       /path/to/modsec-debug.log</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDebugLog
 383       /usr/local/apache/logs/modsec-debug.log</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N105B3"></a><code class="literal">SecDebugLogLevel</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the verboseness of
 384       the debug log data.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDebugLogLevel 0|1|2|3|4|5|6|7|8|9</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDebugLogLevel 4</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Levels <code class="literal">1 - 3</code> are always sent to the Apache error log.
 385       Therefore you can always use level <code class="literal">0</code>
 386       as the default logging level in production. Level <code class="literal">5</code> is useful when debugging. It is not
 387       advisable to use higher logging levels in production as excessive
 388       logging can slow down server significantly.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">0</code> - no logging.</p></li><li><p><code class="literal">1</code> - errors (intercepted
 389           requests) only.</p></li><li><p><code class="literal">2</code> - warnings.</p></li><li><p><code class="literal">3</code> - notices.</p></li><li><p><code class="literal">4</code> - details of how
 390           transactions are handled.</p></li><li><p><code class="literal">5</code> - as above, but including
 391           information about each piece of information handled.</p></li><li><p><code class="literal">9</code> - log everything,
 392           including very detailed debugging information.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10613"></a><code class="literal">SecDefaultAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the default action to
 393       take on a rule match.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecDefaultAction
 394       action1,action2,action3</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecDefaultAction
 395       log,auditlog,deny,status:403,phase:2</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Rules following a
 396       <code class="literal">SecDefaultAction</code> directive will inherit this setting
 397       unless a specific action is specified for an individual rule or until
 398       another <code class="literal">SecDefaultAction</code> is specified. Take special
 399       note that in the logging disruptive actions are not allowed, but this
 400       can inadvertently be inherited using a disruptive action in
 401       <code class="literal">SecDefaultAction</code>.</p><p>The default value is minimal (differing from previous
 402       versions):</p><pre class="programlisting">SecDefaultAction phase:2,log,auditlog,pass</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p><code class="literal">SecDefaultAction</code> must specify a disruptive
 403         action and a processing phase and cannot contain metadata
 404         actions.</p></div><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p><code class="literal">SecDefaultAction</code> is <span class="emphasis"><em>not</em></span>
 405         inherited across configuration contexts. (For an example of why this
 406         may be a problem for you, read the following ModSecurity Blog entry
 407         <a href="http://blog.modsecurity.org/2008/07/modsecurity-tri.html" target="_top">http://blog.modsecurity.org/2008/07/modsecurity-tri.html</a>).</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1065E"></a><code class="literal">SecGeoLookupDb</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the path to the
 408       geographical database file.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecGeoLookupDb /path/to/db</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecGeoLookupDb
 409       /usr/local/geo/data/GeoLiteCity.dat</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Check out
 410       <code class="literal">maxmind.com</code> for free database files.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10689"></a><code class="literal">SecGuardianLog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configuration directive to use
 411       the httpd-guardian script to monitor for Denial of Service (DoS)
 412       attacks.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecGuardianLog |/path/to/httpd-guardian</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecGuardianLog
 413       |/usr/local/apache/bin/httpd-guardian</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> By default httpd-guardian
 414       will defend against clients that send more than 120 requests in a
 415       minute, or more than 360 requests in five minutes.</p><p>Since 1.9, ModSecurity supports a new directive, SecGuardianLog,
 416       that is designed to send all access data to another program using the
 417       piped logging feature. Since Apache is typically deployed in a
 418       multi-process fashion, making information sharing difficult, the idea is
 419       to deploy a single external process to observe all requests in a
 420       stateful manner, providing additional protection.</p><p>Development of a state of the art external protection tool will be
 421       a focus of subsequent ModSecurity releases. However, a fully functional
 422       tool is already available as part of the <a href="http://www.apachesecurity.net/tools/" target="_top">Apache httpd tools
 423       project</a>. The tool is called httpd-guardian and can be used to
 424       defend against Denial of Service attacks. It uses the blacklist tool
 425       (from the same project) to interact with an iptables-based (Linux) or
 426       pf-based (*BSD) firewall, dynamically blacklisting the offending IP
 427       addresses. It can also interact with SnortSam (http://www.snortsam.net).
 428       Assuming httpd-guardian is already configured (look into the source code
 429       for the detailed instructions) you only need to add one line to your
 430       Apache configuration to deploy it:</p><pre class="programlisting">SecGuardianLog |/path/to/httpd-guardian</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N106BC"></a><code class="literal">SecMarker</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Adds a fixed rule marker in the
 431       ruleset to be used as a target in a <code class="literal">skipAfter</code> action.
 432       A <code class="literal">SecMarker</code> directive essentially creates a rule that
 433       does nothing and whose only purpose it to carry the given ID.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecMarker
 434       ID</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecMarker 9999</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><pre class="programlisting">SecRule REQUEST_URI "^/$" \
 435     "chain,t:none,t:urlDecode,t:lowercase,t:normalisePath,<span class="emphasis"><em>skipAfter:99</em></span>"
 436 SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
 437 SecRule REQUEST_HEADERS:User-Agent \
 438     "^Apache \(internal dummy connection\)$" "t:none"
 439 SecRule &amp;REQUEST_HEADERS:Host "@eq 0" \
 440     "deny,log,status:400,id:08,severity:4,msg:'Missing a Host Header'"
 441 SecRule &amp;REQUEST_HEADERS:Accept "@eq 0" \
 442     "log,deny,log,status:400,id:15,msg:'Request Missing an Accept Header'"
 443 <span class="emphasis"><em>
 444 SecMarker 99</em></span></pre></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N106F4"></a><code class="literal">SecPdfProtect</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Enables the PDF XSS protection
 445       functionality. Once enabled access to PDF files is tracked. Direct
 446       access attempts are redirected to links that contain one-time tokens.
 447       Requests with valid tokens are allowed through unmodified. Requests with
 448       invalid tokens are also allowed through but with forced download of the
 449       PDF files. This implementation uses response headers to detect PDF files
 450       and thus can be used with dynamically generated PDF files that do not
 451       have the <code class="filename">.pdf</code> extension in the request URI.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtect On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtect On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1071F"></a><code class="literal">SecPdfProtectMethod</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configure desired protection
 452       method to be used when requests for PDF files are detected. Possible
 453       values are <code class="literal">TokenRedirection</code> and
 454       <code class="literal">ForcedDownload</code>. The token redirection approach will
 455       attempt to redirect with tokens where possible. This allows PDF files to
 456       continue to be opened inline but only works for GET requests. Forced
 457       download always causes PDF files to be delivered as opaque binaries and
 458       attachments. The latter will always be used for non-GET requests. Forced
 459       download is considered to be more secure but may cause usability
 460       problems for users ("This PDF won't open anymore!").</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectMethod method</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectMethod TokenRedirection</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span>
 461       <code class="literal">TokenRedirection</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10755"></a><code class="literal">SecPdfProtectSecret</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the secret that will be
 462       used to construct one-time tokens. You should use a reasonably long
 463       value for the secret (e.g. 16 characters is good). Once selected the
 464       secret should not be changed as it will break the tokens that were sent
 465       prior to change. But it's not a big deal even if you change it. It will
 466       just force download of PDF files with tokens that were issued in the
 467       last few seconds.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectSecret secret</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectSecret
 468       MyRandomSecretString</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1077C"></a><code class="literal">SecPdfProtectTimeout</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the token timeout. After
 469       token expires it can no longer be used to allow access to PDF file.
 470       Request will be allowed through but the PDF will be delivered as
 471       attachment.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectTimeout timeout</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectTimeout 10</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">10</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N107AA"></a><code class="literal">SecPdfProtectTokenName</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Defines the name of the token.
 472       The only reason you would want to change the name of the token is if you
 473       wanted to hide the fact you are running ModSecurity. It's a good reason
 474       but it won't really help as the adversary can look into the algorithm
 475       used for PDF protection and figure it out anyway. It does raise the bar
 476       slightly so go ahead if you want to.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecPdfProtectTokenName name</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecPdfProtectTokenName PDFTOKEN</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p><span class="emphasis"><em>Default:</em></span> <code class="literal">PDFTOKEN</code></p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N107D8"></a><code class="literal">SecRequestBodyAccess</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether request
 477       bodies will be buffered and processed by ModSecurity by default.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyAccess On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyAccess On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive is
 478       required if you plan to inspect <code class="literal">POST_PAYLOAD</code>. This
 479       directive must be used along with the "phase:2" processing phase action
 480       and <code class="literal">REQUEST_BODY</code> variable/location. If any of these 3
 481       parts are not configured, you will not be able to inspect the request
 482       bodies.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - access request
 483           bodies.</p></li><li><p><code class="literal">Off</code> - do not attempt to
 484           access request bodies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10816"></a><code class="literal">SecRequestBodyLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
 485       body size ModSecurity will accept for buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyLimit NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyLimit 134217728</code></p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> 131072 KB (134217728
 486       bytes) is the default setting. Anything over this limit will be rejected
 487       with status code 413 Request Entity Too Large. There is a hard limit of
 488       1 GB.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10839"></a><code class="literal">SecRequestBodyNoFilesLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
 489       body size ModSecurity will accept for buffering, excluding the size of
 490       files being transported in the request. This directive comes handy to
 491       further reduce susceptibility to DoS attacks when someone is sending
 492       request bodies of very large sizes. Web applications that require file
 493       uploads must configure <code class="literal">SecRequestBodyLimit</code> to a high
 494       value. Since large files are streamed to disk file uploads will not
 495       increase memory consumption. However, it's still possible for someone to
 496       take advantage of a large request body limit and send non-upload
 497       requests with large body sizes. This directive eliminates that
 498       loophole.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyNoFilesLimit
 499       NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyLimit 131072</code></p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> 1 MB (1048576 bytes) is
 500       the default setting. This value is very conservative. For most
 501       applications you should be able to reduce it down to 128 KB or lower.
 502       Anything over the limit will be rejected with status code <code class="literal">413
 503       Request Entity Too Large</code>. There is a hard limit of 1
 504       GB.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10864"></a><code class="literal">SecRequestBodyInMemoryLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum request
 505       body size ModSecurity will store in memory.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRequestBodyInMemoryLimit
 506       NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRequestBodyInMemoryLimit 131072</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>By default the limit is 128 KB:</p><pre class="programlisting"># Store up to 128 KB in memory
 507 SecRequestBodyInMemoryLimit 131072</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10890"></a><code class="literal">SecResponseBodyLimit</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the maximum response
 508       body size that will be accepted for buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyLimit NUMBER_IN_BYTES</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyLimit 524228</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Anything over this limit
 509       will be rejected with status code 500 Internal Server Error. This
 510       setting will not affect the responses with MIME types that are not
 511       marked for buffering. There is a hard limit of 1 GB.</p><p>By default this limit is configured to 512 KB:</p><pre class="programlisting"># Buffer response bodies of up to 512 KB in length
 512 SecResponseBodyLimit 524288</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N108BC"></a><code class="literal">SecResponseBodyLimitAction</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description</em></span>: Controls what happens once a
 513       response body limit, configured with
 514       <code class="literal">SecResponseBodyLimit</code>, is encountered. By default
 515       ModSecurity will reject a response body that is longer than specified.
 516       Some web sites, however, will produce very long responses making it
 517       difficult to come up with a reasonable limit. Such sites would have to
 518       raise the limit significantly to function properly defying the purpose
 519       of having the limit in the first place (to control memory consumption).
 520       With the ability to choose what happens once a limit is reached site
 521       administrators can choose to inspect only the first part of the
 522       response, the part that can fit into the desired limit, and let the rest
 523       through. Some could argue that allowing parts of responses to go
 524       uninspected is a weakness. This is true in theory but only applies to
 525       cases where the attacker controls the output (e.g. can make it arbitrary
 526       long). In such cases, however, it is not possible to prevent leakage
 527       anyway. The attacker could compress, obfuscate, or even encrypt data
 528       before it is sent back, and therefore bypass any monitoring
 529       device.</p><p><span class="emphasis"><em>Syntax</em></span>: <code class="literal">SecResponseBodyLimitAction
 530       Reject|ProcessPartial</code></p><p><span class="emphasis"><em>Example Usage</em></span>:
 531       <code class="literal">SecResponseBodyLimitAction ProcessPartial</code></p><p><span class="emphasis"><em>Processing Phase</em></span>: N/A</p><p><span class="emphasis"><em>Scope</em></span>: Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N108E7"></a><code class="literal">SecResponseBodyMimeType</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures which<code class="literal"> MIME</code> types are to be considered for response
 532       body buffering.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyMimeType mime/type</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyMimeType text/plain
 533       text/html</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Multiple<code class="literal"> SecResponseBodyMimeType</code> directives can be
 534       used to add<code class="literal"> MIME</code> types.</p><p>The default value is <code class="literal">text/plaintext/html</code>:</p><pre class="programlisting">SecResponseBodyMimeType text/plain text/html</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10923"></a><code class="literal">SecResponseBodyMimeTypesClear</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Clears the list of <code class="literal">MIME</code> types considered for response body
 535       buffering, allowing you to start populating the list from
 536       scratch.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyMimeTypesClear</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyMimeTypesClear</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1094E"></a><code class="literal">SecResponseBodyAccess</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether response
 537       bodies are to be buffer and analysed or not.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecResponseBodyAccess On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecResponseBodyAccess On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive is
 538       required if you plan to inspect HTML responses. This directive must be
 539       used along with the "phase:4" processing phase action and RESPONSE_BODY
 540       variable/location. If any of these 3 parts are not configured, you will
 541       not be able to inspect the response bodies.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - access response bodies
 542           (but only if the MIME type matches, see above).</p></li><li><p><code class="literal">Off</code> - do not attempt to
 543           access response bodies.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10984"></a><code class="literal">SecRule</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> <code class="literal">SecRule</code> is the main ModSecurity directive. It
 544       is used to analyse data and perform actions based on the results.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRule
 545       VARIABLES OPERATOR [ACTIONS]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRule REQUEST_URI "attack" \</code></p><p><code class="literal">
 546       "phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><p>In general, the format of this rule is as follows:</p><pre class="programlisting">SecRule VARIABLES OPERATOR [ACTIONS]</pre><p>The second part, <code class="literal">OPERATOR</code>,
 547       specifies how they are going to be checked. The third (optional) part,
 548       <code class="literal">ACTIONS</code>, specifies what to do
 549       whenever the operator used performs a successful match against a
 550       variable.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N109C2"></a>Variables in rules</h4></div></div><div></div></div><p>The first part,<code class="literal"> VARIABLES</code>,
 551         specifies which variables are to be checked. For example, the
 552         following rule will reject a transaction that has the word<span class="emphasis"><em>
 553         dirty</em></span> in the URI:</p><pre class="programlisting">SecRule ARGS dirty</pre><p>Each rule can specify one or more variables:</p><pre class="programlisting">SecRule ARGS|REQUEST_HEADERS:User-Agent dirty</pre><p>There is a third format supported by the selection operator -
 554         XPath expression. XPath expressions can only used against the special
 555         variable XML, which is available only of the request body was
 556         processed as XML.</p><pre class="programlisting">SecRule XML:/xPath/Expression dirty</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Not all collections support all selection operator format
 557           types. You should refer to the documentation of each collection to
 558           determine what is and isn't supported.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N109DE"></a>Collections</h4></div></div><div></div></div><p>A variable can contain one or many pieces of data, depending on
 559         the nature of the variable and the way it is used. We've seen examples
 560         of both approaches in the previous section. When a variable can
 561         contain more than one value we refer to it as a
 562         <span class="emphasis"><em>collection</em></span>.</p><p>Collections are always expanded before a rule is run. For
 563         example, the following rule:</p><pre class="programlisting">SecRule ARGS dirty</pre><p>will be expanded to:</p><pre class="programlisting">SecRule ARGS:p dirty
 564 SecRule ARGS:q dirty</pre><p>in a requests that has only two parameters, named
 565         <code class="literal">p</code> and <code class="literal">q</code>.</p><p>Collections come in several flavours:</p><div class="variablelist"><dl><dt><span class="term">Read-only</span></dt><dd><p>Created at runtime using transaction data. For example:
 566               <code class="literal">ARGS</code> (contains a list of all request
 567               parameter values) and <code class="literal">REQUEST_HEADERS</code>
 568               (contains a list of all request header values).</p></dd><dt><span class="term">Transient Read/Write</span></dt><dd><p>The <code class="literal">TX</code> collection is created (empty)
 569               for every transaction. Rules can read from it and write to it
 570               (using the <code class="literal">setvar</code> action, for example), but
 571               the information stored in this collection will not survive the
 572               end of transaction.</p></dd><dt><span class="term">Persistent Read/Write</span></dt><dd><p>There are several collections that can be written to, but
 573               which are persisted to the storage backend. These collections
 574               are used to track clients across transactions. Examples of
 575               collections that fall into this type are <code class="literal">IP</code>,
 576               <code class="literal">SESSION</code> and <code class="literal">USER</code>.</p></dd></dl></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A2B"></a>Operators in rules</h4></div></div><div></div></div><p>In the simplest possible case you will use a regular expression
 577         pattern as the second rule parameter. This is what we've done in the
 578         examples above. If you do this ModSecurity assumes you want to use the
 579         <code class="literal">rx</code> (regular expression) operator.
 580         You can also explicitly specify the operator you want to use by using
 581         <code class="literal">@</code>, followed by the name of an
 582         operator, at the beginning of the second <code class="literal">SecRule</code>
 583         parameter:</p><pre class="programlisting">SecRule ARGS "@rx dirty"</pre><p>Note how we had to use double quotes to delimit the second rule
 584         parameter. This is because the second parameter now has whitespace in
 585         it. Any number of whitespace characters can follow the name of the
 586         operator. If there are any non-whitespace characters there, they will
 587         all be treated as a special parameter to the operator. In the case of
 588         the regular expression operator the special parameter is the pattern
 589         that will be used for comparison.</p><p>The @ can be the second character if you are using negation to
 590         negate the result returned by the operator:</p><pre class="programlisting">SecRule &amp;ARGS "!@rx ^0$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A46"></a>Operator negation</h4></div></div><div></div></div><p>Operator results can be negated by using an exclamation mark at
 591         the beginning of the second parameter. The following rule matches if
 592         the word <code class="literal">dirty</code> does <span class="emphasis"><em>not</em></span> appear
 593         in the <code class="literal">User-Agent</code> request header:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent !dirty</pre><p>You can use the exclamation mark in combination with any
 594         parameter. If you do, the exclamation mark needs to go first, followed
 595         by the explicit operator reference. The following rule has the same
 596         effect as the previous example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "!@rx dirty"</pre><p>If you need to use negation in a rule that is going to be
 597         applied to several variables then it may not be immediately clear what
 598         will happen. Consider the following example:</p><pre class="programlisting">SecRule ARGS:p|ARGS:q !dirty</pre><p>The above rule is identical to:</p><pre class="programlisting">SecRule ARGS:p !dirty
 599 SecRule ARGS:q !dirty</pre><div class="warning" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Warning</h3><p>Negation is applied to operations against individual
 600           operations, not agains the entire variable list.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N10A6B"></a>Actions in rules</h4></div></div><div></div></div><p>The third parameter, <code class="literal">ACTIONS</code>,
 601         can be omitted only because there is a helper feature that specifies
 602         the default action list. If the parameter isn't omitted the actions
 603         specified in the parameter will be merged with the default action list
 604         to create the actual list of actions that will be processed on a rule
 605         match.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10A74"></a><code class="literal">SecRuleInheritance</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether the current
 606       context will inherit rules from the parent context (configuration
 607       options are inherited in most cases - you should look up the
 608       documentation for every directive to determine if it is inherited or
 609       not).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleInheritance On|Off</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleInheritance Off</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Resource-specific
 610       contexts (e.g.<code class="literal"> Location</code>, <code class="literal">Directory</code>, etc) cannot override
 611       <span class="emphasis"><em>phase1</em></span> rules configured in the main server or in
 612       the virtual server. This is because phase 1 is run early in the request
 613       processing process, before Apache maps request to resource. Virtual host
 614       context can override phase 1 rules configured in the main server.</p><p>Example: The following example shows where ModSecurity may be
 615       enabled in the main Apache configuration scope, however you might want
 616       to configure your VirtualHosts differently. In the first example, the
 617       first VirtualHost is not inheriting the ModSecurity main config
 618       directives and in the second one it is.</p><pre class="programlisting">SecRuleEngine On
 619 SecDefaultAction log,pass,phase:2
 620 ...
 621
 622 &lt;VirtualHost *:80&gt;
 623 ServerName app1.com
 624 ServerAlias www.app1.com<span class="emphasis"><em>
 625 SecRuleInheritance Off</em></span>
 626 SecDefaultAction log,deny,phase:1,redirect:http://www.site2.com
 627 ...
 628 &lt;/VirtualHost&gt;
 629
 630 &lt;VirtualHost *:80&gt;
 631 ServerName app2.com
 632 ServerAlias www.app2.com
 633 <span class="emphasis"><em>SecRuleInheritance On</em></span> SecRule ARGS "attack"
 634 ...
 635 &lt;/VirtualHost&gt;</pre><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - inherit rules from the
 636           parent context.</p></li><li><p><code class="literal">Off</code> - do not inherit rules
 637           from the parent context.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Configuration contexts are an Apache concept. Directives
 638             <code class="literal">&lt;Directory&gt;</code>,
 639             <code class="literal">&lt;Files&gt;</code>,
 640             <code class="literal">&lt;Location&gt;</code> and
 641             <code class="literal">&lt;VirtualHost&gt;</code> are all used to create
 642             configuration contexts. For more information please go to the
 643             Apache documentation section <a href="http://httpd.apache.org/docs/2.0/sections.html" target="_top">Configuration
 644             Sections</a>.</p></div></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10AD7"></a><code class="literal">SecRuleEngine</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the rules
 645       engine.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleEngine On|Off|DetectionOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleEngine On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive can also
 646       be controlled by the ctl action (ctl:ruleEngine=off) for per rule
 647       processing.</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - process rules.</p></li><li><p><code class="literal">Off</code> - do not process
 648           rules.</p></li><li><p><code class="literal">DetectionOnly</code> - process
 649           rules but never intercept transactions, even when rules are
 650           configured to do so.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B13"></a><code class="literal">SecRuleRemoveById</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Removes matching rules from the
 651       parent contexts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleUpdateActionById RULEID
 652       ACTIONLIST</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleRemoveByID 1 2 "9000-9010"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive supports
 653       multiple parameters, where each parameter can either be a rule ID, or a
 654       range. Parameters that contain spaces must be delimited using double
 655       quotes.</p><pre class="programlisting">SecRuleRemoveById 1 2 5 10-20 "400-556" 673</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B3D"></a><code class="literal">SecRuleRemoveByMsg</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Removes matching rules from the
 656       parent contexts.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleRemoveByMsg REGEX</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleRemoveByMsg "FAIL"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive supports
 657       multiple parameters. Each parameter is a regular expression that will be
 658       applied to the message (specified using the <code class="literal">msg</code> action).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10B68"></a><code class="literal">SecRuleScript</code> (Experimental)</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This directive creates a special
 659       rule that executes a Lua script to decide whether to match or not. The
 660       main difference from <code class="literal">SecRule</code> is that there are no
 661       targets nor operators. The script can fetch any variable from the
 662       ModSecurity context and use any (Lua) operator to test them. The second
 663       optional parameter is the list of actions whose meaning is identical to
 664       that of <code class="literal">SecRule</code>.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleScript
 665       /path/to/script.lua [ACTIONS]</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleScript "/path/to/file.lua"
 666       "block"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> None</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>All Lua scripts are compiled at configuration time and cached in
 667         memory. To reload scripts you must reload the entire ModSecurity
 668         configuration by restarting Apache.</p></div><p>Example script:</p><pre class="programlisting">-- Your script must define the <span class="emphasis"><em>main</em></span> entry
 669 -- point, as below.
 670 function main()
 671     -- Log something at level 1. Normally you shouldn't be
 672     -- logging anything, especially not at level 1, but this is
 673     -- just to show you can. Useful for debugging.
 674     m.log(1, "Hello world!");
 675
 676     -- Retrieve one variable.
 677     local var1 = m.getvar("REMOTE_ADDR");
 678
 679     -- Retrieve one variable, applying one transformation function.
 680     -- The second parameter is a string.
 681     local var2 = m.getvar("ARGS", "lowercase");
 682
 683     -- Retrieve one variable, applying several transformation functions.
 684     -- The second parameter is now a list. You should note that m.getvar()
 685     -- requires the use of comma to separate collection names from
 686     -- variable names. This is because only one variable is returned.
 687     local var3 = m.getvar("ARGS.p", { "lowercase", "compressWhitespace" } );
 688
 689     -- If you want this rule to match return a string
 690     -- containing the error message. The message <span class="emphasis"><em>must</em></span> contain the name
 691     -- of the variable where the problem is located.
 692     -- return "Variable ARGS:p looks suspicious!"
 693
 694     -- Otherwise, simply return nil.
 695     return nil;
 696 end</pre><p>In this first example we were only retrieving one variable at the
 697       time. In this case the name of the variable is known to you. In many
 698       cases, however, you will want to examine variables whose names you won't
 699       know in advance, for example script parameters.</p><p>Example showing use of <code class="literal">m.getvars()</code> to retrieve
 700       many variables at once:</p><pre class="programlisting">function main()
 701     -- Retrieve script parameters.
 702     local d = m.getvars("ARGS", { "lowercase", "htmlEntityDecode" } );
 703
 704     -- Loop through the paramters.
 705     for i = 1, #d do
 706         -- Examine parameter value.
 707         if (string.find(d[i].value, "&lt;script")) then
 708             -- Always specify the name of the variable where the
 709             -- problem is located in the error message.
 710             return ("Suspected XSS in variable " .. d[i].name .. ".");
 711         end
 712     end
 713
 714     -- Nothing wrong found.
 715     return nil;
 716 end</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Go to <a href="http://www.lua.org/" target="_top">http://www.lua.org/</a> to find more
 717         about the Lua programming language. The reference manual too is
 718         available online, at <a href="http://www.lua.org/manual/5.1/" target="_top">http://www.lua.org/manual/5.1/</a>.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Lua support is marked as <span class="emphasis"><em>experimental</em></span> as
 719         the way the progamming interface may continue to evolve while we are
 720         working for the best implementation style. Any user input into the
 721         programming interface is appreciated.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10BC2"></a><code class="literal">SecRuleUpdateActionById</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Updates the action list of the
 722       specified rule.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecRuleRemoveById RULEID ACTIONLIST</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecRuleUpdateActionById 12345
 723       deny,status:403</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> Any</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.5.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive merges the
 724       specified action list with the rule's action list. There are two
 725       limitations. The rule ID cannot be changed, nor can the phase. Further
 726       note that actions that may be specified multiple times are appended to
 727       the original.</p><pre class="programlisting">SecAction \
 728   "t:lowercase,phase:2,id:12345,pass,msg:'The Message',log,auditlog"
 729 SecRuleUpdateActionById 12345 "t:compressWhitespace,deny,status:403,msg:'A new message'</pre><p>The example above will cause the rule to be executed as if it was
 730       specified as follows:</p><pre class="programlisting">SecAction \
 731   "t:lowercase,phase:2,id:12345,log,auditlog,t:compressWhitespace,deny,status:403,msg:'A new message'"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10BF1"></a><code class="literal">SecServerSignature</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Instructs ModSecurity to change
 732       the data presented in the "Server:" response header token.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecServerSignature "WEB SERVER
 733       SOFTWARE"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecServerSignature
 734       "Netscape-Enterprise/6.0"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Main</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> In order for this
 735       directive to work, you must set the Apache ServerTokens directive to
 736       Full. ModSecurity will overwrite the server signature data held in this
 737       memory space with the data set in this directive. If ServerTokens is not
 738       set to Full, then the memory space is most likely not large enough to
 739       hold the new data we are looking to insert.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C18"></a><code class="literal">SecTmpDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory where
 740       temporary files will be created.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecTmpDir
 741       /path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecTmpDir /tmp</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Needs to be writable by
 742       the Apache user process. This is the directory location where Apache
 743       will swap data to disk if it runs out of memory (more data than what was
 744       specified in the SecRequestBodyInMemoryLimit directive) during
 745       inspection.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C3F"></a><code class="literal">SecUploadDir</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the directory where
 746       intercepted files will be stored.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadDir
 747       /path/to/dir</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadDir /tmp</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directory must be on
 748       the same filesystem as the temporary directory defined with <code class="literal">SecTmpDir</code>. This directive is used with
 749       <code class="literal">SecUploadKeepFiles</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C6E"></a><code class="literal">SecUploadFileMode</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures the mode
 750       (permissions) of any uploaded files using an octal mode (as used in
 751       chmod).</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadFileMode octal_mode|"default"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadFileMode 0640</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.1.6</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This feature is not
 752       available on operating systems not supporting octal file modes. The
 753       default mode (0600) only grants read/write access to the account writing
 754       the file. If access from another account is needed (using clamd is a
 755       good example), then this directive may be required. However, use this
 756       directive with caution to avoid exposing potentially sensitive data to
 757       unauthorized users. Using the value "default" will revert back to the
 758       default setting.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The process umask may still limit the mode if it is being more
 759         restrictive than the mode set using this directive.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10C98"></a><code class="literal">SecUploadKeepFiles</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures whether or not the
 760       intercepted files will be kept after transaction is processed.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecUploadKeepFiles On|Off|RelevantOnly</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecUploadKeepFiles On</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> This directive requires
 761       the storage directory to be defined (using <code class="literal">SecUploadDir</code>).</p><p>Possible values are:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">On</code> - Keep uploaded
 762           files.</p></li><li><p><code class="literal">Off</code> - Do not keep uploaded
 763           files.</p></li><li><p><code class="literal">RelevantOnly</code> - This will
 764           keep only those files that belong to requests that are deemed
 765           relevant.</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10CD8"></a><code class="literal">SecWebAppId</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Creates a partition on the
 766       server that belongs to one web application.</p><p><span class="emphasis"><em>Syntax:</em></span> <code class="literal">SecWebAppId
 767       "NAME"</code></p><p><span class="emphasis"><em>Example Usage:</em></span> <code class="literal">SecWebAppId "WebApp1"</code></p><p><span class="emphasis"><em>Processing Phase:</em></span> N/A</p><p><span class="emphasis"><em>Scope:</em></span> Any</p><p><span class="emphasis"><em>Version:</em></span> 2.0.0</p><p><span class="emphasis"><em>Dependencies/Notes:</em></span> Partitions are used to
 768       avoid collisions between session IDs and user IDs. This directive must
 769       be used if there are multiple applications deployed on the same server.
 770       If it isn't used, a collision between session IDs might occur. The
 771       default value is<code class="literal"> default</code>.
 772       Example:</p><pre class="programlisting">&lt;VirtualHost *:80&gt;
 773 ServerName app1.com
 774 ServerAlias www.app1.com
 775 <span class="emphasis"><em>SecWebAppId "App1"</em></span>
 776 SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
 777 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
 778 ...
 779 &lt;/VirtualHost&gt;
 780
 781 &lt;VirtualHost *:80&gt;
 782 ServerName app2.com
 783 ServerAlias www.app2.com<span class="emphasis"><em>
 784 SecWebAppId "App2"</em></span>
 785 SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
 786 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
 787 ...
 788 &lt;/VirtualHost&gt;</pre><p>In the two examples configurations shown, SecWebAppId is being
 789       used in conjunction with the Apache VirtualHost directives. What this
 790       achieves is to create more unique collection names when being hosted on
 791       one server. Normally, when setsid is used, ModSecurity will create a
 792       collection with the name "SESSION" and it will hold the value specified.
 793       With using SecWebAppId as shown in the examples, however, the name of
 794       the collection would become "App1_SESSION" and "App2_SESSION".</p><p>SecWebAppId is relevant in two cases:</p><div class="orderedlist"><ol type="1"><li><p>You are logging transactions/alerts to the ModSecurity Console
 795           and you want to use the web application ID to search only the
 796           transactions belonging to that application.</p></li><li><p>You are using the data persistence facility (collections
 797           SESSION and USER) and you need to avoid collisions between sessions
 798           and users belonging to different applications.</p></li></ol></div></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="processing-phases"></a>Processing Phases</h2></div></div><div></div></div><p>ModSecurity 2.x allows rules to be placed in one of the following
 799     five phases:</p><div class="orderedlist"><ol type="1"><li><p>Request headers (<code class="literal">REQUEST_HEADERS</code>)</p></li><li><p>Request body (<code class="literal">REQUEST_BODY</code>)</p></li><li><p>Response headers (<code class="literal">RESPONSE_HEADERS</code>)</p></li><li><p>Response body (<code class="literal">RESPONSE_BODY</code>)</p></li><li><p>Logging (<code class="literal">LOGGING</code>)</p></li></ol></div><p>Below is a diagram of the standard Apache Request Cycle. In the
 800     diagram, the 5 ModSecurity processing phases are shown.</p><p><div><img src="apache_request_cycle-modsecurity.jpg" width="495"></div></p><p>In order to select the phase a rule executes during, use the phase
 801     action either directly in the rule or in using the
 802     <code class="literal">SecDefaultAction</code> directive:</p><pre class="programlisting">SecDefaultAction "log,pass,<span class="emphasis"><em>phase:2</em></span>"
 803 SecRule REQUEST_HEADERS:Host "!^$" "deny,<span class="emphasis"><em>phase:1</em></span>"</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Keep in mind that rules are executed according to phases, so even
 804       if two rules are adjacent in a configuration file, but are set to
 805       execute in different phases, they would not happen one after the other.
 806       The order of rules in the configuration file is important only within
 807       the rules of each phase. This is especially important when using the
 808       <code class="literal">skip</code> and <code class="literal">skipAfter</code> actions.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The <code class="literal">LOGGING</code> phase is special. It is executed at
 809       the end of each transaction no matter what happened in the previous
 810       phases. This means it will be processed even if the request was
 811       intercepted or the <code class="literal">allow</code> action was used to pass the
 812       transaction through.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D73"></a>Phase Request Headers</h3></div></div><div></div></div><p>Rules in this phase are processed immediately after Apache
 813       completes reading the request headers (post-read-request phase). At this
 814       point the request body has not been read yet, meaning not all request
 815       arguments are available. Rules should be placed in this phase if you
 816       need to have them run early (before Apache does something with the
 817       request), to do something before the request body has been read,
 818       determine whether or not the request body should be buffered, or decide
 819       how you want the request body to be processed (e.g. whether to parse it
 820       as XML or not).</p><p><span class="emphasis"><em>Note</em></span></p><p>Rules in this phase can not leverage Apache scope directives
 821       (Directory, Location, LocationMatch, etc...) as the post-read-request
 822       hook does not have this information yet. The exception here is the
 823       VirtualHost directive. If you want to use ModSecurity rules inside
 824       Apache locations, then they should run in Phase 2. Refer to the Apache
 825       Request Cycle/ModSecurity Processing Phases diagram.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D7D"></a>Phase Request Body</h3></div></div><div></div></div><p>This is the general-purpose input analysis phase. Most of the
 826       application-oriented rules should go here. In this phase you are
 827       guaranteed to have received the request arguments (provided the request
 828       body has been read). ModSecurity supports three encoding types for the
 829       request body phase:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">application/x-www-form-urlencoded</code> - used to
 830           transfer form data</p></li><li><p><code class="literal">multipart/form-data</code> - used for file
 831           transfers</p></li><li><p><code class="literal">text/xml</code> - used for passing XML data</p></li></ul></div><p>Other encodings are not used by most web applications.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D97"></a>Phase Response Headers</h3></div></div><div></div></div><p>This phase takes place just before response headers are sent back
 832       to the client. Run here if you want to observe the response before that
 833       happens, and if you want to use the response headers to determine if you
 834       want to buffer the response body. Note that some response status codes
 835       (such as 404) are handled earlier in the request cycle by Apache and my
 836       not be able to be triggered as expected. Additionally, there are some
 837       response headers that are added by Apache at a later hook (such as Date,
 838       Server and Connection) that we would not be able to trigger on or
 839       sanitize. This should work appropriately in a proxy setup or within
 840       phase:5 (logging).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D9C"></a>Phase Response Body</h3></div></div><div></div></div><p>This is the general-purpose output analysis phase. At this point
 841       you can run rules against the response body (provided it was buffered,
 842       of course). This is the phase where you would want to inspect the
 843       outbound HTML for information disclosure, error messages or failed
 844       authentication text.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10DA1"></a>Phase Logging</h3></div></div><div></div></div><p>This phase is run just before logging takes place. The rules
 845       placed into this phase can only affect how the logging is performed.
 846       This phase can be used to inspect the error messages logged by Apache.
 847       You cannot deny/block connections in this phase as it is too late. This
 848       phase also allows for inspection of other response headers that weren't
 849       available during phase:3 or phase:4. Note that you must be careful not
 850       to inherit a disruptive action into a rule in this phase as this is a
 851       configuration error in ModSecurity 2.5.0 and later versions.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="variables"></a>Variables</h2></div></div><div></div></div><p>The following variables are supported in ModSecurity 2.x:</p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10DAC"></a><code class="literal">ARGS</code></h3></div></div><div></div></div><p><code class="literal">ARGS</code> is a collection and can be used on its own
 852       (means all arguments including the POST Payload), with a static
 853       parameter (matches arguments with that name), or with a regular
 854       expression (matches all arguments with name that matches the regular
 855       expression). To look at only the query string or body arguments, see the
 856       <code class="literal">ARGS_GET</code> and <code class="literal">ARGS_POST</code>
 857       collections.</p><p>Some variables are actually collections, which are expanded into
 858       more variables at runtime. The following example will examine all
 859       request arguments:<pre class="programlisting">SecRule ARGS dirty</pre>
 860       Sometimes, however, you will want to look only at parts of a collection.
 861       This can be achieved with the help of the <span class="emphasis"><em>selection
 862       operator</em></span>(colon). The following example will only look at the
 863       arguments named<code class="literal"> p</code> (do note that, in
 864       general, requests can contain multiple arguments with the same name):
 865       <pre class="programlisting">SecRule ARGS:p dirty</pre>
 866       It is also possible to specify exclusions. The following will examine
 867       all request arguments for the word<span class="emphasis"><em> dirty</em></span>, except
 868       the ones named <code class="literal">z</code> (again, there can be
 869       zero or more arguments named<code class="literal"> z</code>):
 870       <pre class="programlisting">SecRule ARGS|!ARGS:z dirty</pre>
 871       There is a special operator that allows you to count how many variables
 872       there are in a collection. The following rule will trigger if there is
 873       more than zero arguments in the request (ignore the second parameter for
 874       the time being): <pre class="programlisting">SecRule &amp;ARGS !^0$</pre>
 875       And sometimes you need to look at an array of parameters, each with a
 876       slightly different name. In this case you can specify a regular
 877       expression in the selection operator itself. The following rule will
 878       look into all arguments whose names begin with <code class="literal">id_</code>: <pre class="programlisting">SecRule ARGS:/^id_/ dirty</pre></p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Using <code class="literal">ARGS:p</code> will not result in any
 879         invocations against the operator if argument p does not exist.</p><p>In ModSecurity 1.X, the <code class="literal">ARGS</code> variable stood
 880         for <code class="literal">QUERY_STRING</code> + <code class="literal">POST_PAYLOAD</code>,
 881         whereas now it expands to individual variables.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10DFE"></a><code class="literal">ARGS_COMBINED_SIZE</code></h3></div></div><div></div></div><p>This variable allows you to set more targeted evaluations on the
 882       total size of the Arguments as compared with normal Apache LimitRequest
 883       directives. For example, you could create a rule to ensure that the
 884       total size of the argument data is below a certain threshold (to help
 885       prevent buffer overflow issues). Example: Block request if the size of
 886       the arguments is above 25 characters.</p><pre class="programlisting">SecRule REQUEST_FILENAME "^/cgi-bin/login\.php" \
 887     "chain,log,deny,phase:2,t:none,t:lowercase,t:normalisePath"
 888 SecRule <span class="emphasis"><em>ARGS_COMBINED_SIZE</em></span> "@gt 25"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E0B"></a><code class="literal">ARGS_NAMES</code></h3></div></div><div></div></div><p>Is a collection of the argument names. You can search for specific
 889       argument names that you want to block. In a positive policy scenario,
 890       you can also whitelist (using an inverted rule with the ! character)
 891       only authorized argument names. Example: This example rule will only
 892       allow 2 argument names - p and a. If any other argument names are
 893       injected, it will be blocked.</p><pre class="programlisting">SecRule REQUEST_FILENAME "/index.php" \
 894     "chain,log,deny,status:403,phase:2,t:none,t:lowercase,t:normalisePath"
 895 SecRule<span class="emphasis"><em> ARGS_NAMES</em></span> "!^(p|a)$" "t:none,t:lowercase"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E18"></a><code class="literal">ARGS_GET</code></h3></div></div><div></div></div><p><code class="literal">ARGS_GET</code> is similar to <code class="literal">ARGS</code>,
 896       but only contains arguments from the query string.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E26"></a><code class="literal">ARGS_GET_NAMES</code></h3></div></div><div></div></div><p><code class="literal">ARGS_GET_NAMES</code> is similar to
 897       <code class="literal">ARGS_NAMES</code>, but only contains argument names from the
 898       query string.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E34"></a><code class="literal">ARGS_POST</code></h3></div></div><div></div></div><p><code class="literal">ARGS_POST</code> is similar to
 899       <code class="literal">ARGS</code>, but only contains arguments from the POST
 900       body.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E42"></a><code class="literal">ARGS_POST_NAMES</code></h3></div></div><div></div></div><p><code class="literal">ARGS_POST_NAMES</code> is similar to
 901       <code class="literal">ARGS_NAMES</code>, but only contains argument names from the
 902       POST body.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E50"></a><code class="literal">AUTH_TYPE</code></h3></div></div><div></div></div><p>This variable holds the authentication method used to validate a
 903       user. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>AUTH_TYPE</em></span> "basic" log,deny,status:403,phase:1,t:lowercase</pre><p><span class="emphasis"><em>Note</em></span></p><p>This data will not be available in a proxy-mode deployment as the
 904       authentication is not local. In a proxy-mode deployment, you would need
 905       to inspect the <code class="literal">REQUEST_HEADERS:Authorization</code>
 906       header.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E66"></a><code class="literal">ENV</code></h3></div></div><div></div></div><p>Collection, requires a single parameter (after colon). The
 907       <code class="literal">ENV</code> variable is set with setenv and does not give
 908       access to the CGI environment variables. Example:</p><pre class="programlisting">SecRule REQUEST_FILENAME "printenv" pass,<span class="emphasis"><em>setenv:tag=suspicious</em></span>
 909 SecRule <span class="emphasis"><em>ENV:tag</em></span> "suspicious"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E7A"></a><code class="literal">FILES</code></h3></div></div><div></div></div><p>Collection. Contains a collection of original file names (as they
 910       were called on the remote user's file system). Note: only available if
 911       files were extracted from the request body. Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> FILES</em></span> "\.conf$" log,deny,status:403,phase:2</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E87"></a><code class="literal">FILES_COMBINED_SIZE</code></h3></div></div><div></div></div><p>Single value. Total size of the uploaded files. Note: only
 912       available if files were extracted from the request body. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>FILES_COMBINED_SIZE</em></span> "@gt 1000" log,deny,status:403,phase:2</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10E94"></a><code class="literal">FILES_NAMES</code></h3></div></div><div></div></div><p>Collection w/o parameter. Contains a list of form fields that were
 913       used for file upload. Note: only available if files were extracted from
 914       the request body. Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> FILES_NAMES</em></span> "^upfile$" log,deny,status:403,phase:2</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10EA1"></a><code class="literal">FILES_SIZES</code></h3></div></div><div></div></div><p>Collection. Contains a list of file sizes. Useful for implementing
 915       a size limitation on individual uploaded files. Note: only available if
 916       files were extracted from the request body. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>FILES_SIZES</em></span> "@gt 100" log,deny,status:403,phase:2</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10EAE"></a><code class="literal">FILES_TMPNAMES</code></h3></div></div><div></div></div><p>Collection. Contains a collection of temporary files' names on the
 917       disk. Useful when used together with <code class="literal">@inspectFile.</code> Note: only available if files
 918       were extracted from the request body. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>FILES_TMPNAMES</em></span> "@inspectFile /path/to/inspect_script.pl"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10EBF"></a><code class="literal">GEO</code></h3></div></div><div></div></div><p><code class="literal">GEO</code> is a collection populated by the results of
 919       the last <code class="literal">@geoLookup</code> operator. The
 920       collection can be used to match geographical fields looked from an IP
 921       address or hostname.</p><p>Available since ModSecurity 2.5.0.</p><p>Fields:</p><div class="itemizedlist"><ul type="disc"><li><p><span class="emphasis"><em>COUNTRY_CODE:</em></span> Two character country code.
 922           EX: US, GB, etc.</p></li><li><p><span class="emphasis"><em>COUNTRY_CODE3:</em></span> Up to three character
 923           country code.</p></li><li><p><span class="emphasis"><em>COUNTRY_NAME:</em></span> The full country
 924           name.</p></li><li><p><span class="emphasis"><em>COUNTRY_CONTINENT:</em></span> The two character
 925           continent that the country is located. EX: EU</p></li><li><p><span class="emphasis"><em>REGION:</em></span> The two character region. For US,
 926           this is state. For Canada, providence, etc.</p></li><li><p><span class="emphasis"><em>CITY:</em></span> The city name if supported by the
 927           database.</p></li><li><p><span class="emphasis"><em>POSTAL_CODE:</em></span> The postal code if supported
 928           by the database.</p></li><li><p><span class="emphasis"><em>LATITUDE:</em></span> The latitude if supported by
 929           the database.</p></li><li><p><span class="emphasis"><em>LONGITUDE:</em></span> The longitude if supported by
 930           the database.</p></li><li><p><span class="emphasis"><em>DMA_CODE:</em></span> The metropolitan area code if
 931           supported by the database. (US only)</p></li><li><p><span class="emphasis"><em>AREA_CODE:</em></span> The phone system area code.
 932           (US only)</p></li></ul></div><p>Example:</p><pre class="programlisting">SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat
 933 ...
 934 SecRule REMOTE_ADDR "<span class="emphasis"><em>@geoLookup</em></span>" "chain,drop,msg:'Non-GB IP address'"
 935 SecRule GEO:COUNTRY_CODE "!@streq GB"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10F11"></a><code class="literal">HIGHEST_SEVERITY</code></h3></div></div><div></div></div><p>This variable holds the highest severity of any rules that have
 936       matched so far. Severities are numeric values and thus can be used with
 937       comparison operators such as <code class="literal">@lt</code>,
 938       etc.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Higher severities have a lower numeric value.</p><p>A value of 255 indicates no severity has been set.</p></div><pre class="programlisting">SecRule HIGHEST_SEVERITY "@le 2" "phase:2,deny,status:500,msg:'severity %{HIGHEST_SEVERITY}'"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10F24"></a><code class="literal">MATCHED_VAR</code></h3></div></div><div></div></div><p>This variable holds the value of the variable that was matched
 939       against. It is similar to the TX:0, except it can be used for all
 940       operators and does not require that the <code class="literal">capture</code> action be specified.</p><pre class="programlisting">SecRule ARGS pattern chain,deny
 941 ...
 942 SecRule <span class="emphasis"><em>MATCHED_VAR</em></span> "further scrutiny"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10F35"></a><code class="literal">MATCHED_VAR_NAME</code></h3></div></div><div></div></div><p>This variable holds the full name of the variable that was matched
 943       against.</p><pre class="programlisting">SecRule ARGS pattern setvar:tx.mymatch=%{MATCHED_VAR_NAME}
 944 ...
 945 SecRule <span class="emphasis"><em>TX:MYMATCH</em></span> "@eq ARGS:param" deny</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10F42"></a><code class="literal">MODSEC_BUILD</code></h3></div></div><div></div></div><p>This variable holds the ModSecurity build number. This variable is
 946       intended to be used to check the build number prior to using a feature
 947       that is available only in a certain build. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>MODSEC_BUILD</em></span> "!@ge 02050102" skipAfter:12345
 948 SecRule ARGS "@pm some key words" id:12345,deny,status:500</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10F4F"></a><code class="literal">MULTIPART_CRLF_LF_LINES</code></h3></div></div><div></div></div><p>This flag variable will be set to <code class="literal">1</code> whenever a
 949       multi-part request uses mixed line terminators. The
 950       <code class="literal">multipart/form-data</code> RFC requires
 951       <code class="literal">CRLF</code> sequence to be used to terminate lines. Since
 952       some client implementations use only <code class="literal">LF</code> to terminate
 953       lines you might want to allow them to proceed under certain
 954       circumstances (if you want to do this you will need to stop using
 955       <code class="literal">MULTIPART_STRICT_ERROR</code> and check each multi-part flag
 956       variable individually, avoiding <code class="literal">MULTIPART_LF_LINE</code>).
 957       However, mixing <code class="literal">CRLF</code> and <code class="literal">LF</code> line
 958       terminators is dangerous as it can allow for evasion. Therefore, in such
 959       cases, you will have to add a check for
 960       <code class="literal">MULTIPART_CRLF_LF_LINES</code>.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10F7A"></a><code class="literal">MULTIPART_STRICT_ERROR</code></h3></div></div><div></div></div><p><code class="literal">MULTIPART_STRICT_ERROR</code> will be set to
 961       <code class="literal">1</code> when any of the following variables is also set to
 962       <code class="literal">1</code>: <code class="literal">REQBODY_PROCESSOR_ERROR</code>,
 963       <code class="literal">MULTIPART_BOUNDARY_QUOTED</code>,
 964       <code class="literal">MULTIPART_BOUNDARY_WHITESPACE</code>,
 965       <code class="literal">MULTIPART_DATA_BEFORE</code>,
 966       <code class="literal">MULTIPART_DATA_AFTER</code>,
 967       <code class="literal">MULTIPART_HEADER_FOLDING</code>,
 968       <code class="literal">MULTIPART_LF_LINE</code>,
 969       <code class="literal">MULTIPART_SEMICOLON_MISSING</code>
 970       <code class="literal">MULTIPART_INVALID_QUOTING</code>. Each of these variables
 971       covers one unusual (although sometimes legal) aspect of the request body
 972       in <code class="literal">multipart/form-data format</code>. Your policies should
 973       <span class="emphasis"><em>always</em></span> contain a rule to check either this variable
 974       (easier) or one or more individual variables (if you know exactly what
 975       you want to accomplish). Depending on the rate of false positives and
 976       your default policy you should decide whether to block or just warn when
 977       the rule is triggered.</p><p>The best way to use this variable is as in the example
 978       below:</p><pre class="programlisting">SecRule MULTIPART_STRICT_ERROR "!@eq 0" \
 979 "phase:2,t:none,log,deny,msg:'Multipart request body \
 980 failed strict validation: \
 981 PE %{REQBODY_PROCESSOR_ERROR}, \
 982 BQ %{MULTIPART_BOUNDARY_QUOTED}, \
 983 BW %{MULTIPART_BOUNDARY_WHITESPACE}, \
 984 DB %{MULTIPART_DATA_BEFORE}, \
 985 DA %{MULTIPART_DATA_AFTER}, \
 986 HF %{MULTIPART_HEADER_FOLDING}, \
 987 LF %{MULTIPART_LF_LINE}, \
 988 SM %{MULTIPART_SEMICOLON_MISSING}, \
 989 IQ %{MULTIPART_INVALID_QUOTING}'"</pre><p>The <code class="literal">multipart/form-data</code> parser was upgraded in
 990       ModSecurity v2.1.3 to actively look for signs of evasion. Many variables
 991       (as listed above) were added to expose various facts discovered during
 992       the parsing process. The <code class="literal">MULTIPART_STRICT_ERROR</code>
 993       variable is handy to check on all abnormalities at once. The individual
 994       variables allow detection to be fine-tuned according to your
 995       circumstances in order to reduce the number of false positives. Detailed
 996       analysis of various evasion techniques covered will be released as a
 997       separated document at a later date.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10FC6"></a><code class="literal">MULTIPART_UNMATCHED_BOUNDARY</code></h3></div></div><div></div></div><p>Set to <code class="literal">1</code> when, during the parsing phase of a
 998       <code class="literal">multipart/request-body</code>, ModSecurity encounters what
 999       feels like a boundary but it is not. Such an event may occur when
1000       evasion of ModSecurity is attempted.</p><p>The best way to use this variable is as in the example
1001       below:</p><pre class="programlisting">SecRule MULTIPART_UNMATCHED_BOUNDARY "!@eq 0" \
1002 "phase:2,t:none,log,deny,msg:'Multipart parser detected a possible unmatched boundary.'"</pre><p>Change the rule from blocking to logging-only if many false
1003       positives are encountered.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10FDC"></a><code class="literal">PATH_INFO</code></h3></div></div><div></div></div><p>Besides passing query information to a script/handler, you can
1004       also pass additional data, known as extra path information, as part of
1005       the URL. Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> PATH_INFO</em></span> "^/(bin|etc|sbin|opt|usr)"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10FE9"></a><code class="literal">QUERY_STRING</code></h3></div></div><div></div></div><p>This variable holds form data passed to the script/handler by
1006       appending data after a question mark. Warning: Not URL-decoded.
1007       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>QUERY_STRING</em></span> "attack"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10FF6"></a><code class="literal">REMOTE_ADDR</code></h3></div></div><div></div></div><p>This variable holds the IP address of the remote client.
1008       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REMOTE_ADDR</em></span> "^192\.168\.1\.101$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11003"></a><code class="literal">REMOTE_HOST</code></h3></div></div><div></div></div><p>If HostnameLookUps are set to On, then this variable will hold the
1009       DNS resolved remote host name. If it is set to Off, then it will hold
1010       the remote IP address. Possible uses for this variable would be to deny
1011       known bad client hosts or network blocks, or conversely, to allow in
1012       authorized hosts. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REMOTE_HOST</em></span> "\.evil\.network\org$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11010"></a><code class="literal">REMOTE_PORT</code></h3></div></div><div></div></div><p>This variable holds information on the source port that the client
1013       used when initiating the connection to our web server. Example: in this
1014       example, we are evaluating to see if the <code class="literal">REMOTE_PORT</code>
1015       is less than 1024, which would indicate that the user is a privileged
1016       user (root).</p><pre class="programlisting">SecRule <span class="emphasis"><em>REMOTE_PORT</em></span> "@lt 1024" phase:1,log,pass,setenv:remote_port=privileged</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11021"></a><code class="literal">REMOTE_USER</code></h3></div></div><div></div></div><p>This variable holds the username of the authenticated user. If
1017       there are no password (basic|digest) access controls in place, then this
1018       variable will be empty. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REMOTE_USER</em></span> "admin"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This data will not be available in a proxy-mode deployment as the
1019       authentication is not local.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11033"></a><code class="literal">REQBODY_PROCESSOR</code></h3></div></div><div></div></div><p>Built-in processors are <code class="literal">URLENCODED</code>,<code class="literal">
1020       MULTIPART</code>, and <code class="literal">XML</code>.
1021       Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> REQBODY_PROCESSOR</em></span> "^XML$ chain
1022 SecRule XML "@validateDTD /opt/apache-frontend/conf/xml.dtd"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1104C"></a><code class="literal">REQBODY_PROCESSOR_ERROR</code></h3></div></div><div></div></div><p>Possible values are 0 (no error) or 1 (error). This variable will
1023       be set by request body processors (typically the
1024       <code class="classname">multipart/request-data</code> parser or the XML parser)
1025       when they fail to properly parse a request payload.</p><p>Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> REQBODY_PROCESSOR_ERROR</em></span> "@eq 1" deny,phase:2</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Your policies <span class="emphasis"><em>must</em></span> have a rule to check
1026         REQBODY_PROCESSOR_ERROR at the beginning of phase 2. Failure to do so
1027         will leave the door open for impedance mismatch attacks. It is
1028         possible, for example, that a payload that cannot be parsed by
1029         ModSecurity can be successfully parsed by more tolerant parser
1030         operating in the application. If your policy dictates blocking then
1031         you should reject the request if error is detected. When operating in
1032         detection-only mode your rule should alert with high severity when
1033         request body processing fails.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11064"></a><code class="literal">REQBODY_PROCESSOR_ERROR_MSG</code></h3></div></div><div></div></div><p>Empty, or contains the error message from the processor.
1034       Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> REQBODY_PROCESSOR_ERROR_MSG</em></span> "failed to parse" t:lowercase</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11071"></a><code class="literal">REQUEST_BASENAME</code></h3></div></div><div></div></div><p>This variable holds just the filename part of
1035       <code class="literal">REQUEST_FILENAME</code> (e.g. index.php).</p><p>Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_BASENAME</em></span> "^login\.php$" phase:2,t:none,t:lowercase</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please note that anti-evasion transformations are not applied to
1036         this variable by default. <code class="literal">REQUEST_BASENAME</code> will
1037         recognise both <code class="literal">/</code> and <code class="literal">\</code> as path
1038         separators.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11093"></a><code class="literal">REQUEST_BODY</code></h3></div></div><div></div></div><p>This variable holds the data in the request body (including
1039       <code class="literal">POST_PAYLOAD</code> data). <code class="literal">REQUEST_BODY</code>
1040       should be used if the original order of the arguments is important
1041       (<code class="literal">ARGS</code> should be used in all other cases).
1042       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_BODY</em></span> "^username=\w{25,}\&amp;password=\w{25,}\&amp;Submit\=login$"</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>This variable is only available if the
1043         <code class="literal">URLENCODED</code> request body processor parsed a request
1044         body. This will occur by default when an
1045         <code class="literal">application/x-www-form-urlencoded</code> is detected, or
1046         the <code class="literal">URLENCODED</code> request body parser is forced. As of
1047         2.5.7 it is possible to force the presence of the
1048         <code class="literal">REQUEST_BODY</code> variable, but only when there is no
1049         request body processor defined, using the
1050         <code class="literal">ctl:forceRequestBodyVariable</code> option in the
1051         <code class="literal">REQUEST_HEADERS</code> phase.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N110C7"></a><code class="literal">REQUEST_COOKIES</code></h3></div></div><div></div></div><p>This variable is a collection of all of the cookie data. Example:
1052       the following example is using the Ampersand special operator to count
1053       how many variables are in the collection. In this rule, it would trigger
1054       if the request does not include any Cookie headers.</p><pre class="programlisting">SecRule<span class="emphasis"><em> &amp;REQUEST_COOKIES</em></span> "@eq 0"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N110D4"></a><code class="literal">REQUEST_COOKIES_NAMES</code></h3></div></div><div></div></div><p>This variable is a collection of the cookie names in the request
1055       headers. Example: the following rule will trigger if the JSESSIONID
1056       cookie is not present.</p><pre class="programlisting">SecRule<span class="emphasis"><em> &amp;REQUEST_COOKIES_NAMES:JSESSIONID</em></span> "@eq 0"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N110E1"></a><code class="literal">REQUEST_FILENAME</code></h3></div></div><div></div></div><p>This variable holds the relative <code class="literal">REQUEST_URI</code>
1057       minus the <code class="literal">QUERY_STRING</code> part (e.g. /index.php).
1058       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_FILENAME</em></span> "^/cgi-bin/login\.php$" phase:2,t:none,t:normalisePath</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please note that anti-evasion transformations are not used on
1059         <code class="literal">REQUEST_FILENAME</code> by default.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N110FD"></a><code class="literal">REQUEST_HEADERS</code></h3></div></div><div></div></div><p>This variable can be used as either a collection of all of the
1060       request headers or can be used to specify individual headers (by using
1061       REQUEST_HEADERS<span class="emphasis"><em>:Header-Name</em></span>). Example: the first
1062       example uses <code class="literal">REQUEST_HEADERS</code> as a collection and is
1063       applying the <code class="literal">validateUrlEncoding</code> operator against all
1064       headers.</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_HEADERS</em></span> "@validateUrlEncoding"</pre><p>Example: the second example is targeting only the
1065       <code class="literal">Host</code> header.</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_HEADERS:Host</em></span> "^[\d\.]+$" \
1066     "deny,log,status:400,msg:'Host header is a numeric IP address'"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11121"></a><code class="literal">REQUEST_HEADERS_NAMES</code></h3></div></div><div></div></div><p>This variable is a collection of the names of all of the request
1067       headers. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_HEADERS_NAMES</em></span> "^x-forwarded-for" \
1068     "log,deny,status:403,t:lowercase,msg:'Proxy Server Used'"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1112E"></a><code class="literal">REQUEST_LINE</code></h3></div></div><div></div></div><p>This variable holds the complete request line sent to the server
1069       (including the REQUEST_METHOD and HTTP version data). Example: this
1070       example rule will trigger if the request method is something other than
1071       GET, HEAD, POST or if the HTTP is something other than HTTP/0.9, 1.0 or
1072       1.1.</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_LINE</em></span> "!(^((?:(?:pos|ge)t|head))|http/(0\.9|1\.0|1\.1)$)" t:none,t:lowercase</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1113B"></a><code class="literal">REQUEST_METHOD</code></h3></div></div><div></div></div><p>This variable holds the request method used by the client.</p><p>The following example will trigger if the request method is either
1073       <code class="literal">CONNECT</code> or TRACE.</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_METHOD</em></span> "^((?:connect|trace))$" t:none,t:lowercase</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1114E"></a><code class="literal">REQUEST_PROTOCOL</code></h3></div></div><div></div></div><p>This variable holds the request protocol version information.
1074       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_PROTOCOL</em></span> "!^http/(0\.9|1\.0|1\.1)$" t:none,t:lowercase</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1115B"></a><code class="literal">REQUEST_URI</code></h3></div></div><div></div></div><p>This variable holds the full URL including the
1075       <code class="literal">QUERY_STRING</code> data (e.g. /index.php?p=X), however it
1076       will never contain a domain name, even if it was provided on the request
1077       line. It also does not include either the
1078       <code class="literal">REQUEST_METHOD</code> or the HTTP version info.</p><p>Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>REQUEST_URI</em></span> "attack" phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please note that anti-evasion transformations are not used on
1079         <code class="literal">REQUEST_URI</code> by default.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11179"></a><code class="literal">REQUEST_URI_RAW</code></h3></div></div><div></div></div><p>Same as <code class="literal">REQUEST_URI</code> but will contain the domain
1080       name if it was provided on the request line (e.g.
1081       http://www.example.com/index.php?p=X).</p><p>Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> REQUEST_URI_RAW</em></span> "http:/" phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Please note that anti-evasion transformations are not used on
1082         <code class="literal">REQUEST_URI_RAW</code> by default.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11193"></a><code class="literal">RESPONSE_BODY</code></h3></div></div><div></div></div><p>This variable holds the data for the response payload.</p><p>Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> RESPONSE_BODY</em></span> "ODBC Error Code"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N111A2"></a><code class="literal">RESPONSE_CONTENT_LENGTH</code></h3></div></div><div></div></div><p>Response body length in bytes. Can be available starting with
1083       phase 3 but it does not have to be (as the length of response body is
1084       not always known in advance.) If the size is not known this variable
1085       will contain a zero. If <code class="literal">RESPONSE_CONTENT_LENGTH</code>
1086       contains a zero in phase 5 that means the actual size of the response
1087       body was 0.</p><p>The value of this variable can change between phases if the body
1088       is modified. For example, in embedded mode
1089       <code class="literal">mod_deflate</code> can compress the response body between
1090       phases 4 and 5.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N111B3"></a><code class="literal">RESPONSE_CONTENT_TYPE</code></h3></div></div><div></div></div><p>Response content type. Only available starting with phase
1091       3.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N111BA"></a><code class="literal">RESPONSE_HEADERS</code></h3></div></div><div></div></div><p>This variable is similar to the REQUEST_HEADERS variable and can
1092       be used in the same manner. Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> RESPONSE_HEADERS</em></span><span class="emphasis"><em>:X-Cache</em></span> "MISS"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This variable may not have access to some headers when running in
1093       embedded-mode. Headers such as Server, Date, Connection and Content-Type
1094       are added during a later Apache hook just prior to sending the data to
1095       the client. This data should be available, however, either during
1096       ModSecurity phase:5 (logging) or when running in proxy-mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N111CE"></a><code class="literal">RESPONSE_HEADERS_NAMES</code></h3></div></div><div></div></div><p>This variable is a collection of the response header names.
1097       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>RESPONSE_HEADERS_NAMES</em></span> "Set-Cookie"</pre><p><span class="emphasis"><em>Note</em></span></p><p>Same limitations as RESPONSE_HEADERS with regards to access to
1098       some headers in embedded-mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N111E0"></a><code class="literal">RESPONSE_PROTOCOL</code></h3></div></div><div></div></div><p>This variable holds the HTTP response protocol information.
1099       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>RESPONSE_PROTOCOL</em></span> "^HTTP\/0\.9"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N111ED"></a><code class="literal">RESPONSE_STATUS</code></h3></div></div><div></div></div><p>This variable holds the HTTP response status code as generated by
1100       Apache. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>RESPONSE_STATUS</em></span> "^[45]"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This directive may not work as expected in embedded-mode as Apache
1101       handles many of the stock response codes (404, 401, etc...) earlier in
1102       Phase 2. This variable should work as expected in a proxy-mode
1103       deployment.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N111FF"></a><code class="literal">RULE</code></h3></div></div><div></div></div><p>This variable provides access to the <code class="literal">id</code>, <code class="literal">rev</code>,
1104       <code class="literal">severity</code>, <code class="literal">logdata</code>, and <code class="literal">msg</code> fields of the rule that triggered the
1105       action. Only available for expansion in action strings (e.g.<code class="literal">setvar:tx.varname=%{rule.id}</code>). Example:</p><pre class="programlisting">SecRule &amp;REQUEST_HEADERS:Host "@eq 0" "log,deny,setvar:tx.varname=<span class="emphasis"><em>%{rule.id}</em></span>"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11224"></a><code class="literal">SCRIPT_BASENAME</code></h3></div></div><div></div></div><p>This variable holds just the local filename part of
1106       SCRIPT_FILENAME. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>SCRIPT_BASENAME</em></span> "^login\.php$"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This variable is not available in proxy mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11236"></a><code class="literal">SCRIPT_FILENAME</code></h3></div></div><div></div></div><p>This variable holds the full path on the server to the requested
1107       script. (e.g. SCRIPT_NAME plus the server path). Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>SCRIPT_FILENAME</em></span> "^/usr/local/apache/cgi-bin/login\.php$"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This variable is not available in proxy mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11248"></a><code class="literal">SCRIPT_GID</code></h3></div></div><div></div></div><p>This variable holds the group id (numerical value) of the group
1108       owner of the script. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>SCRIPT_GID</em></span> "!^46$"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This variable is not available in proxy mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1125A"></a><code class="literal">SCRIPT_GROUPNAME</code></h3></div></div><div></div></div><p>This variable holds the group name of the group owner of the
1109       script. Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> SCRIPT_GROUPNAME</em></span> "!^apache$"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This variable is not available in proxy mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1126C"></a><code class="literal">SCRIPT_MODE</code></h3></div></div><div></div></div><p>This variable holds the script's permissions mode data (numerical
1110       - 1=execute, 2=write, 4=read and 7=read/write/execute). Example: will
1111       trigger if the script has the WRITE permissions set.</p><pre class="programlisting">SecRule <span class="emphasis"><em>SCRIPT_MODE</em></span> "^(2|3|6|7)$"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This variable is not available in proxy mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1127E"></a><code class="literal">SCRIPT_UID</code></h3></div></div><div></div></div><p>This variable holds the user id (numerical value) of the owner of
1112       the script. Example: the example rule below will trigger if the UID is
1113       not 46 (the Apache user).</p><pre class="programlisting">SecRule<span class="emphasis"><em> SCRIPT_UID</em></span> "!^46$"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This variable is not available in proxy mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11290"></a><code class="literal">SCRIPT_USERNAME</code></h3></div></div><div></div></div><p>This variable holds the username of the owner of the script.
1114       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>SCRIPT_USERNAME</em></span> "!^apache$"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This variable is not available in proxy mode.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N112A2"></a><code class="literal">SERVER_ADDR</code></h3></div></div><div></div></div><p>This variable contains the IP address of the server.
1115       Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> SERVER_ADDR</em></span> "^192\.168\.1\.100$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N112AF"></a><code class="literal">SERVER_NAME</code></h3></div></div><div></div></div><p>This variable contains the server's hostname or IP address.
1116       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>SERVER_NAME</em></span> "hostname\.com$"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This data is taken from the Host header submitted in the client
1117       request.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N112C1"></a><code class="literal">SERVER_PORT</code></h3></div></div><div></div></div><p>This variable contains the local port that the web server is
1118       listening on. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>SERVER_PORT</em></span> "^80$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N112CE"></a><code class="literal">SESSION</code></h3></div></div><div></div></div><p>This variable is a collection, available only after <code class="literal">setsid</code> is executed. Example: the following
1119       example shows how to initialize a SESSION collection with setsid, how to
1120       use setvar to increase the session.score values, how to set the
1121       session.blocked variable and finally how to deny the connection based on
1122       the session:blocked value.</p><pre class="programlisting">SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
1123 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
1124 SecRule REQUEST_URI "^/cgi-bin/finger$" \
1125     "phase:2,t:none,t:lowercase,t:normalisePath,pass,log,setvar:<span class="emphasis"><em>session.score</em></span>=+10"
1126 SecRule<span class="emphasis"><em> SESSION:SCORE</em></span> "@gt 50" "pass,log,setvar:<span class="emphasis"><em>session.blocked</em></span>=1"
1127 SecRule<span class="emphasis"><em> SESSION:BLOCKED</em></span> "@eq 1" "log,deny,status:403"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N112E8"></a><code class="literal">SESSIONID</code></h3></div></div><div></div></div><p>This variable is the value set with <code class="literal">setsid</code>. Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>SESSIONID</em></span> !^$ chain,nolog,pass
1128 SecRule REQUEST_COOKIES:PHPSESSID !^$
1129 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N112F9"></a><code class="literal">TIME</code></h3></div></div><div></div></div><p>This variable holds a formatted string representing the time
1130       (hour:minute:second). Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> TIME</em></span> "^(([1](8|9))|([2](0|1|2|3))):\d{2}:\d{2}$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11306"></a><code class="literal">TIME_DAY</code></h3></div></div><div></div></div><p>This variable holds the current date (1-31). Example: this rule
1131       would trigger anytime between the 10th and 20th days of the
1132       month.</p><pre class="programlisting">SecRule <span class="emphasis"><em>TIME_DAY</em></span> "^(([1](0|1|2|3|4|5|6|7|8|9))|20)$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11313"></a><code class="literal">TIME_EPOCH</code></h3></div></div><div></div></div><p>This variable holds the time in seconds since 1970.
1133       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>TIME_EPOCH</em></span> "@gt 1000"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11320"></a><code class="literal">TIME_HOUR</code></h3></div></div><div></div></div><p>This variable holds the current hour (0-23). Example: this rule
1134       would trigger during "off hours".</p><pre class="programlisting">SecRule<span class="emphasis"><em> TIME_HOUR</em></span> "^(0|1|2|3|4|5|6|[1](8|9)|[2](0|1|2|3))$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1132D"></a><code class="literal">TIME_MIN</code></h3></div></div><div></div></div><p>This variable holds the current minute (0-59). Example: this rule
1135       would trigger during the last half hour of every hour.</p><pre class="programlisting">SecRule <span class="emphasis"><em>TIME_MIN</em></span> "^(3|4|5)"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1133A"></a><code class="literal">TIME_MON</code></h3></div></div><div></div></div><p>This variable holds the current month (0-11). Example: this rule
1136       would match if the month was either November (10) or December
1137       (11).</p><pre class="programlisting">SecRule<span class="emphasis"><em> TIME_MON</em></span> "^1"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11347"></a><code class="literal">TIME_SEC</code></h3></div></div><div></div></div><p>This variable holds the current second count (0-59).
1138       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>TIME_SEC</em></span> "@gt 30"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11354"></a><code class="literal">TIME_WDAY</code></h3></div></div><div></div></div><p>This variable holds the current weekday (0-6). Example: this rule
1139       would trigger only on week-ends (Saturday and Sunday).</p><pre class="programlisting">SecRule <span class="emphasis"><em>TIME_WDAY</em></span> "^(0|6)$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11361"></a><code class="literal">TIME_YEAR</code></h3></div></div><div></div></div><p>This variable holds the current four-digit year data.
1140       Example:</p><pre class="programlisting">SecRule <span class="emphasis"><em>TIME_YEAR</em></span> "^2006$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1136E"></a><code class="literal">TX</code></h3></div></div><div></div></div><p>Transaction Collection. This is used to store pieces of data,
1141       create a transaction anomaly score, and so on. Transaction variables are
1142       set for 1 request/response cycle. The scoring and evaluation will not
1143       last past the current request/response process. Example: In this
1144       example, we are using setvar to increase the tx.score value by 5 points.
1145       We then have a follow-up run that will evaluate the transactional score
1146       this request and then it will decided whether or not to allow/deny the
1147       request through.</p><p>The following is a list of reserved names in the TX
1148       collection:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">TX:0</code> - The matching value
1149           when using the <code class="literal">@rx</code> or <code class="literal">@pm</code> operator with the <code class="literal">capture</code> action.</p></li><li><p><code class="literal">TX:1-TX:9</code> - The captured
1150           subexpression value when using the <code class="literal">@rx</code> operator with capturing parens and the
1151           <code class="literal">capture</code> action.</p></li></ul></div><pre class="programlisting">SecRule WEBSERVER_ERROR_LOG "does not exist" "phase:5,pass,<span class="emphasis"><em>setvar:tx.score=+5</em></span>"
1152 SecRule<span class="emphasis"><em> TX:SCORE</em></span> "@gt 20" deny,log</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N113A1"></a><code class="literal">USERID</code></h3></div></div><div></div></div><p>This variable is the value set with <code class="literal">setuid</code>. Example:</p><pre class="programlisting">SecAction setuid:%{REMOTE_USER},nolog
1153 SecRule<span class="emphasis"><em> USERID</em></span> "Admin"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N113B2"></a><code class="literal">WEBAPPID</code></h3></div></div><div></div></div><p>This variable is the value set with <code class="literal">SecWebAppId</code>. Example:</p><pre class="programlisting">SecWebAppId "WebApp1"
1154 SecRule<span class="emphasis"><em> WEBAPPID</em></span> "WebApp1" "chain,log,deny,status:403"
1155 SecRule REQUEST_HEADERS:Transfer-Encoding "!^$"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N113C3"></a><code class="literal">WEBSERVER_ERROR_LOG</code></h3></div></div><div></div></div><p>Contains zero or more error messages produced by the web server.
1156       Access to this variable is in phase:5 (logging). Example:</p><pre class="programlisting">SecRule<span class="emphasis"><em> WEBSERVER_ERROR_LOG</em></span> "File does not exist" "phase:5,setvar:tx.score=+5"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N113D0"></a><code class="literal">XML</code></h3></div></div><div></div></div><p>Can be used standalone (as a target for
1157       <code class="literal">validateDTD</code> and <code class="literal">validateSchema</code>) or
1158       with an XPath expression parameter (which makes it a valid target for
1159       any function that accepts plain text). Example using XPath:</p><pre class="programlisting">SecDefaultAction log,deny,status:403,phase:2
1160 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
1161     phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=<span class="emphasis"><em>XML</em></span>
1162 SecRule REQBODY_PROCESSOR "<span class="emphasis"><em>!^XML$</em></span>" skipAfter:12345
1163 SecRule <span class="emphasis"><em>XML:/employees/employee/name/text()</em></span> Fred
1164 SecRule <span class="emphasis"><em>XML:/xq:employees/employee/name/text()</em></span> Fred \
1165     id:12345,xmlns:xq=http://www.example.com/employees</pre><p>The first XPath expression does not use namespaces. It would match
1166       against payload such as this one:</p><pre class="programlisting">&lt;employees&gt;
1167     &lt;employee&gt;
1168         &lt;name&gt;Fred Jones&lt;/name&gt;
1169         &lt;address location="home"&gt;
1170             &lt;street&gt;900 Aurora Ave.&lt;/street&gt;
1171             &lt;city&gt;Seattle&lt;/city&gt;
1172             &lt;state&gt;WA&lt;/state&gt;
1173             &lt;zip&gt;98115&lt;/zip&gt;
1174         &lt;/address&gt;
1175         &lt;address location="work"&gt;
1176             &lt;street&gt;2011 152nd Avenue NE&lt;/street&gt;
1177             &lt;city&gt;Redmond&lt;/city&gt;
1178             &lt;state&gt;WA&lt;/state&gt;
1179             &lt;zip&gt;98052&lt;/zip&gt;
1180         &lt;/address&gt;
1181         &lt;phone location="work"&gt;(425)555-5665&lt;/phone&gt;
1182         &lt;phone location="home"&gt;(206)555-5555&lt;/phone&gt;
1183         &lt;phone location="mobile"&gt;(206)555-4321&lt;/phone&gt;
1184     &lt;/employee&gt;
1185 &lt;/employees&gt;</pre><p>The second XPath expression does use namespaces. It would match
1186       the following payload:</p><pre class="programlisting">&lt;xq:employees xmlns:xq="http://www.example.com/employees"&gt;
1187     &lt;employee&gt;
1188         &lt;name&gt;Fred Jones&lt;/name&gt;
1189         &lt;address location="home"&gt;
1190             &lt;street&gt;900 Aurora Ave.&lt;/street&gt;
1191             &lt;city&gt;Seattle&lt;/city&gt;
1192             &lt;state&gt;WA&lt;/state&gt;
1193             &lt;zip&gt;98115&lt;/zip&gt;
1194         &lt;/address&gt;
1195         &lt;address location="work"&gt;
1196             &lt;street&gt;2011 152nd Avenue NE&lt;/street&gt;
1197             &lt;city&gt;Redmond&lt;/city&gt;
1198             &lt;state&gt;WA&lt;/state&gt;
1199             &lt;zip&gt;98052&lt;/zip&gt;
1200         &lt;/address&gt;
1201         &lt;phone location="work"&gt;(425)555-5665&lt;/phone&gt;
1202         &lt;phone location="home"&gt;(206)555-5555&lt;/phone&gt;
1203         &lt;phone location="mobile"&gt;(206)555-4321&lt;/phone&gt;
1204     &lt;/employee&gt;
1205 &lt;/xq:employees&gt;</pre><p>Note the different namespace used in the second example.</p><p>To learn more about XPath we suggest the following
1206       resources:</p><div class="orderedlist"><ol type="1"><li><p><a href="http://www.w3.org/TR/xpath" target="_top">XPath
1207           Standard</a></p></li><li><p><a href="http://www.zvon.org/xxl/XPathTutorial/General/examples.html" target="_top">XPath
1208           Tutorial</a></p></li></ol></div></div></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
1209     a copy of this data and places it into memory. It is on this data in
1210     memory that transformation functions are applied. The raw request/response
1211     data is never altered. Transformation functions are used to transform a
1212     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
1213     previous versions of ModSecurity.</p><p>The following rule will ensure that an attacker does not use mixed
1214     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>
1215     multiple transformation actions can be used in the same rule, for example
1216     the following rule also ensures that an attacker does not use URL encoding
1217     (%xx encoding) for evasion. Note the order of the transformation
1218     functions, which ensures that a URL encoded letter is first decoded and
1219     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
1220     occurs for every rule until the next. Note that transformation actions are
1221     additive, so if a rule explicitly list actions, the translation actions
1222     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
1223       spaces (ASCII 32) and then compresses multiple consecutive space
1224       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>.
1225       This function uses only up to two bytes in the decoding process, meaning
1226       it is useful to uncover ASCII characters (that wouldn't normally be
1227       encoded) encoded using CSS encoding, or to counter evasion which is a
1228       combination of a backslash and non-hexadecimal characters (e.g.
1229       <code class="literal">ja\vascript</code> is equivalent to
1230       <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>,
1231       <code class="literal">\f</code>, <code class="literal">\n</code>, <code class="literal">\r</code>,
1232       <code class="literal">\t</code>, <code class="literal">\v</code>, <code class="literal">\\</code>,
1233       <code class="literal">\?</code>, <code class="literal">\'</code>, <code class="literal">\"</code>,
1234       <code class="literal">\xHH</code> (hexadecimal), <code class="literal">\0OOO</code> (octal). Invalid encodings are left in
1235       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
1236       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
1237           number)</p></li><li><p><code class="literal">&amp;#DDD</code> and <code class="literal">&amp;#DDD;</code> (where D is any decimal
1238           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,
1239       possibly resulting in a loss of information. It is thus useful to
1240       uncover bytes that would otherwise not need to be encoded, but it cannot
1241       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
1242       <code class="literal">\uHHHH</code> code is in the range of
1243       <code class="literal">FF01</code>-<code class="literal">FF5E</code> (the full width ASCII
1244       codes), then the higher byte is used to detect and adjust the lower
1245       byte. Otherwise, only the lower byte will be used and the higher byte
1246       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
1247       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
1248       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
1249       computed hash is in a raw binary form and may need encoded into text to
1250       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
1251       ModSecurity to remove all transformation functions associated with the
1252       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
1253       directory back-references (except when they are at the beginning of the
1254       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
1255       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
1256       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
1257       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
1258       8th bit of each target byte with a zero parity bit which allows
1259       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
1260       (<code class="literal">/* ... */</code>) with a single space
1261       (multiple consecutive occurrences of a space will not be compressed).
1262       Unterminated comments will too be replaced with a space (ASCII 32).
1263       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
1264       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
1265       encodings (i.e. the ones that use non-hexadecimal characters, or the
1266       ones that are at the end of string and have one or two characters
1267       missing) will not be converted. If you want to detect invalid encodings
1268       use the <code class="literal">@validateUrlEncoding</code>
1269       operator. The transformation function should not be used against
1270       variables that have already been URL-decoded unless it is your intention
1271       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
1272       of <code class="literal">FF01</code>-<code class="literal">FF5E</code> (the full width ASCII
1273       codes), then the higher byte is used to detect and adjust the lower
1274       byte. Otherwise, only the lower byte will be used and the higher byte
1275       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
1276       computed hash is in a raw binary form and may need encoded to be usable
1277       (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
1278       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
1279       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
1280       sides of input.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="actions"></a>Actions</h2></div></div><div></div></div><p>Each action belongs to one of five groups:</p><div class="variablelist"><dl><dt><span class="term">Disruptive actions</span></dt><dd><p>Cause ModSecurity to do something. In many cases something
1281           means block transaction, but not in all. For example, the allow
1282           action is classified as a disruptive action, but it does the
1283           opposite of blocking. There can only be one disruptive action per
1284           rule (if there are multiple disruptive actions present, or
1285           inherited, only the last one will take effect), or rule chain (in a
1286           chain, a disruptive action can only appear in the first
1287           rule).</p></dd><dt><span class="term">Non-disruptive actions</span></dt><dd><p>Do something, but that something does not and cannot affect
1288           the rule processing flow. Setting a variable, or changing its value
1289           is an example of a non-disruptive action. Non-disruptive action can
1290           appear in any rule, including each rule belonging to a chain.</p></dd><dt><span class="term">Flow actions</span></dt><dd><p>These actions affect the rule flow (for example
1291           <code class="literal">skip</code> or <code class="literal">skipAfter</code>).</p></dd><dt><span class="term">Meta-data actions</span></dt><dd><p>Meta-data actions are used to provide more information about
1292           rules. Examples include <code class="literal">id</code>,
1293           <code class="literal">rev</code>, <code class="literal">severity</code> and
1294           <code class="literal">msg</code>.</p></dd><dt><span class="term">Data actions</span></dt><dd><p>Not really actions, these are mere containers that hold data
1295           used by other actions. For example, the <code class="literal">status</code>
1296           action holds the status that will be used for blocking (if it takes
1297           place).</p></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N115EC"></a><code class="literal">allow</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Stops rule processing on a
1298       successful match and allows the transaction to proceed.</p><p><span class="emphasis"><em>Action Group:</em></span> Disruptive</p><p>Example:</p><pre class="programlisting">SecRule REMOTE_ADDR "^192\.168\.1\.100$" nolog,phase:1,<span class="emphasis"><em>allow</em></span></pre><p>Prior to ModSecurity 2.5 the <code class="literal">allow</code> action would
1299       only affect the current phase. An <code class="literal">allow</code> in phase 1
1300       would skip processing the remaining rules in phase 1 but the rules from
1301       phase 2 would execute. Starting with v2.5.0 <code class="literal">allow</code> was
1302       enhanced to allow for fine-grained control of what is done. The
1303       following rules now apply:</p><div class="orderedlist"><ol type="1"><li><p>If used one its own, like in the example above,
1304           <code class="literal">allow</code> will affect the entire transaction,
1305           stopping processing of the current phase but also skipping over all
1306           other phases apart from the logging phase. (The logging phase is
1307           special; it is designed to always execute.)</p></li><li><p>If used with parameter "phase", <code class="literal">allow</code> will
1308           cause the engine to stop processing the current phase. Other phases
1309           will continue as normal.</p></li><li><p>If used with parameter "request", <code class="literal">allow</code>
1310           will cause the engine to stop processing the current phase. The next
1311           phase to be processed will be phase
1312           <code class="literal">RESPONSE_HEADERS</code>.</p></li></ol></div><p>Examples:</p><pre class="programlisting"># Do not process request but process response.
1313 SecAction phase:1,allow:request
1314
1315 # Do not process transaction (request and response).
1316 SecAction phase:1,allow
1317 </pre><p>If you want to allow a response through, put a rule in phase
1318       <code class="literal">RESPONSE_HEADERS</code> and simply use
1319       <code class="literal">allow</code> on its own:</p><pre class="programlisting"># Allow response through.
1320 SecAction phase:3,allow</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1163C"></a>append</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Appends text given as parameter
1321       to the end of response body. For this action to work content injection
1322       must be enabled by setting <code class="literal">SecContentInjection</code> to
1323       <code class="literal">On</code>. Also make sure you check the content type of the
1324       response before you make changes to it (e.g. you don't want to inject
1325       stuff into images).</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p><span class="emphasis"><em>Processing Phases:</em></span> 3 and 4.</p><p>Example:</p><pre class="programlisting">SecRule RESPONSE_CONTENT_TYPE "^text/html" "nolog,pass,<span class="emphasis"><em>append:'&lt;hr&gt;Footer'</em></span>"</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>While macro expansion is allowed in the additional content, you
1326         are strongly cautioned against inserting user defined data
1327         fields.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1165E"></a><code class="literal">auditlog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Marks the transaction for
1328       logging in the audit log.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecRule REMOTE_ADDR "^192\.168\.1\.100$" <span class="emphasis"><em>auditlog</em></span>,phase:1,allow</pre><p><span class="emphasis"><em>Note</em></span></p><p>The auditlog action is now explicit if log is already
1329       specified.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11678"></a><code class="literal">block</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Performs the default disruptive
1330       action.</p><p><span class="emphasis"><em>Action Group:</em></span> Disruptive</p><p>It is intended to be used by ruleset writers to signify that the
1331       rule was intended to block and leaves the "how" up to the administrator.
1332       This action is currently a placeholder which will just be replaced by
1333       the action from the last <code class="literal">SecDefaultAction</code> in the same
1334       context. Using the <code class="literal">block</code> action with the
1335       <code class="literal">SecRuleUpdateActionById</code> directive allows a rule to be
1336       reverted back to the previous <code class="literal">SecDefaultAction</code>
1337       disruptive action.</p><p>In future versions of ModSecurity, more control and functionality
1338       will be added to define "how" to block.</p><p>Examples:</p><p>In the following example, the second rule will "deny" because of
1339       the SecDefaultAction disruptive action. The intent being that the
1340       administrator could easily change this to another disruptive action
1341       without editing the actual rules.</p><pre class="programlisting">### Administrator defines "how" to block (deny,status:403)...
1342 SecDefaultAction phase:2,deny,status:403,log,auditlog
1343
1344 ### Included from a rulest...
1345 # Intent is to warn for this User Agent
1346 SecRule REQUEST_HEADERS:User-Agent "perl" "phase:2,<span class="emphasis"><em>pass</em></span>,msg:'Perl based user agent identified'"
1347 # Intent is to block for this User Agent, "how" described in SecDefaultAction
1348 SecRule REQUEST_HEADERS:User-Agent "nikto" "phase:2,<span class="emphasis"><em>block</em></span>,msg:'Nikto Scanners Identified'"</pre><p>In the following example, The rule is reverted back to the
1349       <code class="literal">pass</code> action defined in the SecDefaultAction directive
1350       by using the <code class="literal">SecRuleUpdateActionById</code> directive in
1351       conjuction with the <code class="literal">block</code> action. This allows an
1352       administrator to override an action in a 3rd party rule without
1353       modifying the rule itself.</p><pre class="programlisting">### Administrator defines "how" to block (deny,status:403)...
1354 SecDefaultAction phase:2,pass,log,auditlog
1355
1356 ### Included from a rulest...
1357 SecRule REQUEST_HEADERS:User-Agent "nikto" "id:1,phase:2,<span class="emphasis"><em>deny</em></span>,msg:'Nikto Scanners Identified'"
1358
1359 ### Added by the administrator
1360 SecRuleUpdateActionById 1 "<span class="emphasis"><em>block</em></span>"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N116BD"></a><code class="literal">capture</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> When used together with the
1361       regular expression operator, capture action will create copies of
1362       regular expression captures and place them into the transaction variable
1363       collection. Up to ten captures will be copied on a successful pattern
1364       match, each with a name consisting of a digit from 0 to 9.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_BODY "^username=(\w{25,})" phase:2,<span class="emphasis"><em>capture</em></span>,t:none,chain
1365 SecRule TX:1 "(?:(?:a(dmin|nonymous)))"</pre><p><span class="emphasis"><em>Note</em></span></p><p>The 0 data captures the entire REGEX match and 1 captures the data
1366       in the first parens, etc...</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N116D7"></a><code class="literal">chain</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Chains the rule where the action
1367       is placed with the rule that immediately follows it. The result is
1368       called a<span class="emphasis"><em> rule chain</em></span>. Chained rules allow for more
1369       complex rule matches where you want to use a number of different
1370       VARIABLES to create a better rule and to help prevent false
1371       positives.</p><p><span class="emphasis"><em>Action Group:</em></span> Flow</p><p>Example:</p><pre class="programlisting"># Refuse to accept POST requests that do
1372 # not specify request body length. Do note that
1373 # this rule should be preceeded by a rule that verifies
1374 # only valid request methods (e.g. GET, HEAD and POST) are used.
1375 SecRule REQUEST_METHOD ^POST$<span class="emphasis"><em> chain</em></span>,t:none
1376 SecRule REQUEST_HEADERS:Content-Length ^$ t:none</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>In programming language concepts, think of chained rules
1377         somewhat similar to AND conditional statements. The actions specified
1378         in the first portion of the chained rule will only be triggered if all
1379         of the variable checks return positive hits. If one aspect of the
1380         chained rule is negative, then the entire rule chain is negative. Also
1381         note that disruptive actions, execution phases, metadata actions (id,
1382         rev, msg), skip and skipAfter actions can only be specified on by the
1383         chain starter rule.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N116F2"></a><code class="literal">ctl</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> The ctl action allows
1384       configuration options to be updated for the transaction.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting"># Parse requests with Content-Type "text/xml" as XML
1385 SecRule REQUEST_CONTENT_TYPE ^text/xml nolog,pass,<span class="emphasis"><em>ctl:requestBodyProcessor=XML</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>The following configuration options are supported:</p><div class="orderedlist"><ol type="1"><li><p><code class="literal">auditEngine</code></p></li><li><p><code class="literal">auditLogParts</code></p></li><li><p><code class="literal">debugLogLevel</code></p></li><li><p><code class="literal">ruleRemoveById</code> (single rule
1386           ID, or a single rule ID range accepted as parameter)</p></li><li><p><code class="literal">requestBodyAccess</code></p></li><li><p><code class="literal">forceRequestBodyVariable</code></p></li><li><p><code class="literal">requestBodyLimit</code></p></li><li><p><code class="literal">requestBodyProcessor</code></p></li><li><p><code class="literal">responseBodyAccess</code></p></li><li><p><code class="literal">responseBodyLimit</code></p></li><li><p><code class="literal">ruleEngine</code></p></li></ol></div><p>With the exception of<code class="literal">
1387       requestBodyProcessor</code> and <code class="literal">
1388       forceRequestBodyVariable</code>, each configuration option
1389       corresponds to one configuration directive and the usage is
1390       identical.</p><p>The <code class="literal">requestBodyProcessor</code> option allows you to
1391       configure the request body processor. By default ModSecurity will use
1392       the <code class="literal">URLENCODED</code> and<code class="literal"> MULTIPART</code> processors to process an <code class="literal">application/x-www-form-urlencoded</code> and a
1393       <code class="literal">multipart/form-data</code> bodies,
1394       respectively. A third processor, <code class="literal">XML</code>, is also
1395       supported, but it is never used implicitly. Instead you must tell
1396       ModSecurity to use it by placing a few rules in the<code class="literal"> REQUEST_HEADERS</code> processing phase. After the
1397       request body was processed as XML you will be able to use the
1398       XML-related features to inspect it.</p><p>Request body processors will not interrupt a transaction if an
1399       error occurs during parsing. Instead they will set variables<code class="literal"> REQBODY_PROCESSOR_ERROR</code> and<code class="literal"> REQBODY_PROCESSOR_ERROR_MSG</code>. These variables
1400       should be inspected in the <code class="literal">REQUEST_BODY</code> phase and an appropriate action
1401       taken.</p><p>The <code class="literal">forceRequestBodyVariable</code> option allows you
1402       to configure the <code class="literal">REQUEST_BODY</code> variable to be set when
1403       there is no request body processor configured. This allows for
1404       inspection of request bodies of unknown types.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11786"></a><code class="literal">deny</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Stops rule processing and
1405       intercepts transaction.</p><p><span class="emphasis"><em>Action Group:</em></span> Disruptive</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "nikto" "log,<span class="emphasis"><em>deny</em></span>,msg:'Nikto Scanners Identified'"</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1179B"></a><code class="literal">deprecatevar</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Decrement counter based on its
1406       age.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-Disruptive</p><p>Example: The following example will decrement the counter by 60
1407       every 300 seconds.</p><pre class="programlisting">SecAction deprecatevar:session.score=60/300</pre><p><span class="emphasis"><em>Note</em></span></p><p>Counter values are always positive, meaning the value will never
1408       go below zero.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N117B2"></a><code class="literal">drop</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Immediately initiate a
1409       "connection close" action to tear down the TCP connection by sending a
1410       FIN packet.</p><p><span class="emphasis"><em>Action Group:</em></span> Disruptive</p><p>Example: The following example initiates an IP collection for
1411       tracking Basic Authentication attempts. If the client goes over the
1412       threshold of more than 25 attempts in 2 minutes, it will DROP subsequent
1413       connections.</p><pre class="programlisting">SecAction phase:1,initcol:ip=%{REMOTE_ADDR},nolog
1414 SecRule ARGS:login "!^$" \
1415     nolog,phase:1,setvar:ip.auth_attempt=+1,deprecatevar:ip.auth_attempt=20/120
1416 SecRule IP:AUTH_ATTEMPT "@gt 25" \
1417     "log,<span class="emphasis"><em>drop</em></span>,phase:1,msg:'Possible Brute Force Attack'"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This action is currently not available on Windows based builds.
1418       This action is extremely useful when responding to both Brute Force and
1419       Denial of Service attacks in that, in both cases, you want to minimize
1420       both the network bandwidth and the data returned to the client. This
1421       action causes error message to appear in the log "(9)Bad file
1422       descriptor: core_output_filter: writing data to the network"</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N117CC"></a><code class="literal">exec</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Executes an external
1423       script/binary supplied as parameter. As of v2.5.0, if the parameter
1424       supplied to <code class="literal">exec</code> is a Lua script (detected by the
1425       <code class="filename">.lua</code> extension) the script will be processed
1426       <span class="emphasis"><em>internally</em></span>. This means you will get direct access
1427       to the internal request context from the script. Please read the
1428       <code class="literal">SecRuleScript</code> documentation for more details on how
1429       to write Lua scripts.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting"># The following is going to execute /usr/local/apache/bin/test.sh
1430 # as a shell script on rule match.
1431 SecRule REQUEST_URI "^/cgi-bin/script\.pl" \
1432     "phase:2,t:none,t:lowercase,t:normalisePath,log,<span class="emphasis"><em>exec:/usr/local/apache/bin/test.sh</em></span>"
1433
1434 # The following is going to process /usr/local/apache/conf/exec.lua
1435 # internally as a Lua script on rule match.
1436 SecRule ARGS:p attack log,<span class="emphasis"><em>exec:/usr/local/apache/conf/exec.lua</em></span></pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The exec action is executed independently from any disruptive
1437         actions. External scripts will always be called with no parameters.
1438         Some transaction information will be placed in environment variables.
1439         All the usual CGI environment variables will be there. You should be
1440         aware that forking a threaded process results in all threads being
1441         replicated in the new process. Forking can therefore incur larger
1442         overhead in multi-threaded operation. The script you execute must
1443         write something (anything) to stdout. If it doesn't ModSecurity will
1444         assume execution didn't work.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N117F5"></a><code class="literal">expirevar</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures a collection variable
1445       to expire after the given time in seconds.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_COOKIES:JSESSIONID "!^$" nolog,phase:1,pass,chain
1446 SecAction setsid:%{REQUEST_COOKIES:JSESSIONID}
1447 SecRule REQUEST_URI "^/cgi-bin/script\.pl" \
1448     "phase:2,t:none,t:lowercase,t:normalisePath,log,allow,\
1449 setvar:session.suspicious=1,<span class="emphasis"><em>expirevar:session.suspicious=3600</em></span>,phase:1"</pre><p><span class="emphasis"><em>Note</em></span></p><p>You should use expirevar actions at the same time that you use
1450       setvar actions in order to keep the indented expiration time. If they
1451       are used on their own (perhaps in a SecAction directive) the expire time
1452       could get re-set. When variables are removed from collections, and there
1453       are no other changes, collections are not written to disk at the end of
1454       request. This is because the variables can always be expired again when
1455       the collection is read again on a subsequent request.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1180F"></a><code class="literal">id</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Assigns a unique ID to the rule
1456       or chain.</p><p><span class="emphasis"><em>Action Group:</em></span> Meta-data</p><p>Example:</p><pre class="programlisting">SecRule &amp;REQUEST_HEADERS:Host "@eq 0" \
1457     "log,<span class="emphasis"><em>id:60008</em></span>,severity:2,msg:'Request Missing a Host Header'"</pre><p><span class="emphasis"><em>Note</em></span></p><p>These are the reserved ranges:</p><div class="itemizedlist"><ul type="disc"><li><p>1-99,999; reserved for local (internal) use. Use as you see
1458           fit but do not use this range for rules that are distributed to
1459           others.</p></li><li><p>100,000-199,999; reserved for internal use of the engine, to
1460           assign to rules that do not have explicit IDs.</p></li><li><p>200,000-299,999; reserved for rules published at
1461           modsecurity.org.</p></li><li><p>300,000-399,999; reserved for rules published at
1462           gotroot.com.</p></li><li><p>400,000-419,999; unused (available for reservation).</p></li><li><p>420,000-429,999; reserved for <a href="http://projects.otaku42.de/wiki/ScallyWhack" target="_top">ScallyWhack</a>.</p></li><li><p>430,000-899,999; unused (available for reservation).</p></li><li><p>900,000-999,999; reserved for the <a href="http://www.modsecurity.org/projects/rules/" target="_top">Core Rules</a>
1463           project.</p></li><li><p>1,000,000 and above; unused (available for
1464           reservation).</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1184E"></a><code class="literal">initcol</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Initialises a named persistent
1465       collection, either by loading data from storage or by creating a new
1466       collection in memory.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example: The following example initiates IP address
1467       tracking.</p><pre class="programlisting">SecAction <span class="emphasis"><em>phase:1,initcol:ip=%{REMOTE_ADDR}</em></span>,nolog</pre><p><span class="emphasis"><em>Note</em></span></p><p>Normally you will want to use <span class="emphasis"><em>phase:1</em></span> along
1468       with <span class="emphasis"><em>initcol</em></span> so that the collection is available in
1469       all phases.</p><p>Collections are loaded into memory when the initcol action is
1470       encountered. The collection in storage will be persisted (and the
1471       appropriate counters increased) <span class="emphasis"><em>only</em></span> if it was
1472       changed during transaction processing.</p><p>See the "Persistant Storage" section for further details.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11875"></a><code class="literal">log</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Indicates that a successful
1473       match of the rule needs to be logged.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecAction phase:1,initcol:ip=%{REMOTE_ADDR},<span class="emphasis"><em>log</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>This action will log matches to the Apache error log file and the
1474       ModSecurity audit log.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1188E"></a><code class="literal">logdata</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Allows a data fragment to be
1475       logged as part of the alert message.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecRule &amp;ARGS:p "@eq 0" "log,<span class="emphasis"><em>logdata:'%{TX.0}'"</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>The logdata information appears in the error and/or audit log
1476       files and is not sent back to the client in response headers. Macro
1477       expansion is preformed so you may use variable names such as %{TX.0},
1478       etc. The information is properly escaped for use with logging binary
1479       data.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N118A7"></a><code class="literal">msg</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Assigns a custom message to the
1480       rule or chain.</p><p><span class="emphasis"><em>Action Group:</em></span> Meta-data</p><p>Example:</p><pre class="programlisting">SecRule &amp;REQUEST_HEADERS:Host "@eq 0" \
1481     "log,id:60008<span class="emphasis"><em>,</em></span>severity:2,<span class="emphasis"><em>msg:'Request Missing a Host Header'"</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>The msg information appears in the error and/or audit log files
1482       and is not sent back to the client in response headers.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N118C3"></a><code class="literal">multiMatch</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> If enabled ModSecurity will
1483       perform multiple operator invocations for every target, before and after
1484       every anti-evasion transformation is performed.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase
1485 SecRule ARGS "attack" <span class="emphasis"><em>multiMatch</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>Normally, variables are evaluated once, only after all
1486       transformation functions have completed. With multiMatch, variables are
1487       checked against the operator before and after every transformation
1488       function that changes the input.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N118DC"></a><code class="literal">noauditlog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Indicates that a successful
1489       match of the rule should not be used as criteria whether the transaction
1490       should be logged to the audit log.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "Test" allow,<span class="emphasis"><em>noauditlog</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>If the SecAuditEngine is set to On, all of the transactions will
1491       be logged. If it is set to RelevantOnly, then you can control it with
1492       the noauditlog action. Even if the noauditlog action is applied to a
1493       specific rule and a rule either before or after triggered an audit
1494       event, then the transaction will be logged to the audit log. The correct
1495       way to disable audit logging for the entire transaction is to use
1496       "<code class="literal">ctl:auditEngine=Off</code>"</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N118F9"></a><code class="literal">nolog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Prevents rule matches from
1497       appearing in both the error and audit logs.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "Test" allow,<span class="emphasis"><em>nolog</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>The nolog action also implies noauditlog.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11912"></a><code class="literal">pass</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Continues processing with the
1498       next rule in spite of a successful match.</p><p><span class="emphasis"><em>Action Group:</em></span> Disruptive</p><p>Example1:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "Test" log,<span class="emphasis"><em>pass</em></span></pre><p>When using <span class="emphasis"><em>pass</em></span> with SecRule with multiple
1499       targets, <span class="emphasis"><em>all</em></span> targets will be processed and
1500       <span class="emphasis"><em>all</em></span> non-disruptive actions will trigger for
1501       <span class="emphasis"><em>every</em></span> match found. In the second example the
1502       TX:test target would be incremented by 1 for each matching
1503       argument.</p><p>Example2:</p><pre class="programlisting">SecRule ARGS "test" log,<span class="emphasis"><em>pass</em></span>,setvar:TX.test=+1</pre><p><span class="emphasis"><em>Note</em></span></p><p>The transaction will not be interrupted but a log will be
1504       generated for each matching target (unless logging has been
1505       suppressed).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11941"></a><code class="literal">pause</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Pauses transaction processing
1506       for the specified number of milliseconds.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "Test" log,deny,status:403,<span class="emphasis"><em>pause:5000</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>This feature can be of limited benefit for slowing down Brute
1507       Force Scanners, however use with care. If you are under a Denial of
1508       Service type of attack, the pause feature may make matters worse as this
1509       feature will cause child processes to sit idle until the pause is
1510       completed.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1195A"></a><code class="literal">phase</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Places the rule (or the rule
1511       chain) into one of five available processing phases.</p><p><span class="emphasis"><em>Action Group:</em></span> Meta-data</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,<span class="emphasis"><em>phase:1</em></span>,t:removeNulls,t:lowercase
1512 SecRule REQUEST_HEADERS:User-Agent "Test" log,deny,status:403</pre><p><span class="emphasis"><em>Note</em></span></p><p>Keep in mind that is you specify the incorrect phase, the target
1513       variable that you specify may be empty. This could lead to a false
1514       negative situation where your variable and operator (RegEx) may be
1515       correct, but it misses malicious data because you specified the wrong
1516       phase.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11974"></a>prepend</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Prepends text given as parameter
1517       to the response body. For this action to work content injection must be
1518       enabled by setting <code class="literal">SecContentInjection</code> to
1519       <code class="literal">On</code>. Also make sure you check the content type of the
1520       response before you make changes to it (e.g. you don't want to inject
1521       stuff into images).</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p><span class="emphasis"><em>Processing Phases:</em></span> 3 and 4.</p><p>Example:</p><pre class="programlisting">SecRule RESPONSE_CONTENT_TYPE ^text/html "phase:3,nolog,pass,<span class="emphasis"><em>prepend:'Header&lt;br&gt;'</em></span>"</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>While macro expansion is allowed in the additional content, you
1522         are strongly cautioned against inserting user defined data
1523         fields.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11996"></a><code class="literal">proxy</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Intercepts transaction by
1524       forwarding request to another web server using the proxy backend.</p><p><span class="emphasis"><em>Action Group:</em></span> Disruptive</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "Test" log,<span class="emphasis"><em>proxy:http://www.honeypothost.com/</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>For this action to work, mod_proxy must also be installed. This
1525       action is useful if you would like to proxy matching requests onto a
1526       honeypot webserver.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N119AF"></a><code class="literal">redirect</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Intercepts transaction by
1527       issuing a redirect to the given location.</p><p><span class="emphasis"><em>Action Group:</em></span> Disruptive</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:User-Agent "Test" \
1528     log,<span class="emphasis"><em>redirect:http://www.hostname.com/failed.html</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>If the <code class="literal">status</code> action is present
1529       and its value is acceptable (301, 302, 303, or 307) it will be used for
1530       the redirection. Otherwise status code 302 will be used.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N119CC"></a><code class="literal">rev</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Specifies rule revision.</p><p><span class="emphasis"><em>Action Group:</em></span> Meta-data</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_METHOD "^PUT$" "id:340002,<span class="emphasis"><em>rev:1</em></span>,severity:2,msg:'Restricted HTTP function'"</pre><p><span class="emphasis"><em>Note</em></span></p><p>This action is used in combination with the <code class="literal">id</code> action to allow the same rule ID to be used
1531       after changes take place but to still provide some indication the rule
1532       changed.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N119EA"></a><code class="literal">sanitiseArg</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Sanitises (replaces each byte
1533       with an asterisk) a named request argument prior to audit
1534       logging.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecAction nolog,phase:2,<span class="emphasis"><em>sanitiseArg:password</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>The sanitize actions do not sanitize any data within the actual
1535       raw requests but only on the copy of data within memory that is set to
1536       log to the audit log. It will not sanitize the data in the
1537       modsec_debug.log file (if the log level is set high enough to capture
1538       this data).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A03"></a><code class="literal">sanitiseMatched</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Sanitises the variable (request
1539       argument, request header, or response header) that caused a rule
1540       match.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example: This action can be used to sanitise arbitrary transaction
1541       elements when they match a condition. For example, the example below
1542       will sanitise any argument that contains the word<span class="emphasis"><em>
1543       password</em></span> in the name.</p><pre class="programlisting">SecRule ARGS_NAMES password nolog,pass,<span class="emphasis"><em>sanitiseMatched</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>Same note as sanitiseArg.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A1F"></a><code class="literal">sanitiseRequestHeader</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Sanitises a named request
1544       header.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example: This will sanitise the data in the Authorization
1545       header.</p><pre class="programlisting">SecAction log,phase:1,<span class="emphasis"><em>sanitiseRequestHeader:Authorization</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>Same note as sanitiseArg.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A38"></a><code class="literal">sanitiseResponseHeader</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Sanitises a named response
1546       header.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example: This will sanitise the Set-Cookie data sent to the
1547       client.</p><pre class="programlisting">SecAction log,phase:3,<span class="emphasis"><em>sanitiseResponseHeader:Set-Cookie</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>Same note as sanitiseArg.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A51"></a><code class="literal">severity</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Assigns severity to the rule it
1548       is placed with.</p><p><span class="emphasis"><em>Action Group:</em></span> Meta-data</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_METHOD "^PUT$" "id:340002,rev:1,<span class="emphasis"><em>severity:CRITICAL</em></span>,msg:'Restricted HTTP function'"</pre><p><span class="emphasis"><em>Note</em></span></p><p>Severity values in ModSecurity follow those of syslog, as
1549       below:</p><div class="itemizedlist"><ul type="disc"><li><p>0 - EMERGENCY</p></li><li><p>1 - ALERT</p></li><li><p>2 - CRITICAL</p></li><li><p>3 - ERROR</p></li><li><p>4 - WARNING</p></li><li><p>5 - NOTICE</p></li><li><p>6 - INFO</p></li><li><p>7 - DEBUG</p></li></ul></div><p>It is possible to specify severity levels using either the
1550       numerical values or the text values. You should always specify severity
1551       levels using the text values. The use of the numerical values is
1552       deprecated (as of v2.5.0) and may be removed in one of the susequent
1553       major updates.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A86"></a><code class="literal">setuid</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Special-purpose action that
1554       initialises the <code class="literal">USER</code>
1555       collection.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecAction <span class="emphasis"><em>setuid:%{REMOTE_USER}</em></span>,nolog</pre><p><span class="emphasis"><em>Note</em></span></p><p>After initialisation takes place the variable <code class="literal">USERID</code> will be available for use in the
1556       subsequent rules.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11AA8"></a><code class="literal">setsid</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Special-purpose action that
1557       initialises the <code class="literal">SESSION</code>
1558       collection.</p><p><span class="emphasis"><em>Action Group: </em></span>Non-disruptive</p><p>Example:</p><pre class="programlisting"># Initialise session variables using the session cookie value
1559 SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
1560 SecAction <span class="emphasis"><em>setsid:%{REQUEST_COOKIES.PHPSESSID}</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>On first invocation of this action the collection will be empty
1561       (not taking the predefined variables into account - see <code class="literal">initcol</code> for more information). On subsequent
1562       invocations the contents of the collection (session, in this case) will
1563       be retrieved from storage. After initialisation takes place the
1564       variable<code class="literal"> SESSIONID</code> will be available
1565       for use in the subsequent rules.This action understands each application
1566       maintains its own set of sessions. It will utilise the current web
1567       application ID to create a session namespace.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11ACD"></a><code class="literal">setenv</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Creates, removes, or updates an
1568       environment variable.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Examples:</p><p>To create a new variable (if you omit the value <code class="literal">1</code> will be used):</p><pre class="programlisting">setenv:name=value</pre><p>To remove a variable:</p><pre class="programlisting">setenv:!name</pre><p><span class="emphasis"><em>Note</em></span></p><p>This action can be used to establish communication with other
1569       Apache modules.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11AEF"></a><code class="literal">setvar</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Creates, removes, or updates a
1570       variable in the specified collection.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Examples:</p><p>To create a new variable:</p><pre class="programlisting">setvar:tx.score=10</pre><p>To remove a variable prefix the name with exclamation mark:</p><pre class="programlisting">setvar:!tx.score</pre><p>To increase or decrease variable value use <code class="literal">+</code> and <code class="literal">-</code>
1571       characters in front of a numerical value:</p><pre class="programlisting">setvar:tx.score=+5</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11B15"></a><code class="literal">skip</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Skips one or more rules (or
1572       chains) on successful match.</p><p><span class="emphasis"><em>Action Group:</em></span> Flow</p><p>Example:</p><p><pre class="programlisting">SecRule REQUEST_URI "^/$" \
1573 "phase:2,chain,t:none<span class="emphasis"><em>,skip:2</em></span>"
1574 SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
1575 SecRule REQUEST_HEADERS:User-Agent "^Apache \(internal dummy connection\)$" "t:none"
1576 SecRule &amp;REQUEST_HEADERS:Host "@eq 0" \
1577     "deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'"
1578 SecRule &amp;REQUEST_HEADERS:Accept "@eq 0" \
1579     "log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'"</pre></p><p><span class="emphasis"><em>Note</em></span></p><p>Skip only applies to the current processing phase and not
1580       necessarily the order in which the rules appear in the configuration
1581       file. If you group rules by processing phases, then skip should work as
1582       expected. This action can not be used to skip rules within one chain.
1583       Accepts a single parameter denoting the number of rules (or chains) to
1584       skip.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11B30"></a><code class="literal">skipAfter</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Skips rules (or chains) on
1585       successful match resuming rule execution after the specified rule ID or
1586       marker (see <code class="literal">SecMarker</code>) is found.</p><p><span class="emphasis"><em>Action Group:</em></span> Flow</p><p>Example:</p><p><pre class="programlisting">SecRule REQUEST_URI "^/$" "chain,t:none,<span class="emphasis"><em>skipAfter:960015</em></span>"
1587 SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
1588 SecRule REQUEST_HEADERS:User-Agent "^Apache \(internal dummy connection\)$" "t:none"
1589 SecRule &amp;REQUEST_HEADERS:Host "@eq 0" \
1590     "deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'"
1591 SecRule &amp;REQUEST_HEADERS:Accept "@eq 0" \
1592     "log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'"</pre></p><p><span class="emphasis"><em>Note</em></span></p><p><code class="literal">SkipAfter</code> only applies to the current
1593       processing phase and not necessarily the order in which the rules appear
1594       in the configuration file. If you group rules by processing phases, then
1595       skip should work as expected. This action can not be used to skip rules
1596       within one chain. Accepts a single parameter denoting the last rule ID
1597       to skip.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11B52"></a><code class="literal">status</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Specifies the response status
1598       code to use with actions<code class="literal"> deny</code>
1599       and<code class="literal"> redirect</code>.</p><p><span class="emphasis"><em>Action Group:</em></span> Data</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,<span class="emphasis"><em>status:403</em></span>,phase:1</pre><p><span class="emphasis"><em>Note</em></span></p><p>Status actions defined in Apache scope locations (such as
1600       Directory, Location, etc...) may be superseded by phase:1 action
1601       settings. The Apache ErrorDocument directive will be triggered if
1602       present in the configuration. Therefore if you have previously defined a
1603       custom error page for a given status then it will be executed and its
1604       output presented to the user.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11B74"></a><code class="literal">t</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This action can be used which
1605       transformation function should be used against the specified variables
1606       before they (or the results, rather) are run against the operator
1607       specified in the rule.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase
1608 SecRule REQUEST_COOKIES:SESSIONID "47414e81cbbef3cf8366e84eeacba091" \
1609     log,deny,status:403,<span class="emphasis"><em>t:md5,t:hexEncode</em></span></pre><p><span class="emphasis"><em>Note</em></span></p><p>Any transformation functions that you specify in a SecRule will be
1610       in addition to previous ones specified in SecDefaultAction. Use of
1611       "t:none" will remove all transformation functions for the specified
1612       rule.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11B8D"></a><code class="literal">tag</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Assigns custom text to a rule or
1613       chain.</p><p><span class="emphasis"><em>Action Group:</em></span> Meta-data</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_FILENAME "\b(?:n(?:map|et|c)|w(?:guest|sh)|cmd(?:32)?|telnet|rcmd|ftp)\.exe\b" \
1614     "t:none,t:lowercase,deny,msg:'System Command Access',id:'950002',<span class="emphasis"><em>\
1615 tag:'WEB_ATTACK/FILE_INJECTION',tag:'OWASP/A2'</em></span>,severity:'2'"</pre><p><span class="emphasis"><em>Note</em></span></p><p>The tag information appears in the error and/or audit log files.
1616       Its intent is to be used to automate classification of rules and the
1617       alerts generated by rules. Multiple tags can be used per
1618       rule/chain.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11BA7"></a><code class="literal">xmlns</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> This action should be used
1619       together with an XPath expression to register a namespace.</p><p><span class="emphasis"><em>Action Group:</em></span> Data</p><p>Example:</p><pre class="programlisting">SecRule REQUEST_HEADERS:Content-Type "text/xml" \
1620     "phase:1,pass,ctl:requestBodyProcessor=XML,ctl:requestBodyAccess=On,<span class="emphasis"><em> \
1621     xmlns:xsd="http://www.w3.org/2001/XMLSchema"</em></span>
1622 SecRule XML:/soap:Envelope/soap:Body/q1:getInput/id() "123" phase:2,deny</pre></div></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
1623     operator syntax uses the <code class="literal">@</code> symbol followed by the
1624     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
1625       comparison and returns true if the parameter value is found at the
1626       beginning of the input. Macro expansion is performed so you may use
1627       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
1628 SecRule REQUEST_ADDR "^(.*)\.\d+$" deny,status:403,capture,chain
1629 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
1630       comparison and returns true if the parameter value is found anywhere in
1631       the input. Macro expansion is performed so you may use variable names
1632       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
1633 SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain
1634 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
1635       comparison and returns true if the parameter value is found at the end
1636       of the input. Macro expansion is performed so you may use variable names
1637       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
1638 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
1639       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
1640       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
1641       data fields from an IP address or hostname in the target data. The
1642       results will be captured in the <code class="literal">GEO</code>
1643       collection.</p><p>You must provide a database via <code class="literal">SecGeoLookupDb</code> before this operator can be
1644       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>
1645         successful</em></span> lookup. For this reason, you probably want to
1646         use the <span class="emphasis"><em>pass,nolog</em></span> actions. This allows for
1647         <code class="literal">setvar</code> and other non-disruptive
1648         actions to be executed on a match. If you wish to block on a failed
1649         lookup, then do something like this (look for an empty GEO
1650         collection):</p><pre class="programlisting">SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat
1651 ...
1652 SecRule REMOTE_ADDR "@geoLookup" "pass,nolog"
1653 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
1654       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
1655       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
1656       script/binary given as parameter to the operator against every file
1657       extracted from the request. As of v2.5.0, if the supplied filename is
1658       not absolute it is treated as relative to the directory in which the
1659       configuration file resides. Also as of v2.5.0, if the filename is
1660       determined to be a Lua script (based on its extension) the script will
1661       be processed by the internal engine. As such it will have full access to
1662       the ModSecurity context.</p><p>Example of using an external binary/script:</p><pre class="programlisting"># Execute external script to validate uploaded files.
1663 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)
1664     -- Do something to the file to verify it. In this example, we
1665     -- read up to 10 characters from the beginning of the file.
1666     local f = io.open(filename, "rb");
1667     local d = f:read(10);
1668     f:close();
1669
1670     -- Return null if there is no reason to believe there is ansything
1671     -- wrong with the file (no match). Returning any text will be taken
1672     -- to mean a match should be trigerred.
1673     return null;
1674 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
1675       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
1676       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
1677       operator uses a set based matching engine (Aho-Corasick) for faster
1678       matches of keyword lists. It will match any one of its arguments
1679       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
1680       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
1681       operator uses a set based matching engine (Aho-Corasick) for faster
1682       matches of keyword lists. This operator is the same as
1683       <code class="literal">@pm</code> except that it takes a list of files as
1684       arguments. It will match any one of the phrases listed in the file(s)
1685       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
1686           of line markers will be stripped from the phrases, however,
1687           whitespace will not be trimmed from phrases in the file. Empty lines
1688           and comment lines (beginning with a '#') are ignored.</p></li><li><p>To allow easier inclusion of phrase files with rulesets,
1689           relative paths may be used to the phrase files. In this case, the
1690           path of the file containing the rule is prepended to the phrase file
1691           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
1692       two files matched within the User-Agent HTTP header value. The
1693       <code class="literal">blacklist2</code> file would need to be placed in the same
1694       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
1695       given as parameter. Parameter can be an IPv4 address, or a
1696       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.
1697       This is the default operator, so if the "@" operator is not defined, it
1698       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
1699       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
1700           are newline characters present.</p></li><li><p>All matches are case-sensitive. If you do not care about case
1701           sensitivity you either need to implement the <code class="literal">lowercase</code> transformation function, or use
1702           the per-pattern<code class="literal">(?i)</code>modifier, as
1703           allowed by PCRE.</p></li><li><p>The <code class="literal">PCRE_DOTALL</code> and
1704           <code class="literal">PCRE_DOLLAR_ENDONLY</code> flags are set
1705           during compilation, meaning a single dot will match any character,
1706           including the newlines and a <code class="literal">$</code>
1707           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
1708       comparison and returns true if the parameter value matches the input
1709       exactly. Macro expansion is performed so you may use variable names such
1710       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
1711 SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain
1712 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
1713       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
1714       byte range. This can be useful to avoid stack overflow attacks (since
1715       they usually contain "random" binary content). Default range values are
1716       0 and 255, i.e. all byte values are allowed. This directive does not
1717       check byte range in a POST payload when
1718       <code class="literal">multipart/form-data</code> encoding (file upload) is used.
1719       Doing so would prevent binary files from being uploaded. However, after
1720       the parameters are extracted from such request they are checked for a
1721       valid range.</p><p>validateByteRange is similar to the ModSecurity 1.X
1722       SecFilterForceByteRange Directive however since it works in a rule
1723       context, it has the following differences:</p><div class="itemizedlist"><ul type="disc"><li><p>You can specify a different range for different
1724           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
1725           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
1726       by the XML request body processor against the supplied DTD.</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,status:403,phase:2
1727 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
1728     phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML
1729 SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345
1730 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
1731         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
1732       by the XML request body processor against the supplied XML
1733       Schema.</p><p>Example:</p><pre class="programlisting">SecDefaultAction log,deny,status:403,phase:2
1734 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
1735     phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML
1736 SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345
1737 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
1738         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
1739       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
1740       URL. The byte is escaped with a % followed by two hexadecimal values
1741       (0-F). This directive does not check encoding in a POST payload when the
1742       <code class="literal">multipart/form-data</code> encoding (file upload) is used.
1743       It is not necessary to do so because URL encoding is not used for this
1744       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
1745       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
1746       between 0-65535 are encoded in a UTF-8 byte sequence that is escaped by
1747       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
1748           six byte encodings. ModSecurity will locate cases when a byte or
1749           more is missing.</p></li><li><p>Invalid encoding. The two most significant bits in most
1750           characters are supposed to be fixed to 0x80. Attackers can use this
1751           to subvert Unicode decoders.</p></li><li><p>Overlong characters. ASCII characters are mapped directly into
1752           the Unicode space and are thus represented with a single byte.
1753           However, most ASCII characters can also be encoded with two, three,
1754           four, five, and six characters thus tricking the decoder into
1755           thinking that the character is something else (and, presumably,
1756           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
1757       regular expression as a potential credit card number. It first matches
1758       with a single generic regular expression then runs the resulting match
1759       through a Luhn checksum algorithm to further verify it as a potential
1760       credit card number.</p><p>Example:</p><pre class="programlisting">SecRule ARGS "<span class="emphasis"><em>@verifyCC \d{13,16}</em></span>" \
1761               "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
1762       comparison and returns true if the input value is found anywhere within
1763       the parameter value. Note that this is similar to
1764       <code class="literal">@contains</code>, except that the target and match values
1765       are reversed. Macro expansion is performed so you may use variable names
1766       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
1767
1768 SecAction "pass,setvar:'tx.allowed_methods=get,post,head'"
1769 SecRule REQUEST_METHOD "!<span class="emphasis"><em>@within %{tx.allowed_methods}</em></span>" t:lowercase,deny,status:403</pre></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N11DF1"></a>Macro Expansion</h2></div></div><div></div></div><p>Macros allow for using place holders in rules that will be expanded
1770     out to their values at runtime. Currently only variable expansion is
1771     supported, however more options may be added in future versions of
1772     ModSecurity.</p><p>Format:</p><pre class="programlisting">%{VARIABLE}
1773 %{COLLECTION.VARIABLE}</pre><p>Macro expansion can be used in actions such as initcol, setsid,
1774     setuid, setvar, setenv, logdata. Operators that are evaluated at runtime
1775     support expansion and are noted above. Such operators include @beginsWith,
1776     @endsWith, @contains, @within and @streq. You cannot use macro expansion
1777     for operators that are "compiled" such as @pm, @rx, etc. as these
1778     operators have their values fixed at configure time for efficiency.</p><p>Some values you may want to expand include: TX, REMOTE_ADDR, USERID,
1779     HIGHEST_SEVERITY, MATCHED_VAR, MATCHED_VAR_NAME, MULTIPART_STRICT_ERROR,
1780     RULE, SESSION, USERID, among others.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N11DFF"></a>Persistant Storage</h2></div></div><div></div></div><p>At this time it is only possible to have three collections in which
1781     data is stored persistantly (i.e. data available to multiple requests).
1782     These are: <code class="literal">IP</code>, <code class="literal"> SESSION</code> and <code class="literal">USER</code>.</p><p>Every collection contains several built-in variables that are
1783     available and are read-only unless otherwise specified:</p><div class="orderedlist"><ol type="1"><li><p><code class="literal">CREATE_TIME</code> - date/time of
1784         the creation of the collection.</p></li><li><p><code class="literal">IS_NEW</code> - set to 1 if the
1785         collection is new (not yet persisted) otherwise set to 0.</p></li><li><p><code class="literal">KEY</code> - the value of the
1786         initcol variable (the client's IP address in the example).</p></li><li><p><code class="literal">LAST_UPDATE_TIME</code> - date/time
1787         of the last update to the collection.</p></li><li><p><code class="literal">TIMEOUT</code> - date/time in
1788         seconds when the collection will be updated on disk from memory (if no
1789         other updates occur). This variable may be set if you wish to specifiy
1790         an explicit expiration time (default is 3600 seconds).</p></li><li><p><code class="literal">UPDATE_COUNTER</code> - how many
1791         times the collection has been updated since creation.</p></li><li><p><code class="literal">UPDATE_RATE</code> - is the average
1792         rate updates per minute since creation.</p></li></ol></div><p>To create a collection to hold session variables (<code class="literal">SESSION</code>) use action <code class="literal">setsid</code>. To create a collection to hold user
1793     variables (<code class="literal">USER</code>) use action <code class="literal">setuid</code>. To create a collection to hold client
1794     address variables (<code class="literal">IP</code>) use action
1795     <code class="literal">initcol</code>.</p><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>ModSecurity implements atomic updates of persistent variables only
1796       for integer variables (counters) at this time. Variables are read from
1797       storage whenever <code class="literal">initcol</code> is encountered in the rules
1798       and persisted at the end of request processing. Counters are adjusted by
1799       applying a delta generated by re-reading the persisted data just before
1800       being persisted. This keeps counter data consistent even if the counter
1801       was modified and persisted by another thread/process during the
1802       transaction.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>ModSecurity uses a Berkley Database (SDBM) for persistant storage.
1803       This type of database is generally limited to storing a maximum of 1008
1804       bytes per key. This may be a limitation if you are attempting to store a
1805       considerable amount of data in variables for a single key. Some of this
1806       limitation is planned to be reduced in a future version of
1807       ModSecurity.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="N11E63"></a>Miscellaneous Topics</h2></div></div><div></div></div><p></p><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11E67"></a>Impedance Mismatch</h3></div></div><div></div></div><p>Web application firewalls have a difficult job trying to make
1808       sense of data that passes by, without any knowledge of the application
1809       and its business logic. The protection they provide comes from having an
1810       independent layer of security on the outside. Because data validation is
1811       done twice, security can be increased without having to touch the
1812       application. In some cases, however, the fact that everything is done
1813       twice brings problems. Problems can arise in the areas where the
1814       communication protocols are not well specified, or where either the
1815       device or the application do things that are not in the specification.
1816       In such cases it may be possible to design payload that will be
1817       interpreted in one way by one device and in another by the other device.
1818       This problem is better known as Impedance Mismatch. It can be exploited
1819       to evade the security devices.</p><p>While we will continue to enhance ModSecurity to deal with various
1820       evasion techniques the problem can only be minimized, but never solved.
1821       With so many different application backend chances are some will always
1822       do something completely unexpected. The only solution is to be aware of
1823       the technologies in the backend when writing rules, adapting the rules
1824       to remove the mismatch. See the next section for some examples.</p><div class="section" lang="en"><div class="titlepage"><div><div><h4 class="title"><a name="N11E6E"></a>PHP Peculiarities for ModSecurity Users</h4></div></div><div></div></div><p>When writing rules to protect PHP applications you need to pay
1825         attention to the following facts:</p><div class="orderedlist"><ol type="1"><li><p>When "register_globals" is set to "On" request parameters
1826             are automatically converted to script variables. In some PHP
1827             versions it is even possible to override the $GLOBALS
1828             array.</p></li><li><p>Whitespace at the beginning of parameter names is ignored.
1829             (This is very dangerous if you are writing rules to target
1830             specific named variables.)</p></li><li><p>The remaining whitespace (in parameter names) is converted
1831             to underscores. The same applies to dots and to a "[" if the
1832             variable name does not contain a matching closing bracket.
1833             (Meaning that if you want to exploit a script through a variable
1834             that contains an underscore in the name you can send a parameter
1835             with a whitespace or a dot instead.)</p></li><li><p>Cookies can be treated as request parameters.</p></li><li><p>The discussion about variable names applies equally to the
1836             cookie names.</p></li><li><p>The order in which parameters are taken from the request and
1837             the environment is EGPCS (environment, GET, POST, Cookies,
1838             built-in variables). This means that a POST parameter will
1839             overwrite the parameters transported on the request line (in
1840             QUERY_STRING).</p></li><li><p>When "magic_quotes_gpc" is set to "On" PHP will use
1841             backslash to escape the following characters: single quote, double
1842             quote, backslash, and the nul byte.</p></li><li><p>If "magic_quotes_sybase" is set to "On" only the single
1843             quote will be escaped using another single quote. In this case the
1844             "magic_quotes_gpc" setting becomes irrelevant. The
1845             "magic_quotes_sybase" setting completely overrides the
1846             "magic_quotes_gpc" behaviour but "magic_quotes_gpc" still must be
1847             set to "On" for the Sybase-specific quoting to be work.</p></li><li><p>PHP will also automatically create nested arrays for you.
1848             For example "p[x][y]=1" results in a total of three
1849             variables.</p></li></ol></div></div></div></div></div><div align="center" class="copyright">Copyright (C) 2004-2009 <a href="http://www.breach.com">Breach Security</a></div></body></html>