Operators
This section documents the operators currently available in Coraza.
beginsWith
Description: Matches if the parameter string appears at the beginning of the input. Supports macro expansion for dynamic string matching.
Example:
# Block requests that don't start with GET
SecRule REQUEST_LINE "!@beginsWith GET" "id:149,deny,log"
# Check if URI starts with /admin
SecRule REQUEST_URI "@beginsWith /admin" "id:151,deny"
contains
Description: Matches if the parameter string is found anywhere in the input. Supports macro expansion for dynamic string matching.
Example:
# Detect PHP files in request line
SecRule REQUEST_LINE "@contains .php" "id:150,deny,log"
# Check if URI contains admin
SecRule REQUEST_URI "@contains admin" "id:151,deny"
detectSQLi
Description: Detects SQL injection attacks using libinjection library. Returns true if SQL injection payload is found in the input. Captures the SQLi fingerprint in field 0 for logging and analysis.
Example:
# Detect SQLi in query string
SecRule ARGS "@detectSQLi" "id:185,deny,log,msg:'SQL Injection Detected'"
# Check request body for SQLi
SecRule REQUEST_BODY "@detectSQLi" "id:186,deny"
detectXSS
Description: Detects Cross-Site Scripting (XSS) attacks using libinjection library. Returns true if XSS payload is found in the input. Uses advanced pattern matching to identify XSS vectors.
Example:
# Detect XSS in request parameters
SecRule ARGS "@detectXSS" "id:187,deny,log,msg:'XSS Attack Detected'"
# Check request body for XSS
SecRule REQUEST_BODY "@detectXSS" "id:188,deny"
endsWith
Description: Matches if the parameter string appears at the end of the input. Supports macro expansion for dynamic string matching.
Example:
# Block requests that don't end with HTTP/1.1
SecRule REQUEST_LINE "!@endsWith HTTP/1.1" "id:152,deny,log"
# Check if filename ends with .exe
SecRule REQUEST_FILENAME "@endsWith .exe" "id:154,deny"
eq
Description: Performs numerical comparison and returns true if the input value is equal to the provided parameter. Both values are converted to integers before comparison. Supports macro expansion for dynamic comparison.
Example:
# Check if request header count is exactly 15
SecRule &REQUEST_HEADERS_NAMES "@eq 15" "id:153,deny,log"
# Compare parameter value to expected number
SecRule ARGS:quantity "@eq 100" "id:154,pass"
ge
Description: Returns true if the input value is greater than or equal to the provided parameter. Both values are converted to integers before comparison. Supports macro expansion for dynamic comparison.
Example:
# Block if too many request headers
SecRule &REQUEST_HEADERS_NAMES "@ge 15" "id:155,deny,log"
# Check minimum value requirement
SecRule ARGS:age "@ge 18" "id:156,pass"
gt
Description: Returns true if the input value is greater than the operator parameter. Both values are converted to integers before comparison. Supports macro expansion for dynamic comparison.
Example:
# Deny if request header count exceeds limit
SecRule &REQUEST_HEADERS_NAMES "@gt 15" "id:158,deny,log"
# Check if quantity exceeds threshold
SecRule ARGS:count "@gt 100" "id:159,deny"
inspectFile
Description: Executes an external program for every variable in the target list. Useful for integrating external validation tools (virus scanners, content analyzers, etc.). The program receives the variable value as a command-line argument and has a 10-second timeout.
Example:
# Scan uploaded files with external antivirus
SecRule FILES_TMPNAMES "@inspectFile /usr/local/bin/av-scan.sh" "id:203,deny,log,msg:'Virus detected'"
# Custom content validation script
SecRule REQUEST_BODY "@inspectFile /opt/waf/scripts/validate-content.py" "id:204,deny"
ipMatch
Description: Performs fast IPv4 or IPv6 address matching with support for CIDR notation. Can match individual IPs or IP ranges. Automatically adds appropriate subnet masks (/32 for IPv4, /128 for IPv6) when not specified.
Example:
# Block specific IPs and ranges
SecRule REMOTE_ADDR "@ipMatch 192.168.1.100,192.168.1.50,10.10.50.0/24" "id:160,deny,log"
# Allow internal network
SecRule REMOTE_ADDR "@ipMatch 10.0.0.0/8,172.16.0.0/12" "id:161,pass"
le
Description: Returns true if the input value is less than or equal to the operator parameter. Both values are converted to integers before comparison. Supports macro expansion for dynamic comparison.
Example:
# Allow requests with reasonable header count
SecRule &REQUEST_HEADERS_NAMES "@le 15" "id:164,pass,log"
# Check maximum value constraint
SecRule ARGS:limit "@le 100" "id:165,pass"
lt
Description: Returns true if the input value is less than the operator parameter. Both values are converted to integers before comparison. Supports macro expansion for dynamic comparison.
Example:
# Ensure header count stays below threshold
SecRule &REQUEST_HEADERS_NAMES "@lt 15" "id:166,pass,log"
# Check value is under limit
SecRule ARGS:quantity "@lt 1000" "id:167,pass"
noMatch
Description: Forces the rule to always return false, effectively disabling rule matching unconditionally. Useful for temporarily disabling rules without removing them, or for rules that only execute actions without needing to match.
Example:
# Disabled rule that never matches
SecRule ARGS "@noMatch" "id:205,deny,log,msg:'This rule will never fire'"
# Rule that only executes actions without matching
SecRule REQUEST_URI "@noMatch" "id:206,pass,setvar:tx.test=1"
pm
Description: Performs case-insensitive pattern matching using the Aho-Corasick algorithm for efficient multi-pattern searching. Matches space-separated keywords or patterns provided as arguments.
Example:
# Detect known malicious user agents
SecRule REQUEST_HEADERS:User-Agent "@pm WebZIP WebCopier Webster" "id:170,deny,log"
# Match multiple attack patternsonerror=" "id:171,deny"
rbl
Description: Looks up the input IP address in the specified RBL (Real-time Block List) service. Performs DNS lookups to check if the IP is listed. Sets TX.httpbl_msg variable with the response text if found. Has a 500ms timeout for DNS queries.
Example:
# Check IP against Spamhaus blocklist
SecRule REMOTE_ADDR "@rbl sbl-xbl.spamhaus.org" "id:183,deny,log,msg:'IP found in RBL'"
# Multiple RBL checks
SecRule REMOTE_ADDR "@rbl dnsbl.example.com" "id:184,deny"
restpath
Description: Takes a path expression with placeholders and transforms it to a regex for REST endpoint validation. Extracts path parameters from the URI and stores them in ARGS_PATH collection for use in rules. Useful for validating REST API endpoints with dynamic path segments.
Example:
# Match REST endpoint and extract path parameters
SecRule REQUEST_URI "@restpath /api/v1/users/{userId}/posts/{postId}" "id:201,pass,log"
# Validate extracted path parameter
SecRule ARGS_PATH:userId "@rx ^[0-9]+$" "id:202,deny,msg:'Invalid user ID format'"
rx
Description: Performs regular expression pattern matching using RE2 syntax. This is the default operator if no @ prefix is specified. Supports capturing groups (up to 9) for use in rule actions. By default enables dotall mode (?s) where . matches newlines for compatibility with ModSecurity.
Example:
# Match User-Agent containing "nikto" (with explicit @rx)
SecRule REQUEST_HEADERS:User-Agent "@rx nikto" "id:180,deny,log"
# Implicit operator usage (same as @rx)
SecRule ARGS "(?i)union.*select" "id:181,deny"
# Capture groups for reuse in actions
SecRule REQUEST_URI "@rx ^/api/v(\d+)" "id:182,setvar:tx.api_version=%{TX.1}"
streq
Description: Performs a string comparison and returns true if the parameter string is identical to the input string. This is a case-sensitive exact match operator. Supports macro expansion for dynamic string matching.
Example:
# Block if foo parameter is not exactly "bar"
SecRule ARGS:foo "!@streq bar" "id:176,deny,log"
# Check if request method is exactly POST
SecRule REQUEST_METHOD "@streq POST" "id:177,deny"
unconditionalMatch
Description: Forces the rule to always return true, unconditionally matching and firing all associated actions. Useful for rules that should always execute their actions regardless of input, such as setting variables, logging, or performing initialization tasks.
Example:
# Always execute action to set variable
SecRule REMOTE_ADDR "@unconditionalMatch" "id:207,phase:1,pass,nolog,setvar:tx.initialized=1"
# Force rule to always match and log
SecRule REQUEST_URI "@unconditionalMatch" "id:208,pass,log,msg:'Request logged'"
validateByteRange
Description: Validates that the byte values used in input fall into the specified range(s). Returns true (violation) if any byte is found outside the allowed ranges. Useful for detecting binary data, control characters, or restricting character sets.
Example:
# Allow only printable ASCII characters
SecRule ARGS "@validateByteRange 10, 13, 32-126" "id:189,deny,log,msg:'Invalid characters'"
# Detect null bytes
SecRule REQUEST_URI "@validateByteRange 1-255" "id:190,deny"
validateNid
Description: Validates that the input contains a valid National Identifier for the specified country. Uses country-specific validation algorithms (Luhn check, format rules, etc.). Supports multiple country codes with custom regex patterns.
Example:
# Validate Chilean RUT format
SecRule ARGS:rut "@validateNid cl ^[0-9]{7,8}-[0-9Kk]$" "id:195,pass,log"
# Reject invalid Chilean national IDs
SecRule ARGS:nid "!@validateNid cl ^[0-9]{7,8}-[0-9Kk]$" "id:196,deny,msg:'Invalid RUT'"
validateSchema
Description: Validates JSON request or response bodies against a JSON Schema specification. Automatically retrieves JSON data from TX variables (json_request_body or json_response_body) based on the current phase. Returns true if validation fails (schema violation).
Example:
# Validate request body against API schema
SecRule REQUEST_BODY "@validateSchema /schemas/api-request.json" "id:197,deny,log,phase:2"
# Validate response body schema
SecRule RESPONSE_BODY "@validateSchema /schemas/api-response.json" "id:198,log,phase:4"
validateURLEncoding
Description: Validates URL-encoded characters in the input string. Checks that percent-encoding follows proper format (%XX where X is a hexadecimal digit). Returns true if invalid encoding is detected (non-hex characters or incomplete sequences).
Example:
# Ensure proper URL encoding in request URI
SecRule REQUEST_URI_RAW "@validateUrlEncoding" "id:191,deny,log,msg:'Invalid URL encoding'"
# Check query string encoding
SecRule QUERY_STRING "@validateUrlEncoding" "id:192,deny"
validateUtf8Encoding
Description: Checks whether the input is a valid UTF-8 encoded string. Detects encoding issues, malformed sequences, and overlong encodings. Useful for preventing UTF-8 validation attacks and ensuring proper character encoding.
Example:
# Ensure valid UTF-8 in request parameters
SecRule ARGS "@validateUtf8Encoding" "id:193,deny,log,msg:'Invalid UTF-8 encoding'"
# Check request body encoding
SecRule REQUEST_BODY "@validateUtf8Encoding" "id:194,deny"
within
Description: Returns true if the input value (the needle) is found anywhere within the @within parameter (the haystack). This is the inverse of contains - it checks if the input is contained in the parameter list. Supports macro expansion for dynamic matching.
Example:
# Allow only specific HTTP methods
SecRule REQUEST_METHOD "!@within GET,POST,HEAD" "id:178,deny,log"
# Check if parameter value is in allowed list
SecRule ARGS:action "@within view,list,search" "id:179,pass"