diff --git a/doc/modsecurity2-apache-reference.xml b/doc/modsecurity2-apache-reference.xml index 3b509987..91599f0c 100644 --- a/doc/modsecurity2-apache-reference.xml +++ b/doc/modsecurity2-apache-reference.xml @@ -2,222 +2,312 @@
- <trademark class="registered">ModSecurity</trademark> Reference Manual + <trademark class="registered">ModSecurity</trademark> Reference + Manual + Version 2.6.0-trunk (Feb 11, 2009) + 2004-2010 - Breach Security, Inc. (http://www.breach.com) + + Breach Security, Inc. (http://www.breach.com) +
Introduction - ModSecurity is a web application firewall (WAF). With over 70% of attacks now carried out - over the web application level, organisations need all the help they can get in making their - systems secure. WAFs are deployed to establish an increased external security layer to detect - and/or prevent attacks before they reach web applications. ModSecurity provides protection - from a range of attacks against web applications and allows for HTTP traffic monitoring and - real-time analysis with little or no changes to existing infrastructure. + + ModSecurity is a web application firewall (WAF). With over 70% of + attacks now carried out over the web application level, organisations need + all the help they can get in making their systems secure. WAFs are + deployed to establish an increased external security layer to detect + and/or prevent attacks before they reach web applications. ModSecurity + provides protection from a range of attacks against web applications and + allows for HTTP traffic monitoring and real-time analysis with little or + no changes to existing infrastructure. +
HTTP Traffic Logging - Web servers are typically well-equipped to log traffic in a form useful for marketing - analyses, but fall short logging traffic to web applications. In particular, most are not - capable of logging the request bodies. Your adversaries know this, and that is why most - attacks are now carried out via POST requests, rendering your systems blind. ModSecurity - makes full HTTP transaction logging possible, allowing complete requests and responses to be - logged. Its logging facilities also allow fine-grained decisions to be made about exactly - what is logged and when, ensuring only the relevant data is recorded. As some of the request - and/or response may contain sensitive data in certain fields, ModSecurity can be configured - to mask these fields before they are written to the audit log. + + Web servers are typically well-equipped to log traffic in a form + useful for marketing analyses, but fall short logging traffic to web + applications. In particular, most are not capable of logging the request + bodies. Your adversaries know this, and that is why most attacks are now + carried out via POST requests, rendering your systems blind. ModSecurity + makes full HTTP transaction logging possible, allowing complete requests + and responses to be logged. Its logging facilities also allow + fine-grained decisions to be made about exactly what is logged and when, + ensuring only the relevant data is recorded. As some of the request + and/or response may contain sensitive data in certain fields, + ModSecurity can be configured to mask these fields before they are + written to the audit log.
+
Real-Time Monitoring and Attack Detection - In addition to providing logging facilities, ModSecurity can monitor the HTTP traffic in - real time in order to detect attacks. In this case, ModSecurity operates as a web intrusion - detection tool, allowing you to react to suspicious events that take place at your web - systems. + + In addition to providing logging facilities, ModSecurity can + monitor the HTTP traffic in real time in order to detect attacks. In + this case, ModSecurity operates as a web intrusion detection tool, + allowing you to react to suspicious events that take place at your web + systems.
+
Attack Prevention and Just-in-time Patching - ModSecurity can also act immediately to prevent attacks from reaching your web - applications. There are three commonly used approaches: + + ModSecurity can also act immediately to prevent attacks from + reaching your web applications. There are three commonly used + approaches: + - Negative security model. A negative security model monitors requests for anomalies, - unusual behaviour, and common web application attacks. It keeps anomaly scores for each - request, IP addresses, application sessions, and user accounts. Requests with high - anomaly scores are either logged or rejected altogether. + Negative security model. A negative security model monitors + requests for anomalies, unusual behaviour, and common web + application attacks. It keeps anomaly scores for each request, IP + addresses, application sessions, and user accounts. Requests with + high anomaly scores are either logged or rejected altogether. + - Positive security model. When a positive security model is deployed, only requests - that are known to be valid are accepted, with everything else rejected. This model - requires knownledge of the web applications you are protecting. Therefore a positive - security model works best with applications that are heavily used but rarely updated so - that maintenance of the model is minimized. + Positive security model. When a positive security model is + deployed, only requests that are known to be valid are accepted, + with everything else rejected. This model requires knownledge of the + web applications you are protecting. Therefore a positive security + model works best with applications that are heavily used but rarely + updated so that maintenance of the model is minimized. + - Known weaknesses and vulnerabilities. Its rule language makes ModSecurity an ideal - external patching tool. External patching (sometimes referred to as Virtual Patching) is - about reducing the window of opportunity. Time needed to patch application - vulnerabilities often runs to weeks in many organisations. With ModSecurity, - applications can be patched from the outside, without touching the application source - code (and even without any access to it), making your systems secure until a proper - patch is applied to the application. + Known weaknesses and vulnerabilities. Its rule language makes + ModSecurity an ideal external patching tool. External patching + (sometimes referred to as Virtual Patching) is about reducing the + window of opportunity. Time needed to patch application + vulnerabilities often runs to weeks in many organisations. With + ModSecurity, applications can be patched from the outside, without + touching the application source code (and even without any access to + it), making your systems secure until a proper patch is applied to + the application.
+
Flexible Rule Engine - A flexible rule engine sits in the heart of ModSecurity. It implements the ModSecurity - Rule Language, which is a specialised programming language designed to work with HTTP - transaction data. The ModSecurity Rule Language is designed to be easy to use, yet flexible: - common operations are simple while complex operations are possible. Certified ModSecurity - Rules, included with ModSecurity, contain a comprehensive set of rules that implement - general-purpose hardening, protocol validation and detection of common web application - security issues. Heavily commented, these rules can be used as a learning tool. + + A flexible rule engine sits in the heart of ModSecurity. It + implements the ModSecurity Rule Language, which is a specialised + programming language designed to work with HTTP transaction data. The + ModSecurity Rule Language is designed to be easy to use, yet flexible: + common operations are simple while complex operations are possible. + Certified ModSecurity Rules, included with ModSecurity, contain a + comprehensive set of rules that implement general-purpose hardening, + protocol validation and detection of common web application security + issues. Heavily commented, these rules can be used as a learning + tool.
+
Embedded-mode Deployment - ModSecurity is an embeddable web application firewall, which means it can be deployed as - part of your existing web server infrastructure provided your web servers are Apache-based. - This deployment method has certain advantages: + + ModSecurity is an embeddable web application firewall, which means + it can be deployed as part of your existing web server infrastructure + provided your web servers are Apache-based. This deployment method has + certain advantages: + - No changes to existing network. It only takes a few minutes to add ModSecurity to - your existing web servers. And because it was designed to be completely passive by - default, you are free to deploy it incrementally and only use the features you need. It - is equally easy to remove or deactivate it if required. + No changes to existing network. It only takes a few minutes to + add ModSecurity to your existing web servers. And because it was + designed to be completely passive by default, you are free to deploy + it incrementally and only use the features you need. It is equally + easy to remove or deactivate it if required. + - No single point of failure. Unlike with network-based deployments, you will not be - introducing a new point of failure to your system. + No single point of failure. Unlike with network-based + deployments, you will not be introducing a new point of failure to + your system. + - Implicit load balancing and scaling. Because it works embedded in web servers, - ModSecurity will automatically take advantage of the additional load balancing and - scalability features. You will not need to think of load balancing and scaling unless - your existing system needs them. + Implicit load balancing and scaling. Because it works embedded + in web servers, ModSecurity will automatically take advantage of the + additional load balancing and scalability features. You will not + need to think of load balancing and scaling unless your existing + system needs them. + - Minimal overhead. Because it works from inside the web server process there is no - overhead for network communication and minimal overhead in parsing and data - exchange. + Minimal overhead. Because it works from inside the web server + process there is no overhead for network communication and minimal + overhead in parsing and data exchange. + - No problem with encrypted or compressed content. Many IDS systems have difficulties - analysing SSL traffic. This is not a problem for ModSecurity because it is positioned to - work when the traffic is decrypted and decompressed. + No problem with encrypted or compressed content. Many IDS + systems have difficulties analysing SSL traffic. This is not a + problem for ModSecurity because it is positioned to work when the + traffic is decrypted and decompressed.
+
Network-based Deployment - ModSecurity works equally well when deployed as part of an Apache-based reverse proxy - server, and many of our customers choose to do so. In this scenario, one installation of - ModSecurity can protect any number of web servers (even the non-Apache ones). + + ModSecurity works equally well when deployed as part of an + Apache-based reverse proxy server, and many of our customers choose to + do so. In this scenario, one installation of ModSecurity can protect any + number of web servers (even the non-Apache ones).
+
Portability - ModSecurity is known to work well on a wide range of operating systems. Our customers - are successfully running it on Linux, Windows, Solaris, FreeBSD, OpenBSD, NetBSD, AIX, Mac - OS X, and HP-UX. + + ModSecurity is known to work well on a wide range of operating + systems. Our customers are successfully running it on Linux, Windows, + Solaris, FreeBSD, OpenBSD, NetBSD, AIX, Mac OS X, and HP-UX.
+
Licensing - ModSecurity is available under two licenses. Users can choose to use the software under - the terms of the GNU General Public License version 2 (licence text is included with the - distribution), as an Open Source / Free Software product. A range of commercial licenses is - also available, together with a range of commercial support contracts. For more information - on commercial licensing please contact Breach Security. + + ModSecurity is available under two licenses. Users can choose to + use the software under the terms of the GNU General Public License + version 2 (licence text is included with the distribution), as an Open + Source / Free Software product. A range of commercial licenses is also + available, together with a range of commercial support contracts. For + more information on commercial licensing please contact Breach + Security. + - ModSecurity, mod_security, ModSecurity Pro, and ModSecurity Core Rules are trademarks - or registered trademarks of Breach Security, Inc. + ModSecurity, mod_security, ModSecurity Pro, and ModSecurity Core + Rules are trademarks or registered trademarks of Breach Security, + Inc.
+
<trademark>ModSecurity Core Rules</trademark> +
Overview - ModSecurity is a web application firewall engine that provides very little protection on - its own. In order to become useful, ModSecurity must be configured with rules. In order to - enable users to take full advantage of ModSecurity out of the box, Breach Security, Inc. is - providing a free certified rule set for ModSecurity 2.x. Unlike intrusion detection and - prevention systems, which rely on signatures specific to known vulnerabilities, the Core - Rules provide generic protection from unknown vulnerabilities often found in web - applications, which are in most cases custom coded. The Core Rules are heavily commented to - allow it to be used as a step-by-step deployment guide for ModSecurity. The latest Core - Rules can be found at the ModSecurity website - http://www.modsecurity.org/projects/rules/. + + ModSecurity is a web application firewall engine that provides + very little protection on its own. In order to become useful, + ModSecurity must be configured with rules. In order to enable users to + take full advantage of ModSecurity out of the box, Breach Security, Inc. + is providing a free certified rule set for ModSecurity 2.x. Unlike + intrusion detection and prevention systems, which rely on signatures + specific to known vulnerabilities, the Core Rules provide generic + protection from unknown vulnerabilities often found in web applications, + which are in most cases custom coded. The Core Rules are heavily + commented to allow it to be used as a step-by-step deployment guide for + ModSecurity. The latest Core Rules can be found at the ModSecurity + website - http://www.modsecurity.org/projects/rules/.
+
Core Rules Content - In order to provide generic web applications protection, the Core Rules use the - following techniques: + + In order to provide generic web applications protection, the Core + Rules use the following techniques: + - HTTP protection - detecting violations of the HTTP protocol and a locally defined - usage policy. + HTTP protection - detecting violations of the HTTP protocol + and a locally defined usage policy. + - Common Web Attacks Protection - detecting common web application security - attack. + Common Web Attacks Protection - detecting common web + application security attack. + - Automation detection - Detecting bots, crawlers, scanners and other surface - malicious activity. + Automation detection - Detecting bots, crawlers, scanners and + other surface malicious activity. + Trojan Protection - Detecting access to Trojans horses. + - Error Hiding - Disguising error messages sent by the server. + Error Hiding - Disguising error messages sent by the + server.
+
Installation + ModSecurity installation requirements: + - ModSecurity 2.x works only with Apache 2.0.x or higher. Version 2.2.x is highly - recommended. + ModSecurity 2.x works only with Apache 2.0.x or higher. Version + 2.2.x is highly recommended. + - Make sure you have mod_unique_id installed. + Make sure you have mod_unique_id installed. + mod_unique_id is packaged with Apache httpd. + libapr and libapr-util - http://apr.apache.org/ + + http://apr.apache.org/ + libpcre - http://www.pcre.org/ + + http://www.pcre.org/ + libxml2 - http://xmlsoft.org/downloads.html + + http://xmlsoft.org/downloads.html + liblua v5.1.x - This library is optional and only needed if you will be using the new Lua - engine. - http://www.lua.org/download.html - Note that ModSecurity requires the dynamic libraries. These are not built by default - in the source distribution, so the binary distribution is recommended. + + This library is optional and only needed if you will be using + the new Lua engine. + + http://www.lua.org/download.html + + Note that ModSecurity requires the dynamic libraries. These are + not built by default in the source distribution, so the binary + distribution is recommended. + libcurl v7.15.1 or higher - If you will be using the ModSecurity Log Collector (mlogc) to send audit logs to a - central repository, then you will also need the curl library. - http://curl.haxx.se/libcurl/ + + If you will be using the ModSecurity Log Collector (mlogc) to + send audit logs to a central repository, then you will also need the + curl library. + + http://curl.haxx.se/libcurl/ Many have had issues with libcurl linked with the GnuTLS @@ -226,239 +316,338 @@ + ModSecurity installation consists of the following steps: + Stop Apache httpd + Unpack the ModSecurity archive + - Building differs for UNIX (or UNIX-like) operating systems and Windows. + Building differs for UNIX (or UNIX-like) operating systems and + Windows. + UNIX + - Run the configure script to generate a Makefile. Typically no options are - needed. - ./configure - Options are available for more customization (use ./configure - --help for a full list), but typically you will only need to specify - the location of the apxs command installed by Apache httpd with - the --with-apxs option. - ./configure - --with-apxs=/path/to/httpd-2.x.y/bin/apxs + Run the configure script to generate a Makefile. + Typically no options are needed except the prefix directory + for installation and possibly the location of the Apache apxs + (or apxs2) utility: + + ./configure --prefix=/usr/local/modsecurity + --with-apxs=/path/to/httpd-2.x.y/bin/apxs + + Other options are available for more customization (use + ./configure --help for a full list). + - There are certain configure options that are meant for debugging an other - development use. If enabled, these options can substantially impact performance. - These options include all --debug-* options as well as the - --enable-performance-measurements options. + There are certain configure options that are meant for + debugging an other development use. If enabled, these + options can substantially impact performance. These options + include all --debug-* options as well as + the --enable-performance-measurements + options. + Compile with: make + - Optionally test with: make test + Optionally test with: make + test + - This is step is still a bit experimental. If you have problems, please send - the full output and error from the build to the support list. Most common issues - are related to not finding the required headers and/or libraries. + This is step is still a bit experimental. If you have + problems, please send the full output and error from the + build to the support list. Most common issues are related to + not finding the required headers and/or libraries. + - Optionally build the ModSecurity Log Collector with: make - mlogc - - - Optionally install mlogc: Review the INSTALL file included in the apache2/mlogc-src directory in the - distribution. - - - Install the ModSecurity module with: make install + Install ModSecurity module and utilities with: + make install + Windows (MS VC++ 8) + - Edit Makefile.win to configure the Apache base and library - paths. + Edit Makefile.win to configure the + Apache base and library paths. + - Compile with: nmake -f Makefile.win + Compile with: nmake -f + Makefile.win + - Install the ModSecurity module with: nmake -f Makefile.win - install + Install the ModSecurity module with: nmake -f + Makefile.win install + - Copy the libxml2.dll and lua5.1.dll to - the Apache bin directory. Alternatively you can follow the step - below for using LoadFile to load these libraries. + Copy the libxml2.dll and + lua5.1.dll to the Apache + bin directory. Alternatively you can follow + the step below for using LoadFile to load these + libraries. + See the included + README_WINDOWS.TXT file for more + details. This file contains the Windows build notes from + Tom Donovan who helps with the Apache Lounge builds + (http://www.apachelounge.com/). + + - Edit the main Apache httpd config file (usually httpd.conf) - On UNIX (and Windows if you did not copy the DLLs as stated above) you must load - libxml2 and lua5.1 before ModSecurity with something like this: - - LoadFile /usr/lib/libxml2.so -LoadFile /usr/lib/liblua5.1.so - - Load the ModSecurity module - with:LoadModule security2_module modules/mod_security2.so + Edit the main Apache httpd config file (usually + httpd.conf) + + On UNIX (and Windows if you did not copy the DLLs as stated + above) you must load libxml2 and lua5.1 before ModSecurity with + something like this: + + LoadFile /usr/lib/libxml2.so +LoadFile /usr/lib/liblua5.1.so + + Load the ModSecurity module with:LoadModule security2_module modules/mod_security2.so + Configure ModSecurity + Start Apache httpd + You should now have ModSecurity 2.x up and running. + - If you have compiled Apache yourself you might experience problems compiling ModSecurity - against PCRE. This is because Apache bundles PCRE but this library is also typically - provided by the operating system. I would expect most (all) vendor-packaged Apache - distributions to be configured to use an external PCRE library (so this should not be a - problem). - You want to avoid Apache using the bundled PCRE library and ModSecurity linking against - the one provided by the operating system. The easiest way to do this is to compile Apache - against the PCRE library provided by the operating system (or you can compile it against the - latest PCRE version you downloaded from the main PCRE distribution site). You can do this at - configure time using the --with-pcre switch. If you are - not in a position to recompile Apache, then, to compile ModSecurity successfully, you'd - still need to have access to the bundled PCRE headers (they are available only in the Apache - source code) and change the include path for ModSecurity (as you did in step 7 above) to - point to them (via the --with-pcre ModSecurity configure option). - Do note that if your Apache is using an external PCRE library you can compile - ModSecurity with WITH_PCRE_STUDY defined,which would - possibly give you a slight performance edge in regular expression processing. - Non-gcc compilers may have problems running out-of-the-box as the current build system - was designed around the gcc compiler and some compiler/linker flags may differ. To use a - non-gcc compiler you may need some manual Makefile tweaks if issues cannot be solved by - exporting custom CFLAGS and CPPFLAGS environment variables. - If you are upgrading from ModSecurity 1.x, please refer to the migration matrix at - http://www.modsecurity.org/documentation/ModSecurity-Migration-Matrix.pdf + If you have compiled Apache yourself you might experience problems + compiling ModSecurity against PCRE. This is because Apache bundles PCRE + but this library is also typically provided by the operating system. I + would expect most (all) vendor-packaged Apache distributions to be + configured to use an external PCRE library (so this should not be a + problem). + + You want to avoid Apache using the bundled PCRE library and + ModSecurity linking against the one provided by the operating system. + The easiest way to do this is to compile Apache against the PCRE library + provided by the operating system (or you can compile it against the + latest PCRE version you downloaded from the main PCRE distribution + site). You can do this at configure time using the --with-pcre switch. If you are not in a + position to recompile Apache, then, to compile ModSecurity successfully, + you'd still need to have access to the bundled PCRE headers (they are + available only in the Apache source code) and change the include path + for ModSecurity (as you did in step 7 above) to point to them (via the + --with-pcre ModSecurity configure option). + + Do note that the current version of PCRE packaged with Apache + 2.2.14 is using an older version which does not support some of the more + advanced features to aide in preventing regex denial of service attacks + (REDoS) on poorly designed regular expressions. + + Non-gcc compilers may have problems running out-of-the-box as the + current build system was designed around the gcc compiler and some + compiler/linker flags may differ. To use a non-gcc compiler you may need + some manual Makefile tweaks if issues cannot be solved by exporting + custom CFLAGS and CPPFLAGS environment variables. + + If you are upgrading from ModSecurity 1.x, please refer to the + migration matrix at http://www.modsecurity.org/documentation/ModSecurity-Migration-Matrix.pdf
+
Configuration Directives - The following section outlines all of the ModSecurity directives. Most of the ModSecurity - directives can be used inside the various Apache Scope Directives such as VirtualHost, Location, LocationMatch, - Directory, etc... There are others, however, that can only be used once - in the main configuration file. This information is specified in the Scope sections below. The - first version to use a given directive is given in the Version sections below. - These rules, along with the Core rules files, should be contained is files outside of the - httpd.conf file and called up with Apache "Include" directives. This allows for easier - updating/migration of the rules. If you create your own custom rules that you would like to - use with the Core rules, you should create a file called - modsecurity_crs_15_customrules.conf and place it in the same directory as the - Core rules files. By using this file name, your custom rules will be called up after the - standard ModSecurity Core rules configuration file but before the other Core rules. This - allows your rules to be evaluated first which can be useful if you need to implement specific - "allow" rules or to correct any false positives in the Core rules as they are applied to your - site. + + The following section outlines all of the ModSecurity directives. + Most of the ModSecurity directives can be used inside the various Apache + Scope Directives such as VirtualHost, + Location, LocationMatch, + Directory, etc... There are others, however, that can + only be used once in the main configuration file. This information is + specified in the Scope sections below. The first version to use a given + directive is given in the Version sections below. + + These rules, along with the Core rules files, should be contained is + files outside of the httpd.conf file and called up with Apache "Include" + directives. This allows for easier updating/migration of the rules. If you + create your own custom rules that you would like to use with the Core + rules, you should create a file called - + modsecurity_crs_15_customrules.conf and place it in + the same directory as the Core rules files. By using this file name, your + custom rules will be called up after the standard ModSecurity Core rules + configuration file but before the other Core rules. This allows your rules + to be evaluated first which can be useful if you need to implement + specific "allow" rules or to correct any false positives in the Core rules + as they are applied to your site. + - It is highly encouraged that you do not edit the Core rules files themselves but rather - place all changes (such as SecRuleRemoveByID, etc...) in your custom - rules file. This will allow for easier upgrading as newer Core rules are released by Breach - Security on the ModSecurity website. + It is highly encouraged that you do not edit the Core rules files + themselves but rather place all changes (such as + SecRuleRemoveByID, etc...) in your custom rules file. + This will allow for easier upgrading as newer Core rules are released by + Breach Security on the ModSecurity website. +
<literal>SecAction</literal> - Description: Unconditionally processes the action list it receives - as the first and only parameter. It accepts one parameter, the syntax of which is identical - to the third parameter of SecRule. - Syntax: - SecAction action1,action2,action3 - Example Usage: - SecAction - nolog,phase:1,initcol:RESOURCE=%{REQUEST_FILENAME} + + Description: Unconditionally processes the + action list it receives as the first and only parameter. It accepts one + parameter, the syntax of which is identical to the third parameter + of SecRule. + + Syntax: SecAction + action1,action2,action3 + + Example Usage: SecAction + nolog,phase:1,initcol:RESOURCE=%{REQUEST_FILENAME} + Processing Phase: Any + Scope: Any + Version: 2.0.0 + Dependencies/Notes: None - SecAction is best used when you unconditionally execute an action. This is explicit - triggering whereas the normal actions are conditional based on data inspection of the - request/response. This is a useful directive when you want to run certain actions such as - initcol to initialize collections. + + SecAction is best used when you unconditionally execute an action. + This is explicit triggering whereas the normal actions are conditional + based on data inspection of the request/response. This is a useful + directive when you want to run certain actions such as + initcol to initialize collections.
+
<literal>SecArgumentSeparator</literal> - Description: Specifies which character to use as separator - for application/x-www-form-urlencoded content. Defaults - to &. Applications are sometimes (very rarely) - written to use a semicolon (;). - Syntax: - SecArgumentSeparator character - Example Usage: - SecArgumentSeparator ; + + Description: Specifies which character to use + as separator for + application/x-www-form-urlencoded content. Defaults to + &. Applications are sometimes + (very rarely) written to use a semicolon (;). + + Syntax: SecArgumentSeparator character + + Example Usage: SecArgumentSeparator ; + Processing Phase: Any + Scope: Main + Version: 2.0.0 + Dependencies/Notes: None - This directive is needed if a backend web application is using a non-standard argument - 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. + + This directive is needed if a backend web application is using a + non-standard argument 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.
+
<literal>SecAuditEngine</literal> - Description: Configures the audit logging engine. - Syntax: - SecAuditEngine On|Off|RelevantOnly - Example Usage: - SecAuditEngine On + + Description: Configures the audit logging + engine. + + Syntax: SecAuditEngine On|Off|RelevantOnly + + Example Usage: SecAuditEngine On + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Can be set/changed with the "ctl" action for the current transaction. - Example: The following example shows the various audit directives used together. + + Dependencies/Notes: Can be set/changed with + the "ctl" action for the current transaction. + + Example: The following example shows the various audit directives + used together. + SecAuditEngine RelevantOnly SecAuditLog logs/audit/audit.log SecAuditLogParts ABCFHZ SecAuditLogType concurrent SecAuditLogStorageDir logs/audit SecAuditLogRelevantStatus ^(?:5|4\d[^4]) + Possible values are: + - On - log all transactions by default. + On - log all transactions + by default. + - Off - do not log transactions by default. + Off - do not log + transactions by default. + - RelevantOnly - by default only log transactions - that have triggered a warning or an error, or have a status code that is considered to - be relevant (see SecAuditLogRelevantStatus). + RelevantOnly - by default + only log transactions that have triggered a warning or an error, or + have a status code that is considered to be relevant (see SecAuditLogRelevantStatus).
+
<literal>SecAuditLog</literal> - Description: Defines the path to the main audit log file. - Syntax: - SecAuditLog /path/to/auditlog - Example Usage: - SecAuditLog /usr/local/apache/logs/audit.log + + Description: Defines the path to the main + audit log file. + + Syntax: SecAuditLog + /path/to/auditlog + + Example Usage: SecAuditLog + /usr/local/apache/logs/audit.log + Processing Phase: N/A + Scope: Any + Version: 2.0.0 Dependencies/Notes: This file is open on @@ -484,521 +673,784 @@ SecAuditLogStorageDir logs/audit SecAuditLog "|/path/to/mlogc /path/to/mlogc.conf"
+
<literal>SecAuditLog2</literal> - Description: Defines the path to the secondary audit log index file - when concurrent logging is enabled. See SecAuditLog2 for - more details. - Syntax: - SecAuditLog2 /path/to/auditlog2 - Example Usage: - SecAuditLog2 /usr/local/apache/logs/audit2.log + + Description: Defines the path to the + secondary audit log index file when concurrent logging is enabled. See + SecAuditLog2 for more details. + + Syntax: SecAuditLog2 + /path/to/auditlog2 + + Example Usage: SecAuditLog2 + /usr/local/apache/logs/audit2.log + Processing Phase: N/A + Scope: Any + Version: 2.1.2 - Dependencies/Notes: A main audit log must be defined via SecAuditLog before this directive may be used. Additionally, - this log is only used for replicating the main audit log index file when concurrent audit - logging is used. It will not be used for non-concurrent audit - logging. + + Dependencies/Notes: A main audit log must be + defined via SecAuditLog before this + directive may be used. Additionally, this log is only used for + replicating the main audit log index file when concurrent audit logging + is used. It will not be used for non-concurrent + audit logging.
+
<literal>SecAuditLogDirMode</literal> - Description: Configures the mode (permissions) of any directories - created for concurrent audit logs using an octal mode (as used in chmod). See SecAuditLogFileMode for controlling the mode of audit log - files. - Syntax: - SecAuditLogDirMode octal_mode|"default" - Example Usage: - SecAuditLogDirMode 02750 + + Description: Configures the mode + (permissions) of any directories created for concurrent audit logs using + an octal mode (as used in chmod). See SecAuditLogFileMode for controlling the mode + of audit log files. + + Syntax: SecAuditLogDirMode octal_mode|"default" + + Example Usage: SecAuditLogDirMode 02750 + Processing Phase: N/A + Scope: Any + Version: 2.5.10 - Dependencies/Notes: 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. + + Dependencies/Notes: 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. + - The process umask may still limit the mode if it is being more restrictive than the - mode set using this directive. + The process umask may still limit the mode if it is being more + restrictive than the mode set using this directive.
+
<literal>SecAuditLogFileMode</literal> - 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 octal_mode|"default" - Example Usage: - SecAuditLogFileMode 00640 + + 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 + octal_mode|"default" + + Example Usage: SecAuditLogFileMode 00640 + Processing Phase: N/A + Scope: Any + Version: 2.5.10 - Dependencies/Notes: 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. + + Dependencies/Notes: 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. + - The process umask may still limit the mode if it is being more restrictive than the - mode set using this directive. + The process umask may still limit the mode if it is being more + restrictive than the mode set using this directive.
+
<literal>SecAuditLogParts</literal> - Description: Defines which part of each transaction are going to be - recorded in audit log. Each part is assigned a single letter. If a letter appears in the - list then the equivalent part of each transactions will be recorded. See below for the list - of all parts. - Syntax: - SecAuditLogParts PARTS - Example Usage: - SecAuditLogParts ABCFHZ + + Description: Defines which part of each + transaction are going to be recorded in audit log. Each part is assigned + a single letter. If a letter appears in the list then the equivalent + part of each transactions will be recorded. See below for the list of + all parts. + + Syntax: SecAuditLogParts PARTS + + Example Usage: SecAuditLogParts ABCFHZ + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: At this time ModSecurity does not log response - bodies of stock Apache responses (e.g. 404), or the - Server and Date - response headers. + + Dependencies/Notes: At this time ModSecurity + does not log response bodies of stock Apache responses (e.g. 404), or the Server and Date response headers. + Default: ABCFHZ. + - Please refer to the ModSecurity Data Formats document for a detailed description of - every available part. + Please refer to the ModSecurity Data Formats document for a + detailed description of every available part. + Available audit log parts: + - A - audit log header (mandatory) + 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) + C - request body (present + only if the request body exists and ModSecurity is configured to + intercept it) + - D - RESERVED for intermediary response headers, - not implemented yet. + 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). 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). + 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). 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). + 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. + G - RESERVED for the actual + response body, not implemented yet. + - H - audit log trailer + 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. + 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 - RESERVED. This part, when implemented, will - contain information about the files uploaded using multipart/form-data encoding. + J - RESERVED. This part, + when implemented, will contain 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 + 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) + Z - final boundary, + signifies the end of the entry (mandatory)
+
<literal>SecAuditLogRelevantStatus</literal> - 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\d[^4]) + + 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\d[^4]) + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Must have the SecAuditEngine - set to RelevantOnly. The parameter is a regular expression. - The main purpose of this directive is to allow you to configure audit logging for only - transactions that generate the specified HTTP Response Status Code. This directive is often - used to the decrease the total size of the audit log file. Keep in mind that if this - parameter is used, then successful attacks that result in a 200 OK status code will not be - logged. + + Dependencies/Notes: Must have the + SecAuditEngine set to + RelevantOnly. The parameter is a regular + expression. + + The main purpose of this directive is to allow you to configure + audit logging for only transactions that generate the specified HTTP + Response Status Code. This directive is often used to the decrease the + total size of the audit log file. Keep in mind that if this parameter is + used, then successful attacks that result in a 200 OK status code will + not be logged.
+
<literal>SecAuditLogStorageDir</literal> - Description: Configures the storage directory where concurrent - audit log entries are to be stored. - Syntax: - SecAuditLogStorageDir /path/to/storage/dir - Example Usage: - SecAuditLogStorageDir /usr/local/apache/logs/audit + + Description: Configures the storage directory + where concurrent audit log entries are to be stored. + + Syntax: SecAuditLogStorageDir + /path/to/storage/dir + + Example Usage: SecAuditLogStorageDir + /usr/local/apache/logs/audit + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: SecAuditLogType must be set to Concurrent. The - directory must already be created before starting Apache and it must be writable by the web - server user as new files are generated at runtime. - As with all logging mechanisms, ensure that you specify a file system location that has - adequate disk space and is not on the root partition. + + Dependencies/Notes: SecAuditLogType must be + set to Concurrent. The directory must already be created before starting + Apache and it must be writable by the web server user as new files are + generated at runtime. + + As with all logging mechanisms, ensure that you specify a file + system location that has adequate disk space and is not on the root + partition.
+
<literal>SecAuditLogType</literal> - Description: Configures the type of audit logging mechanism to be - used. - Syntax: - SecAuditLogType Serial|Concurrent - Example Usage: - SecAuditLogType Serial + + Description: Configures the type of audit + logging mechanism to be used. + + Syntax: SecAuditLogType Serial|Concurrent + + Example Usage: SecAuditLogType Serial + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Must specify SecAuditLogStorageDir if you use concurrent logging. + + Dependencies/Notes: Must specify + SecAuditLogStorageDir if you use concurrent + logging. + Possible values are: + - Serial - all audit log entries will be stored in - the main audit logging file. This is more convenient for casual use but it is slower as - only one audit log entry can be written to the file at any one file. + Serial - all audit log + entries will be stored in the main audit logging file. This is more + convenient for casual use but it is slower as only one audit log + entry can be written to the file at any one file. + - Concurrent - audit log entries will be stored in - separate files, one for each transaction. Concurrent logging is the mode to use if you - are going to send the audit log data off to a remote ModSecurity Console host. + Concurrent - audit log + entries will be stored in separate files, one for each transaction. + Concurrent logging is the mode to use if you are going to send the + audit log data off to a remote ModSecurity Console host.
+
- <literal>SecCacheTransformations</literal> (Deprecated/Experimental) - Description: Controls caching of transformations. 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" + <literal>SecCacheTransformations</literal> + (Deprecated/Experimental) + + Description: Controls caching of + transformations. 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" + Processing Phase: N/A + Scope: Any + Version: 2.5.0 + Dependencies/Notes: N/A + First parameter: + - On - cache transformations (per transaction, per - phase) allowing identical transformations to be performed only once. (default) + On - cache transformations + (per transaction, per phase) allowing identical transformations to + be performed only once. (default) + - Off - do not cache any transformations, forcing - all transformations to be performed for each rule executed. + Off - do not cache any + transformations, forcing all transformations to be performed for + each rule executed. + The following options are allowed (comma separated): + - incremental:on|off - enabling this option will - cache every transformation instead of just the final transformation. (default: - off) + incremental:on|off - + enabling this option will cache every transformation instead of just + the final transformation. (default: off) + - maxitems:N - do not allow more than N - transformations to be cached. The cache will then be disabled. A zero value is - interpreted as "unlimited". This option may be useful to limit caching for a form with a - large number of ARGS. (default: 512) + maxitems:N - do not allow + more than N transformations to be cached. The cache will then be + disabled. A zero value is interpreted as "unlimited". This option + may be useful to limit caching for a form with a large number of + ARGS. (default: 512) + - minlen:N - do not cache the transformation if the - value's length is less than N bytes. (default: 32) + minlen:N - do not cache the + transformation if the value's length is less than N bytes. (default: + 32) + - maxlen:N - do not cache the transformation if the - value's length is more than N bytes. A zero value is interpreted as "unlimited". - (default: 1024) + maxlen:N - do not cache the + transformation if the value's length is more than N bytes. A zero + value is interpreted as "unlimited". (default: 1024)
+
<literal>SecChrootDir</literal> - 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 + + 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 + Processing Phase: N/A + Scope: Main + Version: 2.0.0 - Dependencies/Notes: 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 static files only, or running - scripts using modules.builds. Some problems you might encounter with more complex - setups: + + Dependencies/Notes: 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 static files only, or running scripts using + modules.builds. 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). + 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 uses sendmail and sendmail is outside the - jail. + You cannot send email from PHP because it uses sendmail and + sendmail is outside the jail. + In some cases Apache graceful (reload) no longer works. - 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. + + 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.
+
<literal>SecComponentSignature</literal> - Description: Appends component signature to the ModSecurity - signature. - Syntax: SecComponentSignature "COMPONENT_NAME/X.Y.Z - (COMMENT)" - Example usage: SecComponentSignature "Core - Rules/1.2.3" + + Description: Appends component signature to + the ModSecurity signature. + + Syntax: SecComponentSignature + "COMPONENT_NAME/X.Y.Z (COMMENT)" + + Example usage: SecComponentSignature + "Core Rules/1.2.3" + Processing Phase: N/A + Scope: Main + Version: 2.5.0 - Dependencies/Notes: This directive should be used to make the - presence of significant ModSecurity components known. The entire signature will be recorded - in transaction audit log. It should be used by ModSecurity module and rule set writers to - make debugging easier. + + Dependencies/Notes: This directive should be + used to make the presence of significant ModSecurity components known. + The entire signature will be recorded in transaction audit log. It + should be used by ModSecurity module and rule set writers to make + debugging easier.
+
<literal>SecContentInjection</literal> - Description: Enables content injection using actions append and prepend. - Syntax: - SecContentInjection (On|Off) - Example Usage: - SecContentInjection On + + Description: Enables content injection using + actions append and prepend. + + Syntax: SecContentInjection + (On|Off) + + Example Usage: SecContentInjection + On + Processing Phase: N/A + Scope: Any + Version: 2.5.0 + Dependencies/Notes: N/A
+
<literal>SecCookieFormat</literal> - Description: Selects the cookie format that will be used in the - current configuration context. - Syntax: - SecCookieFormat 0|1 - Example Usage: - SecCookieFormat 0 + + Description: Selects the cookie format that + will be used in the current configuration context. + + Syntax: SecCookieFormat 0|1 + + Example Usage: SecCookieFormat 0 + Processing Phase: N/A + Scope: Any + Version: 2.0.0 + Dependencies/Notes: None + Possible values are: + - 0 - use version 0 (Netscape) cookies. This is - what most applications use. It is the default value. + 0 - use version 0 + (Netscape) cookies. This is what most applications use. It is the + default value. + - 1 - use version 1 cookies. + 1 - use version 1 + cookies.
+
<literal>SecDataDir</literal> - Description: Path where persistent data (e.g. IP address data, - session data, etc) is to be stored. - Syntax: - SecDataDir /path/to/dir - Example Usage: - SecDataDir /usr/local/apache/logs/data + + Description: Path where persistent data (e.g. + IP address data, session data, etc) is to be stored. + + Syntax: SecDataDir + /path/to/dir + + Example Usage: SecDataDir /usr/local/apache/logs/data + Processing Phase: N/A + Scope: Main - Dependencies/Notes: This directive is needed when initcol, setsid - an setuid are used. Must be writable by the web server user. + + Dependencies/Notes: This directive is needed + when initcol, setsid an setuid are used. Must be writable by the web + server user.
+
<literal>SecDebugLog</literal> - 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 + + 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 + Processing Phase: N/A + Scope: Any + Version: 2.0.0 + Dependencies/Notes: None
+
<literal>SecDebugLogLevel</literal> - 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 + + 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 + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Levels 1 - 3 - are always sent to the Apache error log. Therefore you can always use level 0 as the default logging level in production. Level 5 is useful when debugging. It is not advisable to use higher - logging levels in production as excessive logging can slow down server significantly. + + Dependencies/Notes: Levels 1 - 3 are always sent to the Apache error log. + Therefore you can always use level 0 + as the default logging level in production. Level 5 is useful when debugging. It is not + advisable to use higher logging levels in production as excessive + logging can slow down server significantly. + Possible values are: + 0 - no logging. + - 1 - errors (intercepted requests) only. + 1 - errors (intercepted + requests) only. + 2 - warnings. + 3 - notices. + - 4 - details of how transactions are - handled. + 4 - details of how + transactions are handled. + - 5 - as above, but including information about - each piece of information handled. + 5 - as above, but including + information about each piece of information handled. + - 9 - log everything, including very detailed - debugging information. + 9 - log everything, + including very detailed debugging information.
+
<literal>SecDefaultAction</literal> - Description: Defines the default action to take on a rule - match. - Syntax: - SecDefaultAction action1,action2,action3 - Example Usage: - SecDefaultAction - log,auditlog,deny,status:403,phase:2 + + Description: Defines the default action to + take on a rule match. + + Syntax: SecDefaultAction + action1,action2,action3 + + Example Usage: SecDefaultAction + log,auditlog,deny,status:403,phase:2 + Processing Phase: Any + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Rules following a SecDefaultAction directive will inherit this setting unless a specific action - is specified for an individual rule or until another SecDefaultAction is - specified. Take special note that in the logging disruptive actions are not allowed, but - this can inadvertently be inherited using a disruptive action in SecDefaultAction. - The default value is minimal (differing from previous versions): + + Dependencies/Notes: Rules following a + SecDefaultAction directive will inherit this setting + unless a specific action is specified for an individual rule or until + another SecDefaultAction is specified. Take special + note that in the logging disruptive actions are not allowed, but this + can inadvertently be inherited using a disruptive action in + SecDefaultAction. + + The default value is minimal (differing from previous + versions): + SecDefaultAction phase:2,log,auditlog,pass + - SecDefaultAction must specify a disruptive action and a processing - phase and cannot contain metadata actions. + SecDefaultAction must specify a disruptive + action and a processing phase and cannot contain metadata + actions. + - SecDefaultAction is not inherited across - configuration contexts. (For an example of why this may be a problem for you, read the - following ModSecurity Blog entry http://blog.modsecurity.org/2008/07/modsecurity-tri.html). + SecDefaultAction is not + inherited across configuration contexts. (For an example of why this + may be a problem for you, read the following ModSecurity Blog entry + http://blog.modsecurity.org/2008/07/modsecurity-tri.html).
+
<literal>SecGeoLookupDb</literal> - Description: Defines the path to the geographical database - file. - Syntax: - SecGeoLookupDb /path/to/db - Example Usage: - SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat + + Description: Defines the path to the + geographical database file. + + Syntax: SecGeoLookupDb /path/to/db + + Example Usage: SecGeoLookupDb + /usr/local/geo/data/GeoLiteCity.dat + Processing Phase: N/A + Scope: Any + Version: 2.5.0 - Dependencies/Notes: Check out maxmind.com for - free database files. + + Dependencies/Notes: Check out + maxmind.com for free database files.
+
<literal>SecGuardianLog</literal> - Description: Configuration directive to use the httpd-guardian - script to monitor for Denial of Service (DoS) attacks. - Syntax: - SecGuardianLog |/path/to/httpd-guardian - Example Usage: - SecGuardianLog - |/usr/local/apache/bin/httpd-guardian + + Description: Configuration directive to use + the httpd-guardian script to monitor for Denial of Service (DoS) + attacks. + + Syntax: SecGuardianLog |/path/to/httpd-guardian + + Example Usage: SecGuardianLog + |/usr/local/apache/bin/httpd-guardian + Processing Phase: N/A + Scope: Main + Version: 2.0.0 - Dependencies/Notes: By default httpd-guardian will defend against - clients that send more than 120 requests in a minute, or more than 360 requests in five - minutes. - Since 1.9, ModSecurity supports a new directive, SecGuardianLog, that is designed to - send all access data to another program using the piped logging feature. Since Apache is - typically deployed in a multi-process fashion, making information sharing difficult, the - idea is to deploy a single external process to observe all requests in a stateful manner, - providing additional protection. - Development of a state of the art external protection tool will be a focus of subsequent - ModSecurity releases. However, a fully functional tool is already available as part of the - Apache httpd tools - project. The tool is called httpd-guardian and can be used to defend against - Denial of Service attacks. It uses the blacklist tool (from the same project) to interact - with an iptables-based (Linux) or pf-based (*BSD) 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: + + Dependencies/Notes: By default httpd-guardian + will defend against clients that send more than 120 requests in a + minute, or more than 360 requests in five minutes. + + Since 1.9, ModSecurity supports a new directive, SecGuardianLog, + that is designed to send all access data to another program using the + piped logging feature. Since Apache is typically deployed in a + multi-process fashion, making information sharing difficult, the idea is + to deploy a single external process to observe all requests in a + stateful manner, providing additional protection. + + Development of a state of the art external protection tool will be + a focus of subsequent ModSecurity releases. However, a fully functional + tool is already available as part of the Apache httpd tools + project. The tool is called httpd-guardian and can be used to + defend against Denial of Service attacks. It uses the blacklist tool + (from the same project) to interact with an iptables-based (Linux) or + pf-based (*BSD) 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
+
<literal>SecMarker</literal> - Description: Adds a fixed rule marker in the ruleset to be used as - a target in a skipAfter action. A SecMarker directive - essentially creates a rule that does nothing and whose only purpose it to carry the given - ID. - Syntax: - SecMarker ID - Example Usage: - SecMarker 9999 + + Description: Adds a fixed rule marker in the + ruleset to be used as a target in a skipAfter action. + A SecMarker directive essentially creates a rule that + does nothing and whose only purpose it to carry the given ID. + + Syntax: SecMarker + ID + + Example Usage: SecMarker 9999 + Processing Phase: Any + Scope: Any + Version: 2.5.0 + Dependencies/Notes: None - - SecRule REQUEST_URI "^/$" \ + + SecRule REQUEST_URI "^/$" \ "chain,t:none,t:urlDecode,t:lowercase,t:normalisePath,skipAfter:99" SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain" SecRule REQUEST_HEADERS:User-Agent \ @@ -1008,9 +1460,9 @@ SecRule &REQUEST_HEADERS:Host "@eq 0" \ SecRule &REQUEST_HEADERS:Accept "@eq 0" \ "log,deny,log,status:400,id:15,msg:'Request Missing an Accept Header'" -SecMarker 99 - +SecMarker 99
+
<literal>SecPcreMatchLimit</literal> @@ -1097,427 +1549,659 @@ SecRule TX:/^MSC_/ "!@eq 0" "phase:5,pass,log,auditlog,msg:'Potential REDoS'"

<literal>SecPdfProtect</literal> - Description: Enables the PDF XSS protection functionality. 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. - Syntax: - SecPdfProtect On|Off - Example Usage: - SecPdfProtect On + + Description: Enables the PDF XSS protection + functionality. 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. + + Syntax: SecPdfProtect On|Off + + Example Usage: SecPdfProtect On + Processing Phase: N/A + Scope: Any + Version: 2.5.0 + Dependencies/Notes: None
+
<literal>SecPdfProtectMethod</literal> - Description: Configure desired protection method to be used when - requests for PDF files are detected. 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 only works 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!"). - Syntax: - SecPdfProtectMethod method - Example Usage: - SecPdfProtectMethod TokenRedirection + + Description: Configure desired protection + method to be used when requests for PDF files are detected. 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 only works 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!"). + + Syntax: SecPdfProtectMethod method + + Example Usage: SecPdfProtectMethod TokenRedirection + Processing Phase: N/A + Scope: Any + Version: 2.5.0 + Dependencies/Notes: None + Default: - TokenRedirection + TokenRedirection
+
<literal>SecPdfProtectSecret</literal> - Description: Defines the secret that will be used to construct - one-time tokens. 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. - Syntax: - SecPdfProtectSecret secret - Example Usage: - SecPdfProtectSecret MyRandomSecretString + + Description: Defines the secret that will be + used to construct one-time tokens. 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. + + Syntax: SecPdfProtectSecret secret + + Example Usage: SecPdfProtectSecret + MyRandomSecretString + Processing Phase: N/A + Scope: Any + Version: 2.5.0 + Dependencies/Notes: None
+
<literal>SecPdfProtectTimeout</literal> - Description: Defines the token timeout. After token expires it can - no longer be used to allow access to PDF file. Request will be allowed through but the PDF - will be delivered as attachment. - Syntax: - SecPdfProtectTimeout timeout - Example Usage: - SecPdfProtectTimeout 10 + + Description: Defines the token timeout. After + token expires it can no longer be used to allow access to PDF file. + Request will be allowed through but the PDF will be delivered as + attachment. + + Syntax: SecPdfProtectTimeout timeout + + Example Usage: SecPdfProtectTimeout 10 + Processing Phase: N/A + Scope: Any + Version: 2.5.0 + Dependencies/Notes: None - Default: - 10 + + Default: 10
+
<literal>SecPdfProtectTokenName</literal> - Description: Defines the name of the token. The only reason you - would want to change the name of the token is if you wanted to hide the fact 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. - Syntax: - SecPdfProtectTokenName name - Example Usage: - SecPdfProtectTokenName PDFTOKEN + + Description: Defines the name of the token. + The only reason you would want to change the name of the token is if you + wanted to hide the fact 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. + + Syntax: SecPdfProtectTokenName name + + Example Usage: SecPdfProtectTokenName PDFTOKEN + Processing Phase: N/A + Scope: Any + Version: 2.5.0 + Dependencies/Notes: None - Default: - PDFTOKEN + + Default: PDFTOKEN
+
<literal>SecRequestBodyAccess</literal> - Description: Configures whether request bodies will be buffered and - processed by ModSecurity by default. - Syntax: - SecRequestBodyAccess On|Off - Example Usage: - SecRequestBodyAccess On + + Description: Configures whether request + bodies will be buffered and processed by ModSecurity by default. + + Syntax: SecRequestBodyAccess On|Off + + Example Usage: SecRequestBodyAccess On + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: This directive is required if you plan to - inspect request bodies. Inspection can only be carried out in phases 2 and higher, using the - REQUEST_BODY variable/location. If any of these 3 conditions aren't - satisfied, the inspection will not work. + + Dependencies/Notes: This directive is + required if you plan to inspect request bodies. Inspection can only be + carried out in phases 2 and higher, using the + REQUEST_BODY variable/location. If any of these 3 + conditions aren't satisfied, the inspection will not work. + Possible values are: + - On - access request bodies. + On - access request + bodies. + - Off - do not attempt to access request - bodies. + Off - do not attempt to + access request bodies.
+
<literal>SecRequestBodyLimit</literal> - Description: Configures the maximum request body size ModSecurity - will accept for buffering. - Syntax: - SecRequestBodyLimit NUMBER_IN_BYTES - Example Usage: - SecRequestBodyLimit 134217728 + + Description: Configures the maximum request + body size ModSecurity will accept for buffering. + + Syntax: SecRequestBodyLimit NUMBER_IN_BYTES + + Example Usage: SecRequestBodyLimit 134217728 + Scope: Any + Version: 2.0.0 - Dependencies/Notes: 131072 KB (134217728 bytes) is the default - setting. Anything over this limit will be rejected with status code 413 Request Entity Too - Large. There is a hard limit of 1 GB. + + Dependencies/Notes: 131072 KB (134217728 + bytes) is the default setting. Anything over this limit will be rejected + with status code 413 Request Entity Too Large. There is a hard limit of + 1 GB.
+
<literal>SecRequestBodyNoFilesLimit</literal> - Description: Configures the maximum request body size ModSecurity - will accept for buffering, excluding the size of files being transported in the request. - This directive comes handy to further 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. Since 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. - Syntax: - SecRequestBodyNoFilesLimit NUMBER_IN_BYTES - Example Usage: - SecRequestBodyLimit 131072 + + Description: Configures the maximum request + body size ModSecurity will accept for buffering, excluding the size of + files being transported in the request. This directive comes handy to + further 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. Since 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. + + Syntax: SecRequestBodyNoFilesLimit + NUMBER_IN_BYTES + + Example Usage: SecRequestBodyLimit 131072 + Scope: Any + Version: 2.5.0 - Dependencies/Notes: 1 MB (1048576 bytes) is the default setting. - This value is very conservative. 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. + + Dependencies/Notes: 1 MB (1048576 bytes) is + the default setting. This value is very conservative. 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.
+
<literal>SecRequestBodyInMemoryLimit</literal> - Description: Configures the maximum request body size ModSecurity - will store in memory. - Syntax: - SecRequestBodyInMemoryLimit NUMBER_IN_BYTES - Example Usage: - SecRequestBodyInMemoryLimit 131072 + + Description: Configures the maximum request + body size ModSecurity will store in memory. + + Syntax: SecRequestBodyInMemoryLimit + NUMBER_IN_BYTES + + Example Usage: SecRequestBodyInMemoryLimit 131072 + Processing Phase: N/A + Scope: Any + Version: 2.0.0 + Dependencies/Notes: None + By default the limit is 128 KB: + # Store up to 128 KB in memory SecRequestBodyInMemoryLimit 131072
+
<literal>SecResponseBodyLimit</literal> - Description: Configures the maximum response body size that will be - accepted for buffering. - Syntax: - SecResponseBodyLimit NUMBER_IN_BYTES - Example Usage: - SecResponseBodyLimit 524228 + + Description: Configures the maximum response + body size that will be accepted for buffering. + + Syntax: SecResponseBodyLimit NUMBER_IN_BYTES + + Example Usage: SecResponseBodyLimit 524228 + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: 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 marked for buffering. There is a hard limit of 1 GB. + + Dependencies/Notes: 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 + marked for buffering. There is a hard limit of 1 GB. + By default this limit is configured to 512 KB: + # Buffer response bodies of up to 512 KB in length SecResponseBodyLimit 524288
+
<literal>SecResponseBodyLimitAction</literal> - Description: Controls what happens once a response body limit, - configured with SecResponseBodyLimit, is encountered. 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 only applies to cases where 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. + + Description: Controls what happens once a + response body limit, configured with + SecResponseBodyLimit, is encountered. 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 only applies to + cases where 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. + Syntax: SecResponseBodyLimitAction - Reject|ProcessPartial - Example Usage: SecResponseBodyLimitAction - ProcessPartial + Reject|ProcessPartial + + Example Usage: + SecResponseBodyLimitAction ProcessPartial + Processing Phase: N/A + Scope: Any + Version: 2.5.0 + Dependencies/Notes: None
+
<literal>SecResponseBodyMimeType</literal> - Description: Configures which - MIME types are to be considered for response body buffering. - Syntax: - SecResponseBodyMimeType mime/type - Example Usage: - SecResponseBodyMimeType text/plain text/html + + Description: Configures which MIME types are to be considered for response + body buffering. + + Syntax: SecResponseBodyMimeType mime/type + + Example Usage: SecResponseBodyMimeType text/plain + text/html + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Multiple - SecResponseBodyMimeType directives can be used to add to the list of MIME types. You can also use the special null value to request ModSecurity to inspect the bodies of the responses that - do not specify a MIME type. - The default value is text/plain text/html: + + Dependencies/Notes: Multiple SecResponseBodyMimeType directives can be + used to add to the list of MIME + types. You can also use the special null value to + request ModSecurity to inspect the bodies of the responses that do not + specify a MIME type. + + The default value is text/plain + text/html: + SecResponseBodyMimeType text/plain text/html
+
<literal>SecResponseBodyMimeTypesClear</literal> - 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 + + 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 + Processing Phase: N/A + Scope: Any + Version: 2.0.0 + Dependencies/Notes: None
+
<literal>SecResponseBodyAccess</literal> - Description: Configures whether response bodies are to be buffer - and analysed or not. - Syntax: - SecResponseBodyAccess On|Off - Example Usage: - SecResponseBodyAccess On + + Description: Configures whether response + bodies are to be buffer and analysed or not. + + Syntax: SecResponseBodyAccess On|Off + + Example Usage: SecResponseBodyAccess On + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: This directive is required if you plan to - inspect HTML responses. This directive must be used along with the "phase:4" processing - phase action and RESPONSE_BODY variable/location. If any of these 3 parts are not - configured, you will not be able to inspect the response bodies. + + Dependencies/Notes: This directive is + required if you plan to inspect HTML responses. This directive must be + used along with the "phase:4" processing phase action and RESPONSE_BODY + variable/location. If any of these 3 parts are not configured, you will + not be able to inspect the response bodies. + Possible values are: + - On - access response bodies (but only if the MIME - type matches, see above). + On - access response bodies + (but only if the MIME type matches, see above). + - Off - do not attempt to access response - bodies. + Off - do not attempt to + access response bodies.
+
<literal>SecRule</literal> - Description: - SecRule is the main ModSecurity directive. It is used to - analyse data and perform actions based on the results. - Syntax: - SecRule VARIABLES OPERATOR [ACTIONS] - Example Usage: - SecRule REQUEST_URI "attack" \ - "phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath" + + Description: SecRule is the main ModSecurity directive. It + is used to analyse data and perform actions based on the results. + + Syntax: SecRule + VARIABLES OPERATOR [ACTIONS] + + Example Usage: SecRule REQUEST_URI "attack" \ + + + "phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath" + Processing Phase: Any + Scope: Any + Version: 2.0.0 + Dependencies/Notes: None + In general, the format of this rule is as follows: + SecRule VARIABLES OPERATOR [ACTIONS] - The second part, OPERATOR, specifies how they are - going to be checked. The third (optional) part, ACTIONS, - specifies what to do whenever the operator used performs a successful match against a - variable. + + The second part, OPERATOR, + specifies how they are going to be checked. The third (optional) part, + ACTIONS, specifies what to do + whenever the operator used performs a successful match against a + variable. +
Variables in rules - The first part, VARIABLES, specifies which - variables are to be checked. For example, the following rule will reject a transaction - that has the word dirty in the URI: + + The first part, VARIABLES, + specifies which variables are to be checked. For example, the + following rule will reject a transaction that has the word + dirty in the URI: + SecRule ARGS dirty + Each rule can specify one or more variables: + SecRule ARGS|REQUEST_HEADERS:User-Agent dirty - There is a third format supported by the selection operator - XPath expression. XPath - expressions can only used against the special variable XML, which is available only of the - request body was processed as XML. + + There is a third format supported by the selection operator - + XPath expression. XPath expressions can only used against the special + variable XML, which is available only of the request body was + processed as XML. + SecRule XML:/xPath/Expression dirty + - Not all collections support all selection operator format types. You should refer to - the documentation of each collection to determine what is and isn't supported. + Not all collections support all selection operator format + types. You should refer to the documentation of each collection to + determine what is and isn't supported.
+
Collections - A variable can contain one or many pieces of data, depending on the nature of the - variable and the way it is used. We've seen examples of both approaches in the previous - section. When a variable can contain more than one value we refer to it as a - collection. - Collections are always expanded before a rule is run. For example, the following - rule: + + A variable can contain one or many pieces of data, depending on + the nature of the variable and the way it is used. We've seen examples + of both approaches in the previous section. When a variable can + contain more than one value we refer to it as a + collection. + + Collections are always expanded before a rule is run. For + example, the following rule: + SecRule ARGS dirty + will be expanded to: + SecRule ARGS:p dirty SecRule ARGS:q dirty - in a requests that has only two parameters, named p and q. + + in a requests that has only two parameters, named + p and q. + Collections come in several flavours: + Read-only + - Created at runtime using transaction data. For example: ARGS - (contains a list of all request parameter values) and REQUEST_HEADERS (contains a list of all request header values). + Created at runtime using transaction data. For example: + ARGS (contains a list of all request + parameter values) and REQUEST_HEADERS + (contains a list of all request header values). + Transient Read/Write + - The TX collection is created (empty) for every transaction. - Rules can read from it and write to it (using the setvar action, - for example), but the information stored in this collection will not survive the end - of transaction. + The TX collection is created (empty) + for every transaction. Rules can read from it and write to it + (using the setvar action, for example), but + the information stored in this collection will not survive the + end of transaction. + Persistent Read/Write + - There are several collections that can be written to, but which are persisted to - the storage backend. These collections are used to track clients across - transactions. Examples of collections that fall into this type are IP, SESSION and USER. + There are several collections that can be written to, but + which are persisted to the storage backend. These collections + are used to track clients across transactions. Examples of + collections that fall into this type are IP, + SESSION and USER.
+
Operators in rules - In the simplest possible case you will use a regular expression pattern as the second - rule parameter. This is what we've done in the examples above. If you do this ModSecurity - assumes you want to use the rx (regular expression) - operator. You can also explicitly specify the operator you want to use by using @, followed by the name of an operator, at the beginning of - the second SecRule parameter: + + In the simplest possible case you will use a regular expression + pattern as the second rule parameter. This is what we've done in the + examples above. If you do this ModSecurity assumes you want to use the + rx (regular expression) operator. + You can also explicitly specify the operator you want to use by using + @, followed by the name of an + operator, at the beginning of the second SecRule + parameter: + SecRule ARGS "@rx dirty" - Note how we had to use double quotes to delimit the second rule parameter. This is - because the second parameter now has whitespace in it. Any number of whitespace characters - can follow the name of the operator. If there are any non-whitespace characters there, - they will all be treated as a special parameter to the operator. In the case of the - regular expression operator the special parameter is the pattern that will be used for - comparison. - The @ can be the second character if you are using negation to negate the result - returned by the operator: + + Note how we had to use double quotes to delimit the second rule + parameter. This is because the second parameter now has whitespace in + it. Any number of whitespace characters can follow the name of the + operator. If there are any non-whitespace characters there, they will + all be treated as a special parameter to the operator. In the case of + the regular expression operator the special parameter is the pattern + that will be used for comparison. + + The @ can be the second character if you are using negation to + negate the result returned by the operator: + SecRule &ARGS "!@rx ^0$"
+
Operator negation - Operator results can be negated by using an exclamation mark at the beginning of the - second parameter. The following rule matches if the word dirty does - not appear in the User-Agent request - header: + + Operator results can be negated by using an exclamation mark at + the beginning of the second parameter. The following rule matches if + the word dirty does not appear + in the User-Agent request header: + SecRule REQUEST_HEADERS:User-Agent !dirty - You can use the exclamation mark in combination with any parameter. If you do, the - exclamation mark needs to go first, followed by the explicit operator reference. The - following rule has the same effect as the previous example: + + You can use the exclamation mark in combination with any + parameter. If you do, the exclamation mark needs to go first, followed + by the explicit operator reference. The following rule has the same + effect as the previous example: + SecRule REQUEST_HEADERS:User-Agent "!@rx dirty" - If you need to use negation in a rule that is going to be applied to several variables - then it may not be immediately clear what will happen. Consider the following - example: + + If you need to use negation in a rule that is going to be + applied to several variables then it may not be immediately clear what + will happen. Consider the following example: + SecRule ARGS:p|ARGS:q !dirty + The above rule is identical to: + SecRule ARGS:p !dirty SecRule ARGS:q !dirty + - Negation is applied to operations against individual operations, not agains the - entire variable list. + Negation is applied to operations against individual + operations, not agains the entire variable list.
+
Actions in rules - The third parameter, ACTIONS, can be omitted only - because there is a helper feature that specifies the default action list. If the parameter - isn't omitted the actions specified in the parameter will be merged with the default - action list to create the actual list of actions that will be processed on a rule - match. + + The third parameter, ACTIONS, + can be omitted only because there is a helper feature that specifies + the default action list. If the parameter isn't omitted the actions + specified in the parameter will be merged with the default action list + to create the actual list of actions that will be processed on a rule + match.
+
<literal>SecRuleInheritance</literal> - Description: Configures whether the current context will inherit - rules from the parent context (configuration options are inherited in most cases - you - should look up the documentation for every directive to determine if it is inherited or - not). - Syntax: - SecRuleInheritance On|Off - Example Usage: - SecRuleInheritance Off + + Description: Configures whether the current + context will inherit rules from the parent context (configuration + options are inherited in most cases - you should look up the + documentation for every directive to determine if it is inherited or + not). + + Syntax: SecRuleInheritance On|Off + + Example Usage: SecRuleInheritance Off + Processing Phase: Any + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Before ModSecurity 2.6.x it was not possible - for resource-specific contexts (e.g. Location, Directory, etc) to override phase 1 rules configured in the main - server or in the virtual server. Starting with ModSecurity 2.6 this limitation has been - lifted and the rules and the configuration directives can be freely used across - configuration contexts. - Example: The following example shows where ModSecurity may be enabled in the main Apache - configuration scope, however you might want to configure your VirtualHosts differently. In - the first example, the first VirtualHost is not inheriting the ModSecurity main config - directives and in the second one it is. + + Dependencies/Notes: Before ModSecurity 2.6.x + it was not possible for resource-specific contexts (e.g. Location, Directory, etc) to override phase 1 rules + configured in the main server or in the virtual server. Starting with + ModSecurity 2.6 this limitation has been lifted and the rules and the + configuration directives can be freely used across configuration + contexts. + + Example: The following example shows where ModSecurity may be + enabled in the main Apache configuration scope, however you might want + to configure your VirtualHosts differently. In the first example, the + first VirtualHost is not inheriting the ModSecurity main config + directives and in the second one it is. + SecRuleEngine On SecDefaultAction log,pass,phase:2 ... @@ -1536,104 +2220,161 @@ ServerAlias www.app2.com SecRuleInheritance On SecRule ARGS "attack" ... </VirtualHost> + Possible values are: + - On - inherit rules from the parent - context. + On - inherit rules from the + parent context. + - Off - do not inherit rules from the parent - context. + Off - do not inherit rules + from the parent context. + - 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 section Configuration Sections. + 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 section Configuration + Sections.
+
<literal>SecRuleEngine</literal> - Description: Configures the rules engine. - Syntax: - SecRuleEngine On|Off|DetectionOnly - Example Usage: - SecRuleEngine On + + Description: Configures the rules + engine. + + Syntax: SecRuleEngine On|Off|DetectionOnly + + Example Usage: SecRuleEngine On + Processing Phase: Any + Scope: Any + Version: 2.0.0 - Dependencies/Notes: This directive can also be controlled by the - ctl action (ctl:ruleEngine=off) for per rule processing. + + Dependencies/Notes: This directive can also + be controlled by the ctl action (ctl:ruleEngine=off) for per rule + processing. + Possible values are: + On - process rules. + - Off - do not process rules. + Off - do not process + rules. + - DetectionOnly - process rules but never intercept - transactions, even when rules are configured to do so. + DetectionOnly - process + rules but never intercept transactions, even when rules are + configured to do so.
+
<literal>SecRuleRemoveById</literal> - Description: Removes matching rules from the parent - contexts. - Syntax: - SecRuleUpdateActionById RULEID ACTIONLIST - Example Usage: - SecRuleRemoveByID 1 2 "9000-9010" + + Description: Removes matching rules from the + parent contexts. + + Syntax: SecRuleUpdateActionById RULEID + ACTIONLIST + + Example Usage: SecRuleRemoveByID 1 2 "9000-9010" + Processing Phase: Any + Scope: Any + Version: 2.0.0 - Dependencies/Notes: This directive supports multiple parameters, - where each parameter can either be a rule ID, or a range. Parameters that contain spaces - must be delimited using double quotes. + + Dependencies/Notes: This directive supports + multiple parameters, where each parameter can either be a rule ID, or a + range. Parameters that contain spaces must be delimited using double + quotes. + SecRuleRemoveById 1 2 5 10-20 "400-556" 673
+
<literal>SecRuleRemoveByMsg</literal> - Description: Removes matching rules from the parent - contexts. - Syntax: - SecRuleRemoveByMsg REGEX - Example Usage: - SecRuleRemoveByMsg "FAIL" + + Description: Removes matching rules from the + parent contexts. + + Syntax: SecRuleRemoveByMsg REGEX + + Example Usage: SecRuleRemoveByMsg "FAIL" + Processing Phase: Any + Scope: Any + Version: 2.0.0 - Dependencies/Notes: This directive supports multiple parameters. - Each parameter is a regular expression that will be applied to the message (specified using - the msg action). + + Dependencies/Notes: This directive supports + multiple parameters. Each parameter is a regular expression that will be + applied to the message (specified using the msg action).
+
<literal>SecRuleScript</literal> (Experimental) - 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" + + 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" + Processing Phase: Any + Scope: Any + Version: 2.5.0 + Dependencies/Notes: None + - 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. + 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() @@ -1663,11 +2404,15 @@ function main() -- 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: + + 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" } ); @@ -1685,87 +2430,136 @@ end -- Nothing wrong found. return nil; end + - 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/. + 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/. + - Lua support is marked as experimental as the way the progamming - interface may continue to evolve while we are working for the best implementation style. - Any user input into the programming interface is appreciated. + Lua support is marked as experimental as + the way the progamming interface may continue to evolve while we are + working for the best implementation style. Any user input into the + programming interface is appreciated.
+
<literal>SecRuleUpdateActionById</literal> - Description: Updates the action list of the specified rule. - Syntax: - SecRuleRemoveById RULEID ACTIONLIST - Example Usage: - SecRuleUpdateActionById 12345 deny,status:403 + + Description: Updates the action list of the + specified rule. + + Syntax: SecRuleRemoveById RULEID ACTIONLIST + + Example Usage: SecRuleUpdateActionById 12345 + deny,status:403 + Processing Phase: Any + Scope: Any + Version: 2.5.0 - Dependencies/Notes: This directive merges the specified action list - with the rule's action list. There are two limitations. The rule ID cannot be changed, nor - can the phase. Further note that actions that may be specified multiple times are appended - to the original. + + Dependencies/Notes: This directive merges the + specified action list with the rule's action list. There are two + limitations. The rule ID cannot be changed, nor can the phase. Further + note that actions that may be specified multiple times are appended to + the original. + SecAction \ "t:lowercase,phase:2,id:12345,pass,msg:'The Message',log,auditlog" SecRuleUpdateActionById 12345 "t:compressWhitespace,deny,status:403,msg:'A new message' - The example above will cause the rule to be executed as if it was specified as - follows: + + The example above will cause the rule to be executed as if it was + specified as follows: + SecAction \ "t:lowercase,phase:2,id:12345,log,auditlog,t:compressWhitespace,deny,status:403,msg:'A new message'"
+
<literal>SecServerSignature</literal> - Description: Instructs ModSecurity to change the data presented in - the "Server:" response header token. - Syntax: - SecServerSignature "WEB SERVER SOFTWARE" - Example Usage: - SecServerSignature "Netscape-Enterprise/6.0" + + Description: Instructs ModSecurity to change + the data presented in the "Server:" response header token. + + Syntax: SecServerSignature "WEB SERVER + SOFTWARE" + + Example Usage: SecServerSignature + "Netscape-Enterprise/6.0" + Processing Phase: N/A + Scope: Main + Version: 2.0.0 - Dependencies/Notes: 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. + + Dependencies/Notes: 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.
+
<literal>SecTmpDir</literal> - Description: Configures the directory where temporary files will be - created. - Syntax: - SecTmpDir /path/to/dir - Example Usage: - SecTmpDir /tmp + + Description: Configures the directory where + temporary files will be created. + + Syntax: SecTmpDir + /path/to/dir + + Example Usage: SecTmpDir /tmp + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Needs to be writable by the Apache user - process. This is the directory location where Apache will swap data to disk if it runs out - of memory (more data than what was specified in the SecRequestBodyInMemoryLimit directive) - during inspection. + + Dependencies/Notes: Needs to be writable by + the Apache user process. This is the directory location where Apache + will swap data to disk if it runs out of memory (more data than what was + specified in the SecRequestBodyInMemoryLimit directive) during + inspection.
+
<literal>SecUploadDir</literal> - Description: Configures the directory where intercepted files will - be stored. - Syntax: - SecUploadDir /path/to/dir - Example Usage: - SecUploadDir /tmp + + Description: Configures the directory where + intercepted files will be stored. + + Syntax: SecUploadDir + /path/to/dir + + Example Usage: SecUploadDir /tmp + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: This directory must be on the same filesystem - as the temporary directory defined with SecTmpDir. This - directive is used with SecUploadKeepFiles. + + Dependencies/Notes: This directory must be on + the same filesystem as the temporary directory defined with SecTmpDir. This directive is used with + SecUploadKeepFiles.
+
<literal>SecUploadFileLimit</literal> @@ -1804,68 +2598,106 @@ SecRuleUpdateActionById 12345 "t:compressWhitespace,deny,status:403,msg:'A new m
<literal>SecUploadFileMode</literal> - Description: Configures the mode (permissions) of any uploaded - files using an octal mode (as used in chmod). - Syntax: - SecUploadFileMode octal_mode|"default" - Example Usage: - SecUploadFileMode 0640 + + Description: Configures the mode + (permissions) of any uploaded files using an octal mode (as used in + chmod). + + Syntax: SecUploadFileMode octal_mode|"default" + + Example Usage: SecUploadFileMode 0640 + Processing Phase: N/A + Scope: Any + Version: 2.1.6 - Dependencies/Notes: 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. + + Dependencies/Notes: 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. + - The process umask may still limit the mode if it is being more restrictive than the - mode set using this directive. + The process umask may still limit the mode if it is being more + restrictive than the mode set using this directive.
+
<literal>SecUploadKeepFiles</literal> - Description: Configures whether or not the intercepted files will - be kept after transaction is processed. - Syntax: - SecUploadKeepFiles On|Off|RelevantOnly - Example Usage: - SecUploadKeepFiles On + + Description: Configures whether or not the + intercepted files will be kept after transaction is processed. + + Syntax: SecUploadKeepFiles On|Off|RelevantOnly + + Example Usage: SecUploadKeepFiles On + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: This directive requires the storage directory - to be defined (using SecUploadDir). + + Dependencies/Notes: This directive requires + the storage directory to be defined (using SecUploadDir). + Possible values are: + - On - Keep uploaded files. + On - Keep uploaded + files. + - Off - Do not keep uploaded files. + Off - Do not keep uploaded + files. + - RelevantOnly - This will keep only those files - that belong to requests that are deemed relevant. + RelevantOnly - This will + keep only those files that belong to requests that are deemed + relevant.
+
<literal>SecWebAppId</literal> - Description: Creates a partition on the server that belongs to one - web application. - Syntax: - SecWebAppId "NAME" - Example Usage: - SecWebAppId "WebApp1" + + Description: Creates a partition on the + server that belongs to one web application. + + Syntax: SecWebAppId + "NAME" + + Example Usage: SecWebAppId "WebApp1" + Processing Phase: N/A + Scope: Any + Version: 2.0.0 - Dependencies/Notes: Partitions are used to avoid collisions between - session IDs and user IDs. This directive must be used if there are multiple applications - deployed on the same server. If it isn't used, a collision between session IDs might occur. - The default value is default. Example: + + Dependencies/Notes: Partitions are used to + avoid collisions between session IDs and user IDs. This directive must + be used if there are multiple applications deployed on the same server. + If it isn't used, a collision between session IDs might occur. The + default value is default. + Example: + <VirtualHost *:80> ServerName app1.com ServerAlias www.app1.com @@ -1883,366 +2715,512 @@ SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass SecAction setsid:%{REQUEST_COOKIES.PHPSESSID} ... </VirtualHost> - In the two examples configurations shown, SecWebAppId is being used in conjunction with - the Apache VirtualHost directives. What this achieves is to create more unique collection - names when being hosted on one server. Normally, when setsid is used, ModSecurity will - create a collection with the name "SESSION" and it will hold the value specified. With using - SecWebAppId as shown in the examples, however, the name of the collection would become - "App1_SESSION" and "App2_SESSION". + + In the two examples configurations shown, SecWebAppId is being + used in conjunction with the Apache VirtualHost directives. What this + achieves is to create more unique collection names when being hosted on + one server. Normally, when setsid is used, ModSecurity will create a + collection with the name "SESSION" and it will hold the value specified. + With using SecWebAppId as shown in the examples, however, the name of + the collection would become "App1_SESSION" and "App2_SESSION". + SecWebAppId is relevant in two cases: + - You are logging transactions/alerts to the ModSecurity Console and you want to use - the web application ID to search only the transactions belonging to that - application. + You are logging transactions/alerts to the ModSecurity Console + and you want to use the web application ID to search only the + transactions belonging to that application. + - You are using the data persistence facility (collections SESSION and USER) and you - need to avoid collisions between sessions and users belonging to different - applications. + You are using the data persistence facility (collections + SESSION and USER) and you need to avoid collisions between sessions + and users belonging to different applications.
+
Processing Phases - ModSecurity 2.x allows rules to be placed in one of the following five phases: + + ModSecurity 2.x allows rules to be placed in one of the following + five phases: + Request headers (REQUEST_HEADERS) + Request body (REQUEST_BODY) + Response headers (RESPONSE_HEADERS) + Response body (RESPONSE_BODY) + Logging (LOGGING) - Below is a diagram of the normal Apache request cycle. In the diagram, the 5 ModSecurity - processing phases are shown. - - - - In order to select the phase a rule executes during, use the phase action either directly - in the rule or in using the SecDefaultAction directive: + + Below is a diagram of the normal Apache request cycle. In the + diagram, the 5 ModSecurity processing phases are shown. + + + + In order to select the phase a rule executes during, use the phase + action either directly in the rule or in using the + SecDefaultAction directive: + SecDefaultAction "log,pass,phase:2" SecRule REQUEST_HEADERS:Host "!^$" "deny,phase:1" + - Keep in mind that rules are executed according to phases, so even if two rules are - adjacent in a configuration file, but are set to execute in different phases, they would not - happen one after the other. The order of rules in the configuration file is important only - within the rules of each phase. This is especially important when using the skip and skipAfter actions. + Keep in mind that rules are executed according to phases, so even + if two rules are adjacent in a configuration file, but are set to + execute in different phases, they would not happen one after the other. + The order of rules in the configuration file is important only within + the rules of each phase. This is especially important when using the + skip and skipAfter actions. + - The LOGGING phase is special. It is executed at the end of each - transaction no matter what happened in the previous phases. This means it will be processed - even if the request was intercepted or the allow action was used to pass - the transaction through. + The LOGGING phase is special. It is executed at + the end of each transaction no matter what happened in the previous + phases. This means it will be processed even if the request was + intercepted or the allow action was used to pass the + transaction through. +
Phase Request Headers - Phase 1 allows you to inspect a transaction of which request headers are available, but - before a request body (if any) has been read. Place rules into this phase when you want - something to happen before a body has been read, or if you want to influence how a body will - be processed (e.g., configure the buffering options or configure request body processors). - Beware that you won't have complete request information available at this point. If a - request has a body, there may be further parameters in it. Use phase 2 when you need to - inspect all request parameters. + + Phase 1 allows you to inspect a transaction of which request + headers are available, but before a request body (if any) has been read. + Place rules into this phase when you want something to happen before a + body has been read, or if you want to influence how a body will be + processed (e.g., configure the buffering options or configure request + body processors). Beware that you won't have complete request + information available at this point. If a request has a body, there may + be further parameters in it. Use phase 2 when you need to inspect all + request parameters.
+
Phase Request Body - This is the general-purpose input analysis phase. Most of the application-oriented rules - should go here. In this phase you are guaranteed to have received the request arguments - (provided the request body has been read). ModSecurity supports three encoding types for the - request body phase: + + This is the general-purpose input analysis phase. Most of the + application-oriented rules should go here. In this phase you are + guaranteed to have received the request arguments (provided the request + body has been read). ModSecurity supports three encoding types for the + request body phase: + - application/x-www-form-urlencoded - used to transfer form data - (used automatically) + application/x-www-form-urlencoded - used to + transfer form data (used automatically) + - multipart/form-data - used for file transfers (used - automatically) + multipart/form-data - used for file + transfers (used automatically) + - text/xml - used for passing XML data (must be explicitly - configured) + text/xml - used for passing XML data (must + be explicitly configured) + Other encodings are not used by most web applications.
+
Phase Response Headers - This phase takes place just before response headers are sent back to the client. Run - here if you want to observe the response before that happens, and if you want to use the - response headers to determine if you want to buffer the response body. Note that some - response status codes (such as 404) are handled earlier in the request cycle by Apache and - my not be able to be triggered as expected. Additionally, there are some response headers - that are added by Apache at a later hook (such as Date, Server and Connection) that we would - not be able to trigger on or sanitize. This should work appropriately in a proxy setup or - within phase:5 (logging). + + This phase takes place just before response headers are sent back + to the client. Run here if you want to observe the response before that + happens, and if you want to use the response headers to determine if you + want to buffer the response body. Note that some response status codes + (such as 404) are handled earlier in the request cycle by Apache and my + not be able to be triggered as expected. Additionally, there are some + response headers that are added by Apache at a later hook (such as Date, + Server and Connection) that we would not be able to trigger on or + sanitize. This should work appropriately in a proxy setup or within + phase:5 (logging).
+
Phase Response Body - This is the general-purpose output analysis phase. At this point you can run rules - against the response body (provided it was buffered, of course). This is the phase where you - would want to inspect the outbound HTML for information disclosure, error messages or failed - authentication text. + + This is the general-purpose output analysis phase. At this point + you can run rules against the response body (provided it was buffered, + of course). This is the phase where you would want to inspect the + outbound HTML for information disclosure, error messages or failed + authentication text.
+
Phase Logging - This phase is run just before logging takes place. The rules placed into this phase can - only affect how the logging is performed. This phase can be used to inspect the error - messages logged by Apache. You cannot deny/block connections in this phase as it is too - late. This phase also allows for inspection of other response headers that weren't available - during phase:3 or phase:4. Note that you must be careful not to inherit a disruptive action - into a rule in this phase as this is a configuration error in ModSecurity 2.5.0 and later - versions. + + This phase is run just before logging takes place. The rules + placed into this phase can only affect how the logging is performed. + This phase can be used to inspect the error messages logged by Apache. + You cannot deny/block connections in this phase as it is too late. This + phase also allows for inspection of other response headers that weren't + available during phase:3 or phase:4. Note that you must be careful not + to inherit a disruptive action into a rule in this phase as this is a + configuration error in ModSecurity 2.5.0 and later versions.
+
Variables + The following variables are supported in ModSecurity 2.x: +
<literal moreinfo="none">ARGS</literal> - ARGS is a collection and can be used on its own (means all arguments - including the POST Payload), with a static parameter (matches arguments with that name), or - with a regular expression (matches all arguments with name that matches the regular - expression). To look at only the query string or body arguments, see the ARGS_GET and ARGS_POST collections. - Some variables are actually collections, which are expanded into more variables at - runtime. The following example will examine all request - arguments:SecRule ARGS dirty - Sometimes, however, you will want to look only at parts of a collection. This can be - achieved with the help of the selection operator(colon). The following - example will only look at the arguments named p (do note - that, in general, requests can contain multiple arguments with the same name): - SecRule ARGS:p dirty It is also - possible to specify exclusions. The following will examine all request arguments for the - word dirty, except the ones named z (again, there can be zero or more arguments named - z): - SecRule ARGS|!ARGS:z dirty There is a - special operator that allows you to count how many variables there are in a collection. The - following rule will trigger if there is more than zero arguments in the request (ignore the - second parameter for the time being): - SecRule &ARGS !^0$ And sometimes - you need to look at an array of parameters, each with a slightly different name. In this - case you can specify a regular expression in the selection operator itself. The following - rule will look into all arguments whose names begin with id_: - SecRule ARGS:/^id_/ dirty + + ARGS is a collection and can be used on its own + (means all arguments including the POST Payload), with a static + parameter (matches arguments with that name), or with a regular + expression (matches all arguments with name that matches the regular + expression). To look at only the query string or body arguments, see the + ARGS_GET and ARGS_POST + collections. + + Some variables are actually collections, which are expanded into + more variables at runtime. The following example will examine all + request arguments:SecRule ARGS dirty + Sometimes, however, you will want to look only at parts of a collection. + This can be achieved with the help of the selection + operator(colon). The following example will only look at the + arguments named p (do note that, in + general, requests can contain multiple arguments with the same name): + SecRule ARGS:p dirty + It is also possible to specify exclusions. The following will examine + all request arguments for the word dirty, except + the ones named z (again, there can be + zero or more arguments named z): + SecRule ARGS|!ARGS:z dirty + There is a special operator that allows you to count how many variables + there are in a collection. The following rule will trigger if there is + more than zero arguments in the request (ignore the second parameter for + the time being): SecRule &ARGS !^0$ + And sometimes you need to look at an array of parameters, each with a + slightly different name. In this case you can specify a regular + expression in the selection operator itself. The following rule will + look into all arguments whose names begin with id_: SecRule ARGS:/^id_/ dirty + - Using ARGS:p will not result in any invocations against the - operator if argument p does not exist. - In ModSecurity 1.X, the ARGS variable stood for QUERY_STRING + POST_PAYLOAD, whereas now it expands to - individual variables. + Using ARGS:p will not result in any + invocations against the operator if argument p does not exist. + + In ModSecurity 1.X, the ARGS variable stood + for QUERY_STRING + POST_PAYLOAD, + whereas now it expands to individual variables.
+
<literal moreinfo="none">ARGS_COMBINED_SIZE</literal> - This variable allows you to set more targeted evaluations on the total size of the - Arguments as compared with normal Apache LimitRequest directives. For example, you could - create a rule to ensure that the total size of the argument data is below a certain - threshold (to help prevent buffer overflow issues). Example: Block request if the size of - the arguments is above 25 characters. + + This variable allows you to set more targeted evaluations on the + total size of the Arguments as compared with normal Apache LimitRequest + directives. For example, you could create a rule to ensure that the + total size of the argument data is below a certain threshold (to help + prevent buffer overflow issues). Example: Block request if the size of + the arguments is above 25 characters. + SecRule REQUEST_FILENAME "^/cgi-bin/login\.php" \ "chain,log,deny,phase:2,t:none,t:lowercase,t:normalisePath" SecRule ARGS_COMBINED_SIZE "@gt 25"
+
<literal moreinfo="none">ARGS_NAMES</literal> - Is a collection of the argument names. You can search for specific argument names that - you want to block. In a positive policy scenario, you can also whitelist (using an inverted - rule with the ! character) only authorized argument names. Example: This example rule will - only allow 2 argument names - p and a. If any other argument names are injected, it will be - blocked. + + Is a collection of the argument names. You can search for specific + argument names that you want to block. In a positive policy scenario, + you can also whitelist (using an inverted rule with the ! character) + only authorized argument names. Example: This example rule will only + allow 2 argument names - p and a. If any other argument names are + injected, it will be blocked. + SecRule REQUEST_FILENAME "/index.php" \ "chain,log,deny,status:403,phase:2,t:none,t:lowercase,t:normalisePath" SecRule ARGS_NAMES "!^(p|a)$" "t:none,t:lowercase"
+
<literal moreinfo="none">ARGS_GET</literal> - ARGS_GET is similar to ARGS, but only contains - arguments from the query string. + + ARGS_GET is similar to ARGS, + but only contains arguments from the query string.
+
<literal moreinfo="none">ARGS_GET_NAMES</literal> - ARGS_GET_NAMES is similar to ARGS_NAMES, but only - contains argument names from the query string. + + ARGS_GET_NAMES is similar to + ARGS_NAMES, but only contains argument names from the + query string.
+
<literal moreinfo="none">ARGS_POST</literal> - ARGS_POST is similar to ARGS, but only contains - arguments from the POST body. + + ARGS_POST is similar to + ARGS, but only contains arguments from the POST + body.
+
<literal moreinfo="none">ARGS_POST_NAMES</literal> - ARGS_POST_NAMES is similar to ARGS_NAMES, but only - contains argument names from the POST body. + + ARGS_POST_NAMES is similar to + ARGS_NAMES, but only contains argument names from the + POST body.
+
<literal moreinfo="none">AUTH_TYPE</literal> - This variable holds the authentication method used to validate a user. Example: + + This variable holds the authentication method used to validate a + user. Example: + SecRule AUTH_TYPE "basic" log,deny,status:403,phase:1,t:lowercase + Note - This data will not be available in a proxy-mode deployment as the authentication is not - local. In a proxy-mode deployment, you would need to inspect the REQUEST_HEADERS:Authorization header. + + This data will not be available in a proxy-mode deployment as the + authentication is not local. In a proxy-mode deployment, you would need + to inspect the REQUEST_HEADERS:Authorization + header.
+
<literal moreinfo="none">ENV</literal> - Collection, requires a single parameter (after colon). The ENV - variable is set with setenv and does not give access to the CGI environment variables. - Example: + + Collection, requires a single parameter (after colon). The + ENV variable is set with setenv and does not give + access to the CGI environment variables. Example: + SecRule REQUEST_FILENAME "printenv" pass,setenv:tag=suspicious SecRule ENV:tag "suspicious"
+
<literal moreinfo="none">FILES</literal> - Collection. Contains a collection of original file names (as they were called on the - remote user's file system). Note: only available if files were extracted from the request - body. Example: + + Collection. Contains a collection of original file names (as they + were called on the remote user's file system). Note: only available if + files were extracted from the request body. Example: + SecRule FILES "\.conf$" log,deny,status:403,phase:2
+
<literal moreinfo="none">FILES_COMBINED_SIZE</literal> - Single value. Total size of the uploaded files. Note: only available if files were - extracted from the request body. Example: + + Single value. Total size of the uploaded files. Note: only + available if files were extracted from the request body. Example: + SecRule FILES_COMBINED_SIZE "@gt 1000" log,deny,status:403,phase:2
+
<literal moreinfo="none">FILES_NAMES</literal> - Collection w/o parameter. Contains a list of form fields that were used for file upload. - Note: only available if files were extracted from the request body. Example: + + Collection w/o parameter. Contains a list of form fields that were + used for file upload. Note: only available if files were extracted from + the request body. Example: + SecRule FILES_NAMES "^upfile$" log,deny,status:403,phase:2
+
<literal moreinfo="none">FILES_SIZES</literal> - Collection. Contains a list of file sizes. Useful for implementing a size limitation on - individual uploaded files. Note: only available if files were extracted from the request - body. Example: + + Collection. Contains a list of file sizes. Useful for implementing + a size limitation on individual uploaded files. Note: only available if + files were extracted from the request body. Example: + SecRule FILES_SIZES "@gt 100" log,deny,status:403,phase:2
+
<literal moreinfo="none">FILES_TMPNAMES</literal> - Collection. Contains a collection of temporary files' names on the disk. Useful when - used together with @inspectFile. Note: only available if - files were extracted from the request body. Example: + + Collection. Contains a collection of temporary files' names on the + disk. Useful when used together with @inspectFile. Note: only available if files + were extracted from the request body. Example: + SecRule FILES_TMPNAMES "@inspectFile /path/to/inspect_script.pl"
+
<literal moreinfo="none">GEO</literal> - GEO is a collection populated by the results of the last @geoLookup operator. The collection can be used to match - geographical fields looked from an IP address or hostname. + + GEO is a collection populated by the results of + the last @geoLookup operator. The + collection can be used to match geographical fields looked from an IP + address or hostname. + Available since ModSecurity 2.5.0. + Fields: + - COUNTRY_CODE: Two character country code. EX: US, GB, - etc. + COUNTRY_CODE: Two character country code. + EX: US, GB, etc. + - COUNTRY_CODE3: Up to three character country code. + COUNTRY_CODE3: Up to three character + country code. + - COUNTRY_NAME: The full country name. + COUNTRY_NAME: The full country + name. + - COUNTRY_CONTINENT: The two character continent that the country - is located. EX: EU + COUNTRY_CONTINENT: The two character + continent that the country is located. EX: EU + - REGION: The two character region. For US, this is state. For - Canada, providence, etc. + REGION: The two character region. For US, + this is state. For Canada, providence, etc. + - CITY: The city name if supported by the database. + CITY: The city name if supported by the + database. + - POSTAL_CODE: The postal code if supported by the - database. + POSTAL_CODE: The postal code if supported + by the database. + - LATITUDE: The latitude if supported by the database. + LATITUDE: The latitude if supported by + the database. + - LONGITUDE: The longitude if supported by the database. + LONGITUDE: The longitude if supported by + the database. + - DMA_CODE: The metropolitan area code if supported by the - database. (US only) + DMA_CODE: The metropolitan area code if + supported by the database. (US only) + - AREA_CODE: The phone system area code. (US only) + AREA_CODE: The phone system area code. + (US only) + Example: + SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat ... SecRule REMOTE_ADDR "@geoLookup" "chain,drop,msg:'Non-GB IP address'" SecRule GEO:COUNTRY_CODE "!@streq GB"
+
<literal moreinfo="none">HIGHEST_SEVERITY</literal> - This variable holds the highest severity of any rules that have matched so far. - Severities are numeric values and thus can be used with comparison operators such as - @lt, etc. + + This variable holds the highest severity of any rules that have + matched so far. Severities are numeric values and thus can be used with + comparison operators such as @lt, + etc. + Higher severities have a lower numeric value. + A value of 255 indicates no severity has been set. + SecRule HIGHEST_SEVERITY "@le 2" "phase:2,deny,status:500,msg:'severity %{HIGHEST_SEVERITY}'"
+
<literal moreinfo="none">MATCHED_VAR</literal> - This variable holds the value of the variable that was matched against. It is similar to - the TX:0, except it can be used for all operators and does not require that the capture action be specified. + + This variable holds the value of the variable that was matched + against. It is similar to the TX:0, except it can be used for all + operators and does not require that the capture action be specified. + SecRule ARGS pattern chain,deny ... SecRule MATCHED_VAR "further scrutiny"
+
<literal moreinfo="none">MATCHED_VAR_NAME</literal> - This variable holds the full name of the variable that was matched against. + + This variable holds the full name of the variable that was matched + against. + SecRule ARGS pattern setvar:tx.mymatch=%{MATCHED_VAR_NAME} ... SecRule TX:MYMATCH "@eq ARGS:param" deny
+
<literal moreinfo="none">MODSEC_BUILD</literal> - This variable holds the ModSecurity build number. This variable is intended to be used - to check the build number prior to using a feature that is available only in a certain - build. Example: + + This variable holds the ModSecurity build number. This variable is + intended to be used to check the build number prior to using a feature + that is available only in a certain build. Example: + SecRule MODSEC_BUILD "!@ge 02050102" skipAfter:12345 SecRule ARGS "@pm some key words" id:12345,deny,status:500
+
<literal>MULTIPART_CRLF_LF_LINES</literal> - This flag variable will be set to 1 whenever a multi-part request - uses mixed line terminators. The multipart/form-data RFC requires - CRLF sequence to be used to terminate lines. Since some client - implementations use only LF to terminate lines you might want to allow - them to proceed under certain circumstances (if you want to do this you will need to stop - using MULTIPART_STRICT_ERROR and check each multi-part flag variable - individually, avoiding MULTIPART_LF_LINE). However, mixing CRLF and LF line terminators is dangerous as it can allow - for evasion. Therefore, in such cases, you will have to add a check for MULTIPART_CRLF_LF_LINES. + + This flag variable will be set to 1 whenever a + multi-part request uses mixed line terminators. The + multipart/form-data RFC requires + CRLF sequence to be used to terminate lines. Since + some client implementations use only LF to terminate + lines you might want to allow them to proceed under certain + circumstances (if you want to do this you will need to stop using + MULTIPART_STRICT_ERROR and check each multi-part flag + variable individually, avoiding MULTIPART_LF_LINE). + However, mixing CRLF and LF line + terminators is dangerous as it can allow for evasion. Therefore, in such + cases, you will have to add a check for + MULTIPART_CRLF_LF_LINES.
+
<literal>MULTIPART_STRICT_ERROR</literal> + MULTIPART_STRICT_ERROR will be set to 1 when any of the following variables is also set to 1: REQBODY_PROCESSOR_ERROR, @@ -2281,354 +3259,566 @@ SM %{MULTIPART_SEMICOLON_MISSING}, \ IQ %{MULTIPART_INVALID_QUOTING}, \ IQ %{MULTIPART_INVALID_HEADER_FOLDING}, \ FE %{MULTIPART_FILE_LIMIT_EXCEEDED}'" - The multipart/form-data parser was upgraded in ModSecurity v2.1.3 to - actively look for signs of evasion. Many variables (as listed above) were added to expose - various facts discovered during the parsing process. The MULTIPART_STRICT_ERROR variable is handy to check on all abnormalities at once. - The individual variables allow detection to be fine-tuned according to your circumstances in - order to reduce the number of false positives. Detailed analysis of various evasion - techniques covered will be released as a separated document at a later date. + + The multipart/form-data parser was upgraded in + ModSecurity v2.1.3 to actively look for signs of evasion. Many variables + (as listed above) were added to expose various facts discovered during + the parsing process. The MULTIPART_STRICT_ERROR + variable is handy to check on all abnormalities at once. The individual + variables allow detection to be fine-tuned according to your + circumstances in order to reduce the number of false positives. Detailed + analysis of various evasion techniques covered will be released as a + separated document at a later date.
+
<literal>MULTIPART_UNMATCHED_BOUNDARY</literal> - Set to 1 when, during the parsing phase of a multipart/request-body, ModSecurity encounters what seems like a boundary but - it is not. Such an event may occur when evasion of ModSecurity is attempted. - The best way to use this variable is as in the example below: + + Set to 1 when, during the parsing phase of a + multipart/request-body, ModSecurity encounters what + seems like a boundary but it is not. Such an event may occur when + evasion of ModSecurity is attempted. + + The best way to use this variable is as in the example + below: + SecRule MULTIPART_UNMATCHED_BOUNDARY "!@eq 0" \ "phase:2,t:none,log,deny,msg:'Multipart parser detected a possible unmatched boundary.'" - Change the rule from blocking to logging-only if many false positives are - encountered. + + Change the rule from blocking to logging-only if many false + positives are encountered.
+
<literal moreinfo="none">PATH_INFO</literal> - Besides passing query information to a script/handler, you can also pass additional - data, known as extra path information, as part of the URL. Example: + + Besides passing query information to a script/handler, you can + also pass additional data, known as extra path information, as part of + the URL. Example: + SecRule PATH_INFO "^/(bin|etc|sbin|opt|usr)"
+
<literal moreinfo="none">QUERY_STRING</literal> - This variable holds form data passed to the script/handler by appending data after a - question mark. Warning: Not URL-decoded. Example: + + This variable holds form data passed to the script/handler by + appending data after a question mark. Warning: Not URL-decoded. + Example: + SecRule QUERY_STRING "attack"
+
<literal moreinfo="none">REMOTE_ADDR</literal> - This variable holds the IP address of the remote client. Example: + + This variable holds the IP address of the remote client. + Example: + SecRule REMOTE_ADDR "^192\.168\.1\.101$"
+
<literal moreinfo="none">REMOTE_HOST</literal> - If HostnameLookUps are set to On, then this variable will hold the DNS resolved remote - host name. If it is set to Off, then it will hold the remote IP address. Possible uses for - this variable would be to deny known bad client hosts or network blocks, or conversely, to - allow in authorized hosts. Example: + + If HostnameLookUps are set to On, then this variable will hold the + DNS resolved remote host name. If it is set to Off, then it will hold + the remote IP address. Possible uses for this variable would be to deny + known bad client hosts or network blocks, or conversely, to allow in + authorized hosts. Example: + SecRule REMOTE_HOST "\.evil\.network\org$"
+
<literal moreinfo="none">REMOTE_PORT</literal> - This variable holds information on the source port that the client used when initiating - the connection to our web server. Example: in this example, we are evaluating to see if the - REMOTE_PORT is less than 1024, which would indicate that the user is a - privileged user (root). + + This variable holds information on the source port that the client + used when initiating the connection to our web server. Example: in this + example, we are evaluating to see if the REMOTE_PORT + is less than 1024, which would indicate that the user is a privileged + user (root). + SecRule REMOTE_PORT "@lt 1024" phase:1,log,pass,setenv:remote_port=privileged
+
<literal moreinfo="none">REMOTE_USER</literal> - This variable holds the username of the authenticated user. If there are no password - (basic|digest) access controls in place, then this variable will be empty. Example: + + This variable holds the username of the authenticated user. If + there are no password (basic|digest) access controls in place, then this + variable will be empty. Example: + SecRule REMOTE_USER "admin" + Note - This data will not be available in a proxy-mode deployment as the authentication is not - local. + + This data will not be available in a proxy-mode deployment as the + authentication is not local.
+
<literal moreinfo="none">REQBODY_PROCESSOR</literal> - Built-in processors are URLENCODED, MULTIPART, and XML. - Example: + + Built-in processors are URLENCODED, + MULTIPART, and XML. + Example: + SecRule REQBODY_PROCESSOR "^XML$ chain SecRule XML "@validateDTD /opt/apache-frontend/conf/xml.dtd"
+
- <literal moreinfo="none">REQBODY_PROCESSOR_ERROR</literal> - Possible values are 0 (no error) or 1 (error). This variable will be set by request body - processors (typically the multipart/request-data parser or the XML - parser) when they fail to properly parse a request payload. + <literal + moreinfo="none">REQBODY_PROCESSOR_ERROR</literal> + + Possible values are 0 (no error) or 1 (error). This variable will + be set by request body processors (typically the + multipart/request-data parser or the XML parser) + when they fail to properly parse a request payload. + Example: + SecRule REQBODY_PROCESSOR_ERROR "@eq 1" deny,phase:2 + - Your policies must have a rule to check REQBODY_PROCESSOR_ERROR at the beginning of phase 2. Failure to do so will - leave the door open for impedance mismatch attacks. It is possible, for example, that a - payload that cannot be parsed by ModSecurity can be successfully parsed by more tolerant - parser operating in the application. If your policy dictates blocking then you should - reject the request if error is detected. When operating in detection-only mode your rule - should alert with high severity when request body processing fails. + Your policies must have a rule to check + REQBODY_PROCESSOR_ERROR at the beginning of phase + 2. Failure to do so will leave the door open for impedance mismatch + attacks. It is possible, for example, that a payload that cannot be + parsed by ModSecurity can be successfully parsed by more tolerant + parser operating in the application. If your policy dictates blocking + then you should reject the request if error is detected. When + operating in detection-only mode your rule should alert with high + severity when request body processing fails.
+
- <literal moreinfo="none">REQBODY_PROCESSOR_ERROR_MSG</literal> - Empty, or contains the error message from the processor. Example: + <literal + moreinfo="none">REQBODY_PROCESSOR_ERROR_MSG</literal> + + Empty, or contains the error message from the processor. + Example: + SecRule REQBODY_PROCESSOR_ERROR_MSG "failed to parse" t:lowercase
+
<literal moreinfo="none">REQUEST_BASENAME</literal> - This variable holds just the filename part of REQUEST_FILENAME (e.g. - index.php). + + This variable holds just the filename part of + REQUEST_FILENAME (e.g. index.php). + Example: + SecRule REQUEST_BASENAME "^login\.php$" phase:2,t:none,t:lowercase + - Please note that anti-evasion transformations are not applied to this variable by - default. REQUEST_BASENAME will recognise both / and - \ as path separators. + Please note that anti-evasion transformations are not applied to + this variable by default. REQUEST_BASENAME will + recognise both / and \ as path + separators.
+
<literal moreinfo="none">REQUEST_BODY</literal> - This variable holds the data in the request body (including POST_PAYLOAD data). REQUEST_BODY should be used if the - original order of the arguments is important (ARGS should be used in all - other cases). Example: + + This variable holds the data in the request body (including + POST_PAYLOAD data). REQUEST_BODY + should be used if the original order of the arguments is important + (ARGS should be used in all other cases). + Example: + SecRule REQUEST_BODY "^username=\w{25,}\&password=\w{25,}\&Submit\=login$" + - This variable is only available if the URLENCODED request body - processor parsed a request body. This will occur by default when an application/x-www-form-urlencoded is detected, or the URLENCODED request body parser is forced. As of 2.5.7 it is possible to force - the presence of the REQUEST_BODY variable, but only when there is no - request body processor defined, using the ctl:forceRequestBodyVariable - option in the REQUEST_HEADERS phase. + This variable is only available if the + URLENCODED request body processor parsed a request + body. This will occur by default when an + application/x-www-form-urlencoded is detected, or + the URLENCODED request body parser is forced. As of + 2.5.7 it is possible to force the presence of the + REQUEST_BODY variable, but only when there is no + request body processor defined, using the + ctl:forceRequestBodyVariable option in the + REQUEST_HEADERS phase.
+
<literal moreinfo="none">REQUEST_COOKIES</literal> - This variable is a collection of all of the cookie data. Example: the following example - is using the Ampersand special operator to count how many variables are in the collection. - In this rule, it would trigger if the request does not include any Cookie headers. + + This variable is a collection of all of the cookie data. Example: + the following example is using the Ampersand special operator to count + how many variables are in the collection. In this rule, it would trigger + if the request does not include any Cookie headers. + SecRule &REQUEST_COOKIES "@eq 0"
+
<literal moreinfo="none">REQUEST_COOKIES_NAMES</literal> - This variable is a collection of the cookie names in the request headers. Example: the - following rule will trigger if the JSESSIONID cookie is not present. + + This variable is a collection of the cookie names in the request + headers. Example: the following rule will trigger if the JSESSIONID + cookie is not present. + SecRule &REQUEST_COOKIES_NAMES:JSESSIONID "@eq 0"
+
<literal moreinfo="none">REQUEST_FILENAME</literal> - This variable holds the relative REQUEST_URI minus the QUERY_STRING part (e.g. /index.php). Example: + + This variable holds the relative REQUEST_URI + minus the QUERY_STRING part (e.g. /index.php). + Example: + SecRule REQUEST_FILENAME "^/cgi-bin/login\.php$" phase:2,t:none,t:normalisePath + - Please note that anti-evasion transformations are not used on REQUEST_FILENAME by default. + Please note that anti-evasion transformations are not used on + REQUEST_FILENAME by default.
+
<literal moreinfo="none">REQUEST_HEADERS</literal> - This variable can be used as either a collection of all of the request headers or can be - used to specify individual headers (by using - REQUEST_HEADERS:Header-Name). Example: the first example uses - REQUEST_HEADERS as a collection and is applying the validateUrlEncoding operator against all headers. + + This variable can be used as either a collection of all of the + request headers or can be used to specify individual headers (by using + REQUEST_HEADERS:Header-Name). Example: the first + example uses REQUEST_HEADERS as a collection and is + applying the validateUrlEncoding operator against all + headers. + SecRule REQUEST_HEADERS "@validateUrlEncoding" - Example: the second example is targeting only the Host header. + + Example: the second example is targeting only the + Host header. + SecRule REQUEST_HEADERS:Host "^[\d\.]+$" \ "deny,log,status:400,msg:'Host header is a numeric IP address'"
+
<literal moreinfo="none">REQUEST_HEADERS_NAMES</literal> - This variable is a collection of the names of all of the request headers. - Example: + + This variable is a collection of the names of all of the request + headers. Example: + SecRule REQUEST_HEADERS_NAMES "^x-forwarded-for" \ "log,deny,status:403,t:lowercase,msg:'Proxy Server Used'"
+
<literal moreinfo="none">REQUEST_LINE</literal> - This variable holds the complete request line sent to the server (including the - REQUEST_METHOD and HTTP version data). Example: this example rule will trigger if the - request method is something other than GET, HEAD, POST or if the HTTP is something other - than HTTP/0.9, 1.0 or 1.1. + + This variable holds the complete request line sent to the server + (including the REQUEST_METHOD and HTTP version data). Example: this + example rule will trigger if the request method is something other than + GET, HEAD, POST or if the HTTP is something other than HTTP/0.9, 1.0 or + 1.1. + SecRule REQUEST_LINE "!(^((?:(?:pos|ge)t|head))|http/(0\.9|1\.0|1\.1)$)" t:none,t:lowercase
+
<literal moreinfo="none">REQUEST_METHOD</literal> + This variable holds the request method used by the client. - The following example will trigger if the request method is either CONNECT or TRACE. + + The following example will trigger if the request method is either + CONNECT or TRACE. + SecRule REQUEST_METHOD "^((?:connect|trace))$" t:none,t:lowercase
+
<literal moreinfo="none">REQUEST_PROTOCOL</literal> - This variable holds the request protocol version information. Example: + + This variable holds the request protocol version information. + Example: + SecRule REQUEST_PROTOCOL "!^http/(0\.9|1\.0|1\.1)$" t:none,t:lowercase
+
<literal moreinfo="none">REQUEST_URI</literal> - This variable holds the full URL including the QUERY_STRING data - (e.g. /index.php?p=X), however it will never contain a domain name, even if it was provided - on the request line. It also does not include either the REQUEST_METHOD - or the HTTP version info. + + This variable holds the full URL including the + QUERY_STRING data (e.g. /index.php?p=X), however it + will never contain a domain name, even if it was provided on the request + line. It also does not include either the + REQUEST_METHOD or the HTTP version info. + Example: + SecRule REQUEST_URI "attack" phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath + - Please note that anti-evasion transformations are not used on REQUEST_URI by default. + Please note that anti-evasion transformations are not used on + REQUEST_URI by default.
+
<literal moreinfo="none">REQUEST_URI_RAW</literal> - Same as REQUEST_URI but will contain the domain name if it was - provided on the request line (e.g. http://www.example.com/index.php?p=X). + + Same as REQUEST_URI but will contain the domain + name if it was provided on the request line (e.g. + http://www.example.com/index.php?p=X). + Example: + SecRule REQUEST_URI_RAW "http:/" phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath + - Please note that anti-evasion transformations are not used on REQUEST_URI_RAW by default. + Please note that anti-evasion transformations are not used on + REQUEST_URI_RAW by default.
+
<literal moreinfo="none">RESPONSE_BODY</literal> + This variable holds the data for the response payload. + Example: + SecRule RESPONSE_BODY "ODBC Error Code"
+
<literal>RESPONSE_CONTENT_LENGTH</literal> - Response body length in bytes. Can be available starting with phase 3 but it does not - have to be (as the length of response body is not always known in advance.) If the size is - not known this variable will contain a zero. If RESPONSE_CONTENT_LENGTH - contains a zero in phase 5 that means the actual size of the response body was 0. - The value of this variable can change between phases if the body is modified. For - example, in embedded mode mod_deflate can compress the response body - between phases 4 and 5. + + Response body length in bytes. Can be available starting with + phase 3 but it does not have to be (as the length of response body is + not always known in advance.) If the size is not known this variable + will contain a zero. If RESPONSE_CONTENT_LENGTH + contains a zero in phase 5 that means the actual size of the response + body was 0. + + The value of this variable can change between phases if the body + is modified. For example, in embedded mode + mod_deflate can compress the response body between + phases 4 and 5.
+
<literal>RESPONSE_CONTENT_TYPE</literal> - Response content type. Only available starting with phase 3. + + Response content type. Only available starting with phase + 3.
+
<literal moreinfo="none">RESPONSE_HEADERS</literal> - This variable is similar to the REQUEST_HEADERS variable and can be used in the same - manner. Example: + + This variable is similar to the REQUEST_HEADERS variable and can + be used in the same manner. Example: + SecRule RESPONSE_HEADERS:X-Cache "MISS" + Note - This variable may not have access to some headers when running in embedded-mode. Headers - such as Server, Date, Connection and Content-Type are added during a later Apache hook just - prior to sending the data to the client. This data should be available, however, either - during ModSecurity phase:5 (logging) or when running in proxy-mode. + + This variable may not have access to some headers when running in + embedded-mode. Headers such as Server, Date, Connection and Content-Type + are added during a later Apache hook just prior to sending the data to + the client. This data should be available, however, either during + ModSecurity phase:5 (logging) or when running in proxy-mode.
+
<literal moreinfo="none">RESPONSE_HEADERS_NAMES</literal> - This variable is a collection of the response header names. Example: + + This variable is a collection of the response header names. + Example: + SecRule RESPONSE_HEADERS_NAMES "Set-Cookie" + Note - Same limitations as RESPONSE_HEADERS with regards to access to some headers in - embedded-mode. + + Same limitations as RESPONSE_HEADERS with regards to access to + some headers in embedded-mode.
+
<literal moreinfo="none">RESPONSE_PROTOCOL</literal> - This variable holds the HTTP response protocol information. Example: + + This variable holds the HTTP response protocol information. + Example: + SecRule RESPONSE_PROTOCOL "^HTTP\/0\.9"
+
<literal moreinfo="none">RESPONSE_STATUS</literal> - This variable holds the HTTP response status code as generated by Apache. - Example: + + This variable holds the HTTP response status code as generated by + Apache. Example: + SecRule RESPONSE_STATUS "^[45]" + Note - This directive may not work as expected in embedded-mode as Apache handles many of the - stock response codes (404, 401, etc...) earlier in Phase 2. This variable should work as - expected in a proxy-mode deployment. + + This directive may not work as expected in embedded-mode as Apache + handles many of the stock response codes (404, 401, etc...) earlier in + Phase 2. This variable should work as expected in a proxy-mode + deployment.
+
<literal moreinfo="none">RULE</literal> - This variable provides access to the id, rev, severity, logdata, and msg fields of - the rule that triggered the action. Only available for expansion in action strings - (e.g.setvar:tx.varname=%{rule.id}). Example: + + This variable provides access to the id, rev, + severity, logdata, and msg fields of the rule that triggered the + action. Only available for expansion in action strings (e.g.setvar:tx.varname=%{rule.id}). Example: + SecRule &REQUEST_HEADERS:Host "@eq 0" "log,deny,setvar:tx.varname=%{rule.id}"
+
<literal moreinfo="none">SCRIPT_BASENAME</literal> - This variable holds just the local filename part of SCRIPT_FILENAME. Example: + + This variable holds just the local filename part of + SCRIPT_FILENAME. Example: + SecRule SCRIPT_BASENAME "^login\.php$" + Note + This variable is not available in proxy mode.
+
<literal moreinfo="none">SCRIPT_FILENAME</literal> - This variable holds the full path on the server to the requested script. (e.g. - SCRIPT_NAME plus the server path). Example: + + This variable holds the full path on the server to the requested + script. (e.g. SCRIPT_NAME plus the server path). Example: + SecRule SCRIPT_FILENAME "^/usr/local/apache/cgi-bin/login\.php$" + Note + This variable is not available in proxy mode.
+
<literal moreinfo="none">SCRIPT_GID</literal> - This variable holds the group id (numerical value) of the group owner of the script. - Example: + + This variable holds the group id (numerical value) of the group + owner of the script. Example: + SecRule SCRIPT_GID "!^46$" + Note + This variable is not available in proxy mode.
+
<literal moreinfo="none">SCRIPT_GROUPNAME</literal> - This variable holds the group name of the group owner of the script. Example: + + This variable holds the group name of the group owner of the + script. Example: + SecRule SCRIPT_GROUPNAME "!^apache$" + Note + This variable is not available in proxy mode.
+
<literal moreinfo="none">SCRIPT_MODE</literal> - This variable holds the script's permissions mode data (numerical - 1=execute, 2=write, - 4=read and 7=read/write/execute). Example: will trigger if the script has the WRITE - permissions set. + + This variable holds the script's permissions mode data (numerical + - 1=execute, 2=write, 4=read and 7=read/write/execute). Example: will + trigger if the script has the WRITE permissions set. + SecRule SCRIPT_MODE "^(2|3|6|7)$" + Note + This variable is not available in proxy mode.
+
<literal moreinfo="none">SCRIPT_UID</literal> - This variable holds the user id (numerical value) of the owner of the script. Example: - the example rule below will trigger if the UID is not 46 (the Apache user). + + This variable holds the user id (numerical value) of the owner of + the script. Example: the example rule below will trigger if the UID is + not 46 (the Apache user). + SecRule SCRIPT_UID "!^46$" + Note + This variable is not available in proxy mode.
+
<literal moreinfo="none">SCRIPT_USERNAME</literal> - This variable holds the username of the owner of the script. Example: + + This variable holds the username of the owner of the script. + Example: + SecRule SCRIPT_USERNAME "!^apache$" + Note + This variable is not available in proxy mode.
+
<literal moreinfo="none">SERVER_ADDR</literal> - This variable contains the IP address of the server. Example: + + This variable contains the IP address of the server. + Example: + SecRule SERVER_ADDR "^192\.168\.1\.100$"
+
<literal moreinfo="none">SERVER_NAME</literal> - This variable contains the server's hostname or IP address. Example: + + This variable contains the server's hostname or IP address. + Example: + SecRule SERVER_NAME "hostname\.com$" + Note - This data is taken from the Host header submitted in the client request. + + This data is taken from the Host header submitted in the client + request.
+
<literal moreinfo="none">SERVER_PORT</literal> - This variable contains the local port that the web server is listening on. - Example: + + This variable contains the local port that the web server is + listening on. Example: + SecRule SERVER_PORT "^80$"
+
<literal moreinfo="none">SESSION</literal> - This variable is a collection, available only after setsid is executed. Example: the following example shows how to initialize a - SESSION collection with setsid, how to use setvar to increase the session.score values, how - to set the session.blocked variable and finally how to deny the connection based on the - session:blocked value. + + This variable is a collection, available only after setsid is executed. Example: the following + example shows how to initialize a SESSION collection with setsid, how to + use setvar to increase the session.score values, how to set the + session.blocked variable and finally how to deny the connection based on + the session:blocked value. + SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass SecAction setsid:%{REQUEST_COOKIES.PHPSESSID} SecRule REQUEST_URI "^/cgi-bin/finger$" \ @@ -2636,84 +3826,129 @@ SecRule REQUEST_URI "^/cgi-bin/finger$" \ SecRule SESSION:SCORE "@gt 50" "pass,log,setvar:session.blocked=1" SecRule SESSION:BLOCKED "@eq 1" "log,deny,status:403"
+
<literal moreinfo="none">SESSIONID</literal> - This variable is the value set with setsid. - Example: + + This variable is the value set with setsid. Example: + SecRule SESSIONID !^$ chain,nolog,pass SecRule REQUEST_COOKIES:PHPSESSID !^$ SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
+
<literal moreinfo="none">TIME</literal> - This variable holds a formatted string representing the time (hour:minute:second). - Example: + + This variable holds a formatted string representing the time + (hour:minute:second). Example: + SecRule TIME "^(([1](8|9))|([2](0|1|2|3))):\d{2}:\d{2}$"
+
<literal moreinfo="none">TIME_DAY</literal> - This variable holds the current date (1-31). Example: this rule would trigger anytime - between the 10th and 20th days of the month. + + This variable holds the current date (1-31). Example: this rule + would trigger anytime between the 10th and 20th days of the + month. + SecRule TIME_DAY "^(([1](0|1|2|3|4|5|6|7|8|9))|20)$"
+
<literal moreinfo="none">TIME_EPOCH</literal> - This variable holds the time in seconds since 1970. Example: + + This variable holds the time in seconds since 1970. + Example: + SecRule TIME_EPOCH "@gt 1000"
+
<literal moreinfo="none">TIME_HOUR</literal> - This variable holds the current hour (0-23). Example: this rule would trigger during - "off hours". + + This variable holds the current hour (0-23). Example: this rule + would trigger during "off hours". + SecRule TIME_HOUR "^(0|1|2|3|4|5|6|[1](8|9)|[2](0|1|2|3))$"
+
<literal moreinfo="none">TIME_MIN</literal> - This variable holds the current minute (0-59). Example: this rule would trigger during - the last half hour of every hour. + + This variable holds the current minute (0-59). Example: this rule + would trigger during the last half hour of every hour. + SecRule TIME_MIN "^(3|4|5)"
+
<literal moreinfo="none">TIME_MON</literal> - This variable holds the current month (0-11). Example: this rule would match if the - month was either November (10) or December (11). + + This variable holds the current month (0-11). Example: this rule + would match if the month was either November (10) or December + (11). + SecRule TIME_MON "^1"
+
<literal moreinfo="none">TIME_SEC</literal> - This variable holds the current second count (0-59). Example: + + This variable holds the current second count (0-59). + Example: + SecRule TIME_SEC "@gt 30"
+
<literal moreinfo="none">TIME_WDAY</literal> - This variable holds the current weekday (0-6). Example: this rule would trigger only on - week-ends (Saturday and Sunday). + + This variable holds the current weekday (0-6). Example: this rule + would trigger only on week-ends (Saturday and Sunday). + SecRule TIME_WDAY "^(0|6)$"
+
<literal moreinfo="none">TIME_YEAR</literal> - This variable holds the current four-digit year data. Example: + + This variable holds the current four-digit year data. + Example: + SecRule TIME_YEAR "^2006$"
+
<literal moreinfo="none">TX</literal> - Transaction Collection. This is used to store pieces of data, create a transaction - anomaly score, and so on. Transaction variables are set for 1 request/response cycle. The - scoring and evaluation will not last past the current request/response process. Example: In - this example, we are using setvar to increase the tx.score value by 5 points. We then have a - follow-up run that will evaluate the transactional score this request and then it will - decided whether or not to allow/deny the request through. - The following is a list of reserved names in the TX collection: + + Transaction Collection. This is used to store pieces of data, + create a transaction anomaly score, and so on. Transaction variables are + set for 1 request/response cycle. The scoring and evaluation will not + last past the current request/response process. Example: In this + example, we are using setvar to increase the tx.score value by 5 points. + We then have a follow-up run that will evaluate the transactional score + this request and then it will decided whether or not to allow/deny the + request through. + + The following is a list of reserved names in the TX + collection: + - TX:0 - The matching value when using the @rx or @pm operator with - the capture action. + TX:0 - The matching value + when using the @rx or @pm operator with the capture action. + - TX:1-TX:9 - The captured subexpression value when - using the @rx operator with capturing parens and the - capture action. + TX:1-TX:9 - The captured + subexpression value when using the @rx operator with capturing parens and the + capture action. @@ -2731,35 +3966,49 @@ SecAction setsid:%{REQUEST_COOKIES.PHPSESSID} + SecRule WEBSERVER_ERROR_LOG "does not exist" "phase:5,pass,setvar:tx.score=+5" SecRule TX:SCORE "@gt 20" deny,log
+
<literal moreinfo="none">USERID</literal> - This variable is the value set with setuid. - Example: + + This variable is the value set with setuid. Example: + SecAction setuid:%{REMOTE_USER},nolog SecRule USERID "Admin"
+
<literal moreinfo="none">WEBAPPID</literal> - This variable is the value set with SecWebAppId. - Example: + + This variable is the value set with SecWebAppId. Example: + SecWebAppId "WebApp1" SecRule WEBAPPID "WebApp1" "chain,log,deny,status:403" SecRule REQUEST_HEADERS:Transfer-Encoding "!^$"
+
<literal moreinfo="none">WEBSERVER_ERROR_LOG</literal> - Contains zero or more error messages produced by the web server. Access to this variable - is in phase:5 (logging). Example: + + Contains zero or more error messages produced by the web server. + Access to this variable is in phase:5 (logging). Example: + SecRule WEBSERVER_ERROR_LOG "File does not exist" "phase:5,setvar:tx.score=+5"
+
<literal moreinfo="none">XML</literal> - Can be used standalone (as a target for validateDTD and validateSchema) or with an XPath expression parameter (which makes it a valid - target for any function that accepts plain text). Example using XPath: + + Can be used standalone (as a target for + validateDTD and validateSchema) or + with an XPath expression parameter (which makes it a valid target for + any function that accepts plain text). Example using XPath: + SecDefaultAction log,deny,status:403,phase:2 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \ phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML @@ -2767,8 +4016,10 @@ SecRule REQBODY_PROCESSOR "!^XML$" skipAfter:12345 SecRule XML:/employees/employee/name/text() Fred SecRule XML:/xq:employees/employee/name/text() Fred \ id:12345,xmlns:xq=http://www.example.com/employees - The first XPath expression does not use namespaces. It would match against payload such - as this one: + + The first XPath expression does not use namespaces. It would match + against payload such as this one: + <employees> <employee> <name>Fred Jones</name> @@ -2789,8 +4040,10 @@ SecRule XML:/xq:employees/employee/name/text() Fred \ <phone location="mobile">(206)555-4321</phone> </employee> </employees> - The second XPath expression does use namespaces. It would match the following - payload: + + The second XPath expression does use namespaces. It would match + the following payload: + <xq:employees xmlns:xq="http://www.example.com/employees"> <employee> <name>Fred Jones</name> @@ -2811,365 +4064,531 @@ SecRule XML:/xq:employees/employee/name/text() Fred \ <phone location="mobile">(206)555-4321</phone> </employee> </xq:employees> + Note the different namespace used in the second example. - To learn more about XPath we suggest the following resources: + + To learn more about XPath we suggest the following + resources: + - XPath Standard + XPath + Standard + - XPath - Tutorial + XPath + Tutorial
+
Transformation functions - When ModSecurity receives request or response information, it makes a copy of this data - and places it into memory. It is on this data in memory that transformation functions are - applied. The raw request/response data is never altered. Transformation functions are used to - transform a variable before testing it in a rule. + + When ModSecurity receives request or response information, it makes + a copy of this data and places it into memory. It is on this data in + memory that transformation functions are applied. The raw request/response + data is never altered. Transformation functions are used to transform a + variable before testing it in a rule. + Note - There are no default transformation functions as there were in previous versions of - ModSecurity. - The following rule will ensure that an attacker does not use mixed case in order to evade - the ModSecurity rule: + + There are no default transformation functions as there were in + previous versions of ModSecurity. + + The following rule will ensure that an attacker does not use mixed + case in order to evade the ModSecurity rule: + SecRule ARGS:p "xp_cmdshell" "t:lowercase" - multiple transformation actions can be used in the same rule, for example the following rule - also ensures that an attacker does not use URL encoding (%xx encoding) for evasion. Note the - order of the transformation functions, which ensures that a URL encoded letter is first - decoded and than translated to lower case. - - SecRule ARGS:p "xp_cmdshell" "t:urlDecode,t:lowercase" - - One can use the SecDefaultAction command to ensure the translation occurs for every rule - until the next. Note that transformation actions are additive, so if a rule explicitly list - actions, the translation actions set by SecDefaultAction are still performed. - - SecDefaultAction t:urlDecode,t:lowercase - + multiple transformation actions can be used in the same rule, for example + the following rule also ensures that an attacker does not use URL encoding + (%xx encoding) for evasion. Note the order of the transformation + functions, which ensures that a URL encoded letter is first decoded and + than translated to lower case. + + SecRule ARGS:p "xp_cmdshell" "t:urlDecode,t:lowercase" + + One can use the SecDefaultAction command to ensure the translation + occurs for every rule until the next. Note that transformation actions are + additive, so if a rule explicitly list actions, the translation actions + set by SecDefaultAction are still performed. + + SecDefaultAction t:urlDecode,t:lowercase + The following transformation functions are supported: +
<literal>base64Decode</literal> + This function decodes a base64-encoded string.
+
<literal>base64Encode</literal> + This function encodes input string using base64 encoding.
+
<literal>compressWhitespace</literal> - It converts whitespace characters (32, \f, \t, \n, \r, \v, 160) to spaces (ASCII 32) and - then compresses multiple consecutive space characters into one. + + It converts whitespace characters (32, \f, \t, \n, \r, \v, 160) to + spaces (ASCII 32) and then compresses multiple consecutive space + characters into one.
+
cssDecode + Decodes CSS-encoded characters, as specified at http://www.w3.org/TR/REC-CSS2/syndata.html. This function uses only up to two - bytes in the decoding process, meaning it is useful to uncover ASCII characters (that - wouldn't normally be encoded) encoded using CSS encoding, or to counter evasion which is a - combination of a backslash and non-hexadecimal characters (e.g. ja\vascript is equivalent to javascript). + url="http://www.w3.org/TR/REC-CSS2/syndata.html">http://www.w3.org/TR/REC-CSS2/syndata.html. + This function uses only up to two bytes in the decoding process, meaning + it is useful to uncover ASCII characters (that wouldn't normally be + encoded) encoded using CSS encoding, or to counter evasion which is a + combination of a backslash and non-hexadecimal characters (e.g. + ja\vascript is equivalent to + javascript).
+
<literal>escapeSeqDecode</literal> - This function decode ANSI C escape sequences: - \a, \b, \f, \n, \r, - \t, \v, \\, \?, \', \", \xHH (hexadecimal), \0OOO - (octal). Invalid encodings are left in the output. + + This function decode ANSI C escape sequences: \a, \b, + \f, \n, \r, + \t, \v, \\, + \?, \', \", + \xHH (hexadecimal), \0OOO (octal). Invalid encodings are left in + the output.
+
<literal>hexDecode</literal> + This function decodes a hex-encoded string.
+
<literal>hexEncode</literal> + This function encodes input as hex-encoded string.
+
<literal>htmlEntityDecode</literal> - This function decodes HTML entities present in input. The following variants are - supported: + + This function decodes HTML entities present in input. The + following variants are supported: + - &#xHH and &#xHH; (where H is any hexadecimal number) + &#xHH and &#xHH; (where H is any hexadecimal + number) + - &#DDD and &#DDD; (where D is any decimal number) + &#DDD and &#DDD; (where D is any decimal + number) + - &quot and &quot; + &quot and &quot; + - &nbsp and &nbsp; + &nbsp and &nbsp; + - &lt and &lt; + &lt and &lt; + - &gt and &gt; + &gt and &gt; - This function will convert any entity into a single byte only, possibly resulting in a - loss of information. It is thus useful to uncover bytes that would otherwise not need to be - encoded, but it cannot do anything with the characters from the range above 255. + + This function will convert any entity into a single byte only, + possibly resulting in a loss of information. It is thus useful to + uncover bytes that would otherwise not need to be encoded, but it cannot + do anything with the characters from the range above 255.
+
<literal>jsDecode</literal> - Decodes JavaScript escape sequences. If a \uHHHH code is in the range - of FF01-FF5E (the full width ASCII codes), then the - higher byte is used to detect and adjust the lower byte. Otherwise, only the lower byte will - be used and the higher byte zeroed. + + Decodes JavaScript escape sequences. If a + \uHHHH code is in the range of + FF01-FF5E (the full width ASCII + codes), then the higher byte is used to detect and adjust the lower + byte. Otherwise, only the lower byte will be used and the higher byte + zeroed.
+
<literal>length</literal> - This function converts the input to its numeric length (count of bytes). + + This function converts the input to its numeric length (count of + bytes).
+
<literal>lowercase</literal> - This function converts all characters to lowercase using the current C locale. + + This function converts all characters to lowercase using the + current C locale.
+
<literal>md5</literal> - This function calculates an MD5 hash from input. Note that the computed hash is in a raw - binary form and may need encoded into text to be usable (for example: t:md5,t:hexEncode). + + This function calculates an MD5 hash from input. Note that the + computed hash is in a raw binary form and may need encoded into text to + be usable (for example: t:md5,t:hexEncode).
+
<literal><literal>none</literal></literal> - Not an actual transformation function, but an instruction to ModSecurity to remove all - transformation functions associated with the current rule. + + Not an actual transformation function, but an instruction to + ModSecurity to remove all transformation functions associated with the + current rule.
+
<literal>normalisePath</literal> - This function will remove multiple slashes, self-references and directory - back-references (except when they are at the beginning of the input). + + This function will remove multiple slashes, self-references and + directory back-references (except when they are at the beginning of the + input).
+
<literal>normalisePathWin</literal> - Same as normalisePath, but will first convert backslash characters to - forward slashes. + + Same as normalisePath, but will first convert + backslash characters to forward slashes.
+
<literal>parityEven7bit</literal> - This function calculates even parity of 7-bit data replacing the 8th bit of each target - byte with the calculated parity bit. + + This function calculates even parity of 7-bit data replacing the + 8th bit of each target byte with the calculated parity bit.
+
<literal>parityOdd7bit</literal> - This function calculates odd parity of 7-bit data replacing the 8th bit of each target - byte with the calculated parity bit. + + This function calculates odd parity of 7-bit data replacing the + 8th bit of each target byte with the calculated parity bit.
+
<literal>parityZero7bit</literal> - This function calculates zero parity of 7-bit data replacing the 8th bit of each target - byte with a zero parity bit which allows inspection of even/odd parity 7bit data as ASCII7 - data. + + This function calculates zero parity of 7-bit data replacing the + 8th bit of each target byte with a zero parity bit which allows + inspection of even/odd parity 7bit data as ASCII7 data.
+
<literal>removeNulls</literal> + This function removes NULL bytes from input.
+
<literal>removeWhitespace</literal> + This function removes all whitespace characters from input.
+
<literal>replaceComments</literal> - This function replaces each occurrence of a C-style comments (/* ... */) with a single space (multiple consecutive occurrences of a space - will not be compressed). Unterminated comments will too be replaced with a space (ASCII 32). - However, a standalone termination of a comment (*/) will - not be acted upon. + + This function replaces each occurrence of a C-style comments + (/* ... */) with a single space + (multiple consecutive occurrences of a space will not be compressed). + Unterminated comments will too be replaced with a space (ASCII 32). + However, a standalone termination of a comment (*/) will not be acted upon.
+
<literal>replaceNulls</literal> - This function is enabled by default. It replaces NULL bytes in input with spaces (ASCII - 32). + + This function is enabled by default. It replaces NULL bytes in + input with spaces (ASCII 32).
+
<literal>urlDecode</literal> - This function decodes an URL-encoded input string. Invalid encodings (i.e. the ones that - use non-hexadecimal characters, or the ones that are at the end of string and have one or - two characters missing) will not be converted. If you want to detect invalid encodings use - the @validateUrlEncoding operator. The transformation - function should not be used against variables that have already been URL-decoded unless it - is your intention to perform URL decoding twice! + + This function decodes an URL-encoded input string. Invalid + encodings (i.e. the ones that use non-hexadecimal characters, or the + ones that are at the end of string and have one or two characters + missing) will not be converted. If you want to detect invalid encodings + use the @validateUrlEncoding + operator. The transformation function should not be used against + variables that have already been URL-decoded unless it is your intention + to perform URL decoding twice!
+
<literal>urlDecodeUni</literal> - In addition to decoding %xx like urlDecode, - urlDecodeUni also decodes %uXXXX encoding. If - the code is in the range of FF01-FF5E (the full width - ASCII codes), then the higher byte is used to detect and adjust the lower byte. Otherwise, - only the lower byte will be used and the higher byte zeroed. + + In addition to decoding %xx like urlDecode, urlDecodeUni also decodes %uXXXX encoding. If the code is in the range + of FF01-FF5E (the full width ASCII + codes), then the higher byte is used to detect and adjust the lower + byte. Otherwise, only the lower byte will be used and the higher byte + zeroed.
+
<literal>urlEncode</literal> + This function encodes input using URL encoding.
+
<literal>sha1</literal> - This function calculates a SHA1 hash from input. Note that the computed hash is in a raw - binary form and may need encoded to be usable (for example: t:sha1,t:hexEncode). + + This function calculates a SHA1 hash from input. Note that the + computed hash is in a raw binary form and may need encoded to be usable + (for example: t:sha1,t:hexEncode).
+
<literal>trimLeft</literal> - This function removes whitespace from the left side of input. + + This function removes whitespace from the left side of + input.
+
<literal>trimRight</literal> - This function removes whitespace from the right side of input. + + This function removes whitespace from the right side of + input.
+
<literal>trim</literal> - This function removes whitespace from both the left and right sides of input. + + This function removes whitespace from both the left and right + sides of input.
+
Actions + Each action belongs to one of five groups: + Disruptive actions + - Cause ModSecurity to do something. In many cases something means block transaction, - but not in all. For example, the allow action is classified as a disruptive action, but - it does the opposite of blocking. There can only be one disruptive action per rule (if - there are multiple disruptive actions present, or inherited, only the last one will take - effect), or rule chain (in a chain, a disruptive action can only appear in the first - rule). + Cause ModSecurity to do something. In many cases something + means block transaction, but not in all. For example, the allow + action is classified as a disruptive action, but it does the + opposite of blocking. There can only be one disruptive action per + rule (if there are multiple disruptive actions present, or + inherited, only the last one will take effect), or rule chain (in a + chain, a disruptive action can only appear in the first + rule). + Non-disruptive actions + - Do something, but that something does not and cannot affect the rule processing - flow. Setting a variable, or changing its value is an example of a non-disruptive - action. Non-disruptive action can appear in any rule, including each rule belonging to a - chain. + Do something, but that something does not and cannot affect + the rule processing flow. Setting a variable, or changing its value + is an example of a non-disruptive action. Non-disruptive action can + appear in any rule, including each rule belonging to a chain. + Flow actions + - These actions affect the rule flow (for example skip or skipAfter). + These actions affect the rule flow (for example + skip or skipAfter). + Meta-data actions + - Meta-data actions are used to provide more information about rules. Examples include - id, rev, severity and - msg. + Meta-data actions are used to provide more information about + rules. Examples include id, + rev, severity and + msg. + Data actions + - Not really actions, these are mere containers that hold data used by other actions. - For example, the status action holds the status that will be used for - blocking (if it takes place). + Not really actions, these are mere containers that hold data + used by other actions. For example, the status + action holds the status that will be used for blocking (if it takes + place). +
<literal>allow</literal> - Description: Stops rule processing on a successful match and allows - the transaction to proceed. + + Description: Stops rule processing on a + successful match and allows the transaction to proceed. + Action Group: Disruptive + Example: + SecRule REMOTE_ADDR "^192\.168\.1\.100$" nolog,phase:1,allow - Prior to ModSecurity 2.5 the allow action would only affect the - current phase. An allow in phase 1 would skip processing the remaining - rules in phase 1 but the rules from phase 2 would still execute. Starting with v2.5.0 - allow was enhanced to allow for fine-grained control of what is done. - The following rules now apply: + + Prior to ModSecurity 2.5 the allow action would + only affect the current phase. An allow in phase 1 + would skip processing the remaining rules in phase 1 but the rules from + phase 2 would still execute. Starting with v2.5.0 + allow was enhanced to allow for fine-grained control + of what is done. The following rules now apply: + - If used one its own, like in the example above, allow will affect - the entire transaction, stopping processing of the current phase but also skipping over - all other phases apart from the logging phase. (The logging phase is special; it is - designed to always execute.) + If used one its own, like in the example above, + allow will affect the entire transaction, + stopping processing of the current phase but also skipping over all + other phases apart from the logging phase. (The logging phase is + special; it is designed to always execute.) + - If used with parameter "phase", allow will cause the engine to - stop processing the current phase. Other phases will continue as normal. + If used with parameter "phase", allow will + cause the engine to stop processing the current phase. Other phases + will continue as normal. + - If used with parameter "request", allow will cause the engine to - stop processing the current phase. The next phase to be processed will be phase RESPONSE_HEADERS. + If used with parameter "request", allow + will cause the engine to stop processing the current phase. The next + phase to be processed will be phase + RESPONSE_HEADERS. + Examples: + # Do not process request but process response. SecAction phase:1,allow:request # Do not process transaction (request and response). SecAction phase:1,allow - If you want to allow a response through, put a rule in phase RESPONSE_HEADERS and simply use allow on its own: + + If you want to allow a response through, put a rule in phase + RESPONSE_HEADERS and simply use + allow on its own: + # Allow response through. SecAction phase:3,allow
+
append - Description: Appends text given as parameter to the end of response - body. For this action to work content injection must be enabled by setting SecContentInjection to On. Also make sure you check the - content type of the response before you make changes to it (e.g. you don't want to inject - stuff into images). + + Description: Appends text given as parameter + to the end of response body. For this action to work content injection + must be enabled by setting SecContentInjection to + On. Also make sure you check the content type of the + response before you make changes to it (e.g. you don't want to inject + stuff into images). + Action Group: Non-disruptive + Processing Phases: 3 and 4. + Example: + SecRule RESPONSE_CONTENT_TYPE "^text/html" "nolog,pass,append:'<hr>Footer'" + - While macro expansion is allowed in the additional content, you are strongly cautioned - against inserting user defined data fields. + While macro expansion is allowed in the additional content, you + are strongly cautioned against inserting user defined data + fields.
+
<literal>auditlog</literal> - Description: Marks the transaction for logging in the audit - log. + + Description: Marks the transaction for + logging in the audit log. + Action Group: Non-disruptive + Example: + SecRule REMOTE_ADDR "^192\.168\.1\.100$" auditlog,phase:1,allow + Note - The auditlog action is now explicit if log is already specified. + + The auditlog action is now explicit if log is already + specified.
+
<literal>block</literal> - Description: Performs the default disruptive action. + + Description: Performs the default disruptive + action. + Action Group: Disruptive - It is intended to be used by ruleset writers to signify that the rule was intended to - block and leaves the "how" up to the administrator. This action is currently a placeholder - which will just be replaced by the action from the last SecDefaultAction - in the same context. Using the block action with the SecRuleUpdateActionById directive allows a rule to be reverted back to the - previous SecDefaultAction disruptive action. - In future versions of ModSecurity, more control and functionality will be added to - define "how" to block. + + It is intended to be used by ruleset writers to signify that the + rule was intended to block and leaves the "how" up to the administrator. + This action is currently a placeholder which will just be replaced by + the action from the last SecDefaultAction in the same + context. Using the block action with the + SecRuleUpdateActionById directive allows a rule to be + reverted back to the previous SecDefaultAction + disruptive action. + + In future versions of ModSecurity, more control and functionality + will be added to define "how" to block. + Examples: - In the following example, the second rule will "deny" because of the SecDefaultAction - disruptive action. The intent being that the administrator could easily change this to - another disruptive action without editing the actual rules. + + In the following example, the second rule will "deny" because of + the SecDefaultAction disruptive action. The intent being that the + administrator could easily change this to another disruptive action + without editing the actual rules. + ### Administrator defines "how" to block (deny,status:403)... SecDefaultAction phase:2,deny,status:403,log,auditlog @@ -3178,11 +4597,14 @@ SecDefaultAction phase:2,deny,status:403,log,auditlog SecRule REQUEST_HEADERS:User-Agent "perl" "phase:2,pass,msg:'Perl based user agent identified'" # Intent is to block for this User Agent, "how" described in SecDefaultAction SecRule REQUEST_HEADERS:User-Agent "nikto" "phase:2,block,msg:'Nikto Scanners Identified'" - In the following example, The rule is reverted back to the pass - action defined in the SecDefaultAction directive by using the SecRuleUpdateActionById directive in conjuction with the block action. This allows an administrator to override an action in a 3rd party - rule without modifying the rule itself. + + In the following example, The rule is reverted back to the + pass action defined in the SecDefaultAction directive + by using the SecRuleUpdateActionById directive in + conjuction with the block action. This allows an + administrator to override an action in a 3rd party rule without + modifying the rule itself. + ### Administrator defines "how" to block (deny,status:403)... SecDefaultAction phase:2,pass,log,auditlog @@ -3192,158 +4614,238 @@ SecRule REQUEST_HEADERS:User-Agent "nikto" "id:1,phase:2,denyblock"
+
<literal>capture</literal> - Description: When used together with the regular expression - operator, capture action will create copies of regular expression captures and place them - into the transaction variable collection. Up to ten captures will be copied on a successful - pattern match, each with a name consisting of a digit from 0 to 9. + + Description: When used together with the + regular expression operator, capture action will create copies of + regular expression captures and place them into the transaction variable + collection. Up to ten captures will be copied on a successful pattern + match, each with a name consisting of a digit from 0 to 9. + Action Group: Non-disruptive + Example: + SecRule REQUEST_BODY "^username=(\w{25,})" phase:2,capture,t:none,chain SecRule TX:1 "(?:(?:a(dmin|nonymous)))" + Note - The 0 data captures the entire REGEX match and 1 captures the data in the first parens, - etc... + + The 0 data captures the entire REGEX match and 1 captures the data + in the first parens, etc...
+
<literal>chain</literal> - Description: Chains the rule where the action is placed with the - rule that immediately follows it. The result is called a rule chain. - Chained rules allow for more complex rule matches where you want to use a number of - different VARIABLES to create a better rule and to help prevent false positives. + + Description: Chains the rule where the action + is placed with the rule that immediately follows it. The result is + called a rule chain. Chained rules allow for more + complex rule matches where you want to use a number of different + VARIABLES to create a better rule and to help prevent false + positives. + Action Group: Flow + Example: + # Refuse to accept POST requests that do # not specify request body length. Do note that # this rule should be preceeded by a rule that verifies # only valid request methods (e.g. GET, HEAD and POST) are used. SecRule REQUEST_METHOD ^POST$ chain,t:none SecRule REQUEST_HEADERS:Content-Length ^$ t:none + - In programming language concepts, think of chained rules somewhat similar to AND - conditional statements. The actions specified in the first portion of the chained rule - will only be triggered if all of the variable checks return positive hits. If one aspect - of the chained rule is negative, then the entire rule chain is negative. Also note that - disruptive actions, execution phases, metadata actions (id, rev, msg), skip and skipAfter - actions can only be specified on by the chain starter rule. + In programming language concepts, think of chained rules + somewhat similar to AND conditional statements. The actions specified + in the first portion of the chained rule will only be triggered if all + of the variable checks return positive hits. If one aspect of the + chained rule is negative, then the entire rule chain is negative. Also + note that disruptive actions, execution phases, metadata actions (id, + rev, msg), skip and skipAfter actions can only be specified on by the + chain starter rule.
+
<literal>ctl</literal> - Description: The ctl action allows configuration options to be - updated for the transaction. + + Description: The ctl action allows + configuration options to be updated for the transaction. + Action Group: Non-disruptive + Example: + # Parse requests with Content-Type "text/xml" as XML SecRule REQUEST_CONTENT_TYPE ^text/xml nolog,pass,ctl:requestBodyProcessor=XML + Note + The following configuration options are supported: + auditEngine + auditLogParts + debugLogLevel + - ruleRemoveById (single rule ID, or a single rule - ID range accepted as parameter) + ruleRemoveById (single rule + ID, or a single rule ID range accepted as parameter) + requestBodyAccess + - forceRequestBodyVariable + forceRequestBodyVariable + requestBodyLimit + requestBodyProcessor + responseBodyAccess + responseBodyLimit + ruleEngine - With the exception of requestBodyProcessor and - forceRequestBodyVariable, each configuration option - corresponds to one configuration directive and the usage is identical. - The requestBodyProcessor option allows you to configure the request - body processor. By default ModSecurity will use the URLENCODED and MULTIPART processors to - process an application/x-www-form-urlencoded and a - multipart/form-data bodies, respectively. A third - processor, XML, is also supported, but it is never used implicitly. - Instead you must tell ModSecurity to use it by placing a few rules in the REQUEST_HEADERS processing phase. After the request body was - processed as XML you will be able to use the XML-related features to inspect it. - Request body processors will not interrupt a transaction if an error occurs during - parsing. Instead they will set variables - REQBODY_PROCESSOR_ERROR and - REQBODY_PROCESSOR_ERROR_MSG. These variables should be inspected in the REQUEST_BODY phase and an appropriate action taken. - The forceRequestBodyVariable option allows you to configure the - REQUEST_BODY variable to be set when there is no request body processor - configured. This allows for inspection of request bodies of unknown types. + + With the exception of + requestBodyProcessor and + forceRequestBodyVariable, each configuration option + corresponds to one configuration directive and the usage is + identical. + + The requestBodyProcessor option allows you to + configure the request body processor. By default ModSecurity will use + the URLENCODED and MULTIPART processors to process an application/x-www-form-urlencoded and a + multipart/form-data bodies, + respectively. A third processor, XML, is also + supported, but it is never used implicitly. Instead you must tell + ModSecurity to use it by placing a few rules in the REQUEST_HEADERS processing phase. After the + request body was processed as XML you will be able to use the + XML-related features to inspect it. + + Request body processors will not interrupt a transaction if an + error occurs during parsing. Instead they will set variables REQBODY_PROCESSOR_ERROR and REQBODY_PROCESSOR_ERROR_MSG. These variables + should be inspected in the REQUEST_BODY phase and an appropriate action + taken. + + The forceRequestBodyVariable option allows you + to configure the REQUEST_BODY variable to be set when + there is no request body processor configured. This allows for + inspection of request bodies of unknown types.
+
<literal>deny</literal> - Description: Stops rule processing and intercepts - transaction. + + Description: Stops rule processing and + intercepts transaction. + Action Group: Disruptive + Example: + SecRule REQUEST_HEADERS:User-Agent "nikto" "log,deny,msg:'Nikto Scanners Identified'"
+
<literal>deprecatevar</literal> - Description: Decrement counter based on its age. + + Description: Decrement counter based on its + age. + Action Group: Non-Disruptive - Example: The following example will decrement the counter by 60 every 300 - seconds. + + Example: The following example will decrement the counter by 60 + every 300 seconds. + SecAction deprecatevar:session.score=60/300 + Note - Counter values are always positive, meaning the value will never go below zero. + + Counter values are always positive, meaning the value will never + go below zero.
+
<literal>drop</literal> - Description: Immediately initiate a "connection close" action to - tear down the TCP connection by sending a FIN packet. + + Description: Immediately initiate a + "connection close" action to tear down the TCP connection by sending a + FIN packet. + Action Group: Disruptive - Example: The following example initiates an IP collection for tracking Basic - Authentication attempts. If the client goes over the threshold of more than 25 attempts in 2 - minutes, it will DROP subsequent connections. + + Example: The following example initiates an IP collection for + tracking Basic Authentication attempts. If the client goes over the + threshold of more than 25 attempts in 2 minutes, it will DROP subsequent + connections. + SecAction phase:1,initcol:ip=%{REMOTE_ADDR},nolog SecRule ARGS:login "!^$" \ nolog,phase:1,setvar:ip.auth_attempt=+1,deprecatevar:ip.auth_attempt=20/120 SecRule IP:AUTH_ATTEMPT "@gt 25" \ "log,drop,phase:1,msg:'Possible Brute Force Attack'" + Note - This action is currently not available on Windows based builds. This action is extremely - useful when responding to both Brute Force and Denial of Service attacks in that, in both - cases, you want to minimize both the network bandwidth and the data returned to the client. - This action causes error message to appear in the log "(9)Bad file descriptor: - core_output_filter: writing data to the network" + + This action is currently not available on Windows based builds. + This action is extremely useful when responding to both Brute Force and + Denial of Service attacks in that, in both cases, you want to minimize + both the network bandwidth and the data returned to the client. This + action causes error message to appear in the log "(9)Bad file + descriptor: core_output_filter: writing data to the network"
+
<literal>exec</literal> - Description: Executes an external script/binary supplied as - parameter. As of v2.5.0, if the parameter supplied to exec is a Lua - script (detected by the .lua extension) the script will be processed - internally. This means you will get direct access to the internal - request context from the script. Please read the SecRuleScript - documentation for more details on how to write Lua scripts. + + Description: Executes an external + script/binary supplied as parameter. As of v2.5.0, if the parameter + supplied to exec is a Lua script (detected by the + .lua extension) the script will be processed + internally. This means you will get direct access + to the internal request context from the script. Please read the + SecRuleScript documentation for more details on how + to write Lua scripts. + Action Group: Non-disruptive + Example: + # The following is going to execute /usr/local/apache/bin/test.sh # as a shell script on rule match. SecRule REQUEST_URI "^/cgi-bin/script\.pl" \ @@ -3352,604 +4854,947 @@ SecRule REQUEST_URI "^/cgi-bin/script\.pl" \ # The following is going to process /usr/local/apache/conf/exec.lua # internally as a Lua script on rule match. SecRule ARGS:p attack log,exec:/usr/local/apache/conf/exec.lua + - The exec action is executed independently from any disruptive actions. External - scripts will always be called with no parameters. Some transaction information will be - placed in environment variables. All the usual CGI environment variables will be there. - You should be aware that forking a threaded process results in all threads being - replicated in the new process. Forking can therefore incur larger overhead in - multi-threaded operation. The script you execute must write something (anything) to - stdout. If it doesn't ModSecurity will assume execution didn't work. + The exec action is executed independently from any disruptive + actions. External scripts will always be called with no parameters. + Some transaction information will be placed in environment variables. + All the usual CGI environment variables will be there. You should be + aware that forking a threaded process results in all threads being + replicated in the new process. Forking can therefore incur larger + overhead in multi-threaded operation. The script you execute must + write something (anything) to stdout. If it doesn't ModSecurity will + assume execution didn't work.
+
<literal>expirevar</literal> - Description: Configures a collection variable to expire after the - given time in seconds. + + Description: Configures a collection variable + to expire after the given time in seconds. + Action Group: Non-disruptive + Example: + SecRule REQUEST_COOKIES:JSESSIONID "!^$" nolog,phase:1,pass,chain SecAction setsid:%{REQUEST_COOKIES:JSESSIONID} SecRule REQUEST_URI "^/cgi-bin/script\.pl" \ "phase:2,t:none,t:lowercase,t:normalisePath,log,allow,\ setvar:session.suspicious=1,expirevar:session.suspicious=3600,phase:1" + Note - You should use expirevar actions at the same time that you use setvar actions in order - to keep the indented expiration time. If they are used on their own (perhaps in a SecAction - directive) the expire time could get re-set. When variables are removed from collections, - and there are no other changes, collections are not written to disk at the end of request. - This is because the variables can always be expired again when the collection is read again - on a subsequent request. + + You should use expirevar actions at the same time that you use + setvar actions in order to keep the indented expiration time. If they + are used on their own (perhaps in a SecAction directive) the expire time + could get re-set. When variables are removed from collections, and there + are no other changes, collections are not written to disk at the end of + request. This is because the variables can always be expired again when + the collection is read again on a subsequent request.
+
<literal>id</literal> - Description: Assigns a unique ID to the rule or chain. + + Description: Assigns a unique ID to the rule + or chain. + Action Group: Meta-data + Example: + SecRule &REQUEST_HEADERS:Host "@eq 0" \ "log,id:60008,severity:2,msg:'Request Missing a Host Header'" + Note + These are the reserved ranges: + - 1-99,999; reserved for local (internal) use. Use as you see fit but do not use this - range for rules that are distributed to others. + 1-99,999; reserved for local (internal) use. Use as you see + fit but do not use this range for rules that are distributed to + others. + - 100,000-199,999; reserved for internal use of the engine, to assign to rules that do - not have explicit IDs. + 100,000-199,999; reserved for internal use of the engine, to + assign to rules that do not have explicit IDs. + - 200,000-299,999; reserved for rules published at modsecurity.org. + 200,000-299,999; reserved for rules published at + modsecurity.org. + - 300,000-399,999; reserved for rules published at gotroot.com. + 300,000-399,999; reserved for rules published at + gotroot.com. + 400,000-419,999; unused (available for reservation). + 420,000-429,999; reserved for ScallyWhack. + url="http://projects.otaku42.de/wiki/ScallyWhack">ScallyWhack. + 430,000-699,999; unused (available for reservation). + 700,000-799,999; reserved for Ivan Ristic. 900,000-999,999; reserved for the Core Rules project. + url="http://www.modsecurity.org/projects/rules/">Core Rules + project. + - 1,000,000 and above; unused (available for reservation). + 1,000,000 and above; unused (available for + reservation).
+
<literal>initcol</literal> - Description: Initialises a named persistent collection, either by - loading data from storage or by creating a new collection in memory. + + Description: Initialises a named persistent + collection, either by loading data from storage or by creating a new + collection in memory. + Action Group: Non-disruptive - Example: The following example initiates IP address tracking. + + Example: The following example initiates IP address + tracking. + SecAction phase:1,initcol:ip=%{REMOTE_ADDR},nolog + Note - Normally you will want to use phase:1 along with - initcol so that the collection is available in all phases. - Collections are loaded into memory when the initcol action is encountered. The - collection in storage will be persisted (and the appropriate counters increased) - only if it was changed during transaction processing. + + Normally you will want to use phase:1 along + with initcol so that the collection is available in + all phases. + + Collections are loaded into memory when the initcol action is + encountered. The collection in storage will be persisted (and the + appropriate counters increased) only if it was + changed during transaction processing. + See the "Persistant Storage" section for further details.
+
<literal>log</literal> - Description: Indicates that a successful match of the rule needs to - be logged. + + Description: Indicates that a successful + match of the rule needs to be logged. + Action Group: Non-disruptive + Example: + SecAction phase:1,initcol:ip=%{REMOTE_ADDR},log + Note - This action will log matches to the Apache error log file and the ModSecurity audit - log. + + This action will log matches to the Apache error log file and the + ModSecurity audit log.
+
<literal>logdata</literal> - Description: Allows a data fragment to be logged as part of the - alert message. + + Description: Allows a data fragment to be + logged as part of the alert message. + Action Group: Non-disruptive + Example: + SecRule &ARGS:p "@eq 0" "log,logdata:'%{TX.0}'" + Note - The logdata information appears in the error and/or audit log files and is not sent back - to the client in response headers. Macro expansion is preformed so you may use variable - names such as %{TX.0}, etc. The information is properly escaped for use with logging binary - data. + + The logdata information appears in the error and/or audit log + files and is not sent back to the client in response headers. Macro + expansion is preformed so you may use variable names such as %{TX.0}, + etc. The information is properly escaped for use with logging binary + data.
+
<literal>msg</literal> - Description: Assigns a custom message to the rule or chain. + + Description: Assigns a custom message to the + rule or chain. + Action Group: Meta-data + Example: + SecRule &REQUEST_HEADERS:Host "@eq 0" \ "log,id:60008,severity:2,msg:'Request Missing a Host Header'" + Note - The msg information appears in the error and/or audit log files and is not sent back to - the client in response headers. + + The msg information appears in the error and/or audit log files + and is not sent back to the client in response headers.
+
<literal>multiMatch</literal> - Description: If enabled ModSecurity will perform multiple operator - invocations for every target, before and after every anti-evasion transformation is - performed. + + Description: If enabled ModSecurity will + perform multiple operator invocations for every target, before and after + every anti-evasion transformation is performed. + Action Group: Non-disruptive + Example: + SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase SecRule ARGS "attack" multiMatch + Note - Normally, variables are evaluated once, only after all transformation functions have - completed. With multiMatch, variables are checked against the operator before and after - every transformation function that changes the input. + + Normally, variables are evaluated once, only after all + transformation functions have completed. With multiMatch, variables are + checked against the operator before and after every transformation + function that changes the input.
+
<literal>noauditlog</literal> - Description: Indicates that a successful match of the rule should - not be used as criteria whether the transaction should be logged to the audit log. + + Description: Indicates that a successful + match of the rule should not be used as criteria whether the transaction + should be logged to the audit log. + Action Group: Non-disruptive + Example: + SecRule REQUEST_HEADERS:User-Agent "Test" allow,noauditlog + Note - If the SecAuditEngine is set to On, all of the transactions will be logged. If it is set - to RelevantOnly, then you can control it with the noauditlog action. Even if the noauditlog - action is applied to a specific rule and a rule either before or after triggered an audit - event, then the transaction will be logged to the audit log. The correct way to disable - audit logging for the entire transaction is to use "ctl:auditEngine=Off" + + If the SecAuditEngine is set to On, all of the transactions will + be logged. If it is set to RelevantOnly, then you can control it with + the noauditlog action. Even if the noauditlog action is applied to a + specific rule and a rule either before or after triggered an audit + event, then the transaction will be logged to the audit log. The correct + way to disable audit logging for the entire transaction is to use + "ctl:auditEngine=Off"
+
<literal>nolog</literal> - Description: Prevents rule matches from appearing in both the error - and audit logs. + + Description: Prevents rule matches from + appearing in both the error and audit logs. + Action Group: Non-disruptive + Example: + SecRule REQUEST_HEADERS:User-Agent "Test" allow,nolog + Note + The nolog action also implies noauditlog.
+
<literal>pass</literal> - Description: Continues processing with the next rule in spite of a - successful match. + + Description: Continues processing with the + next rule in spite of a successful match. + Action Group: Disruptive + Example1: + SecRule REQUEST_HEADERS:User-Agent "Test" log,pass - When using pass with SecRule with multiple targets, - all targets will be processed and all - non-disruptive actions will trigger for every match found. In the - second example the TX:test target would be incremented by 1 for each matching - argument. + + When using pass with SecRule with multiple + targets, all targets will be processed and + all non-disruptive actions will trigger for + every match found. In the second example the + TX:test target would be incremented by 1 for each matching + argument. + Example2: + SecRule ARGS "test" log,pass,setvar:TX.test=+1 + Note - The transaction will not be interrupted but a log will be generated for each matching - target (unless logging has been suppressed). + + The transaction will not be interrupted but a log will be + generated for each matching target (unless logging has been + suppressed).
+
<literal>pause</literal> - Description: Pauses transaction processing for the specified number - of milliseconds. + + Description: Pauses transaction processing + for the specified number of milliseconds. + Action Group: Non-disruptive + Example: + SecRule REQUEST_HEADERS:User-Agent "Test" log,deny,status:403,pause:5000 + Note - This feature can be of limited benefit for slowing down Brute Force Scanners, however - use with care. If you are under a Denial of Service type of attack, the pause feature may - make matters worse as this feature will cause child processes to sit idle until the pause is - completed. + + This feature can be of limited benefit for slowing down Brute + Force Scanners, however use with care. If you are under a Denial of + Service type of attack, the pause feature may make matters worse as this + feature will cause child processes to sit idle until the pause is + completed.
+
<literal>phase</literal> - Description: Places the rule (or the rule chain) into one of five - available processing phases. + + Description: Places the rule (or the rule + chain) into one of five available processing phases. + Action Group: Meta-data + Example: + SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase SecRule REQUEST_HEADERS:User-Agent "Test" log,deny,status:403 + Note - Keep in mind that is you specify the incorrect phase, the target variable that you - specify may be empty. This could lead to a false negative situation where your variable and - operator (RegEx) may be correct, but it misses malicious data because you specified the - wrong phase. + + Keep in mind that is you specify the incorrect phase, the target + variable that you specify may be empty. This could lead to a false + negative situation where your variable and operator (RegEx) may be + correct, but it misses malicious data because you specified the wrong + phase.
+
prepend - Description: Prepends text given as parameter to the response body. - For this action to work content injection must be enabled by setting SecContentInjection to On. Also make sure you check the - content type of the response before you make changes to it (e.g. you don't want to inject - stuff into images). + + Description: Prepends text given as parameter + to the response body. For this action to work content injection must be + enabled by setting SecContentInjection to + On. Also make sure you check the content type of the + response before you make changes to it (e.g. you don't want to inject + stuff into images). + Action Group: Non-disruptive + Processing Phases: 3 and 4. + Example: + SecRule RESPONSE_CONTENT_TYPE ^text/html "phase:3,nolog,pass,prepend:'Header<br>'" + - While macro expansion is allowed in the additional content, you are strongly cautioned - against inserting user defined data fields. + While macro expansion is allowed in the additional content, you + are strongly cautioned against inserting user defined data + fields.
+
<literal>proxy</literal> - Description: Intercepts transaction by forwarding request to - another web server using the proxy backend. + + Description: Intercepts transaction by + forwarding request to another web server using the proxy backend. + Action Group: Disruptive + Example: + SecRule REQUEST_HEADERS:User-Agent "Test" log,proxy:http://www.honeypothost.com/ + Note - For this action to work, mod_proxy must also be installed. This action is useful if you - would like to proxy matching requests onto a honeypot webserver. + + For this action to work, mod_proxy must also be installed. This + action is useful if you would like to proxy matching requests onto a + honeypot webserver.
+
<literal>redirect</literal> - Description: Intercepts transaction by issuing a redirect to the - given location. + + Description: Intercepts transaction by + issuing a redirect to the given location. + Action Group: Disruptive + Example: + SecRule REQUEST_HEADERS:User-Agent "Test" \ log,redirect:http://www.hostname.com/failed.html + Note - If the status action is present and its value is - acceptable (301, 302, 303, or 307) it will be used for the redirection. Otherwise status - code 302 will be used. + + If the status action is present + and its value is acceptable (301, 302, 303, or 307) it will be used for + the redirection. Otherwise status code 302 will be used.
+
<literal>rev</literal> + Description: Specifies rule revision. + Action Group: Meta-data + Example: + SecRule REQUEST_METHOD "^PUT$" "id:340002,rev:1,severity:2,msg:'Restricted HTTP function'" + Note - This action is used in combination with the id action - to allow the same rule ID to be used after changes take place but to still provide some - indication the rule changed. + + This action is used in combination with the id action to allow the same rule ID to be used + after changes take place but to still provide some indication the rule + changed.
+
<literal>sanitizeArg</literal> - Description: Sanitises (replaces each byte with an asterisk) a - named request argument prior to audit logging. + + Description: Sanitises (replaces each byte + with an asterisk) a named request argument prior to audit + logging. + Action Group: Non-disruptive + Example: + SecAction nolog,phase:2,sanitizeArg:password + Note - The sanitize actions do not sanitize any data within the actual raw requests but only on - the copy of data within memory that is set to log to the audit log. It will not sanitize the - data in the modsec_debug.log file (if the log level is set high enough to capture this - data). + + The sanitize actions do not sanitize any data within the actual + raw requests but only on the copy of data within memory that is set to + log to the audit log. It will not sanitize the data in the + modsec_debug.log file (if the log level is set high enough to capture + this data).
+
<literal>sanitizeMatched</literal> - Description: Sanitises the variable (request argument, request - header, or response header) that caused a rule match. + + Description: Sanitises the variable (request + argument, request header, or response header) that caused a rule + match. + Action Group: Non-disruptive - Example: This action can be used to sanitize arbitrary transaction elements when they - match a condition. For example, the example below will sanitize any argument that contains - the word password in the name. + + Example: This action can be used to sanitize arbitrary transaction + elements when they match a condition. For example, the example below + will sanitize any argument that contains the word + password in the name. + SecRule ARGS_NAMES password nolog,pass,sanitizeMatched + Note + Same note as sanitizeArg.
+
<literal>sanitizeRequestHeader</literal> - Description: Sanitises a named request header. + + Description: Sanitises a named request + header. + Action Group: Non-disruptive - Example: This will sanitize the data in the Authorization header. + + Example: This will sanitize the data in the Authorization + header. + SecAction log,phase:1,sanitizeRequestHeader:Authorization + Note + Same note as sanitizeArg.
+
<literal>sanitizeResponseHeader</literal> - Description: Sanitises a named response header. + + Description: Sanitises a named response + header. + Action Group: Non-disruptive - Example: This will sanitize the Set-Cookie data sent to the client. + + Example: This will sanitize the Set-Cookie data sent to the + client. + SecAction log,phase:3,sanitizeResponseHeader:Set-Cookie + Note + Same note as sanitizeArg.
+
<literal>severity</literal> - Description: Assigns severity to the rule it is placed with. + + Description: Assigns severity to the rule it + is placed with. + Action Group: Meta-data + Example: + SecRule REQUEST_METHOD "^PUT$" "id:340002,rev:1,severity:CRITICAL,msg:'Restricted HTTP function'" + Note - Severity values in ModSecurity follow those of syslog, as below: + + Severity values in ModSecurity follow those of syslog, as + below: + 0 - EMERGENCY + 1 - ALERT + 2 - CRITICAL + 3 - ERROR + 4 - WARNING + 5 - NOTICE + 6 - INFO + 7 - DEBUG - It is possible to specify severity levels using either the numerical values or the text - values. You should always specify severity levels using the text values. The use of the - numerical values is deprecated (as of v2.5.0) and may be removed in one of the susequent - major updates. + + It is possible to specify severity levels using either the + numerical values or the text values. You should always specify severity + levels using the text values. The use of the numerical values is + deprecated (as of v2.5.0) and may be removed in one of the susequent + major updates.
+
<literal>setuid</literal> - Description: Special-purpose action that initialises the USER collection. + + Description: Special-purpose action that + initialises the USER + collection. + Action Group: Non-disruptive + Example: + SecAction setuid:%{REMOTE_USER},nolog + Note - After initialisation takes place the variable USERID - will be available for use in the subsequent rules. + + After initialisation takes place the variable USERID will be available for use in the + subsequent rules.
+
<literal>setsid</literal> - Description: Special-purpose action that initialises the SESSION collection. + + Description: Special-purpose action that + initialises the SESSION + collection. + Action Group: Non-disruptive + Example: + # Initialise session variables using the session cookie value SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass SecAction setsid:%{REQUEST_COOKIES.PHPSESSID} + Note - On first invocation of this action the collection will be empty (not taking the - predefined variables into account - see initcol for more - information). On subsequent invocations the contents of the collection (session, in this - case) will be retrieved from storage. After initialisation takes place the variable SESSIONID will be available for use in the subsequent - rules.This action understands each application maintains its own set of sessions. It will - utilise the current web application ID to create a session namespace. + + On first invocation of this action the collection will be empty + (not taking the predefined variables into account - see initcol for more information). On subsequent + invocations the contents of the collection (session, in this case) will + be retrieved from storage. After initialisation takes place the + variable SESSIONID will be available + for use in the subsequent rules.This action understands each application + maintains its own set of sessions. It will utilise the current web + application ID to create a session namespace.
+
<literal>setenv</literal> - Description: Creates, removes, or updates an environment - variable. + + Description: Creates, removes, or updates an + environment variable. + Action Group: Non-disruptive + Examples: - To create a new variable (if you omit the value 1 - will be used): + + To create a new variable (if you omit the value 1 will be used): + setenv:name=value + To remove a variable: + setenv:!name + Note - This action can be used to establish communication with other Apache modules. + + This action can be used to establish communication with other + Apache modules.
+
<literal>setvar</literal> - Description: Creates, removes, or updates a variable in the - specified collection. + + Description: Creates, removes, or updates a + variable in the specified collection. + Action Group: Non-disruptive + Examples: + To create a new variable: + setvar:tx.score=10 + To remove a variable prefix the name with exclamation mark: + setvar:!tx.score - To increase or decrease variable value use + and - - characters in front of a numerical value: + + To increase or decrease variable value use + and - + characters in front of a numerical value: + setvar:tx.score=+5
+
<literal>skip</literal> - Description: Skips one or more rules (or chains) on successful - match. + + Description: Skips one or more rules (or + chains) on successful match. + Action Group: Flow + Example: - - SecRule REQUEST_URI "^/$" \ + + SecRule REQUEST_URI "^/$" \ "phase:2,chain,t:none,skip:2" SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain" SecRule REQUEST_HEADERS:User-Agent "^Apache \(internal dummy connection\)$" "t:none" SecRule &REQUEST_HEADERS:Host "@eq 0" \ "deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'" SecRule &REQUEST_HEADERS:Accept "@eq 0" \ - "log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'" - + "log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'" + Note - Skip only applies to the current processing phase and not necessarily the order in which - the rules appear in the configuration file. If you group rules by processing phases, then - skip should work as expected. This action can not be used to skip rules within one chain. - Accepts a single parameter denoting the number of rules (or chains) to skip. + + Skip only applies to the current processing phase and not + necessarily the order in which the rules appear in the configuration + file. If you group rules by processing phases, then skip should work as + expected. This action can not be used to skip rules within one chain. + Accepts a single parameter denoting the number of rules (or chains) to + skip.
+
<literal>skipAfter</literal> - Description: Skips rules (or chains) on successful match resuming - rule execution after the specified rule ID or marker (see SecMarker) is - found. + + Description: Skips rules (or chains) on + successful match resuming rule execution after the specified rule ID or + marker (see SecMarker) is found. + Action Group: Flow + Example: - - SecRule REQUEST_URI "^/$" "chain,t:none,skipAfter:960015" + + SecRule REQUEST_URI "^/$" "chain,t:none,skipAfter:960015" SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain" SecRule REQUEST_HEADERS:User-Agent "^Apache \(internal dummy connection\)$" "t:none" SecRule &REQUEST_HEADERS:Host "@eq 0" \ "deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'" SecRule &REQUEST_HEADERS:Accept "@eq 0" \ - "log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'" - + "log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'" + Note - SkipAfter only applies to the current processing phase and not - necessarily the order in which the rules appear in the configuration file. If you group - rules by processing phases, then skip should work as expected. This action can not be used - to skip rules within one chain. Accepts a single parameter denoting the last rule ID to - skip. + + SkipAfter only applies to the current + processing phase and not necessarily the order in which the rules appear + in the configuration file. If you group rules by processing phases, then + skip should work as expected. This action can not be used to skip rules + within one chain. Accepts a single parameter denoting the last rule ID + to skip.
+
<literal>status</literal> - Description: Specifies the response status code to use with - actions deny and - redirect. + + Description: Specifies the response status + code to use with actions deny + and redirect. + Action Group: Data + Example: + SecDefaultAction log,deny,status:403,phase:1 + Note - Status actions defined in Apache scope locations (such as Directory, Location, etc...) - may be superseded by phase:1 action settings. The Apache ErrorDocument directive will be - triggered if present in the configuration. Therefore if you have previously defined a custom - error page for a given status then it will be executed and its output presented to the - user. + + Status actions defined in Apache scope locations (such as + Directory, Location, etc...) may be superseded by phase:1 action + settings. The Apache ErrorDocument directive will be triggered if + present in the configuration. Therefore if you have previously defined a + custom error page for a given status then it will be executed and its + output presented to the user.
+
<literal>t</literal> - Description: This action can be used which transformation function - should be used against the specified variables before they (or the results, rather) are run - against the operator specified in the rule. + + Description: This action can be used which + transformation function should be used against the specified variables + before they (or the results, rather) are run against the operator + specified in the rule. + Action Group: Non-disruptive + Example: + SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase SecRule REQUEST_COOKIES:SESSIONID "47414e81cbbef3cf8366e84eeacba091" \ log,deny,status:403,t:md5,t:hexEncode + Note - Any transformation functions that you specify in a SecRule will be in addition to - previous ones specified in SecDefaultAction. Use of "t:none" will remove all transformation - functions for the specified rule. + + Any transformation functions that you specify in a SecRule will be + in addition to previous ones specified in SecDefaultAction. Use of + "t:none" will remove all transformation functions for the specified + rule.
+
<literal>tag</literal> - Description: Assigns custom text to a rule or chain. + + Description: Assigns custom text to a rule or + chain. + Action Group: Meta-data + Example: + SecRule REQUEST_FILENAME "\b(?:n(?:map|et|c)|w(?:guest|sh)|cmd(?:32)?|telnet|rcmd|ftp)\.exe\b" \ "t:none,t:lowercase,deny,msg:'System Command Access',id:'950002',\ tag:'WEB_ATTACK/FILE_INJECTION',tag:'OWASP/A2',severity:'2'" + Note - The tag information appears in the error and/or audit log files. Its intent is to be - used to automate classification of rules and the alerts generated by rules. Multiple tags - can be used per rule/chain. + + The tag information appears in the error and/or audit log files. + Its intent is to be used to automate classification of rules and the + alerts generated by rules. Multiple tags can be used per + rule/chain.
+
<literal>xmlns</literal> - Description: This action should be used together with an XPath - expression to register a namespace. + + Description: This action should be used + together with an XPath expression to register a namespace. + Action Group: Data + Example: + SecRule REQUEST_HEADERS:Content-Type "text/xml" \ "phase:1,pass,ctl:requestBodyProcessor=XML,ctl:requestBodyAccess=On, \ xmlns:xsd="http://www.w3.org/2001/XMLSchema" SecRule XML:/soap:Envelope/soap:Body/q1:getInput/id() "123" phase:2,deny
+
Operators - A number of operators can be used in rules, as documented below. The operator syntax uses - the @ symbol followed by the specific operator name. + + A number of operators can be used in rules, as documented below. The + operator syntax uses the @ symbol followed by the + specific operator name. +
<literal>beginsWith</literal> - Description: This operator is a string comparison and returns true - if the parameter value is found at the beginning of the input. Macro expansion is performed - so you may use variable names such as %{TX.1}, etc. + + Description: This operator is a string + comparison and returns true if the parameter value is found at the + beginning of the input. Macro expansion is performed so you may use + variable names such as %{TX.1}, etc. + Example: + SecRule REQUEST_LINE "!@beginsWith GET" t:none,deny,status:403 SecRule REQUEST_ADDR "^(.*)\.\d+$" deny,status:403,capture,chain SecRule ARGS:gw "!@beginsWith %{TX.1}"
+
<literal>contains</literal> - Description: This operator is a string comparison and returns true - if the parameter value is found anywhere in the input. Macro expansion is performed so you - may use variable names such as %{TX.1}, etc. + + Description: This operator is a string + comparison and returns true if the parameter value is found anywhere in + the input. Macro expansion is performed so you may use variable names + such as %{TX.1}, etc. + Example: + SecRule REQUEST_LINE "!@contains .php" t:none,deny,status:403 SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain SecRule ARGS:ip "!@contains %{TX.1}"
+
<literal>endsWith</literal> - Description: This operator is a string comparison and returns true - if the parameter value is found at the end of the input. Macro expansion is performed so you - may use variable names such as %{TX.1}, etc. + + Description: This operator is a string + comparison and returns true if the parameter value is found at the end + of the input. Macro expansion is performed so you may use variable names + such as %{TX.1}, etc. + Example: + SecRule REQUEST_LINE "!@endsWith HTTP/1.1" t:none,deny,status:403 SecRule ARGS:route "!@endsWith %{REQUEST_ADDR}" t:none,deny,status:403
+
<literal>eq</literal> - Description: This operator is a numerical comparison and stands for - "equal to." + + Description: This operator is a numerical + comparison and stands for "equal to." + Example: + SecRule &REQUEST_HEADERS_NAMES "@eq 15" Macro expansion is performed so you may use variable names such as %{TX.1}, etc.
+
<literal>ge</literal> - Description: This operator is a numerical comparison and stands for - "greater than or equal to." + + Description: This operator is a numerical + comparison and stands for "greater than or equal to." + Example: + SecRule &REQUEST_HEADERS_NAMES "@ge 15" Macro expansion is performed so you may use variable names such as %{TX.1}, etc.
+
<literal>geoLookup</literal> - Description: This operator looks up various data fields from an IP - address or hostname in the target data. The results will be captured in the GEO collection. - You must provide a database via SecGeoLookupDb before - this operator can be used. + + Description: This operator looks up various + data fields from an IP address or hostname in the target data. The + results will be captured in the GEO + collection. + + You must provide a database via SecGeoLookupDb before this operator can be + used. + - This operator matches and the action is executed on a successful - lookup. For this reason, you probably want to use the pass,nolog - actions. This allows for setvar and other - non-disruptive actions to be executed on a match. If you wish to block on a failed lookup, - then do something like this (look for an empty GEO collection): + This operator matches and the action is executed on a + successful lookup. For this reason, you probably want to + use the pass,nolog actions. This allows for + setvar and other non-disruptive + actions to be executed on a match. If you wish to block on a failed + lookup, then do something like this (look for an empty GEO + collection): + SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat ... SecRule REMOTE_ADDR "@geoLookup" "pass,nolog" SecRule &GEO "@eq 0" "deny,status:403,msg:'Failed to lookup IP'" - See the GEO variable for an example and more - information on various fields available. + + See the GEO variable for an + example and more information on various fields available.
+
<literal>gt</literal> - Description: This operator is a numerical comparison and stands for - "greater than." + + Description: This operator is a numerical + comparison and stands for "greater than." + Example: + SecRule &REQUEST_HEADERS_NAMES "@gt 15" Macro expansion is performed so you may use variable names such as %{TX.1}, etc.
+
<literal>inspectFile</literal> - Description: Executes the external script/binary given as parameter - to the operator against every file extracted from the request. As of v2.5.0, if the supplied - filename is not absolute it is treated as relative to the directory in which the - configuration file resides. Also as of v2.5.0, if the filename is determined to be a Lua - script (based on its extension) the script will be processed by the internal engine. As such - it will have full access to the ModSecurity context. + + Description: Executes the external + script/binary given as parameter to the operator against every file + extracted from the request. As of v2.5.0, if the supplied filename is + not absolute it is treated as relative to the directory in which the + configuration file resides. Also as of v2.5.0, if the filename is + determined to be a Lua script (based on its extension) the script will + be processed by the internal engine. As such it will have full access to + the ModSecurity context. + Example of using an external binary/script: + # Execute external script to validate uploaded files. SecRule FILES_TMPNAMES "@inspectFile /opt/apache/bin/inspect_script.pl" + Example of using Lua script: + SecRule FILES_TMPNANMES "@inspectFile inspect.lua" + Script inspect.lua: + function main(filename) -- Do something to the file to verify it. In this example, we -- read up to 10 characters from the beginning of the file. @@ -3963,43 +5808,63 @@ SecRule FILES_TMPNAMES "@inspectFile /opt/apache/bin/inspec return null; end
+
<literal>le</literal> - Description: This operator is a numerical comparison and stands for - "less than or equal to." + + Description: This operator is a numerical + comparison and stands for "less than or equal to." + Example: + SecRule &REQUEST_HEADERS_NAMES "@le 15" Macro expansion is performed so you may use variable names such as %{TX.1}, etc.
+
<literal>lt</literal> - Description: This operator is a numerical comparison and stands for - "less than." + + Description: This operator is a numerical + comparison and stands for "less than." + Example: + SecRule &REQUEST_HEADERS_NAMES "@lt 15" Macro expansion is performed so you may use variable names such as %{TX.1}, etc.
+
<literal>pm</literal> - Description: Phrase Match operator. This operator uses a set based - matching engine (Aho-Corasick) for faster matches of keyword lists. It will match any one of - its arguments anywhere in the target value. The match is case insensitive. + + Description: Phrase Match operator. This + operator uses a set based matching engine (Aho-Corasick) for faster + matches of keyword lists. It will match any one of its arguments + anywhere in the target value. The match is case insensitive. + Example: + SecRule REQUEST_HEADERS:User-Agent "@pm WebZIP WebCopier Webster WebStripper SiteSnagger ProWebWalker CheeseBot" "deny,status:403 - The above would deny access with 403 if any of the words matched within the User-Agent - HTTP header value. + + The above would deny access with 403 if any of the words matched + within the User-Agent HTTP header value.
+
<literal>pmFromFile</literal> - Description: Phrase Match operator. This operator uses a set based - matching engine (Aho-Corasick) for faster matches of keyword lists. This operator is the - same as @pm except that it takes a list of files as arguments. It will - match any one of the phrases listed in the file(s) anywhere in the target value. + + Description: Phrase Match operator. This + operator uses a set based matching engine (Aho-Corasick) for faster + matches of keyword lists. This operator is the same as + @pm except that it takes a list of files as + arguments. It will match any one of the phrases listed in the file(s) + anywhere in the target value. + Notes: + The contents of the files should be one phrase per line. End @@ -4007,10 +5872,12 @@ end whitespace is trimmed from both sides of the phrases. Empty lines and comment lines (beginning with a '#') are ignored. + - To allow easier inclusion of phrase files with rulesets, relative paths may be used - to the phrase files. In this case, the path of the file containing the rule is prepended - to the phrase file path. + To allow easier inclusion of phrase files with rulesets, + relative paths may be used to the phrase files. In this case, the + path of the file containing the rule is prepended to the phrase file + path. @@ -4031,323 +5898,464 @@ SecRule TX:REMOTE_ADDR "@pmFromFile ip-blacklist.txt" "deny /5.6.7.8/ + Example: + SecRule REQUEST_HEADERS:User-Agent "@pm /path/to/blacklist1 blacklist2" "deny,status:403 - The above would deny access with 403 if any of the patterns in the two files matched - within the User-Agent HTTP header value. The blacklist2 file would need - to be placed in the same path as the file containing the rule. + + The above would deny access with 403 if any of the patterns in the + two files matched within the User-Agent HTTP header value. The + blacklist2 file would need to be placed in the same + path as the file containing the rule.
+
<literal>rbl</literal> - Description: Look up the parameter in the RBL given as parameter. - Parameter can be an IPv4 address, or a hostname. + + Description: Look up the parameter in the RBL + given as parameter. Parameter can be an IPv4 address, or a + hostname. + Example: + SecRule REMOTE_ADDR "@rbl sc.surbl.org"
+
<literal>rx</literal> - Description: Regular expression operator. This is the default - operator, so if the "@" operator is not defined, it is assumed to be rx. + + Description: Regular expression operator. + This is the default operator, so if the "@" operator is not defined, it + is assumed to be rx. + Example: + SecRule REQUEST_HEADERS:User-Agent "@rx nikto" + Note - Regular expressions are handled by the PCRE library (http://www.pcre.org). ModSecurity compiles its regular expressions with the - following settings: + + Regular expressions are handled by the PCRE library (http://www.pcre.org). ModSecurity + compiles its regular expressions with the following settings: + - The entire input is treated as a single line, even when there are newline characters - present. + The entire input is treated as a single line, even when there + are newline characters present. + - All matches are case-sensitive. If you do not care about case sensitivity you either - need to implement the lowercase transformation - function, or use the per-pattern(?i)modifier, as - allowed by PCRE. + All matches are case-sensitive. If you do not care about case + sensitivity you either need to implement the lowercase transformation function, or use + the per-pattern(?i)modifier, as + allowed by PCRE. + - The PCRE_DOTALL and PCRE_DOLLAR_ENDONLY flags are set during compilation, meaning a single dot - will match any character, including the newlines and a $ end anchor will not match a trailing newline character. + The PCRE_DOTALL and + PCRE_DOLLAR_ENDONLY flags are set + during compilation, meaning a single dot will match any character, + including the newlines and a $ + end anchor will not match a trailing newline character.
+
<literal>streq</literal> - Description: This operator is a string comparison and returns true - if the parameter value matches the input exactly. Macro expansion is performed so you may - use variable names such as %{TX.1}, etc. + + Description: This operator is a string + comparison and returns true if the parameter value matches the input + exactly. Macro expansion is performed so you may use variable names such + as %{TX.1}, etc. + Example: + SecRule ARGS:foo "!@streq bar" t:none,deny,status:403 SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain SecRule REQUEST_HEADERS:Ip-Address "!@streq %{TX.1}"
+
<literal>validateByteRange</literal> - Description: Validates the byte range used in the variable falls - into the specified range. + + Description: Validates the byte range used in + the variable falls into the specified range. + Example: + SecRule ARGS:text "@validateByteRange 10, 13, 32-126" + Note - You can force requests to consist only of bytes from a certain byte range. This can be - useful to avoid stack overflow attacks (since they usually contain "random" binary content). - Default range values are 0 and 255, i.e. all byte values are allowed. This directive does - not check byte range in a POST payload when multipart/form-data encoding - (file upload) is used. Doing so would prevent binary files from being uploaded. However, - after the parameters are extracted from such request they are checked for a valid - range. - validateByteRange is similar to the ModSecurity 1.X SecFilterForceByteRange Directive - however since it works in a rule context, it has the following differences: + + You can force requests to consist only of bytes from a certain + byte range. This can be useful to avoid stack overflow attacks (since + they usually contain "random" binary content). Default range values are + 0 and 255, i.e. all byte values are allowed. This directive does not + check byte range in a POST payload when + multipart/form-data encoding (file upload) is used. + Doing so would prevent binary files from being uploaded. However, after + the parameters are extracted from such request they are checked for a + valid range. + + validateByteRange is similar to the ModSecurity 1.X + SecFilterForceByteRange Directive however since it works in a rule + context, it has the following differences: + - You can specify a different range for different variables. + You can specify a different range for different + variables. + It has an "event" context (id, msg....) + - It is executed in the flow of rules rather than being a built in pre-check. + It is executed in the flow of rules rather than being a built + in pre-check.
+
<literal>validateDTD</literal> - Description: Validates the DOM tree generated by the XML request - body processor against the supplied DTD. + + Description: Validates the DOM tree generated + by the XML request body processor against the supplied DTD. + Example: + SecDefaultAction log,deny,status:403,phase:2 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \ phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345 SecRule XML "@validateDTD /path/to/apache2/conf/xml.dtd" "deny,id:12345" + - This operator requires request body to be processed as XML. + This operator requires request body to be processed as + XML.
+
<literal>validateSchema</literal> - Description: Validates the DOM tree generated by the XML request - body processor against the supplied XML Schema. + + Description: Validates the DOM tree generated + by the XML request body processor against the supplied XML + Schema. + Example: + SecDefaultAction log,deny,status:403,phase:2 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \ phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345 SecRule XML "@validateSchema /path/to/apache2/conf/xml.xsd" "deny,id:12345" + - This operator requires request body to be processed as XML. + This operator requires request body to be processed as + XML.
+
<literal>validateUrlEncoding</literal> - Description: Verifies the encodings used in the variable (if any) - are valid. + + Description: Verifies the encodings used in + the variable (if any) are valid. + Example: + SecRule ARGS "@validateUrlEncoding" + Note - URL encoding is an HTTP standard for encoding byte values within a URL. The byte is - escaped with a % followed by two hexadecimal values (0-F). This directive does not check - encoding in a POST payload when the multipart/form-data encoding (file - upload) is used. It is not necessary to do so because URL encoding is not used for this - encoding. + + URL encoding is an HTTP standard for encoding byte values within a + URL. The byte is escaped with a % followed by two hexadecimal values + (0-F). This directive does not check encoding in a POST payload when the + multipart/form-data encoding (file upload) is used. + It is not necessary to do so because URL encoding is not used for this + encoding.
+
<literal>validateUtf8Encoding</literal> - Description: Verifies the variable is a valid UTF-8 encoded - string. + + Description: Verifies the variable is a valid + UTF-8 encoded string. + Example: + SecRule ARGS "@validateUtf8Encoding" + Note - UTF-8 encoding is valid on most web servers. Integer values between 0-65535 are encoded - in a UTF-8 byte sequence that is escaped by percents. The short form is two bytes in - length. + + UTF-8 encoding is valid on most web servers. Integer values + between 0-65535 are encoded in a UTF-8 byte sequence that is escaped by + percents. The short form is two bytes in length. + check for three types of errors: + - Not enough bytes. UTF-8 supports two, three, four, five, and six byte encodings. - ModSecurity will locate cases when a byte or more is missing. + Not enough bytes. UTF-8 supports two, three, four, five, and + six byte encodings. ModSecurity will locate cases when a byte or + more is missing. + - Invalid encoding. The two most significant bits in most characters are supposed to - be fixed to 0x80. Attackers can use this to subvert Unicode decoders. + Invalid encoding. The two most significant bits in most + characters are supposed to be fixed to 0x80. Attackers can use this + to subvert Unicode decoders. + - Overlong characters. ASCII characters are mapped directly into the Unicode space and - are thus represented with a single byte. However, most ASCII characters can also be - encoded with two, three, four, five, and six characters thus tricking the decoder into - thinking that the character is something else (and, presumably, avoiding the security - check). + Overlong characters. ASCII characters are mapped directly into + the Unicode space and are thus represented with a single byte. + However, most ASCII characters can also be encoded with two, three, + four, five, and six characters thus tricking the decoder into + thinking that the character is something else (and, presumably, + avoiding the security check).
+
<literal>verifyCC</literal> - Description: This operator verifies a given regular expression as a - potential credit card number. It first matches with a single generic regular expression then - runs the resulting match through a Luhn checksum algorithm to further verify it as a - potential credit card number. + + Description: This operator verifies a given + regular expression as a potential credit card number. It first matches + with a single generic regular expression then runs the resulting match + through a Luhn checksum algorithm to further verify it as a potential + credit card number. + Example: + SecRule ARGS "@verifyCC \d{13,16}" \ "phase:2,sanitizeMatched,log,auditlog,pass,msg:'Potential credit card number'"
+
<literal>within</literal> - Description: This operator is a string comparison and returns true - if the input value is found anywhere within the parameter value. Note that this is similar - to @contains, except that the target and match values are reversed. Macro - expansion is performed so you may use variable names such as %{TX.1}, etc. + + Description: This operator is a string + comparison and returns true if the input value is found anywhere within + the parameter value. Note that this is similar to + @contains, except that the target and match values + are reversed. Macro expansion is performed so you may use variable names + such as %{TX.1}, etc. + Example: + SecRule REQUEST_METHOD "!@within get,post,head" t:lowercase,deny,status:403 SecAction "pass,setvar:'tx.allowed_methods=get,post,head'" SecRule REQUEST_METHOD "!@within %{tx.allowed_methods}" t:lowercase,deny,status:403
+
Macro Expansion - Macros allow for using place holders in rules that will be expanded out to their values at - runtime. Currently only variable expansion is supported, however more options may be added in - future versions of ModSecurity. + + Macros allow for using place holders in rules that will be expanded + out to their values at runtime. Currently only variable expansion is + supported, however more options may be added in future versions of + ModSecurity. + Format: + %{VARIABLE} %{COLLECTION.VARIABLE} - Macro expansion can be used in actions such as initcol, setsid, setuid, setvar, setenv, - logdata. Operators that are evaluated at runtime support expansion and are noted above. Such - operators include @beginsWith, @endsWith, @contains, @within and @streq. You cannot use macro - expansion for operators that are "compiled" such as @pm, @rx, etc. as these operators have - their values fixed at configure time for efficiency. - Some values you may want to expand include: TX, REMOTE_ADDR, USERID, HIGHEST_SEVERITY, - MATCHED_VAR, MATCHED_VAR_NAME, MULTIPART_STRICT_ERROR, RULE, SESSION, USERID, among - others. + + Macro expansion can be used in actions such as initcol, setsid, + setuid, setvar, setenv, logdata. Operators that are evaluated at runtime + support expansion and are noted above. Such operators include @beginsWith, + @endsWith, @contains, @within and @streq. You cannot use macro expansion + for operators that are "compiled" such as @pm, @rx, etc. as these + operators have their values fixed at configure time for efficiency. + + Some values you may want to expand include: TX, REMOTE_ADDR, USERID, + HIGHEST_SEVERITY, MATCHED_VAR, MATCHED_VAR_NAME, MULTIPART_STRICT_ERROR, + RULE, SESSION, USERID, among others.
+
Persistant Storage - At this time it is only possible to have three collections in which data is stored - persistantly (i.e. data available to multiple requests). These are: IP, SESSION and USER. - Every collection contains several built-in variables that are available and are read-only - unless otherwise specified: + + At this time it is only possible to have three collections in which + data is stored persistantly (i.e. data available to multiple requests). + These are: IP, SESSION and USER. + + Every collection contains several built-in variables that are + available and are read-only unless otherwise specified: + - CREATE_TIME - date/time of the creation of the - collection. + CREATE_TIME - date/time of + the creation of the collection. + - IS_NEW - set to 1 if the collection is new (not yet - persisted) otherwise set to 0. + IS_NEW - set to 1 if the + collection is new (not yet persisted) otherwise set to 0. + - KEY - the value of the initcol variable (the - client's IP address in the example). + KEY - the value of the + initcol variable (the client's IP address in the example). + - LAST_UPDATE_TIME - date/time of the last update to - the collection. + LAST_UPDATE_TIME - date/time + of the last update to the collection. + - TIMEOUT - date/time in seconds when the collection - will be updated on disk from memory (if no other updates occur). This variable may be set - if you wish to specifiy an explicit expiration time (default is 3600 seconds). + TIMEOUT - date/time in + seconds when the collection will be updated on disk from memory (if no + other updates occur). This variable may be set if you wish to specifiy + an explicit expiration time (default is 3600 seconds). + - UPDATE_COUNTER - how many times the collection has - been updated since creation. + UPDATE_COUNTER - how many + times the collection has been updated since creation. + - UPDATE_RATE - is the average rate updates per - minute since creation. + UPDATE_RATE - is the average + rate updates per minute since creation. - To create a collection to hold session variables (SESSION) use action setsid. To create a - collection to hold user variables (USER) use action - setuid. To create a collection to hold client address - variables (IP) use action initcol. + + To create a collection to hold session variables (SESSION) use action setsid. To create a collection to hold user + variables (USER) use action setuid. To create a collection to hold client + address variables (IP) use action + initcol. + - ModSecurity implements atomic updates of persistent variables only for integer variables - (counters) at this time. Variables are read from storage whenever initcol - is encountered in the rules and persisted at the end of request processing. Counters are - adjusted by applying a delta generated by re-reading the persisted data just before being - persisted. This keeps counter data consistent even if the counter was modified and persisted - by another thread/process during the transaction. + ModSecurity implements atomic updates of persistent variables only + for integer variables (counters) at this time. Variables are read from + storage whenever initcol is encountered in the rules + and persisted at the end of request processing. Counters are adjusted by + applying a delta generated by re-reading the persisted data just before + being persisted. This keeps counter data consistent even if the counter + was modified and persisted by another thread/process during the + transaction. + - ModSecurity uses a Berkley Database (SDBM) for persistant storage. This type of database - is generally limited to storing a maximum of 1008 bytes per key. This may be a limitation if - you are attempting to store a considerable amount of data in variables for a single key. - Some of this limitation is planned to be reduced in a future version of ModSecurity. + ModSecurity uses a Berkley Database (SDBM) for persistant storage. + This type of database is generally limited to storing a maximum of 1008 + bytes per key. This may be a limitation if you are attempting to store a + considerable amount of data in variables for a single key. Some of this + limitation is planned to be reduced in a future version of + ModSecurity.
+
Miscellaneous Topics - + + +
Impedance Mismatch - Web application firewalls have a difficult job trying to make sense of data that passes - by, without any knowledge of the application and its business logic. The protection they - provide comes from having an independent layer of security on the outside. Because data - validation is done twice, security can be increased without having to touch the application. - In some cases, however, the fact that everything is done twice brings problems. Problems can - arise in the areas where the communication protocols are not well specified, or where either - the device or the application do things that are not in the specification. In such cases it - may be possible to design payload that will be interpreted in one way by one device and in - another by the other device. This problem is better known as Impedance Mismatch. It can be - exploited to evade the security devices. - While we will continue to enhance ModSecurity to deal with various evasion techniques - the problem can only be minimized, but never solved. With so many different application - backend chances are some will always do something completely unexpected. The only solution - is to be aware of the technologies in the backend when writing rules, adapting the rules to - remove the mismatch. See the next section for some examples. + + Web application firewalls have a difficult job trying to make + sense of data that passes by, without any knowledge of the application + and its business logic. The protection they provide comes from having an + independent layer of security on the outside. Because data validation is + done twice, security can be increased without having to touch the + application. In some cases, however, the fact that everything is done + twice brings problems. Problems can arise in the areas where the + communication protocols are not well specified, or where either the + device or the application do things that are not in the specification. + In such cases it may be possible to design payload that will be + interpreted in one way by one device and in another by the other device. + This problem is better known as Impedance Mismatch. It can be exploited + to evade the security devices. + + While we will continue to enhance ModSecurity to deal with various + evasion techniques the problem can only be minimized, but never solved. + With so many different application backend chances are some will always + do something completely unexpected. The only solution is to be aware of + the technologies in the backend when writing rules, adapting the rules + to remove the mismatch. See the next section for some examples. +
PHP Peculiarities for ModSecurity Users - When writing rules to protect PHP applications you need to pay attention to the - following facts: + + When writing rules to protect PHP applications you need to pay + attention to the following facts: + - When "register_globals" is set to "On" request parameters are automatically - converted to script variables. In some PHP versions it is even possible to override - the $GLOBALS array. + When "register_globals" is set to "On" request parameters + are automatically converted to script variables. In some PHP + versions it is even possible to override the $GLOBALS + array. + - Whitespace at the beginning of parameter names is ignored. (This is very dangerous - if you are writing rules to target specific named variables.) + Whitespace at the beginning of parameter names is ignored. + (This is very dangerous if you are writing rules to target + specific named variables.) + - The remaining whitespace (in parameter names) is converted to underscores. The - same applies to dots and to a "[" if the variable name does not contain a matching - closing bracket. (Meaning that if you want to exploit a script through a variable that - contains an underscore in the name you can send a parameter with a whitespace or a dot - instead.) + The remaining whitespace (in parameter names) is converted + to underscores. The same applies to dots and to a "[" if the + variable name does not contain a matching closing bracket. + (Meaning that if you want to exploit a script through a variable + that contains an underscore in the name you can send a parameter + with a whitespace or a dot instead.) + Cookies can be treated as request parameters. + - The discussion about variable names applies equally to the cookie names. + The discussion about variable names applies equally to the + cookie names. + - The order in which parameters are taken from the request and the environment is - EGPCS (environment, GET, POST, Cookies, built-in variables). This means that a POST - parameter will overwrite the parameters transported on the request line (in - QUERY_STRING). + The order in which parameters are taken from the request and + the environment is EGPCS (environment, GET, POST, Cookies, + built-in variables). This means that a POST parameter will + overwrite the parameters transported on the request line (in + QUERY_STRING). + - When "magic_quotes_gpc" is set to "On" PHP will use backslash to escape the - following characters: single quote, double quote, backslash, and the nul byte. + When "magic_quotes_gpc" is set to "On" PHP will use + backslash to escape the following characters: single quote, double + quote, backslash, and the nul byte. + - If "magic_quotes_sybase" is set to "On" only the single quote will be escaped - using another single quote. In this case the "magic_quotes_gpc" setting becomes - irrelevant. The "magic_quotes_sybase" setting completely overrides the - "magic_quotes_gpc" behaviour but "magic_quotes_gpc" still must be set to "On" for the - Sybase-specific quoting to be work. + If "magic_quotes_sybase" is set to "On" only the single + quote will be escaped using another single quote. In this case the + "magic_quotes_gpc" setting becomes irrelevant. The + "magic_quotes_sybase" setting completely overrides the + "magic_quotes_gpc" behaviour but "magic_quotes_gpc" still must be + set to "On" for the Sybase-specific quoting to be work. + - PHP will also automatically create nested arrays for you. For example "p[x][y]=1" - results in a total of three variables. + PHP will also automatically create nested arrays for you. + For example "p[x][y]=1" results in a total of three + variables.