Variables

ARGS

Collection of all request arguments, including both query string and request body parameters. To inspect only query string or body arguments, see ARGS_GET and ARGS_POST.

Match all arguments:

SecRule ARGS "dirty" "id:7"

Match only the argument named p:

SecRule ARGS:p "dirty" "id:8"

Match all arguments except those named z:

SecRule ARGS|!ARGS:z "dirty" "id:9"

Count the number of arguments (triggers if more than zero):

SecRule &ARGS "!^0$" "id:10"

Match arguments whose names begin with id_:

SecRule ARGS:/^id_/ "dirty" "id:11"

Note : Using ARGS:p will not result in any invocations against the operator if argument p does not exist.

ARGS_COMBINED_SIZE

Contains the combined size of all request parameters. Files are excluded from the calculation. This variable can be useful, for example, to create a rule to ensure that the total size of the argument data is below a certain threshold. The following rule detects a request whose parameters are more than 2500 bytes long:

SecRule ARGS_COMBINED_SIZE "@gt 2500" "id:12"

ARGS_GET

ARGS_GET is similar to ARGS, but contains only query string parameters.

ARGS_GET_NAMES

ARGS_GET_NAMES is similar to ARGS_NAMES, but contains only the names of query string parameters.

ARGS_NAMES

Contains all request parameter names. You can search for specific parameter names that you want to inspect. In a positive policy scenario, you can also allowlist (using an inverted rule with the exclamation mark) only the authorized argument names. This example rule allows only two argument names: p and a:

SecRule ARGS_NAMES "!^(p|a)$" "id:13"

ARGS_PATH

Contains the URL path components as individual items. Useful for matching specific path segments without needing to parse the full URL.

ARGS_POST

ARGS_POST is similar to ARGS, but only contains arguments from the POST body.

ARGS_POST_NAMES

ARGS_POST_NAMES is similar to ARGS_NAMES, but contains only the names of request body parameters.

DURATION

Contains the number of microseconds elapsed since the beginning of the current transaction.

Note: This variable is currently NOT implemented by Coraza, but only kept for compatibility.

ENV

Collection that provides access to environment variables set via the setenv action. Requires a single parameter to specify the name of the desired variable.

# Set environment variable
SecRule REQUEST_FILENAME "printenv" \
"phase:2,id:15,pass,setenv:tag=suspicious"

# Inspect environment variable
SecRule ENV:tag "suspicious" "id:16"

FILES

Contains the original filenames as submitted by the client in the multipart upload (the filename field of Content-Disposition). Available only on inspected multipart/form-data requests.

SecRule FILES "@rx \.conf$" "id:17"

FILES_COMBINED_SIZE

Contains the total size of the files transported in request body. Available only on inspected multipart/form-data requests.

SecRule FILES_COMBINED_SIZE "@gt 100000" "id:18"

FILES_NAMES

Contains a list of form fields that were used for file upload. Available only on inspected multipart/form-data requests.

SecRule FILES_NAMES "^upfile$" "id:19"

FILES_SIZES

Contains a list of individual file sizes. Useful for implementing a size limitation on individual uploaded files. Available only on inspected multipart/form-data requests.

SecRule FILES_SIZES "@gt 100" "id:20"

FILES_TMPNAMES

Contains a list of temporary files’ names on the disk. Useful when used together with @inspectFile. Available only on inspected multipart/form-data requests.

SecRule FILES_TMPNAMES "@inspectFile /path/to/inspect_script.pl" "id:21"

FILES_TMP_CONTENT

Contains a key-value set where value is the content of the file which was uploaded. Useful when used together with @fuzzyHash.

SecRule FILES_TMP_CONTENT "@fuzzyHash $ENV{CONF_DIR}/ssdeep.txt 1" "id:192372,log,deny"

Note : SecUploadKeepFiles must be set to ‘On’ in order to have this collection filled. Note: This variable is currently NOT implemented by Coraza

FULL_REQUEST_LENGTH

Represents the amount of bytes that FULL_REQUEST may use.

SecRule FULL_REQUEST_LENGTH "@eq 205" "id:21"

GEO

Collection intended to be populated by the @geoLookup operator with geographical data for a given IP address. Fields include COUNTRY_CODE, COUNTRY_NAME, COUNTRY_CONTINENT, REGION, CITY, POSTAL_CODE, LATITUDE, LONGITUDE.

SecRule REMOTE_ADDR "@geoLookup" "phase:1,id:22,nolog,pass"
SecRule GEO:COUNTRY_CODE "!@streq GB" "id:23,deny,log,msg:'Non-GB IP address'"

Note: Requires coraza-geoip plugin.

HIGHEST_SEVERITY

Holds the highest severity of any rules that have matched so far. Severities are numeric values and thus can be used with comparison operators such as @lt, and so on. A value of 255 indicates that no severity has been set.

SecRule HIGHEST_SEVERITY "@le 2" "phase:2,id:23,deny,status:500,msg:'severity %{HIGHEST_SEVERITY}'"

Note : Higher severities have a lower numeric value.

INBOUND_DATA_ERROR

This variable will be set to 1 when the request body size is above the setting configured by SecRequestBodyLimit directive. Your policies should always contain a rule to check this variable. Depending on the rate of false positives and your default policy you should decide whether to block or just warn when the rule is triggered.

The behavior depends on SecRequestBodyLimitAction: - ProcessPartial: the body is truncated at the limit, INBOUND_DATA_ERROR is set to 1, and Phase 2 rules run on the partial body. Rules can inspect this variable. - Reject (default): INBOUND_DATA_ERROR is set to 1 but the transaction is interrupted immediately before Phase 2 rules can run. The error is propagated as an interruption (status 413) to the connector; the variable is effectively inaccessible to rules.

This variable is therefore only actionable in rules when SecRequestBodyLimitAction is set to ProcessPartial.

The best way to use this variable is as in the example below (requires ProcessPartial):

SecRule INBOUND_DATA_ERROR "@eq 1" "phase:2,id:24,t:none,log,pass,msg:'Request Body Larger than SecRequestBodyLimit Setting'"

MATCHED_VAR

This variable holds the value of the most-recently matched variable. It is similar to the TX:0, but it is automatically supported by all operators and there is no need to specify the capture action.

SecRule ARGS pattern chain,deny,id:25
  SecRule MATCHED_VAR "further scrutiny"

Note : Be aware that this variable holds data for the last operator match. This means that if there are more than one matches, only the last one will be populated. Use MATCHED_VARS variable if you want all matches.

MATCHED_VARS

Similar to MATCHED_VAR except that it is a collection of all values that matched during the current operator check.

SecRule ARGS "pattern" "chain,deny,id:26"
  SecRule MATCHED_VARS "@eq somevalue" "t:none"

MATCHED_VARS_NAMES

Similar to MATCHED_VAR_NAME except that it is a collection of all variable names that matched during the current operator check.

SecRule ARGS "pattern" "chain,deny,id:28"
  SecRule MATCHED_VARS_NAMES "@eq ARGS:param" "t:none"

MATCHED_VAR_NAME

This variable holds the full name of the variable that was matched against.

SecRule ARGS pattern "chain,deny,id:27"
  SecRule MATCHED_VAR_NAME "@eq ARGS:param"

MULTIPART_FILENAME

This variable contains the multipart data from field FILENAME.

Note: This variable is currently NOT implemented by Coraza

MULTIPART_NAME

This variable contains the multipart data from field NAME.

Note: This variable is currently NOT implemented by Coraza

OUTBOUND_DATA_ERROR

This variable will be set to 1 when the response body size exceeds the limit configured by the SecResponseBodyLimit directive.

The behavior depends on SecResponseBodyLimitAction: - ProcessPartial: the body is truncated at the limit, OUTBOUND_DATA_ERROR is set to 1, and Phase 4 rules run on the partial body. Rules can inspect this variable to log or block the truncated response. - Reject (default): OUTBOUND_DATA_ERROR is set to 1 but the transaction is interrupted immediately with a 500 error before Phase 4 rules can run. The error is propagated as an interruption to the connector; the variable is effectively inaccessible to rules.

This variable is therefore only actionable in rules when SecResponseBodyLimitAction is set to ProcessPartial.

Example rule to deny when the response body exceeds the configured limit (requires ProcessPartial):

SecRule OUTBOUND_DATA_ERROR "@eq 1" "phase:4,id:32,t:none,deny,status:413,msg:'Response Body Larger than SecResponseBodyLimit Setting'"

QUERY_STRING

Contains the query string part of a request URI. The value in QUERY_STRING is always provided raw, without URL decoding taking place.

SecRule QUERY_STRING "attack" "id:34"

REMOTE_ADDR

This variable holds the IP address of the remote client.

SecRule REMOTE_ADDR "@ipMatch 192.168.1.101" "phase:1,id:35,log,pass,msg:'Request from a specific IP address'"

REMOTE_PORT

This variable holds information on the source port that the client used when initiating the connection.

The example evaluates whether the REMOTE_PORT is less than 1024, which would indicate that the user is a privileged user:

SecRule REMOTE_PORT "@lt 1024" "phase:1,id:37,log, pass,msg:'Request from a privileged User'"

REQBODY_ERROR

Contains the status of the request body processor used for request body parsing. The values can be 0 (no error) or 1 (error). This variable will be set by request body processors (typically the multipart/request-data parser, JSON or the XML parser) when they fail to do their work.

SecRule REQBODY_ERROR "@eq 1" "phase:2,id:39,deny,log,msg:'Request Body Processor Error Detected'"

Note : Your policies must have a rule to check for request body processor errors at the very beginning of phase 2. Failure to do so will leave the door open for impedance mismatch attacks. It is possible, for example, that a payload that cannot be parsed by Coraza can be successfully parsed by more tolerant parser operating in the application. If your policy dictates blocking, then you should reject the request if error is detected. When operating in detection-only mode, your rule should alert with high severity when request body processing fails.

REQBODY_ERROR_MSG

If there’s been an error during request body parsing, the variable will contain the following error message:

SecRule REQBODY_ERROR_MSG "failed to parse" "id:40"

REQBODY_PROCESSOR

Contains the name of the currently used request body processor. The default possible values are URLENCODED, MULTIPART, XML, JSON, and RAW.

SecRule REQBODY_PROCESSOR "^XML$" "chain,id:41"
  SecRule XML://* "something" "t:none"

REQBODY_PROCESSOR_ERROR

Same as REQBODY_ERROR, set to 1 when the request body processor fails. Unlike REQBODY_ERROR_MSG, the corresponding error message in REQBODY_PROCESSOR_ERROR_MSG contains only the raw error string without the processor name prefix.

REQBODY_PROCESSOR_ERROR_MSG

Same as REQBODY_ERROR_MSG, but contains only the raw error string from the body processor, without the processor name prepended.

REQUEST_BASENAME

Holds the filename part of REQUEST_FILENAME (e.g., index.php).

Anti-evasion transformations are NOT applied to this variable by default. REQUEST_BASENAME will recognize both / and \ as path separators. The value of this variable depends on what was provided in request. It does not have to correspond to the resource (on disk) that will be used by the web server.

SecRule REQUEST_BASENAME "^login\.php$" "phase:2,id:42,pass,t:none,t:lowercase"

REQUEST_BODY

Holds the raw request body. It is populated only by the URLENCODED and RAW body processors. MULTIPART, XML, and JSON processors parse the body into their own collections and do not populate this variable. ctl:forceRequestBodyVariable=on can be used in the REQUEST_HEADERS phase to force the population of this variable by setting URLENCODED as the processor when no processor would otherwise be selected.

SecRule REQUEST_BODY "@contains foo" "id:1001,phase:2,deny,log"

Note : Requires request body buffering to be enabled.

REQUEST_BODY_LENGTH

Contains the number of bytes read from the request body. The calculation is based on the actual body buffer size, not on the content-length header.

REQUEST_COOKIES

This variable is a collection of all of request cookies (values only).

Example: the following example is using the Ampersand special operator to count how many variables are in the collection. In this rule, it would trigger if the request does not include any Cookie headers.

SecRule &REQUEST_COOKIES "@eq 0" "id:44"

REQUEST_COOKIES_NAMES

This variable is a collection of the names of all request cookies. For example, the following rule will trigger if the JSESSIONID cookie is not present:

SecRule &REQUEST_COOKIES_NAMES:JSESSIONID "@eq 0" "id:45"

REQUEST_FILENAME

Holds the relative request URL without the query string part (e.g., /index.php).

SecRule REQUEST_FILENAME "^/cgi-bin/login\.php$" phase:2,id:46,t:none,t:normalizePath

Note : Anti-evasion transformations are not used on REQUEST_FILENAME. You will have to specify them in the rules that use this variable.

REQUEST_HEADERS

This variable can be used as either a collection of all of the request headers or can be used to inspect selected headers (by using the REQUEST_HEADERS:Header-Name syntax).

SecRule REQUEST_HEADERS:Host "^[\d\.]+$" "deny,id:47,log,status:400,msg:'Host header is a numeric IP address'"

Note: Coraza will treat multiple headers that have identical names as a “list”, processing each single value.

REQUEST_HEADERS_NAMES

Collection of the names of all of the request headers.

SecRule REQUEST_HEADERS_NAMES "^x-forwarded-for" "log,deny,id:48,status:403,t:lowercase,msg:'Proxy Server Used'"

REQUEST_LINE

Holds the complete request line sent to the server (including the request method and HTTP version information).

# Allow only POST, GET and HEAD request methods, as well as only
# the valid protocol versions
SecRule REQUEST_LINE "!(^((?:(?:POS|GE)T|HEAD))|HTTP/(0\.9|1\.0|1\.1)$)" "phase:1,id:49,log,block,t:none"

REQUEST_METHOD

Holds the request method used in the transaction.

SecRule REQUEST_METHOD "^(?:CONNECT|TRACE)$" "id:50,t:none,deny,log,msg:'Suspicious HTTP method used'"

REQUEST_PROTOCOL

Holds the request protocol version information.

SecRule REQUEST_PROTOCOL "!^HTTP/(0\.9|1\.0|1\.1)$" "id:51,t:none,deny,log,msg:'Suspicious HTTP protocol version used'"

REQUEST_URI

Holds the full request URL including the query string data. It is the parsed and normalized form of REQUEST_URI_RAW: fragments are stripped and the URL is reconstructed from the parsed components. If parsing fails, the raw URI is used as-is.

SecRule REQUEST_URI "attack" "phase:1,id:52,t:none,t:urlDecode,t:lowercase,t:normalizePath,deny"

Note : Anti-evasion transformations are not used on REQUEST_URI. You will have to specify them in the rules that use this variable.

REQUEST_URI_RAW

Holds the raw request URI exactly as received on the request line, before any parsing or normalization. This includes the domain name if the client sent an absolute URI (e.g., http://www.example.com/index.php?p=X).

SecRule REQUEST_URI_RAW "^http://" "phase:1,id:53,t:none,t:urlDecode,t:lowercase,t:normalizePath"

Note : Anti-evasion transformations are not used on REQUEST_URI_RAW. You will have to specify them in the rules that use this variable.

RESPONSE_BODY

Holds the data for the response body. Populated only when no response body processor is active. When a processor (e.g. XML) is used, the body is parsed into the processor’s own collections instead. By default, buffering only occurs for MIME types listed in SecResponseBodyMimeType. ctl:forceResponseBodyVariable=on bypasses this MIME type check, forcing buffering regardless of the Content-Type.

SecRule RESPONSE_BODY "ODBC Error Code" "phase:4,id:54,t:none, deny"

Note : Requires response body buffering to be enabled.

RESPONSE_CONTENT_LENGTH

Response body length in bytes. Available starting from phase 4 only when response body buffering is enabled and no response body processor is active. If a body processor (e.g. XML) is used, this variable will not be populated.

Note : Requires response body buffering to be enabled.

RESPONSE_CONTENT_TYPE

Response content type. Available only starting with phase 3. The value is extracted from the Content-Type response header, with parameters (e.g. charset) stripped. It is equivalent to using RESPONSE_HEADERS:Content-Type, but without the parameter suffix.

RESPONSE_HEADERS

This variable refers to response headers, in the same way as REQUEST_HEADERS does to request headers.

SecRule RESPONSE_HEADERS:X-Cache "MISS" "id:55"

RESPONSE_HEADERS_NAMES

Collection of the response header names.

SecRule RESPONSE_HEADERS_NAMES "Set-Cookie" "phase:3,id:56,t:none,log,pass,msg:'Response contains Set-Cookie header'"

The same limitations apply as the ones discussed in RESPONSE_HEADERS.

RESPONSE_PROTOCOL

Holds the HTTP response protocol information.

SecRule RESPONSE_PROTOCOL "^HTTP\/0\.9" "phase:3,id:57,t:none"

RESPONSE_STATUS

Holds the HTTP response status code returned by the backend. Available starting from phase 3.

SecRule RESPONSE_STATUS "^[45]" "phase:3,id:58,t:none,pass,log,msg:'Response status matches 4xx or 5xx'"

RESPONSE_XML

Collection for interacting with the response XML body via XPath expressions.

Not Implemented yet

RES_BODY_PROCESSOR

Contains the name of the currently used response body processor (e.g., XML).

RULE

This is a special collection that provides access to the id, rev, severity, logdata, and msg fields of the rule that triggered the action. It can be used to refer to only the same rule in which it resides.

SecRule &REQUEST_HEADERS:Host "@eq 0" "log,deny,id:59,setvar:tx.varname=%{RULE.id}"

SERVER_ADDR

Contains the IP address of the server.

SecRule SERVER_ADDR "@ipMatch 192.168.1.100" "phase:1,id:67,log,pass,msg:'Request to a specific IP address'"

SERVER_NAME

Contains the server hostname or IP address. Since it originates from the client-supplied Host header, it should NOT be implicitly trusted.

SecRule SERVER_NAME "hostname\.com$" "phase:1,id:68,log,pass,msg:'Request to a specific hostname'"

SERVER_PORT

Contains the target port of the request.

SecRule SERVER_PORT "^80$" "phase:1,id:69,log,pass,msg:'Request to a specific port'"

STATUS_LINE

Holds the full response status line sent by the backend server. (e.g., HTTP/1.1 200 OK).

# Generate an alert when the application returns 500 error.
SecRule STATUS_LINE "@contains 500" "phase:3,id:49,log,pass,logdata:'Application error detected!',t:none"

Note: This variable is currently NOT implemented by Coraza, but only kept for compatibility.

TIME

This variable holds a formatted string representing the time (hour:minute:second).

SecRule TIME "^(([1](8|9))|([2](0|1|2|3))):\d{2}:\d{2}$" "id:74"

TIME_DAY

This variable holds the current date (1–31). The following rule triggers on a transaction that’s happening anytime between the 10th and 20th in a month:

SecRule TIME_DAY "^(([1](0|1|2|3|4|5|6|7|8|9))|20)$" "id:75"

TIME_EPOCH

This variable holds the time in seconds since 1970.

TIME_HOUR

This variable holds the current hour value (0–23). The following rule triggers when a request is made “off hours”:

SecRule TIME_HOUR "^(0|1|2|3|4|5|6|[1](8|9)|[2](0|1|2|3))$" "id:76"

TIME_MIN

This variable holds the current minute value (0–59). The following rule triggers during the last half hour of every hour:

SecRule TIME_MIN "^(3|4|5)" "id:77"

TIME_MON

This variable holds the current month value (0–11). The following rule matches if the month is either November (value 10) or December (value 11):

SecRule TIME_MON "^1" "id:78"

TIME_SEC

This variable holds the current second value (0–59).

SecRule TIME_SEC "@gt 30" "id:79"

TIME_WDAY

This variable holds the current weekday value (0–6). The following rule triggers only on Saturday and Sunday:

SecRule TIME_WDAY "^(0|6)$" "id:80"

TIME_YEAR

This variable holds the current four-digit year value.

SecRule TIME_YEAR "^2006$" "id:81"

TX

Transient transaction collection used to store arbitrary data for the duration of the transaction, such as anomaly scores or state flags.

# Increment transaction attack score on attack
SecRule ARGS "attack" "phase:2,id:82,nolog,pass,setvar:TX.score=+5"

# Block the transactions whose scores are too high
SecRule TX:SCORE "@gt 20" "phase:2,id:83,log,deny"

Some variable names in the TX collection are reserved:

TX:0: the matching value when using the @rx or @pm operator with the capture action
TX:1-TX:9: the captured subexpression values when using the @rx operator with capturing groups

UNIQUE_ID

This variable holds the unique id for the transaction.

URLENCODED_ERROR

This variable is created when an invalid URL encoding is encountered during the parsing of a query string (on every request) or during the parsing of an application/x-www-form-urlencoded request body (only on the requests that use the URLENCODED request body processor).

XML

Special collection used to interact with the XML parser. It must contain a valid XPath expression, which will then be evaluated against a previously parsed XML DOM tree. Requires the XML body processor to be active.

SecRule REQUEST_HEADERS:Content-Type "^text/xml$" "phase:1,id:87,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML"
SecRule XML:/employees/employee/name "Fred" "phase:2,id:88,deny,log"

It would match against payload such as this one:

<employees>
    <employee>
        <name>Fred Jones</name>
        <address location="home">
            <street>900 Aurora Ave.</street>
            <city>Seattle</city>
            <state>WA</state>
            <zip>98115</zip>
        </address>
        <address location="work">
            <street>2011 152nd Avenue NE</street>
            <city>Redmond</city>
            <state>WA</state>
            <zip>98052</zip>
        </address>
        <phone location="work">(425)555-5665</phone>
        <phone location="home">(206)555-5555</phone>
        <phone location="mobile">(206)555-4321</phone>
    </employee>
</employees>

Transformations

Quick Start

Variables

ARGS#

ARGS_COMBINED_SIZE#

ARGS_GET#

ARGS_GET_NAMES#

ARGS_NAMES#

ARGS_PATH#

ARGS_POST#

ARGS_POST_NAMES#

DURATION#

ENV#

FILES#

FILES_COMBINED_SIZE#

FILES_NAMES#

FILES_SIZES#

FILES_TMPNAMES#

FILES_TMP_CONTENT#

FULL_REQUEST_LENGTH#

GEO#

HIGHEST_SEVERITY#

INBOUND_DATA_ERROR#

MATCHED_VAR#

MATCHED_VARS#

MATCHED_VARS_NAMES#

MATCHED_VAR_NAME#

MULTIPART_FILENAME#

MULTIPART_NAME#

OUTBOUND_DATA_ERROR#

QUERY_STRING#

REMOTE_ADDR#

REMOTE_PORT#

REQBODY_ERROR#

REQBODY_ERROR_MSG#

REQBODY_PROCESSOR#

REQBODY_PROCESSOR_ERROR#

REQBODY_PROCESSOR_ERROR_MSG#

REQUEST_BASENAME#

REQUEST_BODY#

REQUEST_BODY_LENGTH#

REQUEST_COOKIES#

REQUEST_COOKIES_NAMES#

REQUEST_FILENAME#

REQUEST_HEADERS#

REQUEST_HEADERS_NAMES#

REQUEST_LINE#

REQUEST_METHOD#

REQUEST_PROTOCOL#

REQUEST_URI#

REQUEST_URI_RAW#

RESPONSE_BODY#

RESPONSE_CONTENT_LENGTH#

RESPONSE_CONTENT_TYPE#

RESPONSE_HEADERS#

RESPONSE_HEADERS_NAMES#

RESPONSE_PROTOCOL#

RESPONSE_STATUS#

RESPONSE_XML#

RES_BODY_PROCESSOR#

RULE#

SERVER_ADDR#

SERVER_NAME#

SERVER_PORT#

STATUS_LINE#

TIME#

TIME_DAY#

TIME_EPOCH#

TIME_HOUR#

TIME_MIN#

TIME_MON#

TIME_SEC#

TIME_WDAY#

TIME_YEAR#

TX#

UNIQUE_ID#

URLENCODED_ERROR#

XML#