diff --git a/Reference-Manual-(v2.x)-Actions.mediawiki b/Reference-Manual-(v2.x)-Actions.mediawiki new file mode 100644 index 0000000..c9450e8 --- /dev/null +++ b/Reference-Manual-(v2.x)-Actions.mediawiki @@ -0,0 +1,869 @@ += ModSecurity® Reference Manual = +== Current as of v2.6 v2.7 v2.8 v2.9 v3.0 == +=== Copyright © 2004-2022 [https://www.trustwave.com/ Trustwave Holdings, Inc.] === + += Actions = +Each action belongs to one of five groups: +*'''Disruptive actions''' - 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). +; Note : '''Disruptive actions will NOT be executed if the SecRuleEngine is set to DetectionOnly'''. If you are creating exception/whitelisting rules that use the allow action, you should also add the ctl:ruleEngine=On action to execute the action. +* '''Non-disruptive action'''s - 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. +* '''Flow actions''' - These actions affect the rule flow (for example skip or skipAfter). +* '''Meta-data actions''' - Meta-data actions are used to provide more information about rules. Examples include id, rev, severity and msg. +* '''Data actions''' - Not really actions, these are mere containers that hold data used by other actions. For example, the status action holds the status that will be used for blocking (if it takes place). + +== accuracy == +'''Description:''' Specifies the relative accuracy level of the rule related to false positives/negatives. The value is a string based on a numeric scale (1-9 where 9 is very strong and 1 has many false positives). + +'''Action Group:''' Meta-data + +'''Version:''' 2.7 + +'''Example:''' +
+SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "\bgetparentfolder\b" \
+	"phase:2,ver:'CRS/2.2.4,accuracy:'9',maturity:'9',capture,t:none,t:htmlEntityDecode,t:compressWhiteSpace,t:lowercase,ctl:auditLogParts=+E,block,msg:'Cross-site Scripting (XSS) Attack',id:'958016',tag:'WEB_ATTACK/XSS',tag:'WASCTC/WASC-8',tag:'WASCTC/WASC-22',tag:'OWASP_TOP_10/A2',tag:'OWASP_AppSensor/IE1',tag:'PCI/6.5.1',logdata:'% \
+{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.xss_score=+%{tx.critical_anomaly_score},setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/XSS-%{matched_var_name}=%{tx.0}"
+
+ +== allow == +'''Description:''' Stops rule processing on a successful match and allows the transaction to proceed. + +'''Action Group:''' Disruptive + +Example: +
+# Allow unrestricted access from 192.168.1.100 
+SecRule REMOTE_ADDR "^192\.168\.1\.100$" phase:1,id:95,nolog,allow
+
+ + +Prior to ModSecurity 2.5 the allow action would only affect the current phase. An allow 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 allow was enhanced to allow for fine-grained control of what is done. The following rules now apply: +#If used one its own, like in the example above, allow 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.) +#If used with parameter "phase", allow will cause the engine to stop processing the current phase. Other phases will continue as normal. +#If used with parameter "request", allow will cause the engine to stop processing the current phase. The next phase to be processed will be phase RESPONSE_HEADERS. + +Examples: +
+# Do not process request but process response.
+SecAction phase:1,allow:request,id:96
+
+# Do not process transaction (request and response).
+SecAction phase:1,allow,id:97
+
+ +If you want to allow a response through, put a rule in phase RESPONSE_HEADERS and simply use allow on its own: +
+# Allow response through.
+SecAction phase:3,allow,id:98
+
+ +== append == +'''Description''': Appends text given as parameter to the end of response body. Content injection must be en- abled (using the SecContentInjection directive). No content type checks are made, which means that before using any of the content injection actions, you must check whether the content type of the response is adequate for injection. + +'''Version:''' 2.x-2.9.x + +'''Supported on libModSecurity:''' No + +'''Action Group:''' Non-disruptive + +'''Processing Phases:''' 3 and 4. + +Example: + +
SecRule RESPONSE_CONTENT_TYPE "^text/html" "nolog,id:99,pass,append:'
Footer'"
+ +; Warning : Although macro expansion is allowed in the additional content, you are strongly cau- tioned against inserting user-defined data fields into output. Doing so would create a cross-site scripting vulnerability. + +== auditlog == +'''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,id:100,allow + +; Note : The auditlog action is now explicit if log is already specified. + +== block == +'''Description:''' Performs the disruptive action defined by the previous SecDefaultAction. + +'''Action Group:''' Disruptive + +This action is essentially a placeholder that is intended to be used by rule writers to request a blocking action, but without specifying how the blocking is to be done. The idea is that such decisions are best left to rule users, as well as to allow users, to override blocking if they so desire. +In future versions of ModSecurity, more control and functionality will be added to define "how" to block. + +Examples: +
+# Specify how blocking is to be done 
+SecDefaultAction phase:2,deny,id:101,status:403,log,auditlog
+
+# Detect attacks where we want to block 
+SecRule ARGS attack1 phase:2,block,id:102
+
+# Detect attacks where we want only to warn 
+SecRule ARGS attack2 phase:2,pass,id:103
+
+ +It is possible to use the SecRuleUpdateActionById directive to override how a rule handles blocking. This is useful in three cases: +#If a rule has blocking hard-coded, and you want it to use the policy you determine +#If a rule was written to block, but you want it to only warn +#If a rule was written to only warn, but you want it to block + +The following example demonstrates the first case, in which the hard-coded block is removed in favor of the user-controllable block: +
+# Specify how blocking is to be done 
+SecDefaultAction phase:2,deny,status:403,log,auditlog,id:104
+
+# Detect attacks and block 
+SecRule ARGS attack1 phase:2,id:1,deny
+
+# Change how rule ID 1 blocks 
+SecRuleUpdateActionById 1 block
+
+ +== capture == +'''Description:''' When used together with the regular expression operator (@rx), the capture action will create copies of the regular expression captures and place them into the transaction variable collection. + +'''Action Group:''' Non-disruptive + +Example: +
+SecRule REQUEST_BODY "^username=(\w{25,})" phase:2,capture,t:none,chain,id:105
+  SecRule TX:1 "(?:(?:a(dmin|nonymous)))"
+
+ +Up to 10 captures will be copied on a successful pattern match, each with a name consisting of a digit from 0 to 9. The TX.0 variable always contains the entire area that the regular expression matched. All the other variables contain the captured values, in the order in which the capturing parentheses appear in the regular expression. + +== chain == +'''Description:''' Chains the current rule with the rule that immediately follows it, creating a rule chain. Chained rules allow for more complex processing logic. + +'''Action Group:''' Flow + +Example: +
+# Refuse to accept POST requests that do not contain Content-Length header. 
+# (Do note that this rule should be preceded by a rule 
+# that verifies only valid request methods are used.) 
+SecRule REQUEST_METHOD "^POST$" phase:1,chain,t:none,id:105
+  SecRule &REQUEST_HEADERS:Content-Length "@eq 0" t:none
+
+ +; Note : Rule chains allow you to simulate logical AND. The disruptive actions specified in the first portion of the chained rule will be triggered only if all of the variable checks return positive hits. If any one aspect of a chained rule comes back negative, then the entire rule chain will fail to match. Also note that disruptive actions, execution phases, metadata actions (id, rev, msg, tag, severity, logdata), skip, and skipAfter actions can be specified only by the chain starter rule. + +The following directives can be used in rule chains: +*SecAction +*SecRule +*SecRuleScript +Special rules control the usage of actions in chained rules: +*Any actions that affect the rule flow (i.e., the disruptive actions, skip and skipAfter) can be used only in the chain starter. They will be executed only if the entire chain matches. +*Non-disruptive rules can be used in any rule; they will be executed if the rule that contains them matches and not only when the entire chain matches. +*The metadata actions (e.g., id, rev, msg) can be used only in the chain starter. + +== ctl == +'''Description''': Changes ModSecurity configuration on transient, per-transaction basis. Any changes made using this action will affect only the transaction in which the action is executed. The default configuration, as well as the other transactions running in parallel, will be unaffected. + +'''Action Group:''' Non-disruptive + +'''Example:''' +
+# Parse requests with Content-Type "text/xml" as XML 
+SecRule REQUEST_CONTENT_TYPE ^text/xml "nolog,pass,id:106,ctl:requestBodyProcessor=XML"
+
+# white-list the user parameter for rule #981260 when the REQUEST_URI is /index.php
+SecRule REQUEST_URI "@beginsWith /index.php" "phase:1,t:none,pass, \
+  nolog,ctl:ruleRemoveTargetById=981260;ARGS:user
+
+ +The following configuration options are supported: +#'''auditEngine''' +#'''auditLogParts''' +#'''debugLogLevel''' (Supported on libModSecurity: TBI) +#'''forceRequestBodyVariable''' +#'''requestBodyAccess''' +#'''requestBodyLimit''' (Supported on libModSecurity: TBI) +#'''requestBodyProcessor''' +#'''responseBodyAccess''' (Supported on libModSecurity: TBI) +#'''responseBodyLimit''' (Supported on libModSecurity: TBI) +#'''ruleEngine''' +#'''ruleRemoveById''' - since this action us triggered at run time, it should be specified '''before''' the rule in which it is disabling. +#'''ruleRemoveByMsg''' (Supported on libModSecurity: TBI) +#'''ruleRemoveByTag''' (Supported on libModSecurity: TBI) +#'''ruleRemoveTargetById''' - since this action is used to just remove targets, users don't need to use the char ! before the target list. +#'''ruleRemoveTargetByMsg''' - since this action is used to just remove targets, users don't need to use the char ! before the target list. (Supported on libModSecurity: TBI) +#'''ruleRemoveTargetByTag''' - since this action is used to just remove targets, users don't need to use the char ! before the target list. +#'''hashEngine''' (Supported on libModSecurity: TBI) +#'''hashEnforcement''' (Supported on libModSecurity: TBI) + +With the exception of the requestBodyProcessor and forceRequestBodyVariable settings, 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. Other two processors are also supported: JSON and XML, but they are 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 is 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 the variables REQBODY_PROCESSOR_ERROR and REQBODY_PROCESSOR_ERROR_MSG. These variables should be inspected in the REQUEST_BODY phase and an appropriate action taken. +The forceRequestBodyVariable option allows you to configure the REQUEST_BODY variable to be set when there is no request body processor configured. This allows for inspection of request bodies of unknown types. + +; Note : There was a ctl:ruleUpdateTargetById introduced in 2.6.0 and removed from the code in 2.7.0. JSON was added as part of v2.8.0-rc1 + +== deny == +'''Description:''' Stops rule processing and intercepts transaction. + +'''Action Group:''' Disruptive + +Example: +SecRule REQUEST_HEADERS:User-Agent "nikto" "log,deny,id:107,msg:'Nikto Scanners Identified'" + +== deprecatevar == +'''Description''': Decrements numerical value over time, which makes sense only applied to the variables stored in persistent storage. + +'''Version:''' 2.x + +'''Supported on libModSecurity:''' TBI + +'''Action Group:''' Non-Disruptive + +Example: The following example will decrement the counter by 60 every 300 seconds. +
+SecAction phase:5,id:108,nolog,pass,deprecatevar:SESSION.score=60/300
+
+ +Counter values are always positive, meaning that the value will never go below zero. Unlike expirevar, the deprecate action must be executed on every request. + +== drop == +'''Description:''' Initiates an immediate close of the TCP connection by sending a FIN packet. + +'''Version:''' 2.x + +'''Supported on libModSecurity:''' TBI + +'''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 phase:1,id:109,initcol:ip=%{REMOTE_ADDR},nolog
+SecRule ARGS:login "!^$" "nolog,phase:1,id:110,setvar:ip.auth_attempt=+1,deprecatevar:ip.auth_attempt=25/120"
+SecRule IP:AUTH_ATTEMPT "@gt 25" "log,drop,phase:1,id:111,msg:'Possible Brute Force Attack'"
+
+ +; Note : This action is currently not available on Windows based builds. +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" + +== exec == +'''Description:''' Executes an external script/binary supplied as parameter. As of v2.5.0, if the parameter supplied to exec is a Lua script (detected by the .lua extension) the script will be processed internally. This means you will get direct access to the internal request context from the script. Please read the SecRuleScript documentation for more details on how to write Lua scripts. + +'''Action Group:''' Non-disruptive + +'''Version:''' 2.x + +'''Supported on libModSecurity:''' YES + +'''Example:''' +
+# Run external program on rule match 
+SecRule REQUEST_URI "^/cgi-bin/script\.pl" "phase:2,id:112,t:none,t:lowercase,t:normalizePath,block,\ exec:/usr/local/apache/bin/test.sh"
+
+# Run Lua script on rule match 
+SecRule ARGS:p attack "phase:2,id:113,block,exec:/usr/local/apache/conf/exec.lua"
+
+The exec action is executed independently from any disruptive actions specified. External scripts will always be called with no parameters. Some transaction information will be placed in environment variables. All the usual CGI environment variables will be there. 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 a multithreaded deployment. The script you execute must write something (anything) to stdout; if it doesn’t, ModSecurity will assume that the script failed, and will record the failure. + +== expirevar == +'''Description:''' Configures a collection variable to expire after the given time period (in seconds). + +'''Version:''' 2.x + +'''Supported on libModSecurity:''' TBI + +'''Action Group:''' Non-disruptive + +'''Example:''' +
+SecRule REQUEST_COOKIES:JSESSIONID "!^$" "nolog,phase:1,id:114,pass,setsid:%{REQUEST_COOKIES:JSESSIONID}"
+SecRule REQUEST_URI "^/cgi-bin/script\.pl" "phase:2,id:115,t:none,t:lowercase,t:normalizePath,log,allow,setvar:session.suspicious=1,expirevar:session.suspicious=3600,phase:1"
+
+ +You should use the expirevar actions at the same time that you use setvar actions in order to keep the intended expiration time. If they are used on their own (perhaps in a SecAction directive), the expire time will be reset. + +== id == +'''Description''': Assigns a unique ID to the rule or chain in which it appears. Starting with ModSecurity 2.7 this action is mandatory and must be numeric. + +'''Action Group:''' Meta-data + +'''Example:''' +
+SecRule &REQUEST_HEADERS:Host "@eq 0" "log,id:60008,severity:2,msg:'Request Missing a Host Header'"
+
+ +; Note : The id action is required for all SecRule/SecAction directives as of v2.7.0 + +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 rules published by Oracle +*200,000–299,999: reserved for rules published Comodo +*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 [http://projects.otaku42.de/wiki/Scally-Whack] +*430,000–439,999: reserved for rules published by Flameeyes [http://www.flameeyes.eu/projects/modsec] +*440.000-599,999: unused (available for reservation) +*600,000-699,999: reserved for use by Akamai [http://www.akamai.com/html/solutions/waf.html] +*700,000–799,999: reserved for Ivan Ristic +*900,000–999,999: reserved for the OWASP ModSecurity Core Rule Set [http://www.owasp.org/index.php/Category:OWASP_ModSecurity_Core_Rule_Set_Project] project +*1,000,000-1,009,999: reserved for rules published by Redhat Security Team +*1,010,000-1,999,999: reserved for WAF | Web Application Firewall and Load Balancer Security (kemptechnologies.com) [https://kemptechnologies.com/solutions/waf/] +*2,000,000-2,999,999: reserved for rules from Trustwave's SpiderLabs Research team +*3,000,000-3,999,999: reserved for use by Akamai [http://www.akamai.com/html/solutions/waf.html] +*4,000,000-4,099,999 reserved: in use by AviNetworks [https://kb.avinetworks.com/docs/latest/vantage-web-app-firewall-beta/] +*4,100,000-4,199,999 reserved: in use by Fastly [https://www.fastly.com/products/cloud-security/#products-cloud-security-web-application-firewall] +*4,200,000-4,299,999 reserved: in use by CMS-Garden [https://www.cms-garden.org/en] +*4,300,000-4,300,999 reserved: in use by Ensim.hu [http://ensim.hu/] +*4,301,000-19,999,999: unused (available for reservation) +*20,000,000-21,999,999: reserved for rules from Trustwave's SpiderLabs Research team +*22,000,000-69,999,999: unused (available for reservation) +*77,000,000-77,999,999 - reserved: in use by Imunify360 - production rules +*88,000,000-88,999,999 - reserved: in use by Imunify360 - beta users +*99,000,000-99,099,999 reserved for use by Microsoft https://azure.microsoft.com/en-us/services/web-application-firewall/ +*99,100,000-99,199,999 reserved for use by WPScan/Jetpack + + +== initcol == +'''Description:''' Initializes 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, which is best done in phase 1: +
+SecAction phase:1,id:116,nolog,pass,initcol:ip=%{REMOTE_ADDR}
+
+ +Collections are loaded into memory on-demand, when the initcol action is executed. A collection will be persisted only if a change was made to it in the course of transaction processing. + +See the "Persistent Storage" section for further details. + +== log == +'''Description:''' Indicates that a successful match of the rule needs to be logged. + +'''Action Group:''' Non-disruptive + +'''Example:''' +
+SecAction phase:1,id:117,pass,initcol:ip=%{REMOTE_ADDR},log
+
+ +This action will log matches to the Apache error log file and the ModSecurity audit log. + +== logdata == +'''Description:''' Logs a data fragment as part of the alert message. + +'''Action Group:''' Non-disruptive + +'''Example:''' +
+SecRule ARGS:p "@rx