This section contains a list of the directives available for use in your ModSecurity configuration file. These directives can be used in the main Apache configuration file, but as we have seen in previous chapters, placing your ModSecurity directives in a separate file is recommended as this makes it much easier to maintain your configuration.
SecAction lets you unconditionally execute actions. This essentially makes it a SecRule statement without the conditional part.
Syntax: SecAction action1,action2,action3
Example: SecAction setuid:%{REMOTE_USER},nolog
Specifies which character to use as a separator in forms and other content that uses the MIME type application/x-www-form-urlencoded. Also used to determine the separator in query strings. Most applications use the default value of & as the separator, but some may use another character.
Syntax: SecArgumentSeparator "<character>" Example: SecArgumentSeparator ";" Default value: "&"
Turns the audit engine on or off, or configures it to log only relevant requests.
Syntax: SecAuditEngine On|Off|RelevantOnly Example: SecAuditEngine On
In the On setting, all transactions are logged, while in the Off setting the audit engine is disabled and no audit logging is performed. When the RelevantOnly setting is used, transactions logged are limited to those that have generated an error or a warning, or that have a status code that matches the regular expression provided to the SecAuditLogRelevantStatus directive.
See Chapter 4, Logging and Auditing for more on audit logging.
Sets the path to the audit log file. Also used to configure mlogc to send audit logs to a ModSecurity console.
Syntax: SecAuditLog <path to file> Example: SecAuditLog logs/modsec_audit.log
If you are using the ModSecurity Log Collector (mlogc) to send data to a ModSecurity Console, then the SecAuditLog directive is used in the following manner to send data to the console using mlogc:
SecAuditLog "/usr/local/bin/mlogc /etc/mlogc.conf"
This causes ModSecurity to invoke mlogc and pass the audit log data to it. The data will then be sent to the ModSecurity Console, provided that you have configured mlogc correctly (see Chapter 4, Logging and Auditing for more information on this).
Sets the path to a second audit log index file when concurrent logging is used.
Syntax: SecAuditLog2 <path to file> Example: SecAuditLog2 logs/modsec_audit2.log
Determines what information is included with each audit log entry. Each part is represented by a character, as described in the following table below. The audit log header (A) and trailer (Z) are mandatory and must be included with each log entry.
Syntax: SecAuditLogParts <parts> Example: SecAuditLog ABCFHZ
|
Character |
Description |
|---|---|
|
A |
Audit log header Boundary that signifies the start of the audit log entry. Contains the time and date stamp of the log entry as well as the client and server IP address. Also contains the unique ID for the log entry, which makes it easy to find the request in the Apache log files. This option is mandatory and will be implicitly included if you don't specify it. |
|
B |
Request headers Contains all of the headers in the request, as sent by the client. |
|
C |
Request body Contains the request body. Only available if request body access is enabled in ModSecurity. |
|
E |
Response body Contains the response body of the request. Only available if response body access is enabled in ModSecurity. If the request was denied by a rule, this instead contains the error page sent to the client. |
|
F |
Response headers Contains the response headers, excluding the date and server headers as these are added late in the response delivery process by Apache. |
|
H |
Audit log trailer Contains information on whether the request was allowed or denied, and with what HTTP status code as well as the ModSecurity message as it appears in the Apache error log. Also contains a timestamp and the server string (as it would appear without any of the modifications that may have been made to it using |
|
I |
Request body without files Contains the same information as C—the request body—except when the encoding used is |
|
K |
Matched rules A list of all rules that matched this event, one per line, in the order that the rules matched. Each listed rule includes any default action lists. |
|
Z |
End of audit log entry Boundary that signifies the end of the audit log entry. This option is mandatory and will be implicitly included if you don't specify it. |
A regular expression for the HTTP response code that determines which requests to log when SecAuditEngine is set to RelevantOnly.
Specifies the directory where ModSecurity stores each individual audit log entry file when SecAuditLogType is set to Concurrent. Make sure the directory exists and is writable by the Apache user.
Syntax: SecAuditLogStorageDir <directory> Example: SecAuditLogStorageDir /var/log/httpd/audit
Sets the type of audit logging to use. This can be either Serial or Concurrent. In serial mode, all audit log data is stored in a single file whereas in concurrent mode, each log entry is stored in a separate file, and the main audit log file is used as an index for the individual files for each request. Concurrent logging is required if you want to send audit log data to a ModSecurity console.
Syntax: SecAuditLogType Serial|Concurrent Example: SecAuditLogType Concurrent Default value: Serial
If concurrent logging is used, you must use SecAuditLogStorageDir to specify the directory where ModSecurity should store the individual log entry files.
This directive enables or disables caching of transformations. Transformation caching can potentially speed up rule processing, however this feature is off by default as of version 2.5.6 of ModSecurity and is marked as experimental.
Syntax: SecCacheTransformations On|Off [options] Example: SecCacheTransformations On "minlen:0,maxlen:256" Default value: Off
Transformation caching, when enabled, is done on a per transaction basis. Following the On or Off statement, a number of options can be provided in a comma-separated list. These options control what transformations are cached, and the maximum number of transformations in the cache. The following options are available:
incremental:on|offSetting incremental to
onwill cache every intermediate transformation as well as the final transformation. If set to off, only the final transformation is cached.maxitems:nSets the maximum number of transformations to be cached. After this number of transformations have been cached, no further caching will take place.
minlen:nSets the minimum length of a transformation for it to be considered for caching.
maxlen:nSets the maximum length of a transformation for it to be considered for caching.
Changes the root directory of the Apache process to the specified directory. This creates a "jail" for the Apache process, making it much more difficult for any attacker who is able to exploit a vulnerability in the web application or the web server to gain further access to the server. See Chapter 7, Chroot Jails for a complete explanation of chroot jails and the SecChrootDir command.
Syntax: SecChrootDir <new root directory> Example: SecChrootDir /chroot
This directive appends an additional signature to the ModSecurity version string. This makes it possible for creators of independent rulesets to make the inclusion of the ruleset known since the component signature will be visible in the audit and debug logs.
Syntax: SecComponentSignature <signature> Example: SecComponentSignature "ModSecurity Book Rules/1.0"
Enables injection of content into the data that is output by the web server. Content can be injected either at the start of the output, using the prepend action, or at the end of the output, using the append action.
Syntax: SecContentInjection On|Off Example: SecContentInjection On Default value: Off
Set the cookie format used. This is either the original Netscape format cookies (when the value 0 is provided) or as defined by RFC 2109 (when the value 1 is provided). Most applications use old format cookies, and the default is set to 0.
Syntax: SecCookieFormat 0|1 Example: SecCookieFormat 0 Default value: 0
Sets the directory where ModSecurity can store persistent data, such as collections pertaining to IP addresses and sessions. This kind of data is created when the initcol, setsid, and setuid actions are used. Make sure that the directory exists and is writable by the Apache user.
Syntax: SecDataDir <directory> Example: SecDataDir /usr/local/apache/modsec_data
Specifies where to store the debug log. This can be a relative path, in which case it is relative to the Apache base directory (for example, if you specify SecDebugLog logs/msd.log and the Apache base directory is /etc/httpd, then the log file will be stored in /etc/httpd/logs/msd.log).
Syntax: SecDebugLog /path/to/modsec_debug.log Example: SecDebugLog /var/log/httpd/modsec_debug.log
Configures the verbosity of the debug log. A value of 0 means no debug log data is recorded while a value of 9 provides the maximum amount of debug information.
Syntax: SecDebugLogLevel 0..9 Example: SecDebugLogLevel 4 Default value: 0
Specifies the default action to take when a rule matches. This is a comma-separated list of actions that are essentially prepended to all rules and will be performed when a rule matches. This means that if SecDefaultAction is specified and a rule without its own action list matches, the default actions will still be taken.
Most rulesets will specify a default action of deny, to make sure that requests will be denied if a rule matches. The default action is overridden by any actions specified in a rule, so even with a default action of deny in place, an allow or pass in a rule will take precedence over the default action.
Syntax: SecDefaultAction <action list> Example: SecDefaultAction "phase:2,deny,log,auditlog" Default value: "phase:2,log,auditlog,pass"
Path to the database file containing information to match IP addresses to geographical locations. For an example on how to use this, refer to Chapter 2.
Syntax: SecGeoLookupDb <path to file> Example: SecGeoLookupDb /usr/local/geoip/GeoIP.dat
Allows ModSecurity to interact with the httpd-guardian script to detect and block denial of service attacks. This script was developed by Ivan Ristic, and will block clients that request an excessive amount of pages from the server (more than 120 requests in a minute or 360 requests in five minutes).
Syntax: SecGuardianLog "|/path/to/httpd-guardian" Example: SecGuardianLog "|/etc/httpd/apache/httpd-guardian"
Sets a marker in the ruleset for use with the skipAfter action. You can think of a SecMarker as a rule that only contains an id and has no other effect.
Syntax: SecMarker <id> Example: SecMarker 1000
Enables cross-site scripting protection for PDF files. See the PDF XSS Protection section in Chapter 6 for more information on this and details on the vulnerability it protects against.
Syntax: SecPdfProtect On|Off Example: SecPdfProtect On Default value: Off
When set to On, you also need to configure SecPdfProtectMethod and SecPdfProtectSecret.
Sets the method to use for PDF XSS protection. You can choose between TokenRedirection and ForcedDownload. When set to TokenRedirection, attempts to access a PDF file will result in a redirection to protect against cross-site scripting attacks. Read more about this in the PDF XSS Protection section of Chapter 6. When the ForcedDownload setting is used, ModSecurity sets the MIME type of PDF files that are accessed to application/x-octet-stream, which causes browsers to download the file instead of allowing users to view it embedded in a page. This also protects against the cross-site scripting vulnerability, but will cause some inconvenience to visitors of your site, as they will no longer be able to view PDF files from within their browser.
Syntax: SecPdfProtectMethod TokenRedirection|ForcedDownload Example: SecPdfProtectMethod TokenRedirection Default Value: TokenRedirection
Sets the secret to use for PDF cross-site scripting protection. This is used to generate the unique tokens involved in the redirection that takes place when PDF protection is enabled. You can use any reasonably long string you like (16 characters or more is good).
Syntax: SecPdfProtectSecret <string> Example: SecPdfProtectSecret ILoveModSecurity
Defines the timeout to use for PDF protection tokens. After the timeout, the tokens expire and can no longer be used to view PDF files embedded in the browser—they will instead be offered as downloads.
Syntax: SecPdfProtectTimeout <timeout> Example: SecPdfProtectTimeout 20 Default value: 10
The name of the token used to protect PDF files.
Syntax: SecPdfProtectTokenName <string> Example: SecPdfProtectTokenName "pdftok"
Controls processing of request bodies. If set to On, request bodies will be buffered and available for processing in ModSecurity. If set to Off, no request body buffering takes place.
Syntax: SeqRequestBodyAccess On|Off Example: SeqRequestBodyAccess On Default value: Off
Configures the maximum size of a request body. Any request with a body over this limit will be rejected with status code 413—Request Entity Too Large. The default value is 128 MB, and ModSecurity has a hard-coded limit of 1 GB.
Syntax: SecRequestBodyLimit <Number of Bytes> Example: SeqRequestBodyLimit 64000000 Default value: 134217728 (128 MB)
Sets the maximum size of request bodies that ModSecurity will accept for buffering when any files included in the request are excluded.
Syntax: SecRequestBodyNoFilesLimit <size in bytes> Example: SecRequestBodyLimit 131072 Default value: 1048576 (1 MB)
Configures the maximum size of a request body to be held in memory. Anything over the size specified will be buffered by creating a temporary file on disk. The default value is set conservatively at 128 KB. If you have a reasonable amount of memory on your system, you may want to increase this limit to something like 5 MB.
Syntax: SecRequestBodyInMemoryLimit <Number of Bytes> Example: SecRequestBodyInMemoryLimit 67108864 Default value: 131072 (128 KB)
Sets the maximum size of the response body for response body buffering. If the response body is larger than this size, then what happens is determined by the setting provided for SecResponseBodyLimitAction (shown next). Requests whose MIME type does not match the MIME types provided to SecResponseBodyMimeTypes are not affected by this.
Syntax: SecResponseBodyLimit <size in bytes> Example: SecResponseBodyLimit 512000
Controls what happens when response body buffering is enabled and the response body exceeds the size set for SecResponseBodyLimit. If Reject is set, the request will be rejected with a 500—Internal Server Error message if it exceeds the limit. If ProcessPartial setting is in effect, then the part of the response body that fits into the buffer is inspected and the entire response is sent to the client (if no rule denies the response after inspecting the part of it that fits in the buffer).
Syntax: SecResponseBodyLimitAction Reject|ProcessPartial Example: SecResponseBodyLimitAction ProcessPartial
This setting controls which requests are considered for response body buffering. Requests that have one of the MIME types set using this directive are buffered while all other requests are not. Each MIME type in the list is separated by whitespace.
Syntax: SecResponseBodyMimeType <mime types> Example: SecResponseBodyMimeType text/html text/plain
Enables or disables access to the HTTP response body. When turned on, this allows the response body to be inspected in rules using the RESPONSE_BODY variable.
Syntax: SecResponseBodyAccess On|Off Example: SecResponseBodyAccess On Default value: Off
The main ModSecurity directive. Rules are used to determine what to do with HTTP requests such as block, allow, forward or a multitude of other conceivable actions. Each rule consists of three parts—the target, which is a variable or collection, which is what the rule is matched against, and operators, which is usually a regular expression used to match against the target.
Finally, a list of actions are used to determine what to do if a rule matches.
For a complete description of SecRule and all the aspects involved in writing rules, please see Chapter 2.
Configures whether or not virtual hosts inherit the main ModSecurity configuration and rules.
Syntax: SecRuleInheritance On|Off Example: SecRuleInheritance On
Turns the rule engine on or off, or configures it to run in detection-only mode. Possible values are On, which turns the rule engine on, Off, which disables the rule engine, or DetectionOnly,which turns the rule engine on, but does not take any action (such as blocking requests) even if a rule matches. This latter directive is useful in combination with debug logging.
Syntax: SecRuleEngine On|Off|DetectionOnly Default value: Off
Removes rules with a matching ID from the ruleset. Several IDs, or even a range of IDs, can be provided.
Syntax: SecRuleRemoveById <list of rule ids> Example: SecRuleRemoveById 1 20 30 400-500
Removes rules whose msg string matches the regular expression from the parent context.
Syntax: SecRuleRemoveByMsg <regular expression> Example: SecRuleRemoveByMsg "access denied"
Amends the specified rule's action list by appending the specified action list to the rule's action list. The only things that cannot be changed are a rule's phase and rule ID.
Syntax: SecRuleUpdateActionById <id> <action list> Example: SecRuleUpdateActionById 280 "t:urlDecode,msg:'Access denied'"
Instructs ModSecurity to change the web server signature as returned by the HTTP response headers. For this to work, ServerTokens Full must be specified in the Apache configuration file.
Syntax: SecServerSignature: "<New server signature>" Example: SecServerSignature "Microsoft-IIS/5.0"
Configures the directory used for creating temporary files. ModSecurity uses temporary files when the data held in memory exceeds the configured memory limits (such as with the directive SecRequestBodyInMemoryLimit). The Apache user must have write access to the directory specified here.
Syntax: SecTmpDir <directory> Example: SecTmpDir /tmp/modsecurity Default value: Temp directory specified by environment variable
Sets the directory where files that have been intercepted are stored.
Syntax: SecUploadDir <directory> Example: SecUploadDir /tmp/modsecurity/
Sets the mode to use for uploaded files that have been intercepted. The mode refers to the Linux file permissions as used with the Linux chmod command.
Syntax: SecUploadFileMode mode Example: SecUploadFileMode 644