ModSecurity variables and collections

Reviewed by Atomicorp WAF Research Team

Adapted ModSecurity documentationThis page has been reorganized, rewritten, and supplemented by Atomicorp from upstream ModSecurity reference material. Source, license, and attribution details.

Variables are the inputs to a SecRule. A scalar represents one value; a collection can expand into many values. Select the narrowest data that expresses the security decision.

Request variables

Variable	Contains
`REQUEST_URI`	Request path, generally including the query string.
`REQUEST_URI_RAW`	Original request URI before normalization.
`REQUEST_FILENAME`	Request path without the query string.
`REQUEST_LINE`	Full request line.
`REQUEST_METHOD`	HTTP method.
`REQUEST_PROTOCOL`	Protocol from the request line.
`QUERY_STRING`	Raw query string.
`REQUEST_HEADERS`	Request-header collection.
`REQUEST_HEADERS_NAMES`	Names of received request headers.
`REQUEST_COOKIES`	Parsed request-cookie collection.
`REQUEST_BODY`	Raw or processor-dependent request body when available.

Arguments and files

Variable	Contains
`ARGS`	All parsed request arguments.
`ARGS_GET`	Query-string arguments.
`ARGS_POST`	Body arguments.
`ARGS_NAMES`	Argument names across request sources.
`FILES`	Temporary paths for intercepted uploads.
`FILES_NAMES`	Client-supplied upload names.
`FILES_SIZES`	Upload sizes.
`FILES_TMPNAMES`	Temporary upload filenames.
`FILES_COMBINED_SIZE`	Combined upload size.

Select one member with ARGS:username. Use a regular-expression selector when names follow a controlled pattern. A negated target such as !ARGS:known_safe removes one member from a larger target list.

Connection and server data

Common inputs include REMOTE_ADDR, REMOTE_HOST, REMOTE_PORT, SERVER_ADDR, SERVER_NAME, SERVER_PORT, UNIQUE_ID, and TIME. Reverse proxies can change what the connector sees as the remote address; configure trusted proxy handling before relying on client IP policy.

Response variables

Variable	Contains
`RESPONSE_STATUS`	HTTP response status.
`RESPONSE_HEADERS`	Response-header collection.
`RESPONSE_HEADERS_NAMES`	Names of response headers.
`RESPONSE_BODY`	Buffered response content when enabled and eligible.
`RESPONSE_CONTENT_TYPE`	Parsed content type.

Response-body data is unavailable unless response inspection is enabled and the MIME type and size fall within configured limits.

Match and rule context

MATCHED_VAR contains the value associated with a match, while MATCHED_VAR_NAME identifies its variable. RULE exposes metadata for the current rule. TX is a per-transaction collection commonly used for flags, captured values, and scores.

SecRule ARGS "@rx attack" \
  "id:100010,phase:2,log,pass,setvar:'tx.reason=%{MATCHED_VAR_NAME}'"

Persistent collections

IP, SESSION, USER, RESOURCE, and GLOBAL can retain state beyond one transaction when initialized and supported. Persistent state can implement counters and expiration, but it adds locking, storage, cleanup, and distributed-consistency concerns. Do not assume counters are a complete DDoS system.

Counting and exclusions

Prefix a collection with & to inspect how many members it contains. Prefix a target with ! to exclude it from the rule target list. Both change what reaches the operator; neither changes the underlying request.

See the exhaustive upstream variable reference for individual syntax and version support.