08. Actions
Actions say what a rule does when it matches: metadata, logging, flow control, variable
changes, engine control (ctl) and exactly one disruptive action
(02-grammar.md#action-list, 03-processing-model.md). The two indexes list every action
and every ctl: option known to any surveyed engine with its status (00-conventions.md,
ADR-0006). The sanitize* spellings are aliases of sanitise* (ADR-0004).
Index of actions
| Action | Status | v2 | v3 | Coraza | Purpose |
|---|---|---|---|---|---|
| accuracy | Extended | yes | yes | yes | Rule accuracy metadata 1–9 |
| allow | Core | yes | yes | yes | Stop processing and let the transaction through |
| append | Deprecated | yes | - | - | Append content to the response |
| auditlog | Core | yes | yes | yes | Mark the transaction for audit logging |
| block | Core | yes | yes | yes | Use the SecDefaultAction disruptive action |
| capture | Core | yes | yes | yes | Store regex groups in TX:0..9 |
| chain | Core | yes | yes | yes | Chain with the next rule |
| ctl | Core | yes | yes | yes | Change engine configuration for this transaction |
| deny | Core | yes | yes | yes | Interrupt with an HTTP status |
| deprecatevar | Deprecated | yes | - | - | Decrement a variable over time |
| drop | Core | yes | yes | yes | Close the connection |
| exec | Extended | yes | yes | yes | Run an external script |
| expirevar | Extended | yes | yes | yes | Expire a persistent variable |
| id | Core | yes | yes | yes | Rule identifier |
| initcol | Extended | yes | yes | yes | Initialise a persistent collection |
| log | Core | yes | yes | yes | Log the match to the error log |
| logdata | Core | yes | yes | yes | Extra data for the log message |
| marker | Deprecated | yes | - | - | Internal: SecMarker placeholder |
| maturity | Extended | yes | yes | yes | Rule maturity metadata 1–9 |
| msg | Core | yes | yes | yes | Log message |
| multiMatch | Core | yes | yes | yes | Evaluate the operator after each transformation |
| noauditlog | Core | yes | yes | yes | Do not audit-log this transaction for this rule |
| nolog | Core | yes | yes | yes | Do not log the match |
| pass | Core | yes | yes | yes | Continue with the next rule |
| pause | Deprecated | yes | - | - | Delay the response |
| phase | Core | yes | yes | yes | Processing phase |
| prepend | Deprecated | yes | - | - | Prepend content to the response |
| proxy | Deprecated | yes | - | - | Proxy the request elsewhere |
| redirect | Core | yes | yes | yes | Interrupt with a redirect |
| rev | Extended | yes | yes | yes | Rule revision metadata |
| sanitiseArg | Deprecated | yes | - | - | Mask an argument in the audit log (alias sanitizeArg) |
| sanitiseMatched | Deprecated | yes | - | - | Mask the matched variable in the audit log (alias sanitizeMatched) |
| sanitiseMatchedBytes | Deprecated | yes | - | - | Mask matched bytes in the audit log (alias sanitizeMatchedBytes) |
| sanitiseRequestHeader | Deprecated | yes | - | - | Mask a request header in the audit log (alias sanitizeRequestHeader) |
| sanitiseResponseHeader | Deprecated | yes | - | - | Mask a response header in the audit log (alias sanitizeResponseHeader) |
| setenv | Extended | yes | yes | yes | Set a process environment variable |
| setrsc | Extended | yes | yes | - | Initialise the RESOURCE collection |
| setsid | Extended | yes | yes | - | Initialise the SESSION collection |
| setuid | Extended | yes | yes | - | Initialise the USER collection |
| setvar | Core | yes | yes | yes | Set, change or delete a variable |
| severity | Core | yes | yes | yes | Rule severity 0–7 |
| skip | Extended | yes | yes | yes | Skip the next N rules |
| skipAfter | Core | yes | yes | yes | Skip to a SecMarker |
| status | Core | yes | yes | yes | HTTP status for deny or redirect |
| t | Core | yes | yes | yes | Add a transformation |
| tag | Core | yes | yes | yes | Rule tag |
| ver | Core | yes | yes | yes | Rule set version |
| xmlns | Extended | yes | yes | - | XML namespace for XPath |
Index of ctl options
| ctl option | Status | v2 | v3 | Coraza | Purpose |
|---|---|---|---|---|---|
| ctl:auditEngine | Core | yes | yes | yes | Audit logging for this transaction |
| ctl:auditLogParts | Core | yes | yes | yes | Audit parts for this transaction |
| ctl:debugLogLevel | Extended | yes | - | yes | Debug level for this transaction |
| ctl:forceRequestBodyVariable | Core | yes | yes | yes | Populate REQUEST_BODY for any content type |
| ctl:forceResponseBodyVariable | Engine-specific | - | - | yes | Coraza: populate RESPONSE_BODY regardless of MIME type |
| ctl:hashEnforcement | Deprecated | yes | - | yes | Hash enforcement for this transaction |
| ctl:hashEngine | Deprecated | yes | - | yes | Hash engine for this transaction |
| ctl:parseXmlIntoArgs | Extended | yes | yes | - | XML values into ARGS for this transaction |
| ctl:requestBodyAccess | Core | yes | yes | yes | Request body access for this transaction |
| ctl:requestBodyLimit | Extended | yes | - | yes | Request body limit for this transaction |
| ctl:requestBodyProcessor | Core | yes | yes | yes | Select the body processor |
| ctl:responseBodyAccess | Extended | yes | - | yes | Response body access for this transaction |
| ctl:responseBodyLimit | Extended | yes | - | yes | Response body limit for this transaction |
| ctl:responseBodyProcessor | Engine-specific | - | - | yes | Coraza: select the response body processor |
| ctl:ruleEngine | Core | yes | yes | yes | Rule engine mode for this transaction |
| ctl:ruleRemoveById | Core | yes | yes | yes | Disable rules by id for this transaction |
| ctl:ruleRemoveByMsg | Extended | yes | - | yes | Disable rules by message for this transaction |
| ctl:ruleRemoveByTag | Core | yes | yes | yes | Disable rules by tag for this transaction |
| ctl:ruleRemoveTargetById | Core | yes | yes | yes | Exclude a variable from rules by id |
| ctl:ruleRemoveTargetByMsg | Extended | yes | - | yes | Exclude a variable from rules by message |
| ctl:ruleRemoveTargetByTag | Core | yes | yes | yes | Exclude a variable from rules by tag |
Core actions
allow
Status: Core
Syntax. allow, allow:phase, allow:request
Semantics. Disruptive. allow stops rule processing for the current phase and
every later phase except logging (phase 5), which MUST still run. allow:phase stops
only the current phase. allow:request stops phases 1 and 2 (the response phases still
run). allow produces no interruption object in any engine (it sets a flag); tests
observe it through which rules do and do not run.
Divergence notes. Coraza 3.8.1 (internal/corazawaf/rulegroup.go, AllowTypeAll)
also skips the logging phase, so its phase 5 rules do not run after allow
(compat/known-gaps.md).
Tests. tests/engine/actions/allow.yaml
auditlog
Status: Core
Syntax. auditlog
Semantics. Marks the transaction as relevant for audit logging when the rule
matches (used with SecAuditEngine RelevantOnly). No effect on rule evaluation.
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
block
Status: Core
Syntax. block
Semantics. A placeholder for the disruptive action inherited from SecDefaultAction
(03-processing-model.md#disruptive-actions). With SecDefaultAction "...,deny" a
block rule denies; with none inherited it passes. CRS uses it on every blocking rule so
that SecDefaultAction decides between blocking and detection.
Divergence notes. None known.
Tests. tests/engine/actions/block-with-default.yaml,
tests/engine/actions/block-without-default.yaml
capture
Status: Core
Syntax. capture
Semantics. After an @rx match, stores the whole match in TX:0 and capture groups
1 to 9 in TX:1…TX:9. Also defined for @detectSQLi (fingerprint in TX:0). Values
persist until the next capturing match.
Divergence notes. None known.
Tests. tests/engine/actions/capture-multimatch.yaml,
tests/engine/variables/tx-and-capture.yaml
chain
Status: Core
Syntax. chain
Semantics. Makes the next rule a member of this rule’s chain
(03-processing-model.md#chains).
Divergence notes. None known.
Tests. tests/engine/processing/chain.yaml
ctl
Status: Core
Syntax. ctl:OPTION=VALUE
Semantics. Changes engine configuration for the current transaction when the rule
matches (03-processing-model.md#ctl-timing). Option names match case-insensitively.
Each option is specified below under ctl:OPTION; statuses are fixed by ADR-0006.
Divergence notes. See the individual options.
Tests. tests/engine/actions/ctl-options.yaml,
tests/engine/processing/ctl-core-options-load.yaml
deny
Status: Core
Syntax. deny
Semantics. Disruptive: interrupts the transaction with the status from status:,
default 403 (03-processing-model.md#disruptive-actions).
Divergence notes. None known.
Tests. tests/engine/processing/disruptive-actions.yaml
drop
Status: Core
Syntax. drop
Semantics. Disruptive: closes the connection without a response where the host
allows, otherwise behaves as deny. Reported as action: drop.
Divergence notes. None known.
Tests. tests/engine/processing/disruptive-actions.yaml
id
Status: Core
Syntax. id:N, N a positive integer; id:'N' is also accepted.
Semantics. The rule’s identifier, mandatory and unique (ADR-0015). Used by every exclusion mechanism and by logs.
Divergence notes. See ADR-0015 for Coraza’s default build.
Tests. tests/engine/actions/metadata-and-log-actions.yaml,
tests/engine/grammar/secrule-requires-id.yaml
log
Status: Core
Syntax. log
Semantics. Writes the match to the engine’s error log and, unless noauditlog
is present, marks the transaction for the audit log. The default when neither log
nor nolog is given.
Divergence notes. Coraza 3.8.1 logs a match only when log is given explicitly or
inherited from SecDefaultAction (internal/corazawaf/transaction.go, r.Log); CRS
sets log in its default actions, so this is rarely visible. Recorded in
compat/known-gaps.md under unobservable divergences.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
logdata
Status: Core
Syntax. logdata:'TEXT' (macros expand).
Semantics. Additional text written with the log message, typically the matched
value (%{MATCHED_VAR}). No effect on evaluation.
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
msg
Status: Core
Syntax. msg:'TEXT' (macros expand).
Semantics. The rule’s log message; also the target of SecRuleRemoveByMsg.
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
multiMatch
Status: Core
Syntax. multiMatch
Semantics. Evaluates the operator against the value before any transformation and
again after each transformation in the t: list, instead of only against the final
value. The rule matches if any evaluation matches.
Divergence notes. None known.
Tests. tests/engine/actions/capture-multimatch.yaml
noauditlog
Status: Core
Syntax. noauditlog
Semantics. The match does not mark the transaction as relevant for audit logging.
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
nolog
Status: Core
Syntax. nolog
Semantics. The match is not written to the error log and implies noauditlog
unless auditlog is also given. The rule still counts as triggered (tests/README.md).
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
pass
Status: Core
Syntax. pass
Semantics. The non-interrupting disruptive action: processing continues with the next rule.
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
phase
Status: Core
Syntax. phase:1…phase:5, phase:request, phase:response, phase:logging
Semantics. The phase the rule runs in (03-processing-model.md#phases); default 2
(ADR-0017).
Divergence notes. See ADR-0017.
Tests. tests/engine/actions/metadata-and-log-actions.yaml,
tests/engine/processing/phases.yaml
redirect
Status: Core
Syntax. redirect:URL (macros expand).
Semantics. Disruptive: interrupts with a redirect to URL; the status is the
status: value when it is 301, 302, 303 or 307, otherwise 302.
Divergence notes. libmodsecurity v3 (src/actions/disruptive/redirect.cc) also
honours 304, 305 and 306; portable rules use the four codes above.
Tests. tests/engine/actions/status-redirect.yaml,
tests/engine/processing/disruptive-actions.yaml
setvar
Status: Core
Syntax. setvar:COLL.key=VALUE, setvar:COLL.key=+N, setvar:COLL.key=-N,
setvar:!COLL.key, setvar:COLL.key (sets 1). Macros expand in VALUE.
Semantics. Creates or replaces a member of a writable collection (TX, and the
persistent collections where Extended). =+N and =-N convert the current value to an
integer, treating an unset or non-numeric value as 0, add or subtract N, and store the
decimal result. ! deletes the member. Names are matched case-insensitively (ADR-0008).
Divergence notes. None known.
Tests. tests/engine/actions/setvar.yaml
severity
Status: Core
Syntax. severity:N with N 0–7, or one of EMERGENCY ALERT CRITICAL ERROR WARNING NOTICE INFO DEBUG (case-insensitive), optionally quoted.
Semantics. Metadata written to logs; lowers HIGHEST_SEVERITY (Extended) when
smaller than its current value.
Divergence notes. None known.
Tests. tests/engine/actions/severity.yaml
skipAfter
Status: Core
Syntax. skipAfter:LABEL
Semantics. On match, skip to the SecMarker LABEL in the current phase; a rule id is
not a label (03-processing-model.md#flow-control, ADR-0016, ADR-0028).
Divergence notes. See ADR-0016 and ADR-0028.
Tests. tests/engine/actions/skipafter.yaml
status
Status: Core
Syntax. status:N
Semantics. The HTTP status code used by deny (any code) and redirect (3xx only).
No effect with other disruptive actions.
Divergence notes. None known.
Tests. tests/engine/actions/status-redirect.yaml
t
Status: Core
Syntax. t:NAME
Semantics. Appends transformation NAME (07-transformations.md) to the rule’s
list; t:none resets the inherited list. Repeatable.
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml,
tests/engine/actions/t-none.yaml
tag
Status: Core
Syntax. tag:'TEXT' (macros expand). Repeatable.
Semantics. Metadata written to logs and the target of SecRuleRemoveByTag,
SecRuleUpdateTargetByTag and ctl:ruleRemoveByTag.
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
ver
Status: Core
Syntax. ver:'TEXT'
Semantics. Rule set version metadata written to logs.
Divergence notes. None known.
Tests. tests/engine/actions/metadata-and-log-actions.yaml
Core ctl options
ctl:auditEngine
Status: Core
Syntax. ctl:auditEngine=On|Off|RelevantOnly
Semantics. Overrides SecAuditEngine for this transaction.
Tests. tests/engine/actions/ctl-options.yaml
ctl:auditLogParts
Status: Core
Syntax. ctl:auditLogParts=+LETTERS or -LETTERS
Semantics. Adds or removes audit log parts for this transaction. The absolute form
(=ABCZ) is Extended (ADR-0006).
Tests. tests/engine/actions/ctl-options.yaml
ctl:forceRequestBodyVariable
Status: Core
Syntax. ctl:forceRequestBodyVariable=On|Off
Semantics. When set in phase 1, REQUEST_BODY is populated regardless of the body
processor or content type.
Tests. tests/engine/actions/ctl-options.yaml
ctl:requestBodyAccess
Status: Core
Syntax. ctl:requestBodyAccess=On|Off
Semantics. Overrides SecRequestBodyAccess for this transaction; effective only in
phase 1.
Tests. tests/engine/actions/ctl-options.yaml
ctl:requestBodyProcessor
Status: Core
Syntax. ctl:requestBodyProcessor=URLENCODED|XML|JSON
Semantics. Selects the request body processor regardless of Content-Type;
effective only in phase 1. Names match case-insensitively. MULTIPART is accepted by
ModSecurity v2 and Coraza but not by libmodsecurity v3 (seclang-scanner.ll defines only
the three values above), so it is Extended.
Tests. tests/engine/actions/ctl-options.yaml
ctl:ruleEngine
Status: Core
Syntax. ctl:ruleEngine=On|Off|DetectionOnly
Semantics. Overrides SecRuleEngine for the later phases and, at once, for the
interruption decision of the current phase: after DetectionOnly or Off no later rule
of the phase interrupts (03-processing-model.md#ctl-timing); whether the remaining
rules are still evaluated after Off is not specified.
Tests. tests/engine/actions/ctl-options.yaml,
tests/engine/processing/ctl-timing.yaml
ctl:ruleRemoveById
Status: Core
Syntax. ctl:ruleRemoveById=ID or =A-B
Semantics. Disables the matching rules for the rest of this transaction
(03-processing-model.md#rule-exceptions).
Tests. tests/engine/actions/ctl-options.yaml
ctl:ruleRemoveByTag
Status: Core
Syntax. ctl:ruleRemoveByTag=TAG
Semantics. Disables every rule one of whose tag values equals TAG for the rest of
this transaction (03-processing-model.md#rule-exceptions, ADR-0029).
Tests. tests/engine/actions/ctl-options.yaml
ctl:ruleRemoveTargetById
Status: Core
Syntax. ctl:ruleRemoveTargetById=ID;TARGET (ID may be a range A-B)
Semantics. Excludes TARGET (a variable with optional key, e.g. ARGS:password)
from the matching rules for the rest of this transaction. This is the mechanism CRS
documents for per-request exclusions.
Tests. tests/engine/actions/ctl-options.yaml
ctl:ruleRemoveTargetByTag
Status: Core
Syntax. ctl:ruleRemoveTargetByTag=TAG;TARGET
Semantics. As ctl:ruleRemoveTargetById, selecting every rule one of whose tag
values equals TAG (ADR-0029).
Tests. tests/engine/actions/ctl-options.yaml
Extended actions
accuracy
Status: Extended
Semantics. Rule accuracy 1–9, metadata only.
Implemented by. v2, v3, Coraza.
exec
Status: Extended
Semantics. Runs an external script or Lua file when the rule matches; process access makes it Extended.
Implemented by. v2, v3, Coraza.
expirevar
Status: Extended
Semantics. expirevar:COLL.key=SECONDS: removes a persistent variable after the interval (ADR-0007).
Implemented by. v2, v3, Coraza.
initcol
Status: Extended
Semantics. initcol:ip=%{REMOTE_ADDR}: initialises a persistent collection (ADR-0007).
Implemented by. v2, v3, Coraza.
maturity
Status: Extended
Semantics. Rule maturity 1–9, metadata only.
Implemented by. v2, v3, Coraza.
rev
Status: Extended
Semantics. Rule revision string, metadata only.
Implemented by. v2, v3, Coraza.
setenv
Status: Extended
Semantics. Sets a variable in the host process environment for downstream modules.
Implemented by. v2, v3, Coraza.
setrsc
Status: Extended
Semantics. Initialises the RESOURCE persistent collection (ADR-0007).
Implemented by. v2, v3.
setsid
Status: Extended
Semantics. Initialises the SESSION persistent collection and SESSIONID (ADR-0007).
Implemented by. v2, v3.
setuid
Status: Extended
Semantics. Initialises the USER persistent collection and USERID (ADR-0007).
Implemented by. v2, v3.
skip
Status: Extended
Semantics. skip:N: skips the next N rules in the phase (03-processing-model.md#flow-control); all three engines implement it, CRS does not use it.
Implemented by. v2, v3, Coraza.
xmlns
Status: Extended
Semantics. Declares an XML namespace prefix for XPath selectors in XML:.
Implemented by. v2, v3.
Deprecated actions
append
Status: Deprecated
Semantics. Appends text to the response body; needs SecContentInjection.
Implemented by. v2.
deprecatevar
Status: Deprecated
Semantics. Decrements a persistent variable over time.
Implemented by. v2.
marker
Status: Deprecated
Semantics. Internal action created by SecMarker; never written by rule authors.
Implemented by. v2.
pause
Status: Deprecated
Semantics. Delays the response by milliseconds.
Implemented by. v2.
prepend
Status: Deprecated
Semantics. Prepends text to the response body; needs SecContentInjection.
Implemented by. v2.
proxy
Status: Deprecated
Semantics. Proxies the request to another URL (Apache mod_proxy).
Implemented by. v2.
sanitiseArg
Status: Deprecated
Semantics. Masks an argument’s value in the audit log; alias sanitizeArg.
Implemented by. v2.
sanitiseMatched
Status: Deprecated
Semantics. Masks the matched variable in the audit log; alias sanitizeMatched.
Implemented by. v2.
sanitiseMatchedBytes
Status: Deprecated
Semantics. Masks the matched bytes in the audit log; alias sanitizeMatchedBytes.
Implemented by. v2.
sanitiseRequestHeader
Status: Deprecated
Semantics. Masks a request header in the audit log; alias sanitizeRequestHeader.
Implemented by. v2.
sanitiseResponseHeader
Status: Deprecated
Semantics. Masks a response header in the audit log; alias sanitizeResponseHeader.
Implemented by. v2.
Extended ctl options
ctl:debugLogLevel
Status: Extended
Semantics. ctl:debugLogLevel=N for this transaction.
Implemented by. v2, Coraza.
ctl:parseXmlIntoArgs
Status: Extended
Semantics. ctl:parseXmlIntoArgs=On|Off|OnlyArgs for this transaction.
Implemented by. v2, v3.
ctl:requestBodyLimit
Status: Extended
Semantics. ctl:requestBodyLimit=BYTES for this transaction.
Implemented by. v2, Coraza.
ctl:responseBodyAccess
Status: Extended
Semantics. ctl:responseBodyAccess=On|Off for this transaction.
Implemented by. v2, Coraza.
ctl:responseBodyLimit
Status: Extended
Semantics. ctl:responseBodyLimit=BYTES for this transaction.
Implemented by. v2, Coraza.
ctl:ruleRemoveByMsg
Status: Extended
Semantics. Disables rules whose msg matches, for this transaction.
Implemented by. v2, Coraza.
ctl:ruleRemoveTargetByMsg
Status: Extended
Semantics. Excludes a target from rules whose msg matches, for this transaction.
Implemented by. v2, Coraza.
Deprecated ctl options
ctl:hashEnforcement
Status: Deprecated
Semantics. Hash enforcement toggle for this transaction (Deprecated hash engine).
Implemented by. v2, Coraza.
ctl:hashEngine
Status: Deprecated
Semantics. Hash engine toggle for this transaction (Deprecated hash engine).
Implemented by. v2, Coraza.
Engine-specific ctl options
ctl:forceResponseBodyVariable
Status: Engine-specific
Semantics. Coraza: populates RESPONSE_BODY regardless of MIME type.
Implemented by. Coraza.
ctl:responseBodyProcessor
Status: Engine-specific
Semantics. Coraza: selects the response body processor (JSON, XML, …).
Implemented by. Coraza.