GUI editor to tame mod_security rules

⌈⌋ branch:  modseccfg


Artifact [41ab489893]

Artifact 41ab489893597222437f23da727fc009574d8fa7538b0183178b7145bf04033e:

  • File dev/directives.md — part of check-in [01df5b822a] at 2020-11-19 15:44:57 on branch trunk — Reshuffle directive categories, add 0640 in place of "octal_mode" (user: mario size: 86475)

== 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.

'''Syntax:''' SecAction "action1,action2,action3,...“

'''Scope:''' Any

'''Version:''' 2.0.0

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.

'''Syntax:''' SecArgumentSeparator character

'''Default:''' &

'''Scope:''' Main(< 2.7.0), Any(2.7.0)

'''Version:''' 2.0.0

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 ModSecurity 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.

'''Syntax:''' SecAuditEngine RelevantOnly

'''Default:''' Off

'''Scope:''' Any

'''Version:''' 2.0.0

The SecAuditEngine directive is used to configure the audit engine, which logs complete transactions. ModSecurity 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 ModSecurity 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))

== SecAuditLog == '''Description:''' Defines the path to the main audit log file (serial logging format) or the concurrent logging index file (concurrent logging format).

'''Syntax:''' SecAuditLog /path/to/audit.log

'''Scope:''' Any Version: 2.0.0

This file will be used to store the audit log entries if serial audit logging format is used. If concurrent audit logging format is used this file will be used as an index, and contain a record of all audit log files created. If you are planning to use concurrent audit logging to send your audit log data off to a remote server you will need to deploy the ModSecurity Log Collector (mlogc), like this: When used in combination with mlogc (only possible with concurrent logging), this directive defines the mlogc location and command line. SecAuditLog "|/path/to/mlogc /path/to/mlogc.conf" 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.

== SecAuditLog2 == '''Description:''' Defines the path to the secondary audit log index file when concurrent logging is enabled. See SecAuditLog for more details.

'''Syntax:''' SecAuditLog2 /path/to/audit.log

'''Scope:''' Any

'''Version:''' 2.1.2

The purpose of SecAuditLog2 is to make logging to two remote servers possible, which is typically achieved by running two instances of the mlogc tool, each with a different configuration (in addition, one of the instances will need to be instructed not to delete the files it submits). This directive can be used only if SecAuditLog was previously configured and only if concurrent logging format is used.

== SecAuditLogDirMode== '''Description:''' Configures the mode (permissions) of any directories created for the concurrent audit logs, using an octal mode value as parameter (as used in chmod).

'''Syntax:''' SecAuditLogDirMode 0640 "default"

'''Default:''' 0600

'''Scope:''' Any

'''Version:''' 2.5.10

The default mode for new audit log directories (0600) only grants read/write access to the owner (typically the account under which Apache is running, for example apache). If access from other accounts is needed (e.g., for use with mpm-itk), then you may use this directive to grant additional read and/or write privileges. You should use this directive with caution to avoid exposing potentially sensitive data to unauthorized users. Using the value default as parameter reverts the configuration back to the default setting. This feature is not available on operating systems not supporting octal file modes.

Example:

SecAuditLogDirMode 02750
; Note : The process umask may still limit the mode if it is being more restrictive than the mode set using this directive.

== SecAuditLogFormat == '''Description:''' Select the output format of the AuditLogs. The format can be either the native AuditLogs format or JSON.

'''Syntax:''' SecAuditLogFormat JSON Native

'''Default:''' Native

'''Scope:''' Any

'''Version:''' 2.9.1

; Note : The JSON format is only available if ModSecurity was compiled with support to JSON via the YAJL library. During the compilation time, the yajl-dev package (or similar) must be part of the system. The configure scripts provides information if the YAJL support was enabled or not.

== SecAuditLogFileMode == '''Description:''' Configures the mode (permissions) of any files created for concurrent audit logs using an octal mode (as used in chmod). See SecAuditLogDirMode for controlling the mode of created audit log directories.

'''Syntax:''' SecAuditLogFileMode 0640 "default"

'''Default:''' 0600

'''Scope:''' Any

'''Version:''' 2.5.10

'''Example Usage:''' SecAuditLogFileMode 00640

This feature is not available on operating systems not supporting octal file modes. The default mode (0600) only grants read/write access to the account writing the file. If access from another account is needed (using mpm-itk is a good example), then this directive may be required. However, use this directive with caution to avoid exposing potentially sensitive data to unauthorized users. Using the value “default” will revert back to the default setting.

; Note : The process umask may still limit the mode if it is being more restrictive than the mode set using this directive.

== SecAuditLogParts == '''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.

'''Syntax:''' SecAuditLogParts PARTLETTERS

'''Example Usage:''' SecAuditLogParts ABCFHZ

'''Scope:''' Any Version: 2.0.0

'''Default:''' ABCFHZ Note

The format of the audit log format is documented in detail in the Audit Log Data Format Documentation. Available audit log parts: A: Audit log header (mandatory). B: Request headers. C: Request body (present only if the request body exists and ModSecurity 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 ModSecurity 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 ModSecurity intercepts the intermediary response body, in which case the actual response body will contain the error message (either the Apache default error message, or the 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. Supported as of v2.5.0. Z: Final boundary, signifies the end of the entry (mandatory).

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

'''Syntax:''' SecAuditLogRelevantStatus REGEX

'''Example Usage:''' SecAuditLogRelevantStatus "^(?:5 4(?!04))"

'''Scope:''' Any

'''Version:''' 2.0.0

'''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.

== SecAuditLogStorageDir == '''Description:''' Configures the directory where concurrent audit log entries are to be stored.

'''Syntax''': SecAuditLogStorageDir /path/to/storage/dir

'''Example Usage:''' SecAuditLogStorageDir /usr/local/apache/logs/audit

'''Scope:''' Any

'''Version:''' 2.0.0

This directive is only needed when concurrent audit logging is used. The directory must already exist and must be writable by the web server user. Audit log entries are created at runtime, after Apache switches to a non-root account. As with all logging mechanisms, ensure that you specify a file system location that has adequate disk space and is not on the main system partition.

== SecAuditLogType == '''Description:''' Configures the type of audit logging mechanism to be used.

'''Syntax:''' SecAuditLogType Serial Concurrent HTTPS

'''Example Usage:''' SecAuditLogType Serial

'''Scope:''' Any

'''Version:''' 2.0.0

The possible values are: ; Serial : Audit log entries will be stored in a single file, specified by SecAuditLog. This is conve- nient for casual use, but it can slow down the server, because only one audit log entry can be written to the file at any one time. ; Concurrent : One file per transaction is used for audit logging. This approach is more scalable when heavy logging is required (multiple transactions can be recorded in parallel). It is also the only choice if you need to use remote logging.

; HTTPS : This functionality is only available on libModSecurity and its currently in testing phase. Depending on the amount of request that you have, it may be suitable. Use the URL of your endpoint instead of the path to a file.

; Note : HTTPS audit log type is currently only supported on libModSecurity.

== SecCacheTransformations == '''Description:''' Controls the caching of transformations, which may speed up the processing of complex rule sets. Caching is off by default starting with 2.5.6, when it was deprecated and downgraded back to experimental.

'''Syntax:''' SecCacheTransformations On Off [options]

'''Example Usage:''' SecCacheTransformations On "minlen:64,maxlen:0"

'''Scope:''' Any

'''Version:''' 2.5.0; deprecated in 2.5.6.

'''Supported on libModSecurity:''' No (Deprecated)

The first directive parameter can be one of the following: *'''On''': Cache transformations (per transaction, per phase) allowing identical transforma- tions to be performed only once. *'''Off''': Do not cache any transformations, leaving all transformations to be performed every time they are needed.

The following options are allowed (multiple options must be comma-separated): *'''incremental:on|off''': Enabling this option will cache every transformation instead of just the final transformation. The default is off. *'''maxitems:N''': Do not allow more than N transformations to be cached. Cache will be disabled once this number is reached. A zero value is interpreted as unlimited. This option may be useful to limit caching for a form with a large number of variables. The default value is 512. *'''minlen:N''': Do not cache the transformation if the variable’s length is less than N bytes. The default setting is 32. *'''maxlen:N''': Do not cache the transformation if the variable’s length is more than N bytes. A zero value is interpreted as unlimited. The default setting is 1024.

== SecChrootDir == '''Description:''' Configures the directory path that will be used to jail the web server process.

'''Syntax:''' SecChrootDir /path/to/chroot/dir

'''Example Usage:''' SecChrootDir /chroot

'''Scope:''' Main

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' TBI

This feature is not available on Windows builds. The internal chroot functionality provided by ModSecurity works great for simple setups. One example of a simple setup is Apache serving only static files, or running applications using built-in modules. Some problems you might encounter with more complex setups:

#DNS lookups do not work (this is because this feature requires a shared library that is loaded on demand, after chroot takes place).

#You cannot send email from PHP, because it wants to use sendmail and sendmail re- sides outside the jail.

#In some cases, when you separate Apache from its configuration, restarts and graceful reloads no longer work.

The best way to use SecChrootDir is the following:

#Create /chroot to be your main jail directory.

#Create /chroot/opt/apache inside jail.

#Create a symlink from /opt/apache to /chroot/opt/apache.

#Now install Apache into /chroot/opt/apache.

You should be aware that the internal chroot feature might not be 100% reliable. Due to the large number of default and third-party modules available for the Apache web server, it is not possible to verify the internal chroot works reliably with all of them. A module, working from within Apache, can do things that make it easy to break out of the jail. In particular, if you are using any of the modules that fork in the module initialisation phase (e.g., mod_fastcgi, mod_fcgid, mod_cgid), you are advised to examine each Apache process and observe its current working directory, process root, and the list of open files. Consider what your options are and make your own decision.

; Note : This directive is not allowed inside VirtualHosts. If enabled, it must be placed in a global server-wide configuration file such as your default modsecurity.conf.

== SecCollectionTimeout == '''Description:''' Specifies the collections timeout. Default is 3600 seconds.

'''Syntax:''' SecCollectionTimeout seconds

'''Default:''' 3600

'''Scope:''' Any

'''Version:''' 2.6.3-2.9.x

'''Supported on libModSecurity:''' No

== SecComponentSignature == '''Description:''' Appends component signature to the ModSecurity signature.

'''Syntax:''' SecComponentSignature "COMPONENT_NAME/X.Y.Z (COMMENT)"

'''Example usage''': SecComponentSignature "core ruleset/2.1.3"

'''Scope:''' Main

'''Version:''' 2.5.0-3.x

'''Supported on libModSecurity:''' Yes

This directive should be used to make the presence of significant rule sets known. The entire signature will be recorded in the transaction audit log.

== SecConnEngine == '''Description:''' Configures the connections engine. This directive affect the directives: SecConnReadStateLimit and SecConnWriteStateLimit.

'''Syntax:''' SecConnEngine On Off DetectionOnly

'''Example Usage:''' SecConnEngine On

'''Scope:''' Any

'''Version:''' 2.8.0-2.9.x

'''Supported on libModSecurity:''' TBI

Possible values are (Same as SecRuleEngine): *'''On''': process SecConn[Read|Write]StateLimit. *'''Off''': Ignore the directives SecConn[Read|Write]StateLimit *'''DetectionOnly''': process SecConn[Read|Write]StateLimit definitions in verbose mode but never executes any disruptive actions

== SecContentInjection == '''Description:''' Enables content injection using actions append and prepend.

'''Syntax:''' SecContentInjection On Off

'''Example Usage:''' SecContentInjection On

'''Scope:''' Any

'''Version:''' 2.5.0-2.9.x

'''Supported on libModSecurity:''' TBI

This directive provides an easy way to control content injection, no matter what the rules want to do. It is not necessary to have response body buffering enabled in order to use content injection.

; Note : This directive must ben enabled if you want to use @rsub + the STREAM_ variables to manipulate live transactional data.

== SecCookieFormat == '''Description:''' Selects the cookie format that will be used in the current configuration context.

'''Syntax:''' SecCookieFormat 0 1

'''Example Usage:''' SecCookieFormat 0

'''Scope:''' Any

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' TBD

The possible values are: *'''0''': Use version 0 (Netscape) cookies. This is what most applications use. It is the default value. *'''1''': Use version 1 cookies.

; Note : Only version 0 (Netscape) cookies is currently supported on libModSecurity (v3)

== SecCookieV0Separator == '''Description:''' Specifies which character to use as the separator for cookie v0 content.

'''Syntax:''' SecCookieV0Separator character

'''Scope:''' Any

'''Version:''' 2.7.0-2.9.x

'''Supported on libModSecurity:''' TBI

== SecDataDir == '''Description:''' Path where persistent data (e.g., IP address data, session data, and so on) is to be stored.

'''Syntax:''' SecDataDir /path/to/dir

'''Example Usage:''' SecDataDir /usr/local/apache/logs/data

'''Scope:''' Main

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' No

This directive must be provided before initcol, setsid, and setuid can be used. The directory to which the directive points must be writable by the web server user.

; Note : This directive is not allowed inside VirtualHosts. If enabled, it must be placed in a global server-wide configuration file such as your default modsecurity.conf.

; Note : SecDataDir is not currently supported. Collections are kept in memory (in_memory-per_process) for now.

== SecDebugLog == '''Description''': Path to the ModSecurity debug log file.

'''Syntax:''' SecDebugLog /path/to/modsec-debug.log

'''Example Usage:''' SecDebugLog /usr/local/apache/logs/modsec-debug.log

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

== SecDebugLogLevel == '''Description:''' Configures the verboseness of the debug log data.

'''Syntax''': SecDebugLogLevel 0 1 2 3 4 5 6 7 8 9

'''Example Usage:''' SecDebugLogLevel 4

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

Messages at levels 1–3 are always copied to the Apache error log. Therefore you can always use level 0 as the default logging level in production if you are very concerned with performance. Having said that, the best value to use is 3. Higher logging levels are not recommended in production, because the heavy logging affects performance adversely.

The possible values for the debug log level are: *0: no logging *1: errors (intercepted requests) only *2: warnings *3: notices *4: details of how transactions are handled *5: as above, but including information about each piece of information handled *9: log everything, including very detailed debugging information

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

'''Syntax:''' SecDefaultAction "action1,action2,action3“

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

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

'''Default:''' phase:2,log,auditlog,pass

Every rule following a previous SecDefaultAction directive in the same configuration context will inherit its settings unless more specific actions are used. Every SecDefaultAction directive must specify a disruptive action and a processing phase and cannot contain metadata actions.

; Warning : SecDefaultAction is not inherited across configuration contexts. (For an example of why this may be a problem, read the following ModSecurity Blog entry http://blog.spiderlabs.com/2008/07/three-modsecurity-rule-language-annoyances.html .)

== SecDisableBackendCompression == '''Description:''' Disables backend compression while leaving the frontend compression enabled.

'''Syntax:''' SecDisableBackendCompression On Off

'''Scope:''' Any

'''Version:''' 2.6.0-2.9.x

'''Supported on libModSecurity:''' TBI

'''Default:''' Off

This directive is necessary in reverse proxy mode when the backend servers support response compression, but you wish to inspect response bodies. Unless you disable backend compression, ModSecurity will only see compressed content, which is not very useful. This directive is not necessary in embedded mode, because ModSecurity performs inspection before response compression takes place.

== SecHashEngine == '''Description:''' Configures the hash engine.

'''Syntax:''' SecHashEngine On Off

'''Example Usage:''' SecHashEngine On

'''Scope''': Any

'''Version:''' 2.7.1-2.9.x

'''Supported on libModSecurity:''' TBI

'''Default:''' Off

The possible values are: *'''On''': Hash engine can process the request/response data. *'''Off''': Hash engine will not process any data.

; Note : Users must enable stream output variables and content injection.

== SecHashKey == '''Description:''' Define the key that will be used by HMAC.

'''Syntax:''' SecHashKey rand TEXT KeyOnly SessionID RemoteIP

'''Example Usage:''' SecHashKey "this_is_my_key" KeyOnly

'''Scope''': Any

'''Version:''' 2.7.1-2.9.x

'''Supported on libModSecurity:''' TBI

ModSecurity hash engine will append, if specified, the user's session id or remote ip to the key before the MAC operation. If the first parameter is "rand" then a random key will be generated and used by the engine.

== SecHashParam == '''Description:''' Define the parameter name that will receive the MAC hash.

'''Syntax:''' SecHashParam TEXT

'''Example Usage:''' SecHashParam "hmac"

'''Scope''': Any

'''Version:''' 2.7.1-2.9.x

'''Supported on libModSecurity:''' TBI

ModSecurity hash engine will add a new parameter to protected HTML elements containing the MAC hash.

== SecHashMethodRx == '''Description:''' Configures what kind of HTML data the hash engine should sign based on regular expression.

'''Syntax:''' SecHashMethodRx TYPE REGEX

'''Example Usage''': SecHashMethodRx HashHref "product_info list_product"

'''Scope:''' Any

'''Version:''' 2.7.1-2.9.x

'''Supported on libModSecurity:''' TBI

As a initial support is possible to protect HREF, FRAME, IFRAME and FORM ACTION html elements as well response Location header when http redirect code are sent.

The possible values for TYPE are: *'''HashHref''': Used to sign href= html elements *'''HashFormAction''': Used to sign form action= html elements *'''HashIframeSrc''': Used to sign iframe src= html elements *'''HashframeSrc''': Used to sign frame src= html elements *'''HashLocation''': Used to sign Location response header

; Note : This directive is used to sign the elements however user must use the @validateHash operator to enforce data integrity.

== SecHashMethodPm == '''Description:''' Configures what kind of HTML data the hash engine should sign based on string search algoritm.

'''Syntax:''' SecHashMethodPm TYPE "string1 string2 string3..."

'''Example Usage''': SecHashMethodPm HashHref "product_info list_product"

'''Scope:''' Any

'''Version:''' 2.7.1-2.9.x

'''Supported on libModSecurity:''' TBI

As a initial support is possible to protect HREF, FRAME, IFRAME and FORM ACTION html elements as well response Location header when http redirect code are sent.

The possible values for TYPE are: *'''HashHref''': Used to sign href= html elements *'''HashFormAction''': Used to sign form action= html elements *'''HashIframeSrc''': Used to sign iframe src= html elements *'''HashframeSrc''': Used to sign frame src= html elements *'''HashLocation''': Used to sign Location response header

; Note : This directive is used to sign the elements however user must use the @validateHash operator to enforce data integrity.

== SecGeoLookupDb == '''Description''': Defines the path to the database that will be used for geolocation lookups.

'''Syntax:''' SecGeoLookupDb /path/to/db

'''Example Usage''': SecGeoLookupDb /path/to/GeoLiteCity.dat

'''Scope:''' Any

'''Version:''' 2.5.0

'''Supported on libModSecurity:''' Yes

ModSecurity relies on the free geolocation databases (GeoLite City and GeoLite Country) that can be obtained from MaxMind [http://www.maxmind.com]. Currently ModSecurity only supports the legacy GeoIP format. Maxmind's newer GeoIP2 format is not yet currently supported.

== SecGsbLookupDb == '''Description''': Defines the path to the database that will be used for Google Safe Browsing (GSB) lookups.

'''Syntax:''' SecGsbLookupDb /path/to/db

'''Example Usage''': SecGsbLookupDb /path/to/GsbMalware.dat

'''Scope:''' Any

'''Version:''' 2.6.0

'''Supported on libModSecurity:''' TBD

ModSecurity relies on the free Google Safe Browsing database that can be obtained from the Google GSB API [http://code.google.com/apis/safebrowsing/].

; Note : Deprecated in 2.7.0 after Google dev team decided to not allow the database download anymore. After registering and obtaining a Safe Browsing API key, you can automatically download the GSB using a tool like wget. For further information on how to proceed with the download, please visit Google's website: https://developers.google.com/safe-browsing/v3/update-guide

== SecGuardianLog == '''Description:''' Configures an external program that will receive the information about every transaction via piped logging.

'''Syntax:''' SecGuardianLog /path/to/httpd-guardian
'''Example Usage:''' SecGuardianLog /usr/local/apache/bin/httpd-guardian

'''Scope:''' Main

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' TBI

Guardian logging is designed to send the information about every request to an external program. Because Apache is typically deployed in a multiprocess fashion, which makes information sharing between processes difficult, the idea is to deploy a single external process to observe all requests in a stateful manner, providing additional protection.

Currently the only tool known to work with guardian logging is httpd-guardian, which is part of the Apache httpd tools project [http://apache-tools.cvs.sourceforge.net/viewvc/apache-tools/apache-tools/]. The httpd-guardian tool is designed to defend against denial of service attacks. It uses the blacklist tool (from the same project) to interact with an iptables-based (on a Linux system) or pf-based (on a BSD system) firewall, dynamically blacklisting the offending IP addresses. It can also interact with SnortSam [http://www.snortsam.net]. Assuming httpd-guardian is already configured (look into the source code for the detailed instructions), you only need to add one line to your Apache configuration to deploy it:

SecGuardianLog |/path/to/httpd-guardian

; Note : This directive is not allowed inside VirtualHosts. If enabled, it must be placed in a global server-wide configuration file such as your default modsecurity.conf.

== SecHttpBlKey == '''Description:''' Configures the user's registered Honeypot Project HTTP BL API Key to use with @rbl.

'''Syntax:''' SecHttpBlKey [12 char access key]

'''Example Usage:''' SecHttpBlKey whdkfieyhtnf

'''Scope:''' Main

'''Version:''' 2.7.0

'''Supported on libModSecurity:''' Yes

If the @rbl operator uses the dnsbl.httpbl.org RBL (http://www.projecthoneypot.org/httpbl_api.php) you must provide an API key. This key is registered to individual users and is included within the RBL DNS requests.

== SecInterceptOnError == '''Description:''' Configures how to respond when rule processing fails.

'''Syntax:''' SecInterceptOnError On Off

'''Example Usage:''' SecInterceptOnError On

'''Scope:''' Main

'''Version:''' 2.6-2.9.x

'''Supported on libModSecurity:''' TBI

When an operator execution fails, that is it returns greater than 0, this directive configures how to react. When set to "Off", the rule is just ignored and the engine will continue executing the rules in phase. When set to "On", the rule will be just dropped and no more rules will be executed in the same phase, also no interception is made.

== 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.

'''Syntax:''' SecMarker ID TEXT

'''Example Usage''': SecMarker 9999

'''Scope:''' Any

'''Version:''' 2.5.0-3.x

'''Supported on libModSecurity:''' Yes

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" \
            "skipAfter:END_HOST_CHECK,phase:2,rev:'2.1.1',t:none,block,msg:'Request Missing a Host Header',id:'960008',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 "^$" \
            "phase:2,rev:'2.1.1',t:none,block,msg:'Request Missing a Host Header',id:'960008',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

== SecPcreMatchLimit == '''Description''': Sets the match limit in the PCRE library.

'''Syntax:''' SecPcreMatchLimit value

'''Example Usage''': SecPcreMatchLimit 1500

'''Scope:''' Main

'''Version''': 2.5.12-2.9.x

'''Supported on libModSecurity:''' TBI

'''Default:''' 1500

The default can be changed when ModSecurity is prepared for compilation: the --enable-pcre-match-limit=val configure option will set a custom default and the --disable-pcre-match-limit option will revert back to the default of the PCRE library. For more information, refer to the pcre_extra field in the pcreapi man page.

; Note : This directive is not allowed inside VirtualHosts. If enabled, it must be placed in a global server-wide configuration file such as your default modsecurity.conf.

== SecPcreMatchLimitRecursion == '''Description:''' Sets the match limit recursion in the PCRE library.

'''Syntax:''' SecPcreMatchLimitRecursion value

'''Example Usage:''' SecPcreMatchLimitRecursion 1500

'''Scope:''' Main

'''Version:''' 2.5.12-2.9.x

'''Supported on libModSecurity:''' TBI

'''Default:''' 1500

The default can be changed when ModSecurity is prepared for compilation: the --enable-pcre-match-limit-recursion=val configure option will set a custom default and the --disable-pcre-match-limit-recursion option will revert back to the default of the PCRE library. For more information, refer to the pcre_extra field in the pcreapi man page.

; Note : This directive is not allowed inside VirtualHosts. If enabled, it must be placed in a global server-wide configuration file such as your default modsecurity.conf.

== SecPdfProtect == '''Description:''' Enables the PDF XSS protection functionality.

'''Syntax:''' SecPdfProtect On Off

'''Example Usage:''' SecPdfProtect On

'''Scope:''' Any

'''Version:''' 2.5.0; removed from trunk

'''Supported on libModSecurity:''' No (Deprecated)

Once enabled access to PDF files is tracked. Direct access attempts are redirected to links that contain one-time tokens. Requests with valid tokens are allowed through, unmodified. Requests with invalid tokens are also allowed through, but with forced download of the PDF files. This implementation uses response headers to detect PDF files and thus can be used with dynamically generated PDF files that do not have the .pdf extension in the request URI.

== SecPdfProtectMethod == '''Description''': Configure desired protection method to be used when requests for PDF files are detected.

'''Syntax:''' SecPdfProtectMethod method

'''Example Usage''': SecPdfProtectMethod TokenRedirection

'''Scope''': Any

'''Version:''' 2.5.0; removed from trunk

'''Supported on libModSecurity:''' No (Deprecated)

'''Default:''' TokenRedirection

Possible values are TokenRedirection and ForcedDownload. The token redirection approach will attempt to redirect with tokens where possible. This allows PDF files to continue to be opened inline but works only for GET requests. Forced download always causes PDF files to be delivered as opaque binaries and attachments. The latter will always be used for non-GET requests. Forced download is considered to be more secure but may cause usability problems for users (“This PDF won’t open anymore!”).

== SecPdfProtectSecret == '''Description:''' Defines the secret that will be used to construct one-time tokens.

'''Syntax:''' SecPdfProtectSecret secret

'''Example Usage:''' SecPdfProtectSecret MyRandomSecretString

'''Scope:''' Any

'''Version:''' 2.5.0; removed from trunk

'''Supported on libModSecurity:''' No (Deprecated)

You should use a reasonably long value for the secret (e.g., 16 characters is good). Once selected, the secret should not be changed, as it will break the tokens that were sent prior to change. But it’s not a big deal even if you change it. It will just force download of PDF files with tokens that were issued in the last few seconds.

== SecPdfProtectTimeout == '''Description''': Defines the token timeout.

'''Syntax:''' SecPdfProtectTimeout timeout

'''Example Usage''': SecPdfProtectTimeout 10

'''Scope:''' Any

'''Version:''' 2.5.0; removed from trunk

'''Supported on libModSecurity:''' No (Deprecated)

'''Default:''' 10

After token expires, it can no longer be used to allow access to a PDF file. Request will be allowed through but the PDF will be delivered as an attachment.

== SecPdfProtectTokenName == '''Description''': Defines the name of the token.

'''Syntax''': SecPdfProtectTokenName name

'''Example Usage''': SecPdfProtectTokenName PDFTOKEN

'''Scope''': Any

'''Version''': 2.5.0; removed from trunk

'''Supported on libModSecurity:''' No (Deprecated)

'''Default:''' PDFTOKEN

The only reason you would want to change the name of the token is if you wanted to hide the fact that you are running ModSecurity. It’s a good reason, but it won’t really help, as the adversary can look into the algorithm used for PDF protection and figure it out anyway. It does raise the bar slightly, so go ahead if you want to.

== SecReadStateLimit == '''Description:''' Establishes a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_READ state.

'''Syntax:''' SecReadStateLimit LIMIT

'''Example Usage''': SecReadStateLimit 50

'''Scope''': Main

'''Version''': 2.5.13, DEPRECATED as of v2.8.0.

'''Supported on libModSecurity:''' No (Deprecated)

'''Default:''' 0 (no limit)

For v2.8.0 or newest refer to SecConnReadStateLimit.

== SecConnReadStateLimit == '''Description:''' Establishes a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_READ state.

'''Syntax:''' SecConnReadStateLimit LIMIT OPTIONAL_IP_MATCH_OPERATOR

'''Example Usage''': SecConnReadStateLimit 50 "!@ipMatch 127.0.0.1"

'''Scope''': Main

'''Version''': v2.8.0-2.9.x (Apache only)

'''Supported on libModSecurity:''' TBI

'''Default:''' 0 (no limit)

This measure is effective against Slowloris-style attacks from a single IP address, but it may not be as good against modified attacks that work by slowly sending request body content. This is because Apache to switches state to SERVER_BUSY_WRITE once request headers have been read. As an alternative, consider mod_reqtimeout (part of Apache as of 2.2.15), which is expected be effective against both attack types. See Blog post on mitigating slow DoS attacks - http://blog.spiderlabs.com/2010/11/advanced-topic-of-the-week-mitigating-slow-http-dos-attacks.html. v2.8.0 and newest supports the @ipMatch, @ipMatchF and @ipMatchFromFile operator along with the its negative (e.g. !@ipMatch) these were used to create suspicious or whitelist. When a suspicious list is informed, just the IPs that belongs to the list will be filtered. A combination of suspicious and whitelist is possible by using multiple definitions of SecConnReadStateLimit, note, however, that the limit will be always overwrite by its successor.

'''Note:''' This functionality is Apache only.

'''Note 2:''' Make sure [[Reference-Manual#secconnengine]] is on prior to use this feature.

== SecSensorId == '''Description:''' Define a sensor ID that will be present into log part H.

'''Syntax:''' SecSensorId TEXT

'''Example Usage''': SecSensorId WAFSensor01

'''Scope''': Main

'''Version''': 2.7.0-2.9.x

'''Supported on libModSecurity:''' TBI

== SecWriteStateLimit == '''Description:''' Establishes a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_WRITE state.

'''Syntax:''' SecWriteStateLimit LIMIT

'''Example Usage''': SecWriteStateLimit 50

'''Scope''': Main

'''Version''': 2.6.0, DEPRECATED as of v2.8.0.

'''Supported on libModSecurity:''' No (Deprecated)

'''Default:''' 0 (no limit)

For v2.8.0 or newest refer to SecConnWriteStateLimit.

== SecConnWriteStateLimit == '''Description:''' Establishes a per-IP address limit of how many connections are allowed to be in SERVER_BUSY_WRITE state.

'''Syntax:''' SecConnWriteStateLimit LIMIT OPTIONAL_IP_MATCH_OPERATOR

'''Example Usage''': SecConnWriteStateLimit 50 "!@ipMatch 127.0.0.1"

'''Scope''': Main

'''Version''': 2.6.0-2.9.x (Apache only)

'''Supported on libModSecurity:''' TBI

'''Default:''' 0 (no limit)

This measure is effective against Slow DoS request body attacks. v2.8.0 and newest supports the @ipMatch, @ipMatchF and @ipMatchFromFile operator along with the its negative (e.g. !@ipMatch) these were used to create suspicious or whitelist. When a suspicious list is informed, just the IPs that belongs to the list will be filtered. A combination of suspicious and whitelist is possible by using multiple definitions of SecConnReadStateLimit, note, however, that the limit will be always overwrite by its successor.

'''Note:''' This functionality is Apache only.

'''Note 2:''' Make sure [[Reference-Manual#secconnengine]] is on prior to use this feature.

== SecRemoteRules == '''Description''': Load rules from a given file hosted on a HTTPS site.

'''Syntax:''' SecRemoteRules [crypto] key https://url

'''Example Usage''': SecRemoteRules some-key https://www.yourserver.com/plain-text-rules.txt

'''Scope:''' Any

'''Version:''' 2.9.0-RC1+

'''Supported on libModSecurity:''' Yes

This is an optional directive that allow the user to load rules from a remote server. Notice that besides the URL the user also needs to supply a key, which could be used by the target server to provide different content for different keys.

Along with the key, supplied by the users, ModSecurity will also send its Unique ID and the `status call' in the format of headers to the target web server. The following headers are used: - ModSec-status - ModSec-unique-id - ModSec-key

The optional option "crypto" tells ModSecurity to expect some encrypted content from server. The utilization of SecRemoteRules is only allowed over TLS, thus, this option may not be necessary.

; Note : A valid and trusted digital certificate is expected on the end server. It is also expected that the server uses TLS, preferable TLS 1.2.

== SecRemoteRulesFailAction == '''Description''': Action that will be taken if SecRemoteRules specify an URL that ModSecurity was not able to download.

'''Syntax:''' SecRemoteRulesFailAction Abort Warn

'''Example Usage''': SecRemoteRulesFailAction Abort

'''Scope:''' Any

'''Version:''' 2.9.0-RC1+

'''Supported on libModSecurity:''' Yes

The default action is to Abort whenever there is a problem downloading a given URL.

; Note : This directive also influences the behaviour of @ipMatchFromFile when used with a HTTPS URI to retrieve the remote file.

== SecRequestBodyAccess == '''Description''': Configures whether request bodies will be buffered and processed by ModSecurity.

'''Syntax:''' SecRequestBodyAccess On Off

'''Example Usage''': SecRequestBodyAccess On

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

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 ModSecurity will store in memory.

'''Syntax:''' SecRequestBodyInMemoryLimit LIMIT_IN_BYTES

'''Example Usage:''' SecRequestBodyInMemoryLimit 131072

'''Scope:''' Any

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' No

'''Default:''' 131072 (128 KB)

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.

; Note : libModSecurity is able to deal with request body in a file or in a buffer (chunked or not). Web servers have properties which controls whenever a request should be saved to a file or used as a buffer (e.g. client_body_buffer_size [https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size]) . If it is a file, ModSecurity will use the file to perform the inspection. If not, the buffer will be used.

== SecRequestBodyLimit == '''Description:''' Configures the maximum request body size ModSecurity will accept for buffering.

'''Syntax:''' SecRequestBodyLimit LIMIT_IN_BYTES

'''Example Usage:''' SecRequestBodyLimit 134217728

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

'''Default:''' 134217728 (131072 KB)

Anything over the limit will be rejected with status code 413 (Request Entity Too Large). There is a hard limit of 1 GB. ; Note : In ModSecurity 2.5.x and earlier, SecRequestBodyLimit works only when used in the main server configuration, or a VirtualHost container. In these versions, request body limit is enforced immediately after phase 1, but before phase 2 configuration (i.e. whatever is placed in a Location container) is resolved. You can work around this limitation by using a phase 1 rule that changes the request body limit dynamically, using the ctl:requestBodyLimit action. ModSecurity 2.6.x (currently in the trunk only) and better do not have this limitation.

== SecRequestBodyNoFilesLimit == '''Description''': Configures the maximum request body size ModSecurity will accept for buffering, excluding the size of any files being transported in the request.

'''Syntax:''' SecRequestBodyNoFilesLimit NUMBER_IN_BYTES

'''Example Usage:''' SecRequestBodyNoFilesLimit 131072

'''Scope:''' Any

'''Version''': 2.5.0

'''Supported on libModSecurity:''' No

'''Default:''' 1048576 (1 MB)

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. 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.

== SecRequestBodyLimitAction == '''Description''': Controls what happens once a request body limit, configured with SecRequestBodyLimit, is encountered

'''Syntax:''' SecRequestBodyLimitAction Reject ProcessPartial

'''Example Usage:''' SecRequestBodyLimitAction ProcessPartial

'''Scope:''' Any

'''Version''': 2.6.0

'''Supported on libModSecurity:''' Yes

By default, ModSecurity will reject a request body that is longer than specified. This is problematic especially when ModSecurity is being run in DetectionOnly mode and the intent is to be totally passive and not take any disruptive actions against the transaction. With the ability to choose what happens once a limit is reached, site administrators can choose to inspect only the first part of the request, the part that can fit into the desired limit, and let the rest through. This is not ideal from a possible evasion issue perspective, however it may be acceptable under certain circumstances.

; Note : When the SecRuleEngine is set to DetectionOnly, SecRequestBodyLimitAction is automatically set to ProcessPartial in order to not cause any disruptions. If you want to know if/when a request body size is over your limit, you can create a rule to check for the existence of the INBOUND_ERROR_DATA variable.

== SecResponseBodyLimit == '''Description:''' Configures the maximum response body size that will be accepted for buffering.

'''Syntax:''' SecResponseBodyLimit LIMIT_IN_BYTES

'''Example Usage:''' SecResponseBodyLimit 524228

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

'''Default''': 524288 (512 KB)

Anything over this limit will be rejected with status code 500 (Internal Server Error). This setting will not affect the responses with MIME types that are not selected for buffering. There is a hard limit of 1 GB.

== SecResponseBodyLimitAction == '''Description:''' Controls what happens once a response body limit, configured with SecResponseBodyLimit, is encountered.

'''Syntax:''' SecResponseBodyLimitAction Reject ProcessPartial

'''Example Usage:''' SecResponseBodyLimitAction ProcessPartial

'''Scope:''' Any

'''Version:''' 2.5.0

'''Supported on libModSecurity:''' Yes

By default, ModSecurity will reject a response body that is longer than specified. Some web sites, however, will produce very long responses, making it difficult to come up with a reasonable limit. Such sites would have to raise the limit significantly to function properly, defying the purpose of having the limit in the first place (to control memory consumption). With the ability to choose what happens once a limit is reached, site administrators can choose to inspect only the first part of the response, the part that can fit into the desired limit, and let the rest through. Some could argue that allowing parts of responses to go uninspected is a weakness. This is true in theory, but applies only to cases in which the attacker controls the output (e.g., can make it arbitrary long). In such cases, however, it is not possible to prevent leakage anyway. The attacker could compress, obfuscate, or even encrypt data before it is sent back, and therefore bypass any monitoring device.

== SecResponseBodyMimeType == '''Description:''' Configures which MIME types are to be considered for response body buffering.

'''Syntax:''' SecResponseBodyMimeType MIMETYPE MIMETYPE ...

'''Example Usage''': SecResponseBodyMimeType text/plain text/html text/xml

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

'''Default:''' text/plain text/html

Multiple SecResponseBodyMimeType directives can be used to add MIME types. Use SecResponseBodyMimeTypesClear to clear previously configured MIME types and start over.

; Note : Users that wish to perform JSON body inspection on response (phase 4) need to add application/json to SecResponseBodyMimeType.

== SecResponseBodyMimeTypesClear == '''Description:''' Clears the list of MIME types considered for response body buffering, allowing you to start populating the list from scratch.

'''Syntax:''' SecResponseBodyMimeTypesClear

'''Example Usage:''' SecResponseBodyMimeTypesClear

'''Scope:''' Any

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' TBI

== SecResponseBodyAccess == '''Description:''' Configures whether response bodies are to be buffered.

'''Syntax:''' SecResponseBodyAccess On Off

'''Example Usage:''' SecResponseBodyAccess On

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

'''Default:''' Off

This directive is required if you plan to inspect HTML responses and implement response blocking. Possible values are: *On: buffer response bodies (but only if the response MIME type matches the list configured with SecResponseBodyMimeType). *Off: do not buffer response bodies.

== SecRule == '''Description:''' Creates a rule that will analyze the selected variables using the selected operator.

'''Syntax:''' SecRule VARIABLES OPERATOR [ACTIONS]

'''Example Usage:''' SecRule ARGS "@rx attack" "phase:1,log,deny,id:1"

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

Every rule must provide one or more variables along with the operator that should be used to inspect them. If no actions are provided, the default list will be used. (There is always a default list, even if one was not explicitly set with SecDefaultAction.) If there are actions specified in a rule, they will be merged with the default list to form the final actions that will be used. (The actions in the rule will overwrite those in the default list.) Refer to SecDefaultAction for more information.

== SecRuleInheritance == '''Description:''' Configures whether the current context will inherit the rules from the parent context.

'''Syntax:''' SecRuleInheritance On Off

'''Example Usage:''' SecRuleInheritance Off

'''Scope:''' Any

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' TBI

'''Default:''' On

Sometimes when you create a more specific configuration context (for example using the <Location> container), you may wish to use a different set of rules than those used in the parent context. By setting SecRuleInheritance to Off, you prevent the parent rules to be inherited, which allows you to start from scratch. In ModSecurity 2.5.x it is not possible to override phase 1 rules from a <Location> configuration context. There are no limitations in that respect in the current development version (and there won’t be in the next major version).

The possible values are: *On: inherit rules from the parent context *Off: do not inherit rules from the parent context ; Note : Configuration contexts are an Apache concept. Directives <Directory>, <Files>, <Location>, and <VirtualHost> are all used to create configuration contexts. For more information, please go to the Apache documentation, under Configuration Sections [http://httpd.apache.org/docs/2.0/sections.html]. This directive does not affect how configuration options are inherited.

== SecRuleEngine == '''Description:''' Configures the rules engine.

'''Syntax:''' SecRuleEngine On Off DetectionOnly

'''Example Usage:''' SecRuleEngine On

'''Scope''': Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

'''Default:''' Off

The possible values are: *'''On''': process rules *'''Off''': do not process rules *'''DetectionOnly''': process rules but never executes any disruptive actions (block, deny, drop, allow, proxy and redirect)

== SecRulePerfTime == '''Description:''' Set a performance threshold for rules. Rules that spend at least the time defined will be logged into audit log Part H as Rules-Performance-Info in the format id=usec, comma separated.

'''Syntax:''' SecRulePerfTime USECS

'''Example Usage:''' SecRulePerfTime 1000

'''Scope:''' Any

'''Version:''' 2.7-2.9.x

'''Supported on libModSecurity:''' TBI

The rules hitting the threshold can be accessed via the collection PERF_RULES.

== SecRuleRemoveById == '''Description:''' Removes the matching rules from the current configuration context.

'''Syntax:''' SecRuleRemoveById ID ID RANGE ...

'''Example Usage:''' SecRuleRemoveByID 1 2 "9000-9010"

'''Scope:''' Any

'''Version:''' 2.0.0 - 3.x

'''Supported on libModSecurity:''' Yes

This directive supports multiple parameters, each of which can be a rule ID or a range. Parameters that contain spaces must be delimited using double quotes.

; Note : '''This directive must be specified after the rule in which it is disabling'''. This should be used within local custom rule files that are processed after third party rule sets. Example file - modsecurity_crs_60_customrules.conf.

== SecRuleRemoveByMsg == '''Description:''' Removes the matching rules from the current configuration context.

'''Syntax:''' SecRuleRemoveByMsg REGEX

'''Example Usage:''' SecRuleRemoveByMsg "FAIL"

'''Scope:''' Any

'''Version:''' 2.0.0-3.x

'''Supported on libModSecurity:''' Yes

Normally, you would use SecRuleRemoveById to remove rules, but that requires the rules to have IDs defined. If they don’t, then you can remove them with SecRuleRemoveByMsg, which matches a regular expression against rule messages.

; Note : This directive must be specified after the rule in which it is disabling. This should be used within local custom rule files that are processed after third party rule sets. Example file - modsecurity_crs_60_customrules.conf.

== SecRuleRemoveByTag == '''Description:''' Removes the matching rules from the current configuration context.

'''Syntax:''' SecRuleRemoveByTag REGEX

'''Example Usage:''' SecRuleRemoveByTag "WEB_ATTACK/XSS"

'''Scope:''' Any

'''Version:''' 2.6-3.x

'''Supported on libModSecurity:''' Yes

Normally, you would use SecRuleRemoveById to remove rules, but that requires the rules to have IDs defined. If they don’t, then you can remove them with SecRuleRemoveByTag, which matches a regular expression against rule tag data. This is useful if you want to disable entire groups of rules based on tag data. Example tags used in the OWASP ModSecurity CRS include: *AUTOMATION/MALICIOUS *AUTOMATION/MISC *AUTOMATION/SECURITY_SCANNER *LEAKAGE/SOURCE_CODE_ASP_JSP *LEAKAGE/SOURCE_CODE_CF *LEAKAGE/SOURCE_CODE_PHP *WEB_ATTACK/CF_INJECTION *WEB_ATTACK/COMMAND_INJECTION *WEB_ATTACK/FILE_INJECTION *WEB_ATTACK/HTTP_RESPONSE_SPLITTING *WEB_ATTACK/LDAP_INJECTION *WEB_ATTACK/PHP_INJECTION *WEB_ATTACK/REQUEST_SMUGGLING *WEB_ATTACK/SESSION_FIXATION *WEB_ATTACK/SQL_INJECTION *WEB_ATTACK/SSI_INJECTION *WEB_ATTACK/XSS

; Note : This directive must be specified after the rule in which it is disabling. This should be used within local custom rule files that are processed after third party rule sets. Example file - modsecurity_crs_60_customrules.conf.

== SecRuleScript == Description: This directive creates a special rule that executes a Lua script to decide whether to match or not. The main difference from SecRule is that there are no targets nor operators. The script can fetch any variable from the ModSecurity context and use any (Lua) operator to test them. The second optional parameter is the list of actions whose meaning is identical to that of SecRule.

'''Syntax:''' SecRuleScript /path/to/script.lua [ACTIONS]

'''Example Usage:''' SecRuleScript "/path/to/file.lua" "block"

'''Scope:''' Any

'''Version:''' 2.5.0-3.x

'''Supported on libModSecurity:''' Yes

; Note : All Lua scripts are compiled at configuration time and cached in memory. To reload scripts you must reload the entire ModSecurity configuration by restarting Apache.

Example script:

-- Your script must define the main entry
-- point, as below.
function main()
    -- Log something at level 1. Normally you shouldn't be
    -- logging anything, especially not at level 1, but this is
    -- just to show you can. Useful for debugging.
    m.log(1, "Hello world!");

-- Retrieve one variable.
local var1 = m.getvar("REMOTE_ADDR");

-- Retrieve one variable, applying one transformation function.
-- The second parameter is a string.
local var2 = m.getvar("ARGS", "lowercase");

-- Retrieve one variable, applying several transformation functions.
-- The second parameter is now a list. You should note that m.getvar()
-- requires the use of comma to separate collection names from
-- variable names. This is because only one variable is returned.
local var3 = m.getvar("ARGS.p", { "lowercase", "compressWhitespace" } );

-- If you want this rule to match return a string
-- containing the error message. The message must contain the name
-- of the variable where the problem is located.
-- return "Variable ARGS:p looks suspicious!"

-- Otherwise, simply return nil.
return nil;

end

In this first example we were only retrieving one variable at the time. In this case the name of the variable is known to you. In many cases, however, you will want to examine variables whose names you won't know in advance, for example script parameters.

Example showing use of m.getvars() to retrieve many variables at once:

function main()
    -- Retrieve script parameters.
    local d = m.getvars("ARGS", { "lowercase", "htmlEntityDecode" } );

-- Loop through the paramters.
for i = 1, #d do
    -- Examine parameter value.
    if (string.find(d[i].value, "<script")) then
        -- Always specify the name of the variable where the
        -- problem is located in the error message.
        return ("Suspected XSS in variable " .. d[i].name .. ".");
    end
end

-- Nothing wrong found.
return nil;

end

; Note : Go to http://www.lua.org/ to find more about the Lua programming language. The reference manual too is available online, at http://www.lua.org/manual/5.1/.

; Note : Lua support is marked as experimental as the way the programming interface may continue to evolve while we are working for the best implementation style. Any user input into the programming interface is appreciated.

; Note : libModSecurity (aka v3) is compatible with Lua 5.2+.

== SecRuleUpdateActionById == '''Description:''' Updates the action list of the specified rule.

'''Syntax:''' SecRuleUpdateActionById RULEID[:offset] ACTIONLIST

'''Example Usage:''' SecRuleUpdateActionById 12345 "deny,status:403"

'''Scope:''' Any

'''Version:''' 2.6.0-2.9.x

'''Supported on libModSecurity:''' TBI

This directive will overwrite the action list of the specified rule with the actions provided in the second parameter. It has two limitations: it cannot be used to change the ID or phase of a rule. Only the actions that can appear only once are overwritten. The actions that are allowed to appear multiple times in a list, will be appended to the end of the list.

SecRule ARGS attack "phase:2,id:12345,t:lowercase,log,pass,msg:'Message text'"
SecRuleUpdateActionById 12345 "t:none,t:compressWhitespace,deny,status:403,msg:'New message text'"
The effective resulting rule in the previous example will be as follows:
SecRule ARGS attack "phase:2,id:12345,t:lowercase,t:none,t:compressWhitespace,deny,status:403,msg:'New Message text'"
The addition of t:none will neutralize any previous transformation functions specified (t:lowercase, in the example).

; Note : If the target rule is a chained rule, you must currently specify chain in the SecRuleUpdateActionById action list as well. This will be fixed in a future version.

== SecRuleUpdateTargetById == '''Description:''' Updates the target (variable) list of the specified rule.

'''Syntax:''' SecRuleUpdateTargetById RULEID TARGET1[,TARGET2,TARGET3] REPLACED_TARGET

'''Example Usage:''' SecRuleUpdateTargetById 12345 "!ARGS:foo"

'''Scope:''' Any

'''Version:''' 2.6-3.x

'''Supported on libModSecurity:''' Yes

This directive will append (or replace) variables to the current target list of the specified rule with the targets provided in the second parameter. Starting with 2.7.0 this feature supports id range.

'''Explicitly Appending Targets'''

This is useful for implementing exceptions where you want to externally update a target list to exclude inspection of specific variable(s).

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}"

SecRuleUpdateTargetById 958895 !ARGS:email

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:
SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/|!ARGS:email "[;|`]W?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}""

Note that is is also possible to use regular expressions in the target specification:

SecRuleUpdateTargetById 981172 "!REQUEST_COOKIES:/^appl1_.*/"

'''Explicitly Replacing Targets'''

You can also entirely replace the target list to something more appropriate for your environment. For example, lets say you want to inspect REQUEST_URI instead of REQUEST_FILENAME, you could do this:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}"

SecRuleUpdateTargetById 958895 REQUEST_URI REQUEST_FILENAME

The effective resulting rule in the previous example replaces the target in the begin of the variable list as follows:
SecRule REQUEST_URI|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}""

; Note : You could also do the same by using the ctl action with the ruleRemoveById directive. That would be useful if you want to only update the targets for a particular URL, thus conditionally appending targets.

== SecRuleUpdateTargetByMsg == '''Description:''' Updates the target (variable) list of the specified rule by rule message.

'''Syntax:''' SecRuleUpdateTargetByMsg TEXT TARGET1[,TARGET2,TARGET3] REPLACED_TARGET

'''Example Usage:''' SecRuleUpdateTargetByMsg "Cross-site Scripting (XSS) Attack" "!ARGS:foo"

'''Scope:''' Any

'''Version:''' 2.7-3.x

'''Supported on libModSecurity:''' Yes

This directive will append (or replace) variables to the current target list of the specified rule with the targets provided in the second parameter.

'''Explicitly Appending Targets'''

This is useful for implementing exceptions where you want to externally update a target list to exclude inspection of specific variable(s).

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}"

SecRuleUpdateTargetByMsg "System Command Injection" !ARGS:email

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:
SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/|!ARGS:email "[;|`]W?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}""
'''Explicitly Replacing Targets'''

You can also entirely replace the target list to something more appropriate for your environment. For example, lets say you want to inspect REQUEST_URI instead of REQUEST_FILENAME, you could do this:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}"

SecRuleUpdateTargetByMsg "System Command Injection" REQUEST_URI REQUEST_FILENAME

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:
SecRule REQUEST_URI|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}""

== SecRuleUpdateTargetByTag == '''Description:''' Updates the target (variable) list of the specified rule by rule tag.

'''Syntax:''' SecRuleUpdateTargetByTag TEXT TARGET1[,TARGET2,TARGET3] REPLACED_TARGET

'''Example Usage:''' SecRuleUpdateTargetByTag "WEB_ATTACK/XSS" "!ARGS:foo"

'''Scope:''' Any

'''Version:''' 2.7-3.x

'''Supported on libModSecurity:''' Yes

This directive will append (or replace) variables to the current target list of the specified rule with the targets provided in the second parameter.

'''Explicitly Appending Targets'''

This is useful for implementing exceptions where you want to externally update a target list to exclude inspection of specific variable(s).

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}"

SecRuleUpdateTargetByTag "WASCTC/WASC-31" !ARGS:email

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:
SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/|!ARGS:email "[;|`]W?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}""
'''Explicitly Replacing Targets'''

You can also entirely replace the target list to something more appropriate for your environment. For example, lets say you want to inspect REQUEST_URI instead of REQUEST_FILENAME, you could do this:

SecRule REQUEST_FILENAME|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}"

SecRuleUpdateTargetByTag "WASCTC/WASC-31" REQUEST_URI REQUEST_FILENAME

The effective resulting rule in the previous example will append the target to the end of the variable list as follows:
SecRule REQUEST_URI|ARGS_NAMES|ARGS|XML:/* "[;|`]W*?bmailb" 
     "phase:2,rev:'2.1.1',capture,t:none,t:htmlEntityDecode,t:compressWhitespace,t:lowercase,ctl:auditLogParts=+E,block,msg:'System Command Injection',id:'958895',tag:'WEB_ATTACK/COMMAND_INJECTION',tag:'WASCTC/WASC-31',tag:'OWASP_TOP_10/A1',tag:'PCI/6.5.2',logdata:'%{TX.0}',severity:'2',setvar:'tx.msg=%{rule.msg}',setvar:tx.anomaly_score=+%{tx.critical_anomaly_score},setvar:tx.command_injection_score=+%{tx.critical_anomaly_score},setvar:tx.%{rule.id}-WEB_ATTACK/COMMAND_INJECTION-%{matched_var_name}=%
{tx.0}""

== SecServerSignature == '''Description:''' Instructs ModSecurity to change the data presented in the "Server:" response header token.

'''Syntax:''' SecServerSignature "WEB SERVER SOFTWARE"

'''Example Usage:''' SecServerSignature "Microsoft-IIS/6.0"

'''Scope:''' Main

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' TBI

In order for this directive to work, you must set the Apache ServerTokens directive to Full. ModSecurity will overwrite the server signature data held in this memory space with the data set in this directive. If ServerTokens is not set to Full, then the memory space is most likely not large enough to hold the new data we are looking to insert.

; Note : This directive is not allowed inside VirtualHosts. If enabled, it must be placed in a global server-wide configuration file such as your default modsecurity.conf.

== SecStatusEngine == '''Description:''' Controls Status Reporting functionality. Uses DNS-based reporting to send software version information to the ModSecurity Project team.

'''Syntax:''' SecStatusEngine On Off

'''Example Usage:''' SecStatusEngine On

'''Scope:''' Any

'''Version:''' 2.8.0-2.9.x

'''Supported on libModSecurity:''' TBI

'''Default:''' Off

If SecStatusEngine directive is not present, it is disabled. If SecStatusEngine is marked as On, the following information will be shared with the ModSecurity project team when the web server is started:

  • Anonymous unique id for the server
  • Version of: ** ModSecurity ** Web Server Software (Apache, IIS, Nginx, Java) ** APR ** Libxml2 ** Lua ** PCRE

; Note : This is an example of the information presented in the Apache error_log representing what data will be sent:

[Mon Jan 20 10:55:22.001020 2014] [:notice] [pid 18231:tid 140735189168512] ModSecurity: StatusEngine call: "2.7.7,Apache/2.4.4 (Unix),1.4.6/1.4.6, 8.32 /8.32 2012-11-30,Lua 5.1/(null),2.7.8/(null),96ce9ba3c2fb71f7a8bb92a88d560d44dbe459b8"
[Mon Jan 20 10:55:22.089012 2014] [:notice] [pid 18231:tid 140735189168512] ModSecurity: StatusEngine call successfully submitted.

== SecStreamInBodyInspection == '''Description:''' Configures the ability to use stream inspection for inbound request data in a re-allocable buffer. For security reasons we are still buffering the stream.

'''Syntax:''' SecStreamInBodyInspection On Off

'''Example Usage:''' SecStreamInBodyInspection On

'''Scope:''' Any

'''Version:''' 2.6.0-2.9.x

'''Default:''' Off

'''Supported on libModSecurity:''' No

This feature enables the creation of the STREAM_INPUT_BODY variable and is useful for data modification or to match data in raw data for any content-types.

; Note : This directive provides full access to REQUEST_BODY payload data. It does not include REQUEST_URI or REQUEST_HEADER data. Also it provides data to all kind of content types, different than REQUEST_BODY.

; Note : This directive is NOT supported for libModSecurity (v3). Naturally, STREAM_INPUT_BODY is also NOT supported on libModSecurity.

; Note : This directive may significantly impact file upload times. The impact depends on server resources and the nature of operations being performed on the request bodies being streamed in.

== SecStreamOutBodyInspection == '''Description:''' Configures the ability to use stream inspection for outbound request data in a re-allocable buffer. For security reasons we are still buffering the stream.

'''Syntax:''' SecStreamOutBodyInspection On Off

'''Example Usage:''' SecStreamOutBodyInspection On

'''Scope:''' Any

'''Version:''' 2.6.0-2.9.x

'''Supported on libModSecurity:''' TBD

'''Default:''' Off

This feature enables the creation of the STREAM_OUTPUT_BODY variable and is useful when you need to do data modification into response body.

; Note : This directive provides access to RESPONSE_BODY payload data. It does not include RESPONSE_HEADER data.

== SecTmpDir == '''Description:''' Configures the directory where temporary files will be created.

'''Syntax:''' SecTmpDir /path/to/dir

'''Example Usage:''' SecTmpDir /tmp

'''Scope:''' Any

'''Version:''' 2.0.0-2.9.x

'''Supported on libModSecurity:''' No

The location specified needs to be writable by the Apache user process. This is the directory location where ModSecurity will swap data to disk if it runs out of memory (more data than what was specified in the SecRequestBodyInMemoryLimit directive) during inspection.

As of ModSecurity version 3.0, SecTmpDir is no longer supported. libModSecurity is able to deal with request body in a file or in a buffer (chunked or not). Web servers have properties which controls whenever a request should be saved to a file or used as a buffer (e.g. client_body_buffer_size https://nginx.org/en/docs/http/ngx_http_core_module.html#client_body_buffer_size) . If it is a file, ModSecurity will use the file to perform the inspection. If not, the buffer will be used.

== SecUnicodeMapFile == '''Description:''' Defines the path to the file that will be used by the urlDecodeUni transformation function to map Unicode code points during normalization and specifies the Code Point to use.

'''Syntax:''' SecUnicodeMapFile /path/to/unicode.mapping CODEPOINT

'''Example Usage:''' SecUnicodeMapFile unicode.mapping 20127

'''Scope:''' Any

'''Version:''' 2.6.1-2.9.x

'''Supported on libModSecurity:''' TBI

== SecUnicodeCodePage == '''Description:''' Defines which Unicode code point will be used by the urlDecodeUni transformation function during normalization.

'''Syntax:''' SecUnicodeCodePage XXXXX

'''Example Usage:''' SecUnicodeCodePage 20127

'''Scope:''' Any

'''Version:''' 2.6.1 - DEPRECATED

'''Supported on libModSecurity:''' No (Deprecated)

== SecUploadDir == '''Description:''' Configures the directory where intercepted files will be stored.

'''Syntax:''' SecUploadDir /path/to/dir

'''Example Usage:''' SecUploadDir /tmp

'''Scope:''' Any

'''Version:''' 2.0.0-3.x

'''Supported on libModSecurity:''' Yes

This directory must be on the same filesystem as the temporary directory defined with SecTmpDir. This directive is used with SecUploadKeepFiles.

== SecUploadFileLimit == '''Description:''' Configures the maximum number of file uploads processed in a multipart POST.

'''Syntax:''' SecUploadFileLimit number

'''Example Usage:''' SecUploadFileLimit 10

'''Scope:''' Any

'''Version:''' 2.5.12-3.x

'''Supported on libModSecurity:''' Yes

The default is set to 100 files, but you are encouraged to reduce this value. Any file over the limit will not be extracted and the MULTIPART_FILE_LIMIT_EXCEEDED and MULTIPART_STRICT_ERROR flags will be set. To prevent bypassing any file checks, you must check for one of these flags.

; Note : If the limit is exceeded, the part name and file name will still be recorded in FILES_NAME and FILES, the file size will be recorded in FILES_SIZES, but there will be no record in FILES_TMPNAMES as a temporary file was not created.

== SecUploadFileMode == '''Description:''' Configures the mode (permissions) of any uploaded files using an octal mode (as used in chmod).

'''Syntax:''' SecUploadFileMode 0640 "default"

'''Example Usage:''' SecUploadFileMode 0640

'''Scope:''' Any

'''Version:''' 2.1.6

'''Supported on libModSecurity:''' Yes

This feature is not available on operating systems not supporting octal file modes. The default mode (0600) only grants read/write access to the account writing the file. If access from another account is needed (using clamd is a good example), then this directive may be required. However, use this directive with caution to avoid exposing potentially sensitive data to unauthorized users. Using the value "default" will revert back to the default setting.

; Note : The process umask may still limit the mode if it is being more restrictive than the mode set using this directive.

== SecUploadKeepFiles == '''Description:''' Configures whether or not the intercepted files will be kept after transaction is processed.

'''Syntax:''' SecUploadKeepFiles On Off RelevantOnly

'''Example Usage:''' SecUploadKeepFiles On

'''Scope:''' Any

'''Version:''' 2.0.0

'''Supported on libModSecurity:''' Yes

This directive requires the storage directory to be defined (using SecUploadDir).

Possible values are:

*'''On''' - Keep uploaded files. *'''Off''' - Do not keep uploaded files. *'''RelevantOnly''' - This will keep only those files that belong to requests that are deemed relevant.

; Note : RelevantOnly is not yet supported on libModSecurity

== SecWebAppId == '''Description:''' Creates an application namespace, allowing for separate persistent session and user storage.

'''Syntax:''' SecWebAppId "NAME"

'''Example Usage:''' SecWebAppId "WebApp1"

'''Scope:''' Any

'''Version:''' 2.0.0-3.x

'''Supported on libModSecurity:''' Yes

'''Default:''' default

Application namespaces are used to avoid collisions between session IDs and user IDs when multiple applications are deployed on the same server. If it isn’t used, a collision between session IDs might occur.

<VirtualHost *:80> 
ServerName app1.example.com 
SecWebAppId "App1" ...
</VirtualHost>

<VirtualHost *:80> ServerName app2.example.com SecWebAppId "App2" ... </VirtualHost>

In the two examples configurations shown, SecWebAppId is being used in conjunction with the Apache VirtualHost directives. Applications namespace information is also recorded in the audit logs (using the WebApp-Info header of the H part).

== SecXmlExternalEntity == '''Description:''' Enable or Disable the loading process of xml external entity. Loading external entity without correct verifying process can lead to a security issue.

'''Syntax:''' SecXmlExternalEntity On Off

'''Example Usage:''' SecXmlExternalEntity Off

'''Scope:''' Any

'''Version:''' 2.7.3

'''Supported on libModSecurity:''' Yes

'''Default:''' default is Off

'''NOTE:''' You must enable this directive if you need to use the @validateSchema or @validateDtd operators.