~ubuntu-branches/ubuntu/quantal/modsecurity-apache/quantal

<html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Actions</title><link href="modsecurity-reference.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.69.1" name="generator"><link rel="start" href="index.html" title="ModSecurity® Reference

Manual"><link rel="up" href="index.html" title="ModSecurity® Reference

Manual"><link rel="prev" href="transformation-functions.html" title="Transformation functions"><link rel="next" href="operators.html" title="Operators"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background:#F5F5F5;width:100%;border-top:1px solid #DDDDDD;border-bottom:1px solid #DDDDDD"><table width="100%" cellspacing="0" cellpadding="0"><tr><td><a href="http://www.modsecurity.org"><img style="margin:4px" src="modsecurity.gif" width="120" height="36" alt="ModSecurity" border="0"></a></td><td align="right"><a href="http://www.breach.com"><img style="margin:6px" src="breach-logo-small.gif" height="36" width="100" border="0"></a></td></tr></table></div><div id="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Actions</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="transformation-functions.html">Prev</a> </td><td align="center" width="60%"> <a accesskey="h" href="index.html">Home</a></td><td align="right" width="20%"> <a accesskey="n" href="operators.html">Next</a></td></tr></table><hr size="1"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="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

means block transaction, but not in all. For example, the allow

action is classified as a disruptive action, but it does the

opposite of blocking. There can only be one disruptive action per

rule (if there are multiple disruptive actions present, or

inherited, only the last one will take effect), or rule chain (in a

chain, a disruptive action can only appear in the first

rule).</p></dd><dt><span class="term">Non-disruptive actions</span></dt><dd><p>Do something, but that something does not and cannot affect

the rule processing flow. Setting a variable, or changing its value

is an example of a non-disruptive action. Non-disruptive action can

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

<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

rules. Examples include <code class="literal">id</code>,

<code class="literal">rev</code>, <code class="literal">severity</code> and

<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

used by other actions. For example, the <code class="literal">status</code>

action holds the status that will be used for blocking (if it takes

place).</p></dd></dl></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N116AD"></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

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

only affect the current phase. An <code class="literal">allow</code> in phase 1

would skip processing the remaining rules in phase 1 but the rules from

phase 2 would execute. Starting with v2.5.0 <code class="literal">allow</code> was

enhanced to allow for fine-grained control of what is done. The

following rules now apply:</p><div class="orderedlist"><ol type="1"><li><p>If used one its own, like in the example above,

<code class="literal">allow</code> will affect the entire transaction,

stopping processing of the current phase but also skipping over all

other phases apart from the logging phase. (The logging phase is

special; it is designed to always execute.)</p></li><li><p>If used with parameter "phase", <code class="literal">allow</code> will

cause the engine to stop processing the current phase. Other phases

will continue as normal.</p></li><li><p>If used with parameter "request", <code class="literal">allow</code>

will cause the engine to stop processing the current phase. The next

phase to be processed will be phase

<code class="literal">RESPONSE_HEADERS</code>.</p></li></ol></div><p>Examples:</p><pre class="programlisting"># Do not process request but process response.

SecAction phase:1,allow:request

# Do not process transaction (request and response).

SecAction phase:1,allow

</pre><p>If you want to allow a response through, put a rule in phase

<code class="literal">RESPONSE_HEADERS</code> and simply use

<code class="literal">allow</code> on its own:</p><pre class="programlisting"># Allow response through.

SecAction phase:3,allow</pre></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N116FD"></a>append</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Appends text given as parameter

to the end of response body. For this action to work content injection

must be enabled by setting <code class="literal">SecContentInjection</code> to

<code class="literal">On</code>. Also make sure you check the content type of the

response before you make changes to it (e.g. you don't want to inject

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:'<hr>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

are strongly cautioned against inserting user defined data

fields.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1171F"></a><code class="literal">auditlog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Marks the transaction for

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

specified.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11739"></a><code class="literal">block</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Performs the default disruptive

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

rule was intended to block and leaves the "how" up to the administrator.

This action is currently a placeholder which will just be replaced by

the action from the last <code class="literal">SecDefaultAction</code> in the same

context. Using the <code class="literal">block</code> action with the

<code class="literal">SecRuleUpdateActionById</code> directive allows a rule to be

reverted back to the previous <code class="literal">SecDefaultAction</code>

disruptive action.</p><p>In future versions of ModSecurity, more control and functionality

will be added to define "how" to block.</p><p>Examples:</p><p>In the following example, the second rule will "deny" because of

the SecDefaultAction disruptive action. The intent being that the

administrator could easily change this to another disruptive action

without editing the actual rules.</p><pre class="programlisting">### Administrator defines "how" to block (deny,status:403)...

SecDefaultAction phase:2,deny,status:403,log,auditlog

### Included from a rulest...

# Intent is to warn for this User Agent

SecRule REQUEST_HEADERS:User-Agent "perl" "phase:2,<span class="emphasis"><em>pass</em></span>,msg:'Perl based user agent identified'"

# Intent is to block for this User Agent, "how" described in SecDefaultAction

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

<code class="literal">pass</code> action defined in the SecDefaultAction directive

by using the <code class="literal">SecRuleUpdateActionById</code> directive in

conjuction with the <code class="literal">block</code> action. This allows an

administrator to override an action in a 3rd party rule without

modifying the rule itself.</p><pre class="programlisting">### Administrator defines "how" to block (deny,status:403)...

SecDefaultAction phase:2,pass,log,auditlog

### Included from a rulest...

SecRule REQUEST_HEADERS:User-Agent "nikto" "id:1,phase:2,<span class="emphasis"><em>deny</em></span>,msg:'Nikto Scanners Identified'"

### Added by the administrator

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="N1177E"></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

regular expression operator, capture action will create copies of

regular expression captures and place them into the transaction variable

collection. Up to ten captures will be copied on a successful pattern

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

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

in the first parens, etc...</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11798"></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

is placed with the rule that immediately follows it. The result is

called a<span class="emphasis"><em> rule chain</em></span>. Chained rules allow for more

complex rule matches where you want to use a number of different

VARIABLES to create a better rule and to help prevent false

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

# not specify request body length. Do note that

# this rule should be preceeded by a rule that verifies

# only valid request methods (e.g. GET, HEAD and POST) are used.

SecRule REQUEST_METHOD ^POST$<span class="emphasis"><em> chain</em></span>,t:none

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

100

somewhat similar to AND conditional statements. The actions specified

101

in the first portion of the chained rule will only be triggered if all

102

of the variable checks return positive hits. If one aspect of the

103

chained rule is negative, then the entire rule chain is negative. Also

104

note that disruptive actions, execution phases, metadata actions (id,

105

rev, msg), skip and skipAfter actions can only be specified on by the

106

chain starter rule.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N117B3"></a><code class="literal">ctl</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> The ctl action allows

107

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

108

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

109

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">

110

requestBodyProcessor</code> and <code class="literal">

111

forceRequestBodyVariable</code>, each configuration option

112

corresponds to one configuration directive and the usage is

113

identical.</p><p>The <code class="literal">requestBodyProcessor</code> option allows you to

114

configure the request body processor. By default ModSecurity will use

115

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

116

<code class="literal">multipart/form-data</code> bodies,

117

respectively. A third processor, <code class="literal">XML</code>, is also

118

supported, but it is never used implicitly. Instead you must tell

119

ModSecurity to use it by placing a few rules in the<code class="literal"> REQUEST_HEADERS</code> processing phase. After the

120

request body was processed as XML you will be able to use the

121

XML-related features to inspect it.</p><p>Request body processors will not interrupt a transaction if an

122

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

123

should be inspected in the <code class="literal">REQUEST_BODY</code> phase and an appropriate action

124

taken.</p><p>The <code class="literal">forceRequestBodyVariable</code> option allows you

125

to configure the <code class="literal">REQUEST_BODY</code> variable to be set when

126

there is no request body processor configured. This allows for

127

inspection of request bodies of unknown types.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11847"></a><code class="literal">deny</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Stops rule processing and

128

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="N1185C"></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

129

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

130

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

131

go below zero.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11873"></a><code class="literal">drop</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Immediately initiate a

132

"connection close" action to tear down the TCP connection by sending a

133

FIN packet.</p><p><span class="emphasis"><em>Action Group:</em></span> Disruptive</p><p>Example: The following example initiates an IP collection for

134

tracking Basic Authentication attempts. If the client goes over the

135

threshold of more than 25 attempts in 2 minutes, it will DROP subsequent

136

connections.</p><pre class="programlisting">SecAction phase:1,initcol:ip=%{REMOTE_ADDR},nolog

137

SecRule ARGS:login "!^$" \

138

nolog,phase:1,setvar:ip.auth_attempt=+1,deprecatevar:ip.auth_attempt=20/120

139

SecRule IP:AUTH_ATTEMPT "@gt 25" \

140

"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.

141

This action is extremely useful when responding to both Brute Force and

142

Denial of Service attacks in that, in both cases, you want to minimize

143

both the network bandwidth and the data returned to the client. This

144

action causes error message to appear in the log "(9)Bad file

145

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="N1188D"></a><code class="literal">exec</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Executes an external

146

script/binary supplied as parameter. As of v2.5.0, if the parameter

147

supplied to <code class="literal">exec</code> is a Lua script (detected by the

148

<code class="filename">.lua</code> extension) the script will be processed

149

<span class="emphasis"><em>internally</em></span>. This means you will get direct access

150

to the internal request context from the script. Please read the

151

<code class="literal">SecRuleScript</code> documentation for more details on how

152

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

153

# as a shell script on rule match.

154

SecRule REQUEST_URI "^/cgi-bin/script\.pl" \

155

"phase:2,t:none,t:lowercase,t:normalisePath,log,<span class="emphasis"><em>exec:/usr/local/apache/bin/test.sh</em></span>"

156

157

# The following is going to process /usr/local/apache/conf/exec.lua

158

# internally as a Lua script on rule match.

159

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

160

actions. External scripts will always be called with no parameters.

161

Some transaction information will be placed in environment variables.

162

All the usual CGI environment variables will be there. You should be

163

aware that forking a threaded process results in all threads being

164

replicated in the new process. Forking can therefore incur larger

165

overhead in multi-threaded operation. The script you execute must

166

write something (anything) to stdout. If it doesn't ModSecurity will

167

assume execution didn't work.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N118B6"></a><code class="literal">expirevar</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Configures a collection variable

168

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

169

SecAction setsid:%{REQUEST_COOKIES:JSESSIONID}

170

SecRule REQUEST_URI "^/cgi-bin/script\.pl" \

171

"phase:2,t:none,t:lowercase,t:normalisePath,log,allow,\

172

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

173

setvar actions in order to keep the indented expiration time. If they

174

are used on their own (perhaps in a SecAction directive) the expire time

175

could get re-set. When variables are removed from collections, and there

176

are no other changes, collections are not written to disk at the end of

177

request. This is because the variables can always be expired again when

178

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="N118D0"></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

179

or chain.</p><p><span class="emphasis"><em>Action Group:</em></span> Meta-data</p><p>Example:</p><pre class="programlisting">SecRule &REQUEST_HEADERS:Host "@eq 0" \

180

"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

181

fit but do not use this range for rules that are distributed to

182

others.</p></li><li><p>100,000-199,999; reserved for internal use of the engine, to

183

assign to rules that do not have explicit IDs.</p></li><li><p>200,000-299,999; reserved for rules published at

184

modsecurity.org.</p></li><li><p>300,000-399,999; reserved for rules published at

185

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-699,999; unused (available for reservation).</p></li><li><p>700,000-799,999; reserved for Ivan Ristic.</p></li><li><p>900,000-999,999; reserved for the <a href="http://www.modsecurity.org/projects/rules/" target="_top">Core Rules</a>

186

project.</p></li><li><p>1,000,000 and above; unused (available for

187

reservation).</p></li></ul></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11912"></a><code class="literal">initcol</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Initialises a named persistent

188

collection, either by loading data from storage or by creating a new

189

collection in memory.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example: The following example initiates IP address

190

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

191

with <span class="emphasis"><em>initcol</em></span> so that the collection is available in

192

all phases.</p><p>Collections are loaded into memory when the initcol action is

193

encountered. The collection in storage will be persisted (and the

194

appropriate counters increased) <span class="emphasis"><em>only</em></span> if it was

195

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="N11939"></a><code class="literal">log</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Indicates that a successful

196

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

197

ModSecurity audit log.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11952"></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

198

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 &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

199

files and is not sent back to the client in response headers. Macro

200

expansion is preformed so you may use variable names such as %{TX.0},

201

etc. The information is properly escaped for use with logging binary

202

data.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N1196B"></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

203

rule or chain.</p><p><span class="emphasis"><em>Action Group:</em></span> Meta-data</p><p>Example:</p><pre class="programlisting">SecRule &REQUEST_HEADERS:Host "@eq 0" \

204

"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

205

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="N11987"></a><code class="literal">multiMatch</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> If enabled ModSecurity will

206

perform multiple operator invocations for every target, before and after

207

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

208

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

209

transformation functions have completed. With multiMatch, variables are

210

checked against the operator before and after every transformation

211

function that changes the input.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N119A0"></a><code class="literal">noauditlog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Indicates that a successful

212

match of the rule should not be used as criteria whether the transaction

213

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

214

be logged. If it is set to RelevantOnly, then you can control it with

215

the noauditlog action. Even if the noauditlog action is applied to a

216

specific rule and a rule either before or after triggered an audit

217

event, then the transaction will be logged to the audit log. The correct

218

way to disable audit logging for the entire transaction is to use

219

"<code class="literal">ctl:auditEngine=Off</code>"</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N119BD"></a><code class="literal">nolog</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Prevents rule matches from

220

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="N119D6"></a><code class="literal">pass</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Continues processing with the

221

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

222

targets, <span class="emphasis"><em>all</em></span> targets will be processed and

223

<span class="emphasis"><em>all</em></span> non-disruptive actions will trigger for

224

<span class="emphasis"><em>every</em></span> match found. In the second example the

225

TX:test target would be incremented by 1 for each matching

226

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

227

generated for each matching target (unless logging has been

228

suppressed).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A05"></a><code class="literal">pause</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Pauses transaction processing

229

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

230

Force Scanners, however use with care. If you are under a Denial of

231

Service type of attack, the pause feature may make matters worse as this

232

feature will cause child processes to sit idle until the pause is

233

completed.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A1E"></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

234

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

235

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

236

variable that you specify may be empty. This could lead to a false

237

negative situation where your variable and operator (RegEx) may be

238

correct, but it misses malicious data because you specified the wrong

239

phase.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A38"></a>prepend</h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Prepends text given as parameter

240

to the response body. For this action to work content injection must be

241

enabled by setting <code class="literal">SecContentInjection</code> to

242

<code class="literal">On</code>. Also make sure you check the content type of the

243

response before you make changes to it (e.g. you don't want to inject

244

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<br>'</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

245

are strongly cautioned against inserting user defined data

246

fields.</p></div></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A5A"></a><code class="literal">proxy</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Intercepts transaction by

247

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

248

action is useful if you would like to proxy matching requests onto a

249

honeypot webserver.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11A73"></a><code class="literal">redirect</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Intercepts transaction by

250

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" \

251

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

252

and its value is acceptable (301, 302, 303, or 307) it will be used for

253

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="N11A90"></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

254

after changes take place but to still provide some indication the rule

255

changed.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11AAE"></a><code class="literal">sanitiseArg</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Sanitises (replaces each byte

256

with an asterisk) a named request argument prior to audit

257

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

258

raw requests but only on the copy of data within memory that is set to

259

log to the audit log. It will not sanitize the data in the

260

modsec_debug.log file (if the log level is set high enough to capture

261

this data).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11AC7"></a><code class="literal">sanitiseMatched</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Sanitises the variable (request

262

argument, request header, or response header) that caused a rule

263

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

264

elements when they match a condition. For example, the example below

265

will sanitise any argument that contains the word<span class="emphasis"><em>

266

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="N11AE3"></a><code class="literal">sanitiseRequestHeader</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Sanitises a named request

267

header.</p><p><span class="emphasis"><em>Action Group:</em></span> Non-disruptive</p><p>Example: This will sanitise the data in the Authorization

268

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="N11AFC"></a><code class="literal">sanitiseResponseHeader</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Sanitises a named response

269

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

270

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="N11B15"></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

271

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

272

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

273

numerical values or the text values. You should always specify severity

274

levels using the text values. The use of the numerical values is

275

deprecated (as of v2.5.0) and may be removed in one of the susequent

276

major updates.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11B4A"></a><code class="literal">setuid</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Special-purpose action that

277

initialises the <code class="literal">USER</code>

278

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

279

subsequent rules.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11B6C"></a><code class="literal">setsid</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Special-purpose action that

280

initialises the <code class="literal">SESSION</code>

281

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

282

SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass

283

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

284

(not taking the predefined variables into account - see <code class="literal">initcol</code> for more information). On subsequent

285

invocations the contents of the collection (session, in this case) will

286

be retrieved from storage. After initialisation takes place the

287

variable<code class="literal"> SESSIONID</code> will be available

288

for use in the subsequent rules.This action understands each application

289

maintains its own set of sessions. It will utilise the current web

290

application ID to create a session namespace.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11B91"></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

291

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

292

Apache modules.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11BB3"></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

293

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>

294

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="N11BD9"></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

295

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 "^/$" \

296

"phase:2,chain,t:none<span class="emphasis"><em>,skip:2</em></span>"

297

SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"

298

SecRule REQUEST_HEADERS:User-Agent "^Apache $internal dummy connection$$" "t:none"

299

SecRule &REQUEST_HEADERS:Host "@eq 0" \

300

"deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'"

301

SecRule &REQUEST_HEADERS:Accept "@eq 0" \

302

"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

303

necessarily the order in which the rules appear in the configuration

304

file. If you group rules by processing phases, then skip should work as

305

expected. This action can not be used to skip rules within one chain.

306

Accepts a single parameter denoting the number of rules (or chains) to

307

skip.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11BF4"></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

308

successful match resuming rule execution after the specified rule ID or

309

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>"

310

SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"

311

SecRule REQUEST_HEADERS:User-Agent "^Apache $internal dummy connection$$" "t:none"

312

SecRule &REQUEST_HEADERS:Host "@eq 0" \

313

"deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'"

314

SecRule &REQUEST_HEADERS:Accept "@eq 0" \

315

"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

316

processing phase and not necessarily the order in which the rules appear

317

in the configuration file. If you group rules by processing phases, then

318

skip should work as expected. This action can not be used to skip rules

319

within one chain. Accepts a single parameter denoting the last rule ID

320

to skip.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C16"></a><code class="literal">status</code></h3></div></div><div></div></div><p><span class="emphasis"><em>Description:</em></span> Specifies the response status

321

code to use with actions<code class="literal"> deny</code>

322

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

323

Directory, Location, etc...) may be superseded by phase:1 action

324

settings. The Apache ErrorDocument directive will be triggered if

325

present in the configuration. Therefore if you have previously defined a

326

custom error page for a given status then it will be executed and its

327

output presented to the user.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C38"></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

328

transformation function should be used against the specified variables

329

before they (or the results, rather) are run against the operator

330

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

331

SecRule REQUEST_COOKIES:SESSIONID "47414e81cbbef3cf8366e84eeacba091" \

332

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

333

in addition to previous ones specified in SecDefaultAction. Use of

334

"t:none" will remove all transformation functions for the specified

335

rule.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C51"></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

336

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" \

337

"t:none,t:lowercase,deny,msg:'System Command Access',id:'950002',<span class="emphasis"><em>\

338

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.

339

Its intent is to be used to automate classification of rules and the

340

alerts generated by rules. Multiple tags can be used per

341

rule/chain.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N11C6B"></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

342

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" \

343

"phase:1,pass,ctl:requestBodyProcessor=XML,ctl:requestBodyAccess=On,<span class="emphasis"><em> \

344

xmlns:xsd="http://www.w3.org/2001/XMLSchema"</em></span>

345

SecRule XML:/soap:Envelope/soap:Body/q1:getInput/id() "123" phase:2,deny</pre></div></div><div id="navfooter"><hr size="1"><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="transformation-functions.html">Prev</a> </td><td align="center" width="20%"> </td><td align="right" width="40%"> <a accesskey="n" href="operators.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Transformation functions </td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%"> Operators</td></tr></table></div><div align="center" class="copyright">Copyright (C) 2004-2010 <a href="http://www.breach.com">Breach Security</a></div></body></html>

b'\\ No newline at end of file'

Older »