Directives

Include

Description: Include and evaluate a file or file pattern.

Version Compatibility: v2.1+

Tinygo Compatibility: false

Syntax: Include /path/coreruleset/rules/*.conf

Include loads a file or a list of files from the filesystem using golang Glob syntax.

Quoting golang documentation:

The syntax of patterns is the same as in Match. The pattern may describe hierarchical names such as /usr/*/bin/ed (assuming the Separator is ‘/’).
Glob ignores file system errors such as I/O errors reading directories. The only possible returned error is ErrBadPattern, when pattern is malformed.`

SecAction

Description: Unconditionally processes the action list it receives as the first and only parameter. The syntax of the parameter is identical to that of the third parameter of SecRule.

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecAction "action1,action2,action3,…

This directive is commonly used to set variables and initialize persistent collections using the initcol action. For example:

SecAction "nolog,phase:1,initcol:RESOURCE=%{REQUEST_FILENAME}"

SecArgumentSeparator

Description: Specifies which character to use as the separator for application/x-www-form- urlencoded content.

Default: &

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecArgumentSeparator <separator>

This directive is needed if a backend web application is using a nonstandard argument separator. Applications are sometimes (very rarely) written to use a semicolon separator. You should not change the default setting unless you establish that the application you are working with requires a different separator. If this directive is not set properly for each web application, then Coraza will not be able to parse the arguments appropriately and the effectiveness of the rule matching will be significantly decreased.

SecAuditEngine

Description: Configures the audit logging engine.

Default: Off

Version Compatibility: v1.0+

Tinygo Compatibility: Partial, some engines and formats might be unavailable.

Syntax: SecAuditEngine RelevantOnly

The SecAuditEngine directive is used to configure the audit engine, which logs complete transactions. Coraza is currently able to log most, but not all transactions. Transactions involving errors (e.g., 400 and 404 transactions) use a different execution path, which Coraza does not support.

The possible values for the audit log engine are as follows:

On: log all transactions
Off: do not log any transactions
RelevantOnly: only the log transactions that have triggered a warning or an error, or have a status code that is considered to be relevant (as determined by the SecAuditLogRelevantStatus directive)

Note : If you need to change the audit log engine configuration on a per-transaction basis (e.g., in response to some transaction data), use the ctl action. The following example demonstrates how SecAuditEngine is used:

SecAuditEngine RelevantOnly
SecAuditLog logs/audit/audit.log
SecAuditLogParts ABCFHZ 
SecAuditLogType concurrent 
SecAuditLogStorageDir logs/audit 
SecAuditLogRelevantStatus ^(?:5|4(?!04))

SecAuditEngine

Description: Defines which parts of each transaction are going to be recorded in the audit log. Each part is assigned a single letter; when a letter appears in the list then the equivalent part will be recorded. See below for the list of all parts.

Default: ABCFHZ

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecAuditLogParts ABCFHZ

The format of the audit log format is documented in detail in the logging page.

Available audit log parts:

A: Audit log header (mandatory).
B: Request headers.
C: Request body (present only if the request body exists and Coraza is configured to intercept it. This would require SecRequestBodyAccess to be set to on).
D: Reserved for intermediary response headers; not implemented yet.
E: Intermediary response body (present only if Coraza is configured to intercept response bodies, and if the audit log engine is configured to record it. Intercepting response bodies requires SecResponseBodyAccess to be enabled). Intermediary response body is the same as the actual response body unless Coraza intercepts the intermediary response body, in which case the actual response body will contain the error message (either the Apache default error message, - orthe ErrorDocument page).
F: Final response headers (excluding the Date and Server headers, which are always added by Apache in the late stage of content delivery).
G: Reserved for the actual response body; not implemented yet.
H: Audit log trailer.
I: This part is a replacement for part C. It will log the same data as C in all cases except when multipart/form-data encoding in used. In this case, it will log a fake application/x-www-form-urlencoded body that contains the information about parameters but not about the files. This is handy if you don’t want to have (often large) files stored in your audit logs.
J: This part contains information about the files uploaded using multipart/form-data encoding.
K: This part contains a full list of every rule that matched (one per line) in the order they were matched. The rules are fully qualified and will thus show inherited actions and default operators.
Z: Final boundary, signifies the end of the entry (mandatory).

SecAuditLog

Description: Defines the path to the main audit log file (serial logging format) or the concurrent logging index file (concurrent logging format). When used in combination with mlogc (only possible with concurrent logging), this directive defines the mlogc location and command line.

Version Compatibility: v1.0+

Tinygo Compatibility: Partial, file writing is not available on all platforms.

Syntax: SecAuditLog /path/to/audit.log

👉

Writing to programs using pipe (|) is not implemented yet.

SecAuditLog "|/path/to/mlogc /path/to/mlogc.conf"

Note : This audit log file is opened on startup when the server typically still runs as root. You should not allow non-root users to have write privileges for this file or for the directory.

SecAuditLogRelevantStatus

Description: Configures which response status code is to be considered relevant for the purpose of audit logging.

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecAuditLogRelevantStatus REGEX

Example Usage: SecAuditLogRelevantStatus "^(?:5|40[1235])"

Dependencies/Notes: Must have SecAuditEngine set to RelevantOnly. Additionally, the auditlog action is present by default in rules, this will make the engine bypass the SecAuditLogRelevantStatus and send rule matches to the audit log regardless of status. You must specify noauditlog in the rules manually or set it in SecDefaultAction.

The main purpose of this directive is to allow you to configure audit logging for only the transactions that have the status code that matches the supplied regular expression. The example provided would log all 5xx and 4xx level status codes, except for 404s. Although you could achieve the same effect with a rule in phase 5, SecAuditLogRelevantStatus is sometimes better, because it continues to work even when SecRuleEngine is disabled.

SecDebugLog

Description: Path to the Coraza debug log file.

Version Compatibility: v1.0+

Tinygo Compatibility: Partial, file writing is not available on all platforms.

Syntax: SecDebugLog /path/to/coraza-debug.log

Logs will be written to this file. Make sure the process user has write access to the directory.

SecDebugLogLevel

Description: Configures the verboseness of the debug log data.

Default: 2

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecDebugLogLevel 4

Depending on the implementation, errors ranging from 1 to 2 might be directly logged to the connector error log. For example, level 2 (error) logs will be written to caddy server error logs.

The possible values for the debug log level are:

0: Fatal
1: Panic
2: Error
3: Warning
4: details of how transactions are handled
5: log everything, including very detailed debugging information

All levels over 5 will be considered as 5.

SecDefaultAction

Description: Defines the default list of actions, which will be inherited by the rules in the same configuration context.

Default: phase:2,log,auditlog,pass

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecDefaultAction "phase:2,log,auditlog,deny,status:403,tag:'SLA 24/7'"

Every rule following a previous SecDefaultAction directive in the same configuration context will inherit its settings unless more specific actions are used.

Rulesets like OWASP Core Ruleset uses this to define operation modes:

You can set the default disruptive action to block for phases 1 and 2 and you can force a phase 3 rule to be disrupted if the thread score is high.
You can set the default disruptive action to deny and each risky rule will interrupt the connection.

**Important:**Every SecDefaultAction directive must specify a disruptive action and a processing phase and cannot contain metadata actions.

SecMarker

Description: Adds a fixed rule marker that can be used as a target in a skipAfter action. A SecMarker directive essentially creates a rule that does nothing and whose only purpose is to carry the given ID.

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecMarker ID|TEXT

The value can be either a number or a text string. The SecMarker directive is available to allow you to choose the best way to implement a skip-over. Here is an example used from the Core Rule Set:

SecMarker BEGIN_HOST_CHECK

SecRule &REQUEST_HEADERS:Host "@eq 0" \
    "id:'960008',skipAfter:END_HOST_CHECK,phase:2,rev:'2.1.1',\
    t:none,block,msg:'Request Missing a Host Header',\
    tag:'PROTOCOL_VIOLATION/MISSING_HEADER_HOST',tag:'WASCTC/WASC-21',\
    tag:'OWASP_TOP_10/A7',tag:'PCI/6.5.10',\
    severity:'5',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.notice_anomaly_score},\
    setvar:tx.protocol_violation_score=+%{tx.notice_anomaly_score},\
    setvar:tx.%{rule.id}-PROTOCOL_VIOLATION/MISSING_HEADER-%{matched_var_name}=%{matched_var}"
SecRule REQUEST_HEADERS:Host "^$" \
    "id:'960008',phase:2,rev:'2.1.1',t:none,block,msg:'Request Missing a Host Header',\
    tag:'PROTOCOL_VIOLATION/MISSING_HEADER_HOST',tag:'WASCTC/WASC-21',\
    tag:'OWASP_TOP_10/A7',tag:'PCI/6.5.10',severity:'5',\
    setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.notice_anomaly_score},\
    setvar:tx.protocol_violation_score=+%{tx.notice_anomaly_score},\
    setvar:tx.%{rule.id}-PROTOCOL_VIOLATION/MISSING_HEADER-%{matched_var_name}=%{matched_var}"

SecMarker END_HOST_CHECK

SecRequestBodyAccess

Description: Configures whether request bodies will be buffered and processed by Coraza.

Default: false

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecRequestBodyAccess On|Off

This directive is required if you want to inspect the data transported request bodies (e.g., POST parameters). Request buffering is also required in order to make reliable blocking possible. The possible values are:

On: buffer request bodies
Off: do not buffer request bodies

SecRequestBodyInMemoryLimit

Description: Configures the maximum request body size that Coraza will store in memory.

Default: 131072 (128 KB)

Version Compatibility: v1.0+

Tinygo Compatibility: Partial, file writing is not available on all platforms.

Syntax: SecRequestBodyInMemoryLimit LIMIT_IN_BYTES

When a multipart/form-data request is being processed, once the in-memory limit is reached, the request body will start to be streamed into a temporary file on disk.

👉

If a tinygo implementation is not capable of writing files, this feature will be disabled.

SecRequestBodyLimit

Description: Configures the maximum request body size Coraza will accept for buffering.

Default: 134217728 (131072 KB)

Version Compatibility: v1.0+

Tinygo Compatibility: true

Syntax: SecRequestBodyLimit 134217728

Anything over the limit will be rejected with status code 413 (Request Entity Too Large). There is a hard limit of 1 GB.

SecRequestBodyNoFilesLimit

Description: Configures the maximum request body size Coraza will accept for buffering, excluding the size of any files being transported in the request. This directive is useful to reduce susceptibility to DoS attacks when someone is sending request bodies of very large sizes. Web applications that require file uploads must configure SecRequestBodyLimit to a high value, but because large files are streamed to disk, file uploads will not increase memory consumption. However, it’s still possible for someone to take advantage of a large request body limit and send non-upload requests with large body sizes. This directive eliminates that loophole.

Default: 1048576 (1 MB)

Tinygo Compatibility: true

Syntax: SecRequestBodyNoFilesLimit 131072

👉

This feature has not been implemented yet, but it might be implemented soon.

Generally speaking, the default value is not small enough. For most applications, you should be able to reduce it down to 128 KB or lower. Anything over the limit will be rejected with status code 413 (Request Entity Too Large). There is a hard limit of 1 GB.

Edit this page on