Each action belongs to one of five groups:
Disruptive actions - are those actions where ModSecurity will intercept the data. They can only appear in the first rule in a chain.
Non-disruptive actions - can appear anywhere.
Flow actions - can appear only in the first rule in a chain.
Meta-data actions(id
,
rev
, severity
, msg
) - can only appear in the first rule in
a chain.
Data actions - can appear anywhere; these actions are completely passive and only serve to carry data used by other actions.
Description: Stops processing on a successful match and allows transaction to proceed.
Action Group: Disruptive
Example:
SecRule REMOTE_ADDR "^192\.168\.1\.100$" nolog,phase:1,allow
Note
The allow action only applies to the current processing phase. If
your intent is to explicitly allow a request, then you should use the
"ctl" action to turn the ruleEngine off -
ctl:ruleEngine=Off
.
Description: Marks the transaction for logging in the audit log.
Action Group: Non-Disruptive
Example:
SecRule REMOTE_ADDR "^192\.168\.1\.100$" auditlog,phase:1,allow
Note
The auditlog action is now explicit if log is already specified.
Description: 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.
Action Group: Non-Disruptive
Example:
SecRule REQUEST_BODY "^username=(\w{25,})" phase:2,capture,t:none,chain
SecRule TX:1 "(?:(?:a(dmin|nonymous)))"
Note
The 0 data captures the entire REGEX match and 1 captures the data in the first parantheses, etc...
Description: Chains the rule where the action is placed with the rule that immediately follows it. The result is called a rule chain. 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.
Action Group: Flow
Example:
# Refuse to accept POST requests that do
# not specify request body length
SecRule REQUEST_METHOD ^POST$ chain
SecRule REQUEST_HEADER:Content-Length ^$
Note
In programming language concepts, think of chained rules somewhat similar to AND conditional statements. The actions specified in the first portion of the chained rule will only be triggered if all of the variable checks return positive hits. If one aspect of the chained rule is negative, then the entire rule chain is negative. Also note that disruptive actions, execution phases, metadata actions (id, rev, msg) and skip actions can only be specified on by the chain starter rule.
Description: The ctl action allows configuration options to be updated for the transaction.
Action Group: Non-Disruptive
Example:
# Parse requests with Content-Type "text/xml" as XML
SecRule REQUEST_CONTENT_TYPE ^text/xml nolog,pass,ctl:requestBodyProcessor=XML
Note
The following configuration options are supported:
auditEngine
auditLogParts
debugLogLevel
requestBodyAccess
requestBodyLimit
requestBodyProcessor
responseBodyAccess
responseBodyLimit
ruleEngine
With the exception of
requestBodyProcessor
, each configuration option corresponds to
one configuration directive and the usage is identical.
The requestBodyProcessor option allows you to configure the
request body processor. By default ModSecurity will use the URLENCODED
and
MULTIPART
processors to process an application/x-www-form-urlencoded
and a
multipart/form-data
body,
respectively. A third processor, XML, is also supported, but it is never
used implicitly. Instead you must tell ModSecurity to use it by placing
a few rules in the REQUEST_HEADERS
processing phase. After the request body was processed as XML you will
be able to use the XML-related features to inspect it.
Request body processors will not interrupt a transaction if an
error occurs during parsing. Instead they will set variables REQBODY_PROCESSOR_ERROR
and REQBODY_PROCESSOR_ERROR_MSG
. These variables
should be inspected in the REQUEST_BODY
phase and an appropriate action
taken.
Description: Stops rule processing and intercepts transaction.
Action Group: Disruptive
Example:
SecRule REQUEST_HEADERS:User-Agent "nikto" "log,deny,msg:'Nikto Scanners Identified'"
Description: Decrement counter based on its age.
Action Group: Non-Disruptive
Example: The following example will decrement the counter by 60 every 300 seconds.
SecAction deprecatevar:session.score=60/300
Note
Counter values are always positive, meaning the value will never go below zero.
Description: Immediately initiate a "connection close" action to tear down the TCP connection by sending a FIN packet.
Action Group: Disruptive
Example: The following example initiates an IP collection for tracking Basic Authentication attempts. If the client goes over the threshold of more than 25 attempts in 2 minutes, it will DROP subsequent connections.
SecAction initcol:ip=%{REMOTE_ADDR},nolog
SecRule ARGS:login "!^$" \
nolog,phase:1,setvar:ip.auth_attempt=+1,deprecatevar:ip.auth_attempt=20/120
SecRule IP:AUTH_ATTEMPT "@gt 25" \
log,drop,phase:1,msg:'Possible Brute Force Attack"
Note
This action is extremely useful when responding to both Brute Force and Denial of Service attacks in that, in both cases, you want to minimize both the network bandwidth and the data returned to the client. This action causes error message to appear in the log "(9)Bad file descriptor: core_output_filter: writing data to the network"
Description: Executes an external script/binary supplied as parameter.
Action Group: Non-Disruptive
Example:
SecRule REQUEST_URI "^/cgi-bin/script\.pl" \
"log,exec:/usr/local/apache/bin/test.sh,phase:1"
Note
This directive does not effect a primary action if it exists. This action will always call script with no parameters, but providing all information in the environment. All the usual CGI environment variables will be there. You can have one binary executed per filter match. Execution will add the header mod_security-executed to the list of request headers. You should be aware that forking a threaded process results in all threads being replicated in the new process. Forking can therefore incur larger overhead in multithreaded operation. The script you execute must write something (anything) to stdout. If it doesn't ModSecurity will assume execution didn't work.
Description: Configurescollection variable to expire after the given time in seconds.
Action Group: Non-Disruptive
Example:
SecRule REQUEST_COOKIES:JSESSIONID "!^$" nolog,phase:1,pass,chain
SecAction setsid:%{REQUEST_COOKIES:JSESSIONID}
SecRule REQUEST_URI "^/cgi-bin/script\.pl" \
"log,allow,setvar:session.suspicious=1,expirevar:session.suspicious=3600,phase:1"
Note
You should use expirevar actions at the same time that you use setvar actions in order to keep the indended expiration time. If they are used on their own (perhaps in a SecAction directive) the expire time could get re-set. When variables are removed from collections, and there are no other changes, collections are not written to disk at the end of request. This is because the variables can always be expired again when the collection is read again on a subsequent request.
Description: Assigns a unique ID to the rule or chain.
Action Group: Metadata
Example:
SecRule &REQUEST_HEADERS:Host "@eq 0" \
"log,id:60008,severity:2,msg:'Request Missing a Host Header'"
Note
These are the reserved ranges:
1-99,999; reserved for local (internal) use. Use as you see fit but do not use this range for rules that are distributed to others.
100,000-199,999; reserved for internal use of the engine, to assign to rules that do not have explicit IDs.
200,000-299,999; reserved for rules published at modsecurity.org.
300,000-399,999; reserved for rules published at gotroot.com.
400,000-419,999; unused (available for reservation).
420,000-429,999; reserved for ScallyWhack.
430,000-899,999; unused (available for reservation).
900,000-999,999; reserved for the Core Rules project.
1,000,000 and above; unused (available for reservation).
Description: Initialises a named persistent collection, either by loading data from storage or by creating a new collection in memory.
Action Group: Non-Disruptive
Example: The following example initiates IP address tracking.
SecAction initcol:ip=%{REMOTE_ADDR},nolog
Note
Every collection contains several built-in variables that are read-only:
CREATE_TIME
- date/time of
the creation of the collection.
KEY
- the value of the
initcol variable (the client's IP address in the example).
LAST_UPDATE_TIME
-
date/time of the last update to the collection.
TIMEOUT
- date/time in
seconds when the collection will be updated on disk from memory (if
no other updates occur).
UPDATE_COUNTER
- how many
times the collection has been updated since creation.
UPDATE_RATE
- is the
average rate updates per minute since creation.
Collections are loaded into memory when the initcol action is encountered. The collection in storage will be updated (and the appropriate counters increased) only if it was changed during transaction processing.
To create a collection to hold session variables (SESSION
) use action setsid
. To create a collection to hold user
variables (USER
) use action
setuid
.
At this time it is only possible to have three
collections: IP
, SESSION
, and USER
.
Description: Indicates that a successful match of the rule needs to be logged.
Action Group: Non-Disruptive
Example:
SecAction initcol:ip=%{REMOTE_ADDR},log
Note
This action will log matches to the Apache error log file and the ModSecurity audit log.
Description: Assigns a custom message to the rule or chain.
Action Group: Metadata
Example:
SecRule &REQUEST_HEADERS:Host "@eq 0" \ "log,id:60008,severity:2,msg:'Request Missing a Host Header'"
Note
The msg information appears in the error and/or audit log files and is not sent back to the client in response headers.
Description: If enabled ModSecurity will perform multiple operator invocations for every target, before and after every anti-evasion transformation is performed.
Action Group: Non-Disruptive
Example:
SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase
SecRule ARGS "attack" multiMatch
Note
Normally, variables are evaluated once, only after all transformation functions have completed. With multiMatch, variables are checked against the operator before and after every transformation function that changes the input.
Description: Indicates that a successful match of the rule should not be used as criteria whether the transaction should be logged to the audit log.
Action Group: Non-Disruptive
Example:
SecRule REQUEST_HEADERS:User-Agent "Test" allow,noauditlog
Note
If the SecAuditEngine is set to On, all of the transactions will
be logged. If it is set to RelevantOnly, then you can control it with
the noauditlog action. Even if the noauditlog action is applied to a
specific rule and a rule either before or after triggered an audit
event, then the tranaction will be logged to the audit log. The correct
way to disable audit logging for the entire transaction is to use
"ctl:auditEngine=Off
"
Description: Prevents rule matches from appearing in both the error and audit logs.
Action Group: Non-Disruptive
Example:
SecRule REQUEST_HEADERS:User-Agent "Test" allow,nolog
Note
The nolog action also implies noauditlog.
Description: Continues processing with the next rule in spite of a successful match.
Action Group: Disruptive
Example:
SecRule REQUEST_HEADERS:User-Agent "Test" log,pass
Note
Transaction will not be interrupted but it will be logged (unless logging has been suppressed).
Description: Pauses transaction processing for the specified number of milliseconds.
Action Group: Disruptive
Example:
SecRule REQUEST_HEADERS:User-Agent "Test" log,deny,status:403,pause:5000
Note
This feature can be of limited benefit for slowing down Brute Force Scanners, however use with care. If you are under a Denial of Service type of attack, the pause feature may make matters worse as this feature will cause child processes to sit idle until the pause is completed.
Description: Places the rule (or the rule chain) into one of five available processing phases.
Action Group: Disruptive
Example:
SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase
SecRule REQUEST_HEADERS:User-Agent "Test" log,deny,status:403
Note
Keep in mind that is you specify the incorrect phase, the target variable that you specify may be empty. This could lead to a false negative situation where your variable and operator (RegEx) may be correct, but it misses malicious data because you specified the wrong phase.
Description: Intercepts transaction by forwarding request to another web server using the proxy backend.
Action Group: Disruptive
Example:
SecRule REQUEST_HEADERS:User-Agent "Test" log,proxy:http://www.honeypothost.com/
Note
For this action to work, mod_proxy must also be installed. This action is useful if you would like to proxy matching requests onto a honeypot webserver.
Description: Intercepts transaction by issuing a redirect to the given location.
Action Group: Disruptive
Example:
SecRule REQUEST_HEADERS:User-Agent "Test" \
log,redirect:http://www.hostname.com/failed.html
Note
If the status
action is present
and its value is acceptable (301, 302, 303, or 307) it will be used for
the redirection. Otherwise status code 302 will be used.
Description: Specifies rule revision.
Action Group: Metadata
Example:
SecRule REQUEST_METHOD "^PUT$" "id:340002,rev:1,severity:2,msg:'Restricted HTTP function'"
Note
This action is used in combination with the id
action to allow the same rule ID to be used
after changes take place but to still provide some indication the rule
changed.
Description: Sanitises (replaces each byte with an asterisk) a named request argument prior to audit logging.
Action Group: Non-Disruptive
Example:
SecAction nolog,phase:2,sanitiseArg:password
Note
The sanitize actions do not sanitize any data within the actual raw requests but only on the copy of data within memory that is set to log to the audit log. It will not sanitize the data in the modsec_debug.log file (if the log level is set high enough to capture this data).
Description: Sanitises the variable (request argument, request header, or response header) that caused a rule match.
Action Group: Non-Disruptive
Example: This action can be used to sanitise arbitrary transaction elements when they match a condition. For example, the example below will sanitise any argument that contains the word password in the name.
SecRule ARGS_NAMES password nolog,pass,sanitiseMatched
Note
Same note as sanitiseArg.
Description: Sanitises a named request header.
Action Group: Non-Disruptive
Example: This will sanitise the data in the Authorization header.
SecAction log,phase:1,sanitiseRequestHeader:Authorization
Note
Same note as sanitiseArg.
Description: Sanitises a named response header.
Action Group: Non-Disruptive
Example: This will sanitise the Set-Cookie data sent to the client.
SecAction log,phase:3,sanitiseResponseHeader:Set-Cookie
Note
Same note as sanitiseArg.
Description: Assigns severity to the rule it is placed with.
Action Group: Metadata
Example:
SecRule REQUEST_METHOD "^PUT$" "id:340002,rev:1,severity:2,msg:'Restricted HTTP function'"
Note
The severity numbers follow the Syslog convention:
0 = EMERGENCY
1 = ALERT
2 = CRITICAL
3 = ERROR
4 = WARNING
5 = NOTICE
6 = INFO
7 = DEBUG
Description: Special-purpose
action that initialises the USER
collection.
Action Group: Non-Disruptive
Example:
SecAction setuid:%{REMOTE_USER},nolog
Note
After initialisation takes place the variable USERID
will be available for use in the
subsequent rules.
Description:
Special-purposeaction that initialises the SESSION
collection.
Action Group: Non-Disruptive
Example:
# Initialise session variables using the session cookie value
SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
Note
On first invocation of this action the collection will be empty
(not taking the pre-defined variables into account - see initcol
for more information). On subsequent
invocations the contents of the collection (session, in this case) will
be retrieved from storage. After initialisation takes place the
variable SESSIONID
will be available
for use in the subsequent rules.This action understands each application
maintains its own set of sessions. It will utilise the current web
application ID to create a session namespace.
Description: Creates, removes, or updates an environment variable.
Action Group: Non-Disruptive
Examples:
To create a new variable (if you omit the value 1
will be used):
setenv:name=value
To remove a variable:
setenv:!name
Note
This action can be used to establish communication with other Apache modules.
Description: Creates, removes, or updates a variable in the specified collection.
Action Group: Non-Disruptive
Examples:
To create a new variable:
setvar:tx.score=10
To remove a variable prefix the name with exclamation mark:
setvar:!tx.score
To increase or decrease variable value use +
and -
characters in front of a numerical value:
setvar:tx.score=+5
Description: Skips one or more rules (or chains) on successful match.
Action Group: Non-Disruptive
Example:
SecRule REQUEST_URI "^/$" "chain,skip:2"
SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
SecRule REQUEST_HEADERS:User-Agent "^Apache \(internal dummy connection\)$" "t:none"
SecRule &REQUEST_HEADERS:Host "@eq 0" \
"deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'"
SecRule &REQUEST_HEADERS:Accept "@eq 0" \
"log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'"
Note
Skip only applies to the current processing phase and not necessarily the order in which the rules appear in the configuration file. If you group rules by processing phases, then skip should work as expected. This action can not be used to skip rules within one chain. Accepts a single paramater denoting the number of rules (or chains) to skip.
Description: Specifies the
response status code to use with actions
deny
and redirect
.
Action Group: Disruptive
Example:
SecDefaultAction log,deny,status:403,phase:1
Note
Staus actions defined in Apache scope locations (such as Directory, Location, etc...) may be superceded by phase:1 action settings. The Apache ErrorDocument directive will be triggered if present in the configuration. Therefore if you have previously defined a custom error page for a given status then it will be executed and its output presented to the user.
Description: This action can be used which transformation function should be used against the specified variables before they (or the results, rather) are run against the operator specified in the rule.
Action Group: Non-Disruptive
Example:
SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase
SecRule REQUEST_COOKIES:SESSIONID "47414e81cbbef3cf8366e84eeacba091" \
log,deny,status:403,t:md5
Note
Any transformation functions that you specify in a SecRule will be in addtion to previous ones specified in SecDefaultAction. Use of "t:none" will remove all transformation functions for the specified rule.
Description: This action should be used together with an XPath expression to register a namespace.
Action Group: Non-Disruptive
Example:
SecRule REQUEST_HEADERS:Content-Type "text/xml" \
phase:1,pass,ctl:requestBodyProcessor=XML,ctl:requestBodyAccess=On,xmlns:xsd="http://www.w3.org/2001/XMLSchema"
SecRule XML:/soap:Envelope/soap:Body/q1:getInput/id() "123" phase:2,deny