1 <?xml version="1.0" encoding="UTF-8"?>
2 <!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.2//EN"
3 "http://www.oasis-open.org/docbook/xml/4.2/docbookx.dtd">
5 <title><trademark class="registered">ModSecurity</trademark> Reference
9 <releaseinfo>Version 2.5.11 (Nov 4, 2009)</releaseinfo>
12 <year>2004-2009</year>
14 <holder>Breach Security, Inc. (<ulink
15 url="http://www.breach.com">http://www.breach.com</ulink>)</holder>
19 <section id="introduction">
20 <title>Introduction</title>
22 <para>ModSecurity is a web application firewall (WAF). With over 70% of
23 attacks now carried out over the web application level, organisations need
24 all the help they can get in making their systems secure. WAFs are
25 deployed to establish an increased external security layer to detect
26 and/or prevent attacks before they reach web applications. ModSecurity
27 provides protection from a range of attacks against web applications and
28 allows for HTTP traffic monitoring and real-time analysis with little or
29 no changes to existing infrastructure.</para>
32 <title>HTTP Traffic Logging</title>
34 <para>Web servers are typically well-equipped to log traffic in a form
35 useful for marketing analyses, but fall short logging traffic to web
36 applications. In particular, most are not capable of logging the request
37 bodies. Your adversaries know this, and that is why most attacks are now
38 carried out via POST requests, rendering your systems blind. ModSecurity
39 makes full HTTP transaction logging possible, allowing complete requests
40 and responses to be logged. Its logging facilities also allow
41 fine-grained decisions to be made about exactly what is logged and when,
42 ensuring only the relevant data is recorded. As some of the request
43 and/or response may contain sensitive data in certain fields,
44 ModSecurity can be configured to mask these fields before they are
45 written to the audit log.</para>
49 <title>Real-Time Monitoring and Attack Detection</title>
51 <para>In addition to providing logging facilities, ModSecurity can
52 monitor the HTTP traffic in real time in order to detect attacks. In
53 this case, ModSecurity operates as a web intrusion detection tool,
54 allowing you to react to suspicious events that take place at your web
59 <title>Attack Prevention and Just-in-time Patching</title>
61 <para>ModSecurity can also act immediately to prevent attacks from
62 reaching your web applications. There are three commonly used
65 <orderedlist continuation="restarts" inheritnum="ignore">
67 <para>Negative security model. A negative security model monitors
68 requests for anomalies, unusual behaviour, and common web
69 application attacks. It keeps anomaly scores for each request, IP
70 addresses, application sessions, and user accounts. Requests with
71 high anomaly scores are either logged or rejected altogether.</para>
75 <para>Positive security model. When a positive security model is
76 deployed, only requests that are known to be valid are accepted,
77 with everything else rejected. This model requires knownledge of the
78 web applications you are protecting. Therefore a positive security
79 model works best with applications that are heavily used but rarely
80 updated so that maintenance of the model is minimized.</para>
84 <para>Known weaknesses and vulnerabilities. Its rule language makes
85 ModSecurity an ideal external patching tool. External patching
86 (sometimes referred to as Virtual Patching) is about reducing the
87 window of opportunity. Time needed to patch application
88 vulnerabilities often runs to weeks in many organisations. With
89 ModSecurity, applications can be patched from the outside, without
90 touching the application source code (and even without any access to
91 it), making your systems secure until a proper patch is applied to
92 the application.</para>
98 <title>Flexible Rule Engine</title>
100 <para>A flexible rule engine sits in the heart of ModSecurity. It
101 implements the ModSecurity Rule Language, which is a specialised
102 programming language designed to work with HTTP transaction data. The
103 ModSecurity Rule Language is designed to be easy to use, yet flexible:
104 common operations are simple while complex operations are possible.
105 Certified ModSecurity Rules, included with ModSecurity, contain a
106 comprehensive set of rules that implement general-purpose hardening,
107 protocol validation and detection of common web application security
108 issues. Heavily commented, these rules can be used as a learning
113 <title>Embedded-mode Deployment</title>
115 <para>ModSecurity is an embeddable web application firewall, which means
116 it can be deployed as part of your existing web server infrastructure
117 provided your web servers are Apache-based. This deployment method has
118 certain advantages:</para>
120 <orderedlist continuation="restarts" inheritnum="ignore">
122 <para>No changes to existing network. It only takes a few minutes to
123 add ModSecurity to your existing web servers. And because it was
124 designed to be completely passive by default, you are free to deploy
125 it incrementally and only use the features you need. It is equally
126 easy to remove or deactivate it if required.</para>
130 <para>No single point of failure. Unlike with network-based
131 deployments, you will not be introducing a new point of failure to
136 <para>Implicit load balancing and scaling. Because it works embedded
137 in web servers, ModSecurity will automatically take advantage of the
138 additional load balancing and scalability features. You will not
139 need to think of load balancing and scaling unless your existing
140 system needs them.</para>
144 <para>Minimal overhead. Because it works from inside the web server
145 process there is no overhead for network communication and minimal
146 overhead in parsing and data exchange.</para>
150 <para>No problem with encrypted or compressed content. Many IDS
151 systems have difficulties analysing SSL traffic. This is not a
152 problem for ModSecurity because it is positioned to work when the
153 traffic is decrypted and decompressed.</para>
159 <title>Network-based Deployment</title>
161 <para>ModSecurity works equally well when deployed as part of an
162 Apache-based reverse proxy server, and many of our customers choose to
163 do so. In this scenario, one installation of ModSecurity can protect any
164 number of web servers (even the non-Apache ones).</para>
168 <title>Portability</title>
170 <para>ModSecurity is known to work well on a wide range of operating
171 systems. Our customers are successfully running it on Linux, Windows,
172 Solaris, FreeBSD, OpenBSD, NetBSD, AIX, Mac OS X, and HP-UX.</para>
175 <section id="licensing">
176 <title>Licensing</title>
178 <para>ModSecurity is available under two licenses. Users can choose to
179 use the software under the terms of the GNU General Public License
180 version 2 (licence text is included with the distribution), as an Open
181 Source / Free Software product. A range of commercial licenses is also
182 available, together with a range of commercial support contracts. For
183 more information on commercial licensing please contact Breach
187 <para>ModSecurity, mod_security, ModSecurity Pro, and ModSecurity Core
188 Rules are trademarks or registered trademarks of Breach Security,
195 <title><trademark>ModSecurity Core Rules</trademark></title>
198 <title>Overview</title>
200 <para>ModSecurity is a web application firewall engine that provides
201 very little protection on its own. In order to become useful,
202 ModSecurity must be configured with rules. In order to enable users to
203 take full advantage of ModSecurity out of the box, Breach Security, Inc.
204 is providing a free certified rule set for ModSecurity 2.x. Unlike
205 intrusion detection and prevention systems, which rely on signatures
206 specific to known vulnerabilities, the Core Rules provide generic
207 protection from unknown vulnerabilities often found in web applications,
208 which are in most cases custom coded. The Core Rules are heavily
209 commented to allow it to be used as a step-by-step deployment guide for
210 ModSecurity. The latest Core Rules can be found at the ModSecurity
212 url="http://www.modsecurity.org/projects/rules/">http://www.modsecurity.org/projects/rules/</ulink>.</para>
216 <title>Core Rules Content</title>
218 <para>In order to provide generic web applications protection, the Core
219 Rules use the following techniques:</para>
223 <para>HTTP protection - detecting violations of the HTTP protocol
224 and a locally defined usage policy.</para>
228 <para>Common Web Attacks Protection - detecting common web
229 application security attack.</para>
233 <para>Automation detection - Detecting bots, crawlers, scanners and
234 other surface malicious activity.</para>
238 <para>Trojan Protection - Detecting access to Trojans horses.</para>
242 <para>Error Hiding - Disguising error messages sent by the
249 <section id="installation">
250 <title>Installation</title>
252 <para>ModSecurity installation requirements:</para>
254 <orderedlist continuation="restarts" inheritnum="ignore">
256 <para>ModSecurity 2.x works only with Apache 2.0.x or higher. Version
257 2.2.x is highly recommended.</para>
261 <para>Make sure you have <literal
262 moreinfo="none">mod_unique_id</literal> installed.</para>
264 <para>mod_unique_id is packaged with Apache httpd.</para>
268 <para>libapr and libapr-util</para>
271 url="http://apr.apache.org/">http://apr.apache.org/</ulink></para>
278 url="http://www.pcre.org/">http://www.pcre.org/</ulink></para>
285 url="http://xmlsoft.org/downloads.html">http://xmlsoft.org/downloads.html</ulink></para>
289 <para>liblua v5.1.x</para>
291 <para>This library is optional and only needed if you will be using
292 the new Lua engine.</para>
295 url="http://www.lua.org/download.html">http://www.lua.org/download.html</ulink></para>
297 <para>Note that ModSecurity requires the dynamic libraries. These are
298 not built by default in the source distribution, so the binary
299 distribution is recommended.</para>
303 <para>libcurl v7.15.1 or higher</para>
305 <para>If you will be using the ModSecurity Log Collector (mlogc) to
306 send audit logs to a central repository, then you will also need the
310 url="http://curl.haxx.se/libcurl/">http://curl.haxx.se/libcurl/</ulink></para>
312 <para>Many have had issues with libcurl linked with the GnuTLS
313 library for SSL/TLS support. It is recommended that the
314 openssl library be used for SSL/TLS support in libcurl.</para>
320 <para>ModSecurity installation consists of the following steps:</para>
322 <orderedlist continuation="restarts" inheritnum="ignore">
324 <para>Stop Apache httpd</para>
328 <para>Unpack the ModSecurity archive</para>
332 <para>Building differs for UNIX (or UNIX-like) operating systems and
341 <para>Run the configure script to generate a Makefile.
342 Typically no options are needed.</para>
344 <para><literal>./configure</literal></para>
346 <para>Options are available for more customization (use
347 <literal>./configure --help</literal> for a full list), but
348 typically you will only need to specify the location of the
349 <literal>apxs</literal> command installed by Apache httpd with
350 the <literal>--with-apxs</literal> option.</para>
352 <para><literal>./configure
353 --with-apxs=/path/to/httpd-2.x.y/bin/apxs</literal></para>
356 <para>There are certain configure options that are meant for
357 debugging an other development use. If enabled, these
358 options can substantially impact performance. These options
359 include all <literal>--debug-*</literal> options as well as
360 the <literal>--enable-performance-measurements</literal>
366 <para>Compile with: <literal>make</literal></para>
370 <para>Optionally test with: <literal>make
371 test</literal></para>
374 <para>This is step is still a bit experimental. If you have
375 problems, please send the full output and error from the
376 build to the support list. Most common issues are related to
377 not finding the required headers and/or libraries.</para>
382 <para>Optionally build the ModSecurity Log Collector with:
383 <literal>make mlogc</literal></para>
387 <para>Optionally install <literal>mlogc</literal>: Review the
388 <literal>INSTALL</literal> file included in the
389 apache2/mlogc-src directory in the distribution.</para>
393 <para>Install the ModSecurity module with: <literal>make
394 install</literal></para>
400 <para>Windows (MS VC++ 8)</para>
404 <para>Edit <literal>Makefile.win</literal> to configure the
405 Apache base and library paths.</para>
409 <para>Compile with: <literal>nmake -f
410 Makefile.win</literal></para>
414 <para>Install the ModSecurity module with: <literal>nmake -f
415 Makefile.win install</literal></para>
419 <para>Copy the <literal>libxml2.dll</literal> and
420 <literal>lua5.1.dll</literal> to the Apache
421 <literal>bin</literal> directory. Alternatively you can follow
422 the step below for using LoadFile to load these
431 <para>Edit the main Apache httpd config file (usually
432 <literal>httpd.conf</literal>)</para>
434 <para>On UNIX (and Windows if you did not copy the DLLs as stated
435 above) you must load libxml2 and lua5.1 before ModSecurity with
436 something like this:</para>
438 <para><programlisting>LoadFile /usr/lib/libxml2.so
439 LoadFile /usr/lib/liblua5.1.so</programlisting></para>
441 <para>Load the ModSecurity module with:<programlisting>LoadModule security2_module modules/mod_security2.so</programlisting></para>
445 <para>Configure ModSecurity</para>
449 <para>Start Apache httpd</para>
453 <para>You should now have ModSecurity 2.x up and running.</para>
458 <para>If you have compiled Apache yourself you might experience problems
459 compiling ModSecurity against PCRE. This is because Apache bundles PCRE
460 but this library is also typically provided by the operating system. I
461 would expect most (all) vendor-packaged Apache distributions to be
462 configured to use an external PCRE library (so this should not be a
465 <para>You want to avoid Apache using the bundled PCRE library and
466 ModSecurity linking against the one provided by the operating system.
467 The easiest way to do this is to compile Apache against the PCRE library
468 provided by the operating system (or you can compile it against the
469 latest PCRE version you downloaded from the main PCRE distribution
470 site). You can do this at configure time using the<literal
471 moreinfo="none"> --with-pcre</literal> switch. If you are not in a
472 position to recompile Apache, then, to compile ModSecurity successfully,
473 you'd still need to have access to the bundled PCRE headers (they are
474 available only in the Apache source code) and change the include path
475 for ModSecurity (as you did in step 7 above) to point to them (via the
476 <literal>--with-pcre</literal> ModSecurity configure option).</para>
478 <para>Do note that if your Apache is using an external PCRE library you
479 can compile ModSecurity with <literal
480 moreinfo="none">WITH_PCRE_STUDY</literal> defined,which would possibly
481 give you a slight performance edge in regular expression
484 <para>Non-gcc compilers may have problems running out-of-the-box as the
485 current build system was designed around the gcc compiler and some
486 compiler/linker flags may differ. To use a non-gcc compiler you may need
487 some manual Makefile tweaks if issues cannot be solved by exporting
488 custom CFLAGS and CPPFLAGS environment variables.</para>
490 <para>If you are upgrading from ModSecurity 1.x, please refer to the
491 migration matrix at <ulink type=""
492 url="http://www.modsecurity.org/documentation/ModSecurity-Migration-Matrix.pdf">http://www.modsecurity.org/documentation/ModSecurity-Migration-Matrix.pdf</ulink></para>
496 <section id="configuration-directives">
497 <title>Configuration Directives</title>
499 <para>The following section outlines all of the ModSecurity directives.
500 Most of the ModSecurity directives can be used inside the various Apache
501 Scope Directives such as <literal>VirtualHost</literal>,
502 <literal>Location</literal>, <literal>LocationMatch</literal>,
503 <literal>Directory</literal>, etc... There are others, however, that can
504 only be used once in the main configuration file. This information is
505 specified in the Scope sections below. The first version to use a given
506 directive is given in the Version sections below.</para>
508 <para>These rules, along with the Core rules files, should be contained is
509 files outside of the httpd.conf file and called up with Apache "Include"
510 directives. This allows for easier updating/migration of the rules. If you
511 create your own custom rules that you would like to use with the Core
512 rules, you should create a file called -
513 <filename>modsecurity_crs_15_customrules.conf</filename> and place it in
514 the same directory as the Core rules files. By using this file name, your
515 custom rules will be called up after the standard ModSecurity Core rules
516 configuration file but before the other Core rules. This allows your rules
517 to be evaluated first which can be useful if you need to implement
518 specific "allow" rules or to correct any false positives in the Core rules
519 as they are applied to your site.</para>
522 <para>It is highly encouraged that you do not edit the Core rules files
523 themselves but rather place all changes (such as
524 <literal>SecRuleRemoveByID</literal>, etc...) in your custom rules file.
525 This will allow for easier upgrading as newer Core rules are released by
526 Breach Security on the ModSecurity website.</para>
530 <title><literal>SecAction</literal></title>
532 <para><emphasis>Description:</emphasis> Unconditionally processes the
533 action list it receives as the first and only parameter. It accepts one
534 parameter, the syntax of which is identical to the third parameter
535 of<literal moreinfo="none"> SecRule</literal>.</para>
537 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecAction
538 action1,action2,action3</literal></para>
540 <para><emphasis>Example Usage:</emphasis> <literal
541 moreinfo="none">SecAction
542 nolog,phase:1,initcol:RESOURCE=%{REQUEST_FILENAME}</literal></para>
544 <para><emphasis>Processing Phase:</emphasis> Any</para>
546 <para><emphasis>Scope:</emphasis> Any</para>
548 <para><emphasis>Version:</emphasis> 2.0.0</para>
550 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
552 <para>SecAction is best used when you unconditionally execute an action.
553 This is explicit triggering whereas the normal Actions are conditional
554 based on data inspection of the request/response. This is a useful
555 directive when you want to run certain actions such as
556 <literal>initcol</literal> to initialize collections.</para>
560 <title><literal>SecArgumentSeparator</literal></title>
562 <para><emphasis>Description:</emphasis> Specifies which character to use
563 as separator for<literal moreinfo="none">
564 application/x-www-form-urlencoded</literal> content. Defaults to
565 <literal moreinfo="none">&</literal>. Applications are sometimes
566 (very rarely) written to use a semicolon (<literal
567 moreinfo="none">;</literal>).</para>
569 <para><emphasis>Syntax:</emphasis> <literal
570 moreinfo="none">SecArgumentSeparator character</literal></para>
572 <para><emphasis>Example Usage:</emphasis> <literal
573 moreinfo="none">SecArgumentSeparator ;</literal></para>
575 <para><emphasis>Processing Phase:</emphasis> Any</para>
577 <para><emphasis>Scope:</emphasis> Main</para>
579 <para><emphasis>Version:</emphasis> 2.0.0</para>
581 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
583 <para>This directive is needed if a backend web application is using a
584 non-standard argument separator. If this directive is not set properly
585 for each web application, then ModSecurity will not be able to parse the
586 arguments appropriately and the effectiveness of the rule matching will
587 be significantly decreased.</para>
591 <title><literal>SecAuditEngine</literal></title>
593 <para><emphasis>Description:</emphasis> Configures the audit logging
596 <para><emphasis>Syntax:</emphasis> <literal
597 moreinfo="none">SecAuditEngine On|Off|RelevantOnly</literal></para>
599 <para><emphasis>Example Usage:</emphasis> <literal
600 moreinfo="none">SecAuditEngine On</literal></para>
602 <para><emphasis>Processing Phase:</emphasis> N/A</para>
604 <para><emphasis>Scope:</emphasis> Any</para>
606 <para><emphasis>Version:</emphasis> 2.0.0</para>
608 <para><emphasis>Dependencies/Notes:</emphasis> Can be set/changed with
609 the "<literal>ctl</literal>" action for the current transaction.</para>
611 <para>Example: The following example shows the various audit directives
612 used together.</para>
614 <programlisting format="linespecific"><emphasis>SecAuditEngine RelevantOnly</emphasis>
615 SecAuditLog logs/audit/audit.log
616 SecAuditLogParts ABCFHZ
617 SecAuditLogType concurrent
618 SecAuditLogStorageDir logs/audit
619 <emphasis>SecAuditLogRelevantStatus ^(?:5|4\d[^4])</emphasis></programlisting>
621 <para>Possible values are:</para>
625 <para><literal moreinfo="none">On</literal> - log all transactions
630 <para><literal moreinfo="none">Off</literal> - do not log
631 transactions by default.</para>
635 <para><literal moreinfo="none">RelevantOnly</literal> - by default
636 only log transactions that have triggered a warning or an error, or
637 have a status code that is considered to be relevant (see<literal
638 moreinfo="none"> SecAuditLogRelevantStatus</literal>).</para>
644 <title><literal>SecAuditLog</literal></title>
646 <para><emphasis>Description:</emphasis> Defines the path to the main
647 audit log file.</para>
649 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecAuditLog
650 /path/to/auditlog</literal></para>
652 <para><emphasis>Example Usage:</emphasis> <literal
653 moreinfo="none">SecAuditLog
654 /usr/local/apache/logs/audit.log</literal></para>
656 <para><emphasis>Processing Phase:</emphasis> N/A</para>
658 <para><emphasis>Scope:</emphasis> Any</para>
660 <para><emphasis>Version:</emphasis> 2.0.0</para>
662 <para><emphasis>Dependencies/Notes:</emphasis> This file is open on
663 startup when the server typically still runs as<emphasis>
664 root</emphasis>. You should not allow non-root users to have write
665 privileges for this file or for the directory it is stored in..</para>
667 <para>This file will be used to store the audit log entries if serial
668 audit logging format is used. If concurrent audit logging format is used
669 this file will be used as an index, and contain a record of all audit
670 log files created. If you are planning to use Concurrent audit logging
671 and sending your audit log data off to a remote Console host or
672 commercial ModSecurity Management Appliance, then you will need to
673 configure and use the ModSecurity Log Collector (mlogc) and use the
674 following format for the audit log:</para>
676 <para><programlisting format="linespecific">SecAuditLog "|/path/to/mlogc /path/to/mlogc.conf"</programlisting></para>
680 <title><literal>SecAuditLog2</literal></title>
682 <para><emphasis>Description:</emphasis> Defines the path to the
683 secondary audit log index file when concurrent logging is enabled. See
684 <literal moreinfo="none">SecAuditLog2</literal> for more details.</para>
686 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecAuditLog2
687 /path/to/auditlog2</literal></para>
689 <para><emphasis>Example Usage:</emphasis> <literal
690 moreinfo="none">SecAuditLog2
691 /usr/local/apache/logs/audit2.log</literal></para>
693 <para><emphasis>Processing Phase:</emphasis> N/A</para>
695 <para><emphasis>Scope:</emphasis> Any</para>
697 <para><emphasis>Version:</emphasis> 2.1.2</para>
699 <para><emphasis>Dependencies/Notes:</emphasis> A main audit log must be
700 defined via <literal moreinfo="none">SecAuditLog</literal> before this
701 directive may be used. Additionally, this log is only used for
702 replicating the main audit log index file when concurrent audit logging
703 is used. It will <emphasis>not</emphasis> be used for non-concurrent
704 audit logging.</para>
708 <title><literal>SecAuditLogDirMode</literal></title>
710 <para><emphasis>Description:</emphasis> Configures the mode
711 (permissions) of any directories created for concurrent audit logs using
712 an octal mode (as used in chmod). See <literal
713 moreinfo="none">SecAuditLogFileMode</literal> for controlling the mode
714 of audit log files.</para>
716 <para><emphasis>Syntax:</emphasis> <literal
717 moreinfo="none">SecAuditLogDirMode octal_mode|"default"</literal></para>
719 <para><emphasis>Example Usage:</emphasis> <literal
720 moreinfo="none">SecAuditLogDirMode 02750</literal></para>
722 <para><emphasis>Processing Phase:</emphasis> N/A</para>
724 <para><emphasis>Scope:</emphasis> Any</para>
726 <para><emphasis>Version:</emphasis> 2.5.10</para>
728 <para><emphasis>Dependencies/Notes:</emphasis> This feature is not
729 available on operating systems not supporting octal file modes. The
730 default mode (0600) only grants read/write access to the account writing
731 the file. If access from another account is needed (using mpm-itk is a
732 good example), then this directive may be required. However, use this
733 directive with caution to avoid exposing potentially sensitive data to
734 unauthorized users. Using the value "default" will revert back to the
735 default setting.</para>
738 <para>The process umask may still limit the mode if it is being more
739 restrictive than the mode set using this directive.</para>
744 <title><literal>SecAuditLogFileMode</literal></title>
746 <para><emphasis>Description:</emphasis> Configures the mode
747 (permissions) of any files created for concurrent audit logs using an
748 octal mode (as used in chmod). See <literal
749 moreinfo="none">SecAuditLogDirMode</literal> for controlling the mode of
750 created audit log directories.</para>
752 <para><emphasis>Syntax:</emphasis> <literal
753 moreinfo="none">SecAuditLogFileMode
754 octal_mode|"default"</literal></para>
756 <para><emphasis>Example Usage:</emphasis> <literal
757 moreinfo="none">SecAuditLogFileMode 00640</literal></para>
759 <para><emphasis>Processing Phase:</emphasis> N/A</para>
761 <para><emphasis>Scope:</emphasis> Any</para>
763 <para><emphasis>Version:</emphasis> 2.5.10</para>
765 <para><emphasis>Dependencies/Notes:</emphasis> This feature is not
766 available on operating systems not supporting octal file modes. The
767 default mode (0600) only grants read/write access to the account writing
768 the file. If access from another account is needed (using mpm-itk is a
769 good example), then this directive may be required. However, use this
770 directive with caution to avoid exposing potentially sensitive data to
771 unauthorized users. Using the value "default" will revert back to the
772 default setting.</para>
775 <para>The process umask may still limit the mode if it is being more
776 restrictive than the mode set using this directive.</para>
781 <title><literal>SecAuditLogParts</literal></title>
783 <para><emphasis>Description:</emphasis> Defines which part of each
784 transaction are going to be recorded in audit log. Each part is assigned
785 a single letter. If a letter appears in the list then the equivalent
786 part of each transactions will be recorded. See below for the list of
789 <para><emphasis>Syntax:</emphasis> <literal
790 moreinfo="none">SecAuditLogParts PARTS</literal></para>
792 <para><emphasis>Example Usage:</emphasis> <literal
793 moreinfo="none">SecAuditLogParts ABCFHZ</literal></para>
795 <para><emphasis>Processing Phase:</emphasis> N/A</para>
797 <para><emphasis>Scope:</emphasis> Any</para>
799 <para><emphasis>Version:</emphasis> 2.0.0</para>
801 <para><emphasis>Dependencies/Notes:</emphasis> At this time ModSecurity
802 does not log response bodies of stock Apache responses (e.g. <literal
803 moreinfo="none">404</literal>), or the <literal
804 moreinfo="none">Server</literal> and <literal
805 moreinfo="none">Date</literal> response headers.</para>
807 <para>Default:<literal moreinfo="none"> ABCFHZ</literal>.</para>
810 <para>Please refer to the ModSecurity Data Formats document for a
811 detailed description of every available part.</para>
814 <para>Available audit log parts:</para>
818 <para><literal moreinfo="none">A</literal> - audit log header
823 <para><literal moreinfo="none">B</literal> - request headers</para>
827 <para><literal moreinfo="none">C</literal> - request body (present
828 only if the request body exists and ModSecurity is configured to
833 <para><literal moreinfo="none">D</literal> - RESERVED for
834 intermediary response headers, not implemented yet.</para>
838 <para><literal moreinfo="none">E</literal> - intermediary response
839 body (present only if ModSecurity is configured to intercept
840 response bodies, and if the audit log engine is configured to record
841 it). Intermediary response body is the same as the actual response
842 body unless ModSecurity intercepts the intermediary response body,
843 in which case the actual response body will contain the error
844 message (either the Apache default error message, or the
845 ErrorDocument page).</para>
849 <para><literal moreinfo="none">F</literal> - final response headers
850 (excluding the Date and Server headers, which are always added by
851 Apache in the late stage of content delivery).</para>
855 <para><literal moreinfo="none">G</literal> - RESERVED for the actual
856 response body, not implemented yet.</para>
860 <para><literal moreinfo="none">H</literal> - audit log
865 <para><literal moreinfo="none">I</literal> - This part is a
866 replacement for part C. It will log the same data as C in all cases
867 except when <literal moreinfo="none">multipart/form-data</literal>
868 encoding in used. In this case it will log a fake <literal
869 moreinfo="none">application/x-www-form-urlencoded</literal> body
870 that contains the information about parameters but not about the
871 files. This is handy if you don't want to have (often large) files
872 stored in your audit logs.</para>
876 <para><literal moreinfo="none">J</literal> - RESERVED. This part,
877 when implemented, will contain information about the files uploaded
878 using <literal>multipart/form-data</literal> encoding.</para>
882 <para><literal moreinfo="none">K</literal> - This part contains a
883 full list of every rule that matched (one per line) in the order
884 they were matched. The rules are fully qualified and will thus show
885 inherited actions and default operators. Supported as of
890 <para><literal moreinfo="none">Z</literal> - final boundary,
891 signifies the end of the entry (mandatory)</para>
897 <title><literal>SecAuditLogRelevantStatus</literal></title>
899 <para><emphasis>Description:</emphasis> Configures which response status
900 code is to be considered relevant for the purpose of audit
903 <para><emphasis>Syntax:</emphasis> <literal
904 moreinfo="none">SecAuditLogRelevantStatus REGEX</literal></para>
906 <para><emphasis>Example Usage:</emphasis> <literal
907 moreinfo="none">SecAuditLogRelevantStatus
908 ^(?:5|4\d[^4])</literal></para>
910 <para><emphasis>Processing Phase:</emphasis> N/A</para>
912 <para><emphasis>Scope:</emphasis> Any</para>
914 <para><emphasis>Version:</emphasis> 2.0.0</para>
916 <para><emphasis>Dependencies/Notes:</emphasis> Must have the
917 <literal>SecAuditEngine</literal> set to
918 <literal>RelevantOnly</literal>. The parameter is a regular
921 <para>The main purpose of this directive is to allow you to configure
922 audit logging for only transactions that generate the specified HTTP
923 Response Status Code. This directive is often used to the decrease the
924 total size of the audit log file. Keep in mind that if this parameter is
925 used, then successful attacks that result in a 200 OK status code will
926 not be logged.</para>
930 <title><literal>SecAuditLogStorageDir</literal></title>
932 <para><emphasis>Description:</emphasis> Configures the storage directory
933 where concurrent audit log entries are to be stored.</para>
935 <para><emphasis>Syntax:</emphasis> <literal
936 moreinfo="none">SecAuditLogStorageDir
937 /path/to/storage/dir</literal></para>
939 <para><emphasis>Example Usage:</emphasis> <literal
940 moreinfo="none">SecAuditLogStorageDir
941 /usr/local/apache/logs/audit</literal></para>
943 <para><emphasis>Processing Phase:</emphasis> N/A</para>
945 <para><emphasis>Scope:</emphasis> Any</para>
947 <para><emphasis>Version:</emphasis> 2.0.0</para>
949 <para><emphasis>Dependencies/Notes:</emphasis> SecAuditLogType must be
950 set to Concurrent. The directory must already be created before starting
951 Apache and it must be writable by the web server user as new files are
952 generated at runtime.</para>
954 <para>As with all logging mechanisms, ensure that you specify a file
955 system location that has adequate disk space and is not on the root
960 <title><literal>SecAuditLogType</literal></title>
962 <para><emphasis>Description:</emphasis> Configures the type of audit
963 logging mechanism to be used.</para>
965 <para><emphasis>Syntax:</emphasis> <literal
966 moreinfo="none">SecAuditLogType Serial|Concurrent</literal></para>
968 <para><emphasis>Example Usage:</emphasis> <literal
969 moreinfo="none">SecAuditLogType Serial</literal></para>
971 <para><emphasis>Processing Phase:</emphasis> N/A</para>
973 <para><emphasis>Scope:</emphasis> Any</para>
975 <para><emphasis>Version:</emphasis> 2.0.0</para>
977 <para><emphasis>Dependencies/Notes:</emphasis> Must specify
978 <literal>SecAuditLogStorageDir</literal> if you use concurrent
981 <para>Possible values are:</para>
983 <orderedlist continuation="restarts" inheritnum="ignore">
985 <para><literal moreinfo="none">Serial</literal> - all audit log
986 entries will be stored in the main audit logging file. This is more
987 convenient for casual use but it is slower as only one audit log
988 entry can be written to the file at any one file.</para>
992 <para><literal moreinfo="none">Concurrent</literal> - audit log
993 entries will be stored in separate files, one for each transaction.
994 Concurrent logging is the mode to use if you are going to send the
995 audit log data off to a remote ModSecurity Console host.</para>
1001 <title><literal>SecCacheTransformations</literal>
1002 (Deprecated/Experimental)</title>
1004 <para><emphasis>Description:</emphasis> Controls caching of
1005 transformations. Caching is off by default starting with 2.5.6, when it
1006 was deprecated and downgraded back to experimental.</para>
1008 <para><emphasis>Syntax:</emphasis> <literal
1009 moreinfo="none">SecCacheTransformations On|Off
1010 [options]</literal></para>
1012 <para><emphasis>Example Usage:</emphasis> <literal
1013 moreinfo="none">SecCacheTransformations On
1014 "minlen:64,maxlen:0"</literal></para>
1016 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1018 <para><emphasis>Scope:</emphasis> Any</para>
1020 <para><emphasis>Version:</emphasis> 2.5.0</para>
1022 <para><emphasis>Dependencies/Notes:</emphasis> N/A</para>
1024 <para>First parameter:</para>
1028 <para><literal moreinfo="none">On</literal> - cache transformations
1029 (per transaction, per phase) allowing identical transformations to
1030 be performed only once. (default)</para>
1034 <para><literal moreinfo="none">Off</literal> - do not cache any
1035 transformations, forcing all transformations to be performed for
1036 each rule executed.</para>
1040 <para>The following options are allowed (comma separated):</para>
1044 <para><literal moreinfo="none">incremental:on|off</literal> -
1045 enabling this option will cache every transformation instead of just
1046 the final transformation. (default: off)</para>
1050 <para><literal moreinfo="none">maxitems:N</literal> - do not allow
1051 more than N transformations to be cached. The cache will then be
1052 disabled. A zero value is interpreted as "unlimited". This option
1053 may be useful to limit caching for a form with a large number of
1054 ARGS. (default: 512)</para>
1058 <para><literal moreinfo="none">minlen:N</literal> - do not cache the
1059 transformation if the value's length is less than N bytes. (default:
1064 <para><literal moreinfo="none">maxlen:N</literal> - do not cache the
1065 transformation if the value's length is more than N bytes. A zero
1066 value is interpreted as "unlimited". (default: 1024)</para>
1072 <title><literal>SecChrootDir</literal></title>
1074 <para><emphasis>Description:</emphasis> Configures the directory path
1075 that will be used to jail the web server process.</para>
1077 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecChrootDir
1078 /path/to/chroot/dir</literal></para>
1080 <para><emphasis>Example Usage:</emphasis> <literal
1081 moreinfo="none">SecChrootDir /chroot</literal></para>
1083 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1085 <para><emphasis>Scope:</emphasis> Main</para>
1087 <para><emphasis>Version:</emphasis> 2.0.0</para>
1089 <para><emphasis>Dependencies/Notes:</emphasis> This feature is not
1090 available on Windows builds. The internal chroot functionality provided
1091 by ModSecurity works great for simple setups. One example of a simple
1092 setup is Apache serving static files only, or running scripts using
1093 modules.builds. Some problems you might encounter with more complex
1098 <para>DNS lookups do not work (this is because this feature requires
1099 a shared library that is loaded on demand, after chroot takes
1104 <para>You cannot send email from PHP because it uses sendmail and
1105 sendmail is outside the jail.</para>
1109 <para>In some cases Apache graceful (reload) no longer works.</para>
1113 <para>You should be aware that the internal chroot feature might not be
1114 100% reliable. Due to the large number of default and third-party
1115 modules available for the Apache web server, it is not possible to
1116 verify the internal chroot works reliably with all of them. A module,
1117 working from within Apache, can do things that make it easy to break out
1118 of the jail. In particular, if you are using any of the modules that
1119 fork in the module initialisation phase (e.g.
1120 <literal>mod_fastcgi</literal>, <literal>mod_fcgid</literal>,
1121 <literal>mod_cgid</literal>), you are advised to examine each Apache
1122 process and observe its current working directory, process root, and the
1123 list of open files. Consider what your options are and make your own
1128 <title><literal>SecComponentSignature</literal></title>
1130 <para><emphasis>Description</emphasis>: Appends component signature to
1131 the ModSecurity signature.</para>
1133 <para><emphasis>Syntax</emphasis>: <literal>SecComponentSignature
1134 "COMPONENT_NAME/X.Y.Z (COMMENT)"</literal></para>
1136 <para><emphasis>Example usage</emphasis>: <literal>SecComponentSignature
1137 "Core Rules/1.2.3"</literal></para>
1139 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1141 <para><emphasis>Scope</emphasis>: Main</para>
1143 <para><emphasis>Version</emphasis>: 2.5.0</para>
1145 <para><emphasis>Dependencies/Notes</emphasis>: This directive should be
1146 used to make the presence of significant ModSecurity components known.
1147 The entire signature will be recorded in transaction audit log. It
1148 should be used by ModSecurity module and rule set writers to make
1149 debugging easier.</para>
1153 <title><literal>SecContentInjection</literal></title>
1155 <para><emphasis>Description:</emphasis> Enables content injection using
1156 actions <literal>append</literal> and <literal>prepend</literal>.</para>
1158 <para><emphasis>Syntax:</emphasis> <literal>SecContentInjection
1159 (On|Off)</literal></para>
1161 <para><emphasis>Example Usage:</emphasis> <literal>SecContentInjection
1164 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1166 <para><emphasis>Scope</emphasis>: Any</para>
1168 <para><emphasis>Version</emphasis>: 2.5.0</para>
1170 <para><emphasis>Dependencies/Notes:</emphasis> N/A</para>
1174 <title><literal>SecCookieFormat</literal></title>
1176 <para><emphasis>Description:</emphasis> Selects the cookie format that
1177 will be used in the current configuration context.</para>
1179 <para><emphasis>Syntax:</emphasis> <literal
1180 moreinfo="none">SecCookieFormat 0|1</literal></para>
1182 <para><emphasis>Example Usage:</emphasis> <literal
1183 moreinfo="none">SecCookieFormat 0</literal></para>
1185 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1187 <para><emphasis>Scope:</emphasis> Any</para>
1189 <para><emphasis>Version:</emphasis> 2.0.0</para>
1191 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1193 <para>Possible values are:</para>
1197 <para><literal moreinfo="none">0</literal> - use version 0
1198 (Netscape) cookies. This is what most applications use. It is the
1199 default value.</para>
1203 <para><literal moreinfo="none">1</literal> - use version 1
1210 <title><literal>SecDataDir</literal></title>
1212 <para><emphasis>Description:</emphasis> Path where persistent data (e.g.
1213 IP address data, session data, etc) is to be stored.</para>
1215 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecDataDir
1216 /path/to/dir</literal></para>
1218 <para><emphasis>Example Usage:</emphasis> <literal
1219 moreinfo="none">SecDataDir /usr/local/apache/logs/data</literal></para>
1221 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1223 <para><emphasis>Scope:</emphasis> Main</para>
1225 <para><emphasis>Dependencies/Notes: </emphasis> This directive is needed
1226 when initcol, setsid an setuid are used. Must be writable by the web
1231 <title><literal>SecDebugLog</literal></title>
1233 <para><emphasis>Description:</emphasis> Path to the ModSecurity debug
1236 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecDebugLog
1237 /path/to/modsec-debug.log</literal></para>
1239 <para><emphasis>Example Usage:</emphasis> <literal
1240 moreinfo="none">SecDebugLog
1241 /usr/local/apache/logs/modsec-debug.log</literal></para>
1243 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1245 <para><emphasis>Scope:</emphasis> Any</para>
1247 <para><emphasis>Version:</emphasis> 2.0.0</para>
1249 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1253 <title><literal>SecDebugLogLevel</literal></title>
1255 <para><emphasis>Description:</emphasis> Configures the verboseness of
1256 the debug log data.</para>
1258 <para><emphasis>Syntax:</emphasis> <literal
1259 moreinfo="none">SecDebugLogLevel 0|1|2|3|4|5|6|7|8|9</literal></para>
1261 <para><emphasis>Example Usage:</emphasis> <literal
1262 moreinfo="none">SecDebugLogLevel 4</literal></para>
1264 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1266 <para><emphasis>Scope:</emphasis> Any</para>
1268 <para><emphasis>Version:</emphasis> 2.0.0</para>
1270 <para><emphasis>Dependencies/Notes:</emphasis> Levels <literal
1271 moreinfo="none">1 - 3</literal> are always sent to the Apache error log.
1272 Therefore you can always use level <literal moreinfo="none">0</literal>
1273 as the default logging level in production. Level <literal
1274 moreinfo="none">5</literal> is useful when debugging. It is not
1275 advisable to use higher logging levels in production as excessive
1276 logging can slow down server significantly.</para>
1278 <para>Possible values are:</para>
1282 <para><literal moreinfo="none">0</literal> - no logging.</para>
1286 <para><literal moreinfo="none">1</literal> - errors (intercepted
1287 requests) only.</para>
1291 <para><literal moreinfo="none">2</literal> - warnings.</para>
1295 <para><literal moreinfo="none">3</literal> - notices.</para>
1299 <para><literal moreinfo="none">4</literal> - details of how
1300 transactions are handled.</para>
1304 <para><literal moreinfo="none">5</literal> - as above, but including
1305 information about each piece of information handled.</para>
1309 <para><literal moreinfo="none">9</literal> - log everything,
1310 including very detailed debugging information.</para>
1316 <title><literal>SecDefaultAction</literal></title>
1318 <para><emphasis>Description:</emphasis> Defines the default action to
1319 take on a rule match.</para>
1321 <para><emphasis>Syntax:</emphasis> <literal
1322 moreinfo="none">SecDefaultAction
1323 action1,action2,action3</literal></para>
1325 <para><emphasis>Example Usage:</emphasis> <literal
1326 moreinfo="none">SecDefaultAction
1327 log,auditlog,deny,status:403,phase:2</literal></para>
1329 <para><emphasis>Processing Phase:</emphasis> Any</para>
1331 <para><emphasis>Scope:</emphasis> Any</para>
1333 <para><emphasis>Version:</emphasis> 2.0.0</para>
1335 <para><emphasis>Dependencies/Notes:</emphasis> Rules following a
1336 <literal>SecDefaultAction</literal> directive will inherit this setting
1337 unless a specific action is specified for an individual rule or until
1338 another <literal>SecDefaultAction</literal> is specified. Take special
1339 note that in the logging disruptive actions are not allowed, but this
1340 can inadvertently be inherited using a disruptive action in
1341 <literal>SecDefaultAction</literal>.</para>
1343 <para>The default value is minimal (differing from previous
1346 <programlisting format="linespecific">SecDefaultAction phase:2,log,auditlog,pass</programlisting>
1349 <para><literal>SecDefaultAction</literal> must specify a disruptive
1350 action and a processing phase and cannot contain metadata
1355 <para><literal>SecDefaultAction</literal> is <emphasis>not</emphasis>
1356 inherited across configuration contexts. (For an example of why this
1357 may be a problem for you, read the following ModSecurity Blog entry
1359 url="http://blog.modsecurity.org/2008/07/modsecurity-tri.html">http://blog.modsecurity.org/2008/07/modsecurity-tri.html</ulink>).</para>
1364 <title><literal>SecGeoLookupDb</literal></title>
1366 <para><emphasis>Description:</emphasis> Defines the path to the
1367 geographical database file.</para>
1369 <para><emphasis>Syntax:</emphasis> <literal
1370 moreinfo="none">SecGeoLookupDb /path/to/db</literal></para>
1372 <para><emphasis>Example Usage:</emphasis> <literal
1373 moreinfo="none">SecGeoLookupDb
1374 /usr/local/geo/data/GeoLiteCity.dat</literal></para>
1376 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1378 <para><emphasis>Scope:</emphasis> Any</para>
1380 <para><emphasis>Version:</emphasis> 2.5.0</para>
1382 <para><emphasis>Dependencies/Notes:</emphasis> Check out
1383 <literal>maxmind.com</literal> for free database files.</para>
1387 <title><literal>SecGuardianLog</literal></title>
1389 <para><emphasis>Description:</emphasis> Configuration directive to use
1390 the httpd-guardian script to monitor for Denial of Service (DoS)
1393 <para><emphasis>Syntax:</emphasis> <literal
1394 moreinfo="none">SecGuardianLog |/path/to/httpd-guardian</literal></para>
1396 <para><emphasis>Example Usage:</emphasis> <literal
1397 moreinfo="none">SecGuardianLog
1398 |/usr/local/apache/bin/httpd-guardian</literal></para>
1400 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1402 <para><emphasis>Scope:</emphasis> Main</para>
1404 <para><emphasis>Version:</emphasis> 2.0.0</para>
1406 <para><emphasis>Dependencies/Notes:</emphasis> By default httpd-guardian
1407 will defend against clients that send more than 120 requests in a
1408 minute, or more than 360 requests in five minutes.</para>
1410 <para>Since 1.9, ModSecurity supports a new directive, SecGuardianLog,
1411 that is designed to send all access data to another program using the
1412 piped logging feature. Since Apache is typically deployed in a
1413 multi-process fashion, making information sharing difficult, the idea is
1414 to deploy a single external process to observe all requests in a
1415 stateful manner, providing additional protection.</para>
1417 <para>Development of a state of the art external protection tool will be
1418 a focus of subsequent ModSecurity releases. However, a fully functional
1419 tool is already available as part of the <ulink type=""
1420 url="http://www.apachesecurity.net/tools/">Apache httpd tools
1421 project</ulink>. The tool is called httpd-guardian and can be used to
1422 defend against Denial of Service attacks. It uses the blacklist tool
1423 (from the same project) to interact with an iptables-based (Linux) or
1424 pf-based (*BSD) firewall, dynamically blacklisting the offending IP
1425 addresses. It can also interact with SnortSam (http://www.snortsam.net).
1426 Assuming httpd-guardian is already configured (look into the source code
1427 for the detailed instructions) you only need to add one line to your
1428 Apache configuration to deploy it:</para>
1430 <programlisting format="linespecific">SecGuardianLog |/path/to/httpd-guardian</programlisting>
1434 <title><literal>SecMarker</literal></title>
1436 <para><emphasis>Description:</emphasis> Adds a fixed rule marker in the
1437 ruleset to be used as a target in a <literal>skipAfter</literal> action.
1438 A <literal>SecMarker</literal> directive essentially creates a rule that
1439 does nothing and whose only purpose it to carry the given ID.</para>
1441 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecMarker
1444 <para><emphasis>Example Usage:</emphasis> <literal
1445 moreinfo="none">SecMarker 9999</literal></para>
1447 <para><emphasis>Processing Phase:</emphasis> Any</para>
1449 <para><emphasis>Scope:</emphasis> Any</para>
1451 <para><emphasis>Version:</emphasis> 2.5.0</para>
1453 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1455 <para><programlisting format="linespecific">SecRule REQUEST_URI "^/$" \
1456 "chain,t:none,t:urlDecode,t:lowercase,t:normalisePath,<emphasis>skipAfter:99</emphasis>"
1457 SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
1458 SecRule REQUEST_HEADERS:User-Agent \
1459 "^Apache \(internal dummy connection\)$" "t:none"
1460 SecRule &REQUEST_HEADERS:Host "@eq 0" \
1461 "deny,log,status:400,id:08,severity:4,msg:'Missing a Host Header'"
1462 SecRule &REQUEST_HEADERS:Accept "@eq 0" \
1463 "log,deny,log,status:400,id:15,msg:'Request Missing an Accept Header'"
1465 SecMarker 99</emphasis></programlisting></para>
1469 <title><literal>SecPdfProtect</literal></title>
1471 <para><emphasis>Description:</emphasis> Enables the PDF XSS protection
1472 functionality. Once enabled access to PDF files is tracked. Direct
1473 access attempts are redirected to links that contain one-time tokens.
1474 Requests with valid tokens are allowed through unmodified. Requests with
1475 invalid tokens are also allowed through but with forced download of the
1476 PDF files. This implementation uses response headers to detect PDF files
1477 and thus can be used with dynamically generated PDF files that do not
1478 have the <filename>.pdf</filename> extension in the request URI.</para>
1480 <para><emphasis>Syntax:</emphasis> <literal
1481 moreinfo="none">SecPdfProtect On|Off</literal></para>
1483 <para><emphasis>Example Usage:</emphasis> <literal
1484 moreinfo="none">SecPdfProtect On</literal></para>
1486 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1488 <para><emphasis>Scope:</emphasis> Any</para>
1490 <para><emphasis>Version:</emphasis> 2.5.0</para>
1492 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1496 <title><literal>SecPdfProtectMethod</literal></title>
1498 <para><emphasis>Description:</emphasis> Configure desired protection
1499 method to be used when requests for PDF files are detected. Possible
1500 values are <literal>TokenRedirection</literal> and
1501 <literal>ForcedDownload</literal>. The token redirection approach will
1502 attempt to redirect with tokens where possible. This allows PDF files to
1503 continue to be opened inline but only works for GET requests. Forced
1504 download always causes PDF files to be delivered as opaque binaries and
1505 attachments. The latter will always be used for non-GET requests. Forced
1506 download is considered to be more secure but may cause usability
1507 problems for users ("This PDF won't open anymore!").</para>
1509 <para><emphasis>Syntax:</emphasis> <literal
1510 moreinfo="none">SecPdfProtectMethod method</literal></para>
1512 <para><emphasis>Example Usage:</emphasis> <literal
1513 moreinfo="none">SecPdfProtectMethod TokenRedirection</literal></para>
1515 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1517 <para><emphasis>Scope:</emphasis> Any</para>
1519 <para><emphasis>Version:</emphasis> 2.5.0</para>
1521 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1523 <para><emphasis>Default:</emphasis>
1524 <literal>TokenRedirection</literal></para>
1528 <title><literal>SecPdfProtectSecret</literal></title>
1530 <para><emphasis>Description:</emphasis> Defines the secret that will be
1531 used to construct one-time tokens. You should use a reasonably long
1532 value for the secret (e.g. 16 characters is good). Once selected the
1533 secret should not be changed as it will break the tokens that were sent
1534 prior to change. But it's not a big deal even if you change it. It will
1535 just force download of PDF files with tokens that were issued in the
1536 last few seconds.</para>
1538 <para><emphasis>Syntax:</emphasis> <literal
1539 moreinfo="none">SecPdfProtectSecret secret</literal></para>
1541 <para><emphasis>Example Usage:</emphasis> <literal
1542 moreinfo="none">SecPdfProtectSecret
1543 MyRandomSecretString</literal></para>
1545 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1547 <para><emphasis>Scope:</emphasis> Any</para>
1549 <para><emphasis>Version:</emphasis> 2.5.0</para>
1551 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1555 <title><literal>SecPdfProtectTimeout</literal></title>
1557 <para><emphasis>Description:</emphasis> Defines the token timeout. After
1558 token expires it can no longer be used to allow access to PDF file.
1559 Request will be allowed through but the PDF will be delivered as
1562 <para><emphasis>Syntax:</emphasis> <literal
1563 moreinfo="none">SecPdfProtectTimeout timeout</literal></para>
1565 <para><emphasis>Example Usage:</emphasis> <literal
1566 moreinfo="none">SecPdfProtectTimeout 10</literal></para>
1568 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1570 <para><emphasis>Scope:</emphasis> Any</para>
1572 <para><emphasis>Version:</emphasis> 2.5.0</para>
1574 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1576 <para><emphasis>Default:</emphasis> <literal>10</literal></para>
1580 <title><literal>SecPdfProtectTokenName</literal></title>
1582 <para><emphasis>Description:</emphasis> Defines the name of the token.
1583 The only reason you would want to change the name of the token is if you
1584 wanted to hide the fact you are running ModSecurity. It's a good reason
1585 but it won't really help as the adversary can look into the algorithm
1586 used for PDF protection and figure it out anyway. It does raise the bar
1587 slightly so go ahead if you want to.</para>
1589 <para><emphasis>Syntax:</emphasis> <literal
1590 moreinfo="none">SecPdfProtectTokenName name</literal></para>
1592 <para><emphasis>Example Usage:</emphasis> <literal
1593 moreinfo="none">SecPdfProtectTokenName PDFTOKEN</literal></para>
1595 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1597 <para><emphasis>Scope:</emphasis> Any</para>
1599 <para><emphasis>Version:</emphasis> 2.5.0</para>
1601 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1603 <para><emphasis>Default:</emphasis> <literal>PDFTOKEN</literal></para>
1607 <title><literal>SecRequestBodyAccess</literal></title>
1609 <para><emphasis>Description:</emphasis> Configures whether request
1610 bodies will be buffered and processed by ModSecurity by default.</para>
1612 <para><emphasis>Syntax:</emphasis> <literal
1613 moreinfo="none">SecRequestBodyAccess On|Off</literal></para>
1615 <para><emphasis>Example Usage:</emphasis> <literal
1616 moreinfo="none">SecRequestBodyAccess On</literal></para>
1618 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1620 <para><emphasis>Scope:</emphasis> Any</para>
1622 <para><emphasis>Version:</emphasis> 2.0.0</para>
1624 <para><emphasis>Dependencies/Notes:</emphasis> This directive is
1625 required if you plan to inspect <literal>POST_PAYLOAD</literal>. This
1626 directive must be used along with the "phase:2" processing phase action
1627 and <literal>REQUEST_BODY</literal> variable/location. If any of these 3
1628 parts are not configured, you will not be able to inspect the request
1631 <para>Possible values are:</para>
1635 <para><literal moreinfo="none">On</literal> - access request
1640 <para><literal moreinfo="none">Off</literal> - do not attempt to
1641 access request bodies.</para>
1647 <title><literal>SecRequestBodyLimit</literal></title>
1649 <para><emphasis>Description:</emphasis> Configures the maximum request
1650 body size ModSecurity will accept for buffering.</para>
1652 <para><emphasis>Syntax:</emphasis> <literal
1653 moreinfo="none">SecRequestBodyLimit NUMBER_IN_BYTES</literal></para>
1655 <para><emphasis>Example Usage:</emphasis> <literal
1656 moreinfo="none">SecRequestBodyLimit 134217728</literal></para>
1658 <para><emphasis>Scope:</emphasis> Any</para>
1660 <para><emphasis>Version:</emphasis> 2.0.0</para>
1662 <para><emphasis>Dependencies/Notes:</emphasis> 131072 KB (134217728
1663 bytes) is the default setting. Anything over this limit will be rejected
1664 with status code 413 Request Entity Too Large. There is a hard limit of
1669 <title><literal>SecRequestBodyNoFilesLimit</literal></title>
1671 <para><emphasis>Description:</emphasis> Configures the maximum request
1672 body size ModSecurity will accept for buffering, excluding the size of
1673 files being transported in the request. This directive comes handy to
1674 further reduce susceptibility to DoS attacks when someone is sending
1675 request bodies of very large sizes. Web applications that require file
1676 uploads must configure <literal>SecRequestBodyLimit</literal> to a high
1677 value. Since large files are streamed to disk file uploads will not
1678 increase memory consumption. However, it's still possible for someone to
1679 take advantage of a large request body limit and send non-upload
1680 requests with large body sizes. This directive eliminates that
1683 <para><emphasis>Syntax:</emphasis> <literal
1684 moreinfo="none">SecRequestBodyNoFilesLimit
1685 NUMBER_IN_BYTES</literal></para>
1687 <para><emphasis>Example Usage:</emphasis> <literal
1688 moreinfo="none">SecRequestBodyLimit 131072</literal></para>
1690 <para><emphasis>Scope:</emphasis> Any</para>
1692 <para><emphasis>Version:</emphasis> 2.5.0</para>
1694 <para><emphasis>Dependencies/Notes:</emphasis> 1 MB (1048576 bytes) is
1695 the default setting. This value is very conservative. For most
1696 applications you should be able to reduce it down to 128 KB or lower.
1697 Anything over the limit will be rejected with status code <literal>413
1698 Request Entity Too Large</literal>. There is a hard limit of 1
1703 <title><literal>SecRequestBodyInMemoryLimit</literal></title>
1705 <para><emphasis>Description:</emphasis> Configures the maximum request
1706 body size ModSecurity will store in memory.</para>
1708 <para><emphasis>Syntax:</emphasis> <literal
1709 moreinfo="none">SecRequestBodyInMemoryLimit
1710 NUMBER_IN_BYTES</literal></para>
1712 <para><emphasis>Example Usage:</emphasis> <literal
1713 moreinfo="none">SecRequestBodyInMemoryLimit 131072</literal></para>
1715 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1717 <para><emphasis>Scope:</emphasis> Any</para>
1719 <para><emphasis>Version:</emphasis> 2.0.0</para>
1721 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1723 <para>By default the limit is 128 KB:</para>
1725 <programlisting format="linespecific"># Store up to 128 KB in memory
1726 SecRequestBodyInMemoryLimit 131072</programlisting>
1730 <title><literal>SecResponseBodyLimit</literal></title>
1732 <para><emphasis>Description:</emphasis> Configures the maximum response
1733 body size that will be accepted for buffering.</para>
1735 <para><emphasis>Syntax:</emphasis> <literal
1736 moreinfo="none">SecResponseBodyLimit NUMBER_IN_BYTES</literal></para>
1738 <para><emphasis>Example Usage:</emphasis> <literal
1739 moreinfo="none">SecResponseBodyLimit 524228</literal></para>
1741 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1743 <para><emphasis>Scope:</emphasis> Any</para>
1745 <para><emphasis>Version:</emphasis> 2.0.0</para>
1747 <para><emphasis>Dependencies/Notes:</emphasis> Anything over this limit
1748 will be rejected with status code 500 Internal Server Error. This
1749 setting will not affect the responses with MIME types that are not
1750 marked for buffering. There is a hard limit of 1 GB.</para>
1752 <para>By default this limit is configured to 512 KB:</para>
1754 <programlisting format="linespecific"># Buffer response bodies of up to 512 KB in length
1755 SecResponseBodyLimit 524288</programlisting>
1759 <title><literal>SecResponseBodyLimitAction</literal></title>
1761 <para><emphasis>Description</emphasis>: Controls what happens once a
1762 response body limit, configured with
1763 <literal>SecResponseBodyLimit</literal>, is encountered. By default
1764 ModSecurity will reject a response body that is longer than specified.
1765 Some web sites, however, will produce very long responses making it
1766 difficult to come up with a reasonable limit. Such sites would have to
1767 raise the limit significantly to function properly defying the purpose
1768 of having the limit in the first place (to control memory consumption).
1769 With the ability to choose what happens once a limit is reached site
1770 administrators can choose to inspect only the first part of the
1771 response, the part that can fit into the desired limit, and let the rest
1772 through. Some could argue that allowing parts of responses to go
1773 uninspected is a weakness. This is true in theory but only applies to
1774 cases where the attacker controls the output (e.g. can make it arbitrary
1775 long). In such cases, however, it is not possible to prevent leakage
1776 anyway. The attacker could compress, obfuscate, or even encrypt data
1777 before it is sent back, and therefore bypass any monitoring
1780 <para><emphasis>Syntax</emphasis>: <literal>SecResponseBodyLimitAction
1781 Reject|ProcessPartial</literal></para>
1783 <para><emphasis>Example Usage</emphasis>:
1784 <literal>SecResponseBodyLimitAction ProcessPartial</literal></para>
1786 <para><emphasis>Processing Phase</emphasis>: N/A</para>
1788 <para><emphasis>Scope</emphasis>: Any</para>
1790 <para><emphasis>Version:</emphasis> 2.5.0</para>
1792 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1796 <title><literal>SecResponseBodyMimeType</literal></title>
1798 <para><emphasis>Description:</emphasis> Configures which<literal
1799 moreinfo="none"> MIME</literal> types are to be considered for response
1800 body buffering.</para>
1802 <para><emphasis>Syntax:</emphasis> <literal
1803 moreinfo="none">SecResponseBodyMimeType mime/type</literal></para>
1805 <para><emphasis>Example Usage:</emphasis> <literal
1806 moreinfo="none">SecResponseBodyMimeType text/plain
1807 text/html</literal></para>
1809 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1811 <para><emphasis>Scope:</emphasis> Any</para>
1813 <para><emphasis>Version:</emphasis> 2.0.0</para>
1815 <para><emphasis>Dependencies/Notes:</emphasis> Multiple<literal
1816 moreinfo="none"> SecResponseBodyMimeType</literal> directives can be
1817 used to add<literal moreinfo="none"> MIME</literal> types.</para>
1819 <para>The default value is <literal
1820 moreinfo="none">text/plaintext/html</literal>:</para>
1822 <programlisting format="linespecific">SecResponseBodyMimeType text/plain text/html</programlisting>
1826 <title><literal>SecResponseBodyMimeTypesClear</literal></title>
1828 <para><emphasis>Description:</emphasis> Clears the list of <literal
1829 moreinfo="none">MIME</literal> types considered for response body
1830 buffering, allowing you to start populating the list from
1833 <para><emphasis>Syntax:</emphasis> <literal
1834 moreinfo="none">SecResponseBodyMimeTypesClear</literal></para>
1836 <para><emphasis>Example Usage:</emphasis> <literal
1837 moreinfo="none">SecResponseBodyMimeTypesClear</literal></para>
1839 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1841 <para><emphasis>Scope:</emphasis> Any</para>
1843 <para><emphasis>Version:</emphasis> 2.0.0</para>
1845 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1849 <title><literal>SecResponseBodyAccess</literal></title>
1851 <para><emphasis>Description:</emphasis> Configures whether response
1852 bodies are to be buffer and analysed or not.</para>
1854 <para><emphasis>Syntax:</emphasis> <literal
1855 moreinfo="none">SecResponseBodyAccess On|Off</literal></para>
1857 <para><emphasis>Example Usage:</emphasis> <literal
1858 moreinfo="none">SecResponseBodyAccess On</literal></para>
1860 <para><emphasis>Processing Phase:</emphasis> N/A</para>
1862 <para><emphasis>Scope:</emphasis> Any</para>
1864 <para><emphasis>Version:</emphasis> 2.0.0</para>
1866 <para><emphasis>Dependencies/Notes:</emphasis> This directive is
1867 required if you plan to inspect HTML responses. This directive must be
1868 used along with the "phase:4" processing phase action and RESPONSE_BODY
1869 variable/location. If any of these 3 parts are not configured, you will
1870 not be able to inspect the response bodies.</para>
1872 <para>Possible values are:</para>
1876 <para><literal moreinfo="none">On</literal> - access response bodies
1877 (but only if the MIME type matches, see above).</para>
1881 <para><literal moreinfo="none">Off</literal> - do not attempt to
1882 access response bodies.</para>
1888 <title><literal>SecRule</literal></title>
1890 <para><emphasis>Description:</emphasis> <literal
1891 moreinfo="none">SecRule</literal> is the main ModSecurity directive. It
1892 is used to analyse data and perform actions based on the results.</para>
1894 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecRule
1895 VARIABLES OPERATOR [ACTIONS]</literal></para>
1897 <para><emphasis>Example Usage:</emphasis> <literal
1898 moreinfo="none">SecRule REQUEST_URI "attack" \</literal></para>
1901 "phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath"</literal></para>
1903 <para><emphasis>Processing Phase:</emphasis> Any</para>
1905 <para><emphasis>Scope:</emphasis> Any</para>
1907 <para><emphasis>Version:</emphasis> 2.0.0</para>
1909 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
1911 <para>In general, the format of this rule is as follows:</para>
1913 <programlisting format="linespecific">SecRule VARIABLES OPERATOR [ACTIONS]</programlisting>
1915 <para>The second part, <literal moreinfo="none">OPERATOR</literal>,
1916 specifies how they are going to be checked. The third (optional) part,
1917 <literal moreinfo="none">ACTIONS</literal>, specifies what to do
1918 whenever the operator used performs a successful match against a
1922 <title>Variables in rules</title>
1924 <para>The first part,<literal moreinfo="none"> VARIABLES</literal>,
1925 specifies which variables are to be checked. For example, the
1926 following rule will reject a transaction that has the word<emphasis>
1927 dirty</emphasis> in the URI:</para>
1929 <programlisting format="linespecific">SecRule ARGS dirty</programlisting>
1931 <para>Each rule can specify one or more variables:</para>
1933 <programlisting format="linespecific">SecRule ARGS|REQUEST_HEADERS:User-Agent dirty</programlisting>
1935 <para>There is a third format supported by the selection operator -
1936 XPath expression. XPath expressions can only used against the special
1937 variable XML, which is available only of the request body was
1938 processed as XML.</para>
1940 <programlisting format="linespecific">SecRule XML:/xPath/Expression dirty</programlisting>
1943 <para>Not all collections support all selection operator format
1944 types. You should refer to the documentation of each collection to
1945 determine what is and isn't supported.</para>
1950 <title>Collections</title>
1952 <para>A variable can contain one or many pieces of data, depending on
1953 the nature of the variable and the way it is used. We've seen examples
1954 of both approaches in the previous section. When a variable can
1955 contain more than one value we refer to it as a
1956 <emphasis>collection</emphasis>.</para>
1958 <para>Collections are always expanded before a rule is run. For
1959 example, the following rule:</para>
1961 <programlisting>SecRule ARGS dirty</programlisting>
1963 <para>will be expanded to:</para>
1965 <programlisting>SecRule ARGS:p dirty
1966 SecRule ARGS:q dirty</programlisting>
1968 <para>in a requests that has only two parameters, named
1969 <literal>p</literal> and <literal>q</literal>.</para>
1971 <para>Collections come in several flavours:</para>
1975 <term>Read-only</term>
1978 <para>Created at runtime using transaction data. For example:
1979 <literal>ARGS</literal> (contains a list of all request
1980 parameter values) and <literal>REQUEST_HEADERS</literal>
1981 (contains a list of all request header values).</para>
1986 <term>Transient Read/Write</term>
1989 <para>The <literal>TX</literal> collection is created (empty)
1990 for every transaction. Rules can read from it and write to it
1991 (using the <literal>setvar</literal> action, for example), but
1992 the information stored in this collection will not survive the
1993 end of transaction.</para>
1998 <term>Persistent Read/Write</term>
2001 <para>There are several collections that can be written to, but
2002 which are persisted to the storage backend. These collections
2003 are used to track clients across transactions. Examples of
2004 collections that fall into this type are <literal>IP</literal>,
2005 <literal>SESSION</literal> and <literal>USER</literal>.</para>
2012 <title>Operators in rules</title>
2014 <para>In the simplest possible case you will use a regular expression
2015 pattern as the second rule parameter. This is what we've done in the
2016 examples above. If you do this ModSecurity assumes you want to use the
2017 <literal moreinfo="none">rx</literal> (regular expression) operator.
2018 You can also explicitly specify the operator you want to use by using
2019 <literal moreinfo="none">@</literal>, followed by the name of an
2020 operator, at the beginning of the second <literal>SecRule</literal>
2023 <programlisting format="linespecific">SecRule ARGS "@rx dirty"</programlisting>
2025 <para>Note how we had to use double quotes to delimit the second rule
2026 parameter. This is because the second parameter now has whitespace in
2027 it. Any number of whitespace characters can follow the name of the
2028 operator. If there are any non-whitespace characters there, they will
2029 all be treated as a special parameter to the operator. In the case of
2030 the regular expression operator the special parameter is the pattern
2031 that will be used for comparison.</para>
2033 <para>The @ can be the second character if you are using negation to
2034 negate the result returned by the operator:</para>
2036 <programlisting format="linespecific">SecRule &ARGS "!@rx ^0$"</programlisting>
2040 <title>Operator negation</title>
2042 <para>Operator results can be negated by using an exclamation mark at
2043 the beginning of the second parameter. The following rule matches if
2044 the word <literal>dirty</literal> does <emphasis>not</emphasis> appear
2045 in the <literal>User-Agent</literal> request header:</para>
2047 <programlisting>SecRule REQUEST_HEADERS:User-Agent !dirty</programlisting>
2049 <para>You can use the exclamation mark in combination with any
2050 parameter. If you do, the exclamation mark needs to go first, followed
2051 by the explicit operator reference. The following rule has the same
2052 effect as the previous example:</para>
2054 <programlisting>SecRule REQUEST_HEADERS:User-Agent "!@rx dirty"</programlisting>
2056 <para>If you need to use negation in a rule that is going to be
2057 applied to several variables then it may not be immediately clear what
2058 will happen. Consider the following example:</para>
2060 <programlisting>SecRule ARGS:p|ARGS:q !dirty</programlisting>
2062 <para>The above rule is identical to:</para>
2064 <programlisting>SecRule ARGS:p !dirty
2065 SecRule ARGS:q !dirty</programlisting>
2068 <para>Negation is applied to operations against individual
2069 operations, not agains the entire variable list.</para>
2074 <title>Actions in rules</title>
2076 <para>The third parameter, <literal moreinfo="none">ACTIONS</literal>,
2077 can be omitted only because there is a helper feature that specifies
2078 the default action list. If the parameter isn't omitted the actions
2079 specified in the parameter will be merged with the default action list
2080 to create the actual list of actions that will be processed on a rule
2086 <title><literal>SecRuleInheritance</literal></title>
2088 <para><emphasis>Description:</emphasis> Configures whether the current
2089 context will inherit rules from the parent context (configuration
2090 options are inherited in most cases - you should look up the
2091 documentation for every directive to determine if it is inherited or
2094 <para><emphasis>Syntax:</emphasis> <literal
2095 moreinfo="none">SecRuleInheritance On|Off</literal></para>
2097 <para><emphasis>Example Usage:</emphasis> <literal
2098 moreinfo="none">SecRuleInheritance Off</literal></para>
2100 <para><emphasis>Processing Phase:</emphasis> Any</para>
2102 <para><emphasis>Scope:</emphasis> Any</para>
2104 <para><emphasis>Version:</emphasis> 2.0.0</para>
2106 <para><emphasis>Dependencies/Notes:</emphasis> Resource-specific
2107 contexts (e.g.<literal moreinfo="none"> Location</literal>, <literal
2108 moreinfo="none">Directory</literal>, etc) cannot override
2109 <emphasis>phase1</emphasis> rules configured in the main server or in
2110 the virtual server. This is because phase 1 is run early in the request
2111 processing process, before Apache maps request to resource. Virtual host
2112 context can override phase 1 rules configured in the main server.</para>
2114 <para>Example: The following example shows where ModSecurity may be
2115 enabled in the main Apache configuration scope, however you might want
2116 to configure your VirtualHosts differently. In the first example, the
2117 first VirtualHost is not inheriting the ModSecurity main config
2118 directives and in the second one it is.</para>
2120 <programlisting format="linespecific">SecRuleEngine On
2121 SecDefaultAction log,pass,phase:2
2124 <VirtualHost *:80>
2126 ServerAlias www.app1.com<emphasis>
2127 SecRuleInheritance Off</emphasis>
2128 SecDefaultAction log,deny,phase:1,redirect:http://www.site2.com
2130 </VirtualHost>
2132 <VirtualHost *:80>
2134 ServerAlias www.app2.com
2135 <emphasis>SecRuleInheritance On</emphasis> SecRule ARGS "attack"
2137 </VirtualHost></programlisting>
2139 <para>Possible values are:</para>
2143 <para><literal moreinfo="none">On</literal> - inherit rules from the
2144 parent context.</para>
2148 <para><literal moreinfo="none">Off</literal> - do not inherit rules
2149 from the parent context.</para>
2152 <para>Configuration contexts are an Apache concept. Directives
2153 <literal><Directory></literal>,
2154 <literal><Files></literal>,
2155 <literal><Location></literal> and
2156 <literal><VirtualHost></literal> are all used to create
2157 configuration contexts. For more information please go to the
2158 Apache documentation section <ulink
2159 url="http://httpd.apache.org/docs/2.0/sections.html">Configuration
2160 Sections</ulink>.</para>
2167 <title><literal>SecRuleEngine</literal></title>
2169 <para><emphasis>Description:</emphasis> Configures the rules
2172 <para><emphasis>Syntax:</emphasis> <literal
2173 moreinfo="none">SecRuleEngine On|Off|DetectionOnly</literal></para>
2175 <para><emphasis>Example Usage:</emphasis> <literal
2176 moreinfo="none">SecRuleEngine On</literal></para>
2178 <para><emphasis>Processing Phase:</emphasis> Any</para>
2180 <para><emphasis>Scope:</emphasis> Any</para>
2182 <para><emphasis>Version:</emphasis> 2.0.0</para>
2184 <para><emphasis>Dependencies/Notes:</emphasis> This directive can also
2185 be controlled by the ctl action (ctl:ruleEngine=off) for per rule
2188 <para>Possible values are:</para>
2192 <para><literal moreinfo="none">On</literal> - process rules.</para>
2196 <para><literal moreinfo="none">Off</literal> - do not process
2201 <para><literal moreinfo="none">DetectionOnly</literal> - process
2202 rules but never intercept transactions, even when rules are
2203 configured to do so.</para>
2209 <title><literal>SecRuleRemoveById</literal></title>
2211 <para><emphasis>Description:</emphasis> Removes matching rules from the
2212 parent contexts.</para>
2214 <para><emphasis>Syntax:</emphasis> <literal
2215 moreinfo="none">SecRuleUpdateActionById RULEID
2216 ACTIONLIST</literal></para>
2218 <para><emphasis>Example Usage:</emphasis> <literal
2219 moreinfo="none">SecRuleRemoveByID 1 2 "9000-9010"</literal></para>
2221 <para><emphasis>Processing Phase:</emphasis> Any</para>
2223 <para><emphasis>Scope:</emphasis> Any</para>
2225 <para><emphasis>Version:</emphasis> 2.0.0</para>
2227 <para><emphasis>Dependencies/Notes:</emphasis> This directive supports
2228 multiple parameters, where each parameter can either be a rule ID, or a
2229 range. Parameters that contain spaces must be delimited using double
2232 <programlisting format="linespecific">SecRuleRemoveById 1 2 5 10-20 "400-556" 673</programlisting>
2236 <title><literal>SecRuleRemoveByMsg</literal></title>
2238 <para><emphasis>Description:</emphasis> Removes matching rules from the
2239 parent contexts.</para>
2241 <para><emphasis>Syntax:</emphasis> <literal
2242 moreinfo="none">SecRuleRemoveByMsg REGEX</literal></para>
2244 <para><emphasis>Example Usage:</emphasis> <literal
2245 moreinfo="none">SecRuleRemoveByMsg "FAIL"</literal></para>
2247 <para><emphasis>Processing Phase:</emphasis> Any</para>
2249 <para><emphasis>Scope:</emphasis> Any</para>
2251 <para><emphasis>Version:</emphasis> 2.0.0</para>
2253 <para><emphasis>Dependencies/Notes:</emphasis> This directive supports
2254 multiple parameters. Each parameter is a regular expression that will be
2255 applied to the message (specified using the <literal
2256 moreinfo="none">msg</literal> action).</para>
2260 <title><literal>SecRuleScript</literal> (Experimental)</title>
2262 <para><emphasis>Description:</emphasis> This directive creates a special
2263 rule that executes a Lua script to decide whether to match or not. The
2264 main difference from <literal>SecRule</literal> is that there are no
2265 targets nor operators. The script can fetch any variable from the
2266 ModSecurity context and use any (Lua) operator to test them. The second
2267 optional parameter is the list of actions whose meaning is identical to
2268 that of <literal>SecRule</literal>.</para>
2270 <para><emphasis>Syntax:</emphasis> <literal>SecRuleScript
2271 /path/to/script.lua [ACTIONS]</literal></para>
2273 <para><emphasis>Example Usage:</emphasis> <literal
2274 moreinfo="none">SecRuleScript "/path/to/file.lua"
2275 "block"</literal></para>
2277 <para><emphasis>Processing Phase:</emphasis> Any</para>
2279 <para><emphasis>Scope:</emphasis> Any</para>
2281 <para><emphasis>Version:</emphasis> 2.5.0</para>
2283 <para><emphasis>Dependencies/Notes:</emphasis> None</para>
2286 <para>All Lua scripts are compiled at configuration time and cached in
2287 memory. To reload scripts you must reload the entire ModSecurity
2288 configuration by restarting Apache.</para>
2291 <para>Example script:</para>
2293 <programlisting>-- Your script must define the <emphasis>main</emphasis> entry
2296 -- Log something at level 1. Normally you shouldn't be
2297 -- logging anything, especially not at level 1, but this is
2298 -- just to show you can. Useful for debugging.
2299 m.log(1, "Hello world!");
2301 -- Retrieve one variable.
2302 local var1 = m.getvar("REMOTE_ADDR");
2304 -- Retrieve one variable, applying one transformation function.
2305 -- The second parameter is a string.
2306 local var2 = m.getvar("ARGS", "lowercase");
2308 -- Retrieve one variable, applying several transformation functions.
2309 -- The second parameter is now a list. You should note that m.getvar()
2310 -- requires the use of comma to separate collection names from
2311 -- variable names. This is because only one variable is returned.
2312 local var3 = m.getvar("ARGS.p", { "lowercase", "compressWhitespace" } );
2314 -- If you want this rule to match return a string
2315 -- containing the error message. The message <emphasis>must</emphasis> contain the name
2316 -- of the variable where the problem is located.
2317 -- return "Variable ARGS:p looks suspicious!"
2319 -- Otherwise, simply return nil.
2321 end</programlisting>
2323 <para>In this first example we were only retrieving one variable at the
2324 time. In this case the name of the variable is known to you. In many
2325 cases, however, you will want to examine variables whose names you won't
2326 know in advance, for example script parameters.</para>
2328 <para>Example showing use of <literal>m.getvars()</literal> to retrieve
2329 many variables at once:</para>
2331 <programlisting>function main()
2332 -- Retrieve script parameters.
2333 local d = m.getvars("ARGS", { "lowercase", "htmlEntityDecode" } );
2335 -- Loop through the paramters.
2337 -- Examine parameter value.
2338 if (string.find(d[i].value, "<script")) then
2339 -- Always specify the name of the variable where the
2340 -- problem is located in the error message.
2341 return ("Suspected XSS in variable " .. d[i].name .. ".");
2345 -- Nothing wrong found.
2347 end</programlisting>
2351 url="http://www.lua.org/">http://www.lua.org/</ulink> to find more
2352 about the Lua programming language. The reference manual too is
2353 available online, at <ulink
2354 url="http://www.lua.org/manual/5.1/">http://www.lua.org/manual/5.1/</ulink>.</para>
2358 <para>Lua support is marked as <emphasis>experimental</emphasis> as
2359 the way the progamming interface may continue to evolve while we are
2360 working for the best implementation style. Any user input into the
2361 programming interface is appreciated.</para>
2366 <title><literal>SecRuleUpdateActionById</literal></title>
2368 <para><emphasis>Description:</emphasis> Updates the action list of the
2369 specified rule.</para>
2371 <para><emphasis>Syntax:</emphasis> <literal
2372 moreinfo="none">SecRuleRemoveById RULEID ACTIONLIST</literal></para>
2374 <para><emphasis>Example Usage:</emphasis> <literal
2375 moreinfo="none">SecRuleUpdateActionById 12345
2376 deny,status:403</literal></para>
2378 <para><emphasis>Processing Phase:</emphasis> Any</para>
2380 <para><emphasis>Scope:</emphasis> Any</para>
2382 <para><emphasis>Version:</emphasis> 2.5.0</para>
2384 <para><emphasis>Dependencies/Notes:</emphasis> This directive merges the
2385 specified action list with the rule's action list. There are two
2386 limitations. The rule ID cannot be changed, nor can the phase. Further
2387 note that actions that may be specified multiple times are appended to
2388 the original.</para>
2390 <programlisting format="linespecific">SecAction \
2391 "t:lowercase,phase:2,id:12345,pass,msg:'The Message',log,auditlog"
2392 SecRuleUpdateActionById 12345 "t:compressWhitespace,deny,status:403,msg:'A new message'</programlisting>
2394 <para>The example above will cause the rule to be executed as if it was
2395 specified as follows:</para>
2397 <programlisting format="linespecific">SecAction \
2398 "t:lowercase,phase:2,id:12345,log,auditlog,t:compressWhitespace,deny,status:403,msg:'A new message'"</programlisting>
2402 <title><literal>SecServerSignature</literal></title>
2404 <para><emphasis>Description:</emphasis> Instructs ModSecurity to change
2405 the data presented in the "Server:" response header token.</para>
2407 <para><emphasis>Syntax:</emphasis> <literal
2408 moreinfo="none">SecServerSignature "WEB SERVER
2409 SOFTWARE"</literal></para>
2411 <para><emphasis>Example Usage:</emphasis> <literal
2412 moreinfo="none">SecServerSignature
2413 "Netscape-Enterprise/6.0"</literal></para>
2415 <para><emphasis>Processing Phase:</emphasis> N/A</para>
2417 <para><emphasis>Scope:</emphasis> Main</para>
2419 <para><emphasis>Version:</emphasis> 2.0.0</para>
2421 <para><emphasis>Dependencies/Notes:</emphasis> In order for this
2422 directive to work, you must set the Apache ServerTokens directive to
2423 Full. ModSecurity will overwrite the server signature data held in this
2424 memory space with the data set in this directive. If ServerTokens is not
2425 set to Full, then the memory space is most likely not large enough to
2426 hold the new data we are looking to insert.</para>
2430 <title><literal>SecTmpDir</literal></title>
2432 <para><emphasis>Description:</emphasis> Configures the directory where
2433 temporary files will be created.</para>
2435 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecTmpDir
2436 /path/to/dir</literal></para>
2438 <para><emphasis>Example Usage:</emphasis> <literal
2439 moreinfo="none">SecTmpDir /tmp</literal></para>
2441 <para><emphasis>Processing Phase:</emphasis> N/A</para>
2443 <para><emphasis>Scope:</emphasis> Any</para>
2445 <para><emphasis>Version:</emphasis> 2.0.0</para>
2447 <para><emphasis>Dependencies/Notes:</emphasis> Needs to be writable by
2448 the Apache user process. This is the directory location where Apache
2449 will swap data to disk if it runs out of memory (more data than what was
2450 specified in the SecRequestBodyInMemoryLimit directive) during
2455 <title><literal>SecUploadDir</literal></title>
2457 <para><emphasis>Description:</emphasis> Configures the directory where
2458 intercepted files will be stored.</para>
2460 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecUploadDir
2461 /path/to/dir</literal></para>
2463 <para><emphasis>Example Usage:</emphasis> <literal
2464 moreinfo="none">SecUploadDir /tmp</literal></para>
2466 <para><emphasis>Processing Phase:</emphasis> N/A</para>
2468 <para><emphasis>Scope:</emphasis> Any</para>
2470 <para><emphasis>Version:</emphasis> 2.0.0</para>
2472 <para><emphasis>Dependencies/Notes:</emphasis> This directory must be on
2473 the same filesystem as the temporary directory defined with <literal
2474 moreinfo="none">SecTmpDir</literal>. This directive is used with
2475 <literal>SecUploadKeepFiles</literal>.</para>
2479 <title><literal>SecUploadFileMode</literal></title>
2481 <para><emphasis>Description:</emphasis> Configures the mode
2482 (permissions) of any uploaded files using an octal mode (as used in
2485 <para><emphasis>Syntax:</emphasis> <literal
2486 moreinfo="none">SecUploadFileMode octal_mode|"default"</literal></para>
2488 <para><emphasis>Example Usage:</emphasis> <literal
2489 moreinfo="none">SecUploadFileMode 0640</literal></para>
2491 <para><emphasis>Processing Phase:</emphasis> N/A</para>
2493 <para><emphasis>Scope:</emphasis> Any</para>
2495 <para><emphasis>Version:</emphasis> 2.1.6</para>
2497 <para><emphasis>Dependencies/Notes:</emphasis> This feature is not
2498 available on operating systems not supporting octal file modes. The
2499 default mode (0600) only grants read/write access to the account writing
2500 the file. If access from another account is needed (using clamd is a
2501 good example), then this directive may be required. However, use this
2502 directive with caution to avoid exposing potentially sensitive data to
2503 unauthorized users. Using the value "default" will revert back to the
2504 default setting.</para>
2507 <para>The process umask may still limit the mode if it is being more
2508 restrictive than the mode set using this directive.</para>
2513 <title><literal>SecUploadKeepFiles</literal></title>
2515 <para><emphasis>Description:</emphasis> Configures whether or not the
2516 intercepted files will be kept after transaction is processed.</para>
2518 <para><emphasis>Syntax:</emphasis> <literal
2519 moreinfo="none">SecUploadKeepFiles On|Off|RelevantOnly</literal></para>
2521 <para><emphasis>Example Usage:</emphasis> <literal
2522 moreinfo="none">SecUploadKeepFiles On</literal></para>
2524 <para><emphasis>Processing Phase:</emphasis> N/A</para>
2526 <para><emphasis>Scope:</emphasis> Any</para>
2528 <para><emphasis>Version:</emphasis> 2.0.0</para>
2530 <para><emphasis>Dependencies/Notes:</emphasis> This directive requires
2531 the storage directory to be defined (using <literal
2532 moreinfo="none">SecUploadDir</literal>).</para>
2534 <para>Possible values are:</para>
2538 <para><literal moreinfo="none">On</literal> - Keep uploaded
2543 <para><literal moreinfo="none">Off</literal> - Do not keep uploaded
2548 <para><literal moreinfo="none">RelevantOnly</literal> - This will
2549 keep only those files that belong to requests that are deemed
2556 <title><literal>SecWebAppId</literal></title>
2558 <para><emphasis>Description:</emphasis> Creates a partition on the
2559 server that belongs to one web application.</para>
2561 <para><emphasis>Syntax:</emphasis> <literal moreinfo="none">SecWebAppId
2562 "NAME"</literal></para>
2564 <para><emphasis>Example Usage:</emphasis> <literal
2565 moreinfo="none">SecWebAppId "WebApp1"</literal></para>
2567 <para><emphasis>Processing Phase:</emphasis> N/A</para>
2569 <para><emphasis>Scope:</emphasis> Any</para>
2571 <para><emphasis>Version:</emphasis> 2.0.0</para>
2573 <para><emphasis>Dependencies/Notes:</emphasis> Partitions are used to
2574 avoid collisions between session IDs and user IDs. This directive must
2575 be used if there are multiple applications deployed on the same server.
2576 If it isn't used, a collision between session IDs might occur. The
2577 default value is<literal moreinfo="none"> default</literal>.
2580 <programlisting format="linespecific"><VirtualHost *:80>
2582 ServerAlias www.app1.com
2583 <emphasis>SecWebAppId "App1"</emphasis>
2584 SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
2585 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
2587 </VirtualHost>
2589 <VirtualHost *:80>
2591 ServerAlias www.app2.com<emphasis>
2592 SecWebAppId "App2"</emphasis>
2593 SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
2594 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
2596 </VirtualHost></programlisting>
2598 <para>In the two examples configurations shown, SecWebAppId is being
2599 used in conjunction with the Apache VirtualHost directives. What this
2600 achieves is to create more unique collection names when being hosted on
2601 one server. Normally, when setsid is used, ModSecurity will create a
2602 collection with the name "SESSION" and it will hold the value specified.
2603 With using SecWebAppId as shown in the examples, however, the name of
2604 the collection would become "App1_SESSION" and "App2_SESSION".</para>
2606 <para>SecWebAppId is relevant in two cases:</para>
2608 <orderedlist continuation="restarts" inheritnum="ignore">
2610 <para>You are logging transactions/alerts to the ModSecurity Console
2611 and you want to use the web application ID to search only the
2612 transactions belonging to that application.</para>
2616 <para>You are using the data persistence facility (collections
2617 SESSION and USER) and you need to avoid collisions between sessions
2618 and users belonging to different applications.</para>
2624 <section id="processing-phases">
2625 <title>Processing Phases</title>
2627 <para>ModSecurity 2.x allows rules to be placed in one of the following
2630 <orderedlist continuation="restarts" inheritnum="ignore">
2632 <para>Request headers (<literal>REQUEST_HEADERS</literal>)</para>
2636 <para>Request body (<literal>REQUEST_BODY</literal>)</para>
2640 <para>Response headers (<literal>RESPONSE_HEADERS</literal>)</para>
2644 <para>Response body (<literal>RESPONSE_BODY</literal>)</para>
2648 <para>Logging (<literal>LOGGING</literal>)</para>
2652 <para>Below is a diagram of the standard Apache Request Cycle. In the
2653 diagram, the 5 ModSecurity processing phases are shown.</para>
2655 <para><graphic contentwidth="5.5in"
2656 fileref="apache_request_cycle-modsecurity.jpg" role="" scale=""
2657 scalefit="" /></para>
2659 <para>In order to select the phase a rule executes during, use the phase
2660 action either directly in the rule or in using the
2661 <literal>SecDefaultAction</literal> directive:</para>
2663 <programlisting format="linespecific">SecDefaultAction "log,pass,<emphasis>phase:2</emphasis>"
2664 SecRule REQUEST_HEADERS:Host "!^$" "deny,<emphasis>phase:1</emphasis>"</programlisting>
2667 <para>Keep in mind that rules are executed according to phases, so even
2668 if two rules are adjacent in a configuration file, but are set to
2669 execute in different phases, they would not happen one after the other.
2670 The order of rules in the configuration file is important only within
2671 the rules of each phase. This is especially important when using the
2672 <literal>skip</literal> and <literal>skipAfter</literal> actions.</para>
2676 <para>The <literal>LOGGING</literal> phase is special. It is executed at
2677 the end of each transaction no matter what happened in the previous
2678 phases. This means it will be processed even if the request was
2679 intercepted or the <literal>allow</literal> action was used to pass the
2680 transaction through.</para>
2684 <title>Phase Request Headers</title>
2686 <para>Rules in this phase are processed immediately after Apache
2687 completes reading the request headers (post-read-request phase). At this
2688 point the request body has not been read yet, meaning not all request
2689 arguments are available. Rules should be placed in this phase if you
2690 need to have them run early (before Apache does something with the
2691 request), to do something before the request body has been read,
2692 determine whether or not the request body should be buffered, or decide
2693 how you want the request body to be processed (e.g. whether to parse it
2694 as XML or not).</para>
2696 <para><emphasis>Note</emphasis></para>
2698 <para>Rules in this phase can not leverage Apache scope directives
2699 (Directory, Location, LocationMatch, etc...) as the post-read-request
2700 hook does not have this information yet. The exception here is the
2701 VirtualHost directive. If you want to use ModSecurity rules inside
2702 Apache locations, then they should run in Phase 2. Refer to the Apache
2703 Request Cycle/ModSecurity Processing Phases diagram.</para>
2707 <title>Phase Request Body</title>
2709 <para>This is the general-purpose input analysis phase. Most of the
2710 application-oriented rules should go here. In this phase you are
2711 guaranteed to have received the request arguments (provided the request
2712 body has been read). ModSecurity supports three encoding types for the
2713 request body phase:</para>
2717 <para><literal>application/x-www-form-urlencoded</literal> - used to
2718 transfer form data</para>
2722 <para><literal>multipart/form-data</literal> - used for file
2727 <para><literal>text/xml</literal> - used for passing XML data</para>
2731 <para>Other encodings are not used by most web applications.</para>
2735 <title>Phase Response Headers</title>
2737 <para>This phase takes place just before response headers are sent back
2738 to the client. Run here if you want to observe the response before that
2739 happens, and if you want to use the response headers to determine if you
2740 want to buffer the response body. Note that some response status codes
2741 (such as 404) are handled earlier in the request cycle by Apache and my
2742 not be able to be triggered as expected. Additionally, there are some
2743 response headers that are added by Apache at a later hook (such as Date,
2744 Server and Connection) that we would not be able to trigger on or
2745 sanitize. This should work appropriately in a proxy setup or within
2746 phase:5 (logging).</para>
2750 <title>Phase Response Body</title>
2752 <para>This is the general-purpose output analysis phase. At this point
2753 you can run rules against the response body (provided it was buffered,
2754 of course). This is the phase where you would want to inspect the
2755 outbound HTML for information disclosure, error messages or failed
2756 authentication text.</para>
2760 <title>Phase Logging</title>
2762 <para>This phase is run just before logging takes place. The rules
2763 placed into this phase can only affect how the logging is performed.
2764 This phase can be used to inspect the error messages logged by Apache.
2765 You cannot deny/block connections in this phase as it is too late. This
2766 phase also allows for inspection of other response headers that weren't
2767 available during phase:3 or phase:4. Note that you must be careful not
2768 to inherit a disruptive action into a rule in this phase as this is a
2769 configuration error in ModSecurity 2.5.0 and later versions.</para>
2773 <section id="variables">
2774 <title>Variables</title>
2776 <para>The following variables are supported in ModSecurity 2.x:</para>
2779 <title><literal moreinfo="none">ARGS</literal></title>
2781 <para><literal>ARGS</literal> is a collection and can be used on its own
2782 (means all arguments including the POST Payload), with a static
2783 parameter (matches arguments with that name), or with a regular
2784 expression (matches all arguments with name that matches the regular
2785 expression). To look at only the query string or body arguments, see the
2786 <literal>ARGS_GET</literal> and <literal>ARGS_POST</literal>
2789 <para>Some variables are actually collections, which are expanded into
2790 more variables at runtime. The following example will examine all
2791 request arguments:<programlisting format="linespecific">SecRule ARGS dirty</programlisting>
2792 Sometimes, however, you will want to look only at parts of a collection.
2793 This can be achieved with the help of the <emphasis>selection
2794 operator</emphasis>(colon). The following example will only look at the
2795 arguments named<literal moreinfo="none"> p</literal> (do note that, in
2796 general, requests can contain multiple arguments with the same name):
2797 <programlisting format="linespecific">SecRule ARGS:p dirty</programlisting>
2798 It is also possible to specify exclusions. The following will examine
2799 all request arguments for the word<emphasis> dirty</emphasis>, except
2800 the ones named <literal moreinfo="none">z</literal> (again, there can be
2801 zero or more arguments named<literal moreinfo="none"> z</literal>):
2802 <programlisting format="linespecific">SecRule ARGS|!ARGS:z dirty</programlisting>
2803 There is a special operator that allows you to count how many variables
2804 there are in a collection. The following rule will trigger if there is
2805 more than zero arguments in the request (ignore the second parameter for
2806 the time being): <programlisting format="linespecific">SecRule &ARGS !^0$</programlisting>
2807 And sometimes you need to look at an array of parameters, each with a
2808 slightly different name. In this case you can specify a regular
2809 expression in the selection operator itself. The following rule will
2810 look into all arguments whose names begin with <literal
2811 moreinfo="none">id_</literal>: <programlisting format="linespecific">SecRule ARGS:/^id_/ dirty</programlisting></para>
2814 <para>Using <literal>ARGS:p</literal> will not result in any
2815 invocations against the operator if argument p does not exist.</para>
2817 <para>In ModSecurity 1.X, the <literal>ARGS</literal> variable stood
2818 for <literal>QUERY_STRING</literal> + <literal>POST_PAYLOAD</literal>,
2819 whereas now it expands to individual variables.</para>
2824 <title><literal moreinfo="none">ARGS_COMBINED_SIZE</literal></title>
2826 <para>This variable allows you to set more targeted evaluations on the
2827 total size of the Arguments as compared with normal Apache LimitRequest
2828 directives. For example, you could create a rule to ensure that the
2829 total size of the argument data is below a certain threshold (to help
2830 prevent buffer overflow issues). Example: Block request if the size of
2831 the arguments is above 25 characters.</para>
2833 <programlisting format="linespecific">SecRule REQUEST_FILENAME "^/cgi-bin/login\.php" \
2834 "chain,log,deny,phase:2,t:none,t:lowercase,t:normalisePath"
2835 SecRule <emphasis>ARGS_COMBINED_SIZE</emphasis> "@gt 25"</programlisting>
2839 <title><literal moreinfo="none">ARGS_NAMES</literal></title>
2841 <para>Is a collection of the argument names. You can search for specific
2842 argument names that you want to block. In a positive policy scenario,
2843 you can also whitelist (using an inverted rule with the ! character)
2844 only authorized argument names. Example: This example rule will only
2845 allow 2 argument names - p and a. If any other argument names are
2846 injected, it will be blocked.</para>
2848 <programlisting format="linespecific">SecRule REQUEST_FILENAME "/index.php" \
2849 "chain,log,deny,status:403,phase:2,t:none,t:lowercase,t:normalisePath"
2850 SecRule<emphasis> ARGS_NAMES</emphasis> "!^(p|a)$" "t:none,t:lowercase"</programlisting>
2854 <title><literal moreinfo="none">ARGS_GET</literal></title>
2856 <para><literal>ARGS_GET</literal> is similar to <literal>ARGS</literal>,
2857 but only contains arguments from the query string.</para>
2861 <title><literal moreinfo="none">ARGS_GET_NAMES</literal></title>
2863 <para><literal>ARGS_GET_NAMES</literal> is similar to
2864 <literal>ARGS_NAMES</literal>, but only contains argument names from the
2865 query string.</para>
2869 <title><literal moreinfo="none">ARGS_POST</literal></title>
2871 <para><literal>ARGS_POST</literal> is similar to
2872 <literal>ARGS</literal>, but only contains arguments from the POST
2877 <title><literal moreinfo="none">ARGS_POST_NAMES</literal></title>
2879 <para><literal>ARGS_POST_NAMES</literal> is similar to
2880 <literal>ARGS_NAMES</literal>, but only contains argument names from the
2885 <title><literal moreinfo="none">AUTH_TYPE</literal></title>
2887 <para>This variable holds the authentication method used to validate a
2888 user. Example:</para>
2890 <programlisting format="linespecific">SecRule <emphasis>AUTH_TYPE</emphasis> "basic" log,deny,status:403,phase:1,t:lowercase</programlisting>
2892 <para><emphasis>Note</emphasis></para>
2894 <para>This data will not be available in a proxy-mode deployment as the
2895 authentication is not local. In a proxy-mode deployment, you would need
2896 to inspect the <literal>REQUEST_HEADERS:Authorization</literal>
2901 <title><literal moreinfo="none">ENV</literal></title>
2903 <para>Collection, requires a single parameter (after colon). The
2904 <literal>ENV</literal> variable is set with setenv and does not give
2905 access to the CGI environment variables. Example:</para>
2907 <programlisting format="linespecific">SecRule REQUEST_FILENAME "printenv" pass,<emphasis>setenv:tag=suspicious</emphasis>
2908 SecRule <emphasis>ENV:tag</emphasis> "suspicious"</programlisting>
2912 <title><literal moreinfo="none">FILES</literal></title>
2914 <para>Collection. Contains a collection of original file names (as they
2915 were called on the remote user's file system). Note: only available if
2916 files were extracted from the request body. Example:</para>
2918 <programlisting format="linespecific">SecRule<emphasis> FILES</emphasis> "\.conf$" log,deny,status:403,phase:2</programlisting>
2922 <title><literal moreinfo="none">FILES_COMBINED_SIZE</literal></title>
2924 <para>Single value. Total size of the uploaded files. Note: only
2925 available if files were extracted from the request body. Example:</para>
2927 <programlisting format="linespecific">SecRule <emphasis>FILES_COMBINED_SIZE</emphasis> "@gt 1000" log,deny,status:403,phase:2</programlisting>
2931 <title><literal moreinfo="none">FILES_NAMES</literal></title>
2933 <para>Collection w/o parameter. Contains a list of form fields that were
2934 used for file upload. Note: only available if files were extracted from
2935 the request body. Example:</para>
2937 <programlisting format="linespecific">SecRule<emphasis> FILES_NAMES</emphasis> "^upfile$" log,deny,status:403,phase:2</programlisting>
2941 <title><literal moreinfo="none">FILES_SIZES</literal></title>
2943 <para>Collection. Contains a list of file sizes. Useful for implementing
2944 a size limitation on individual uploaded files. Note: only available if
2945 files were extracted from the request body. Example:</para>
2947 <programlisting format="linespecific">SecRule <emphasis>FILES_SIZES</emphasis> "@gt 100" log,deny,status:403,phase:2</programlisting>
2951 <title><literal moreinfo="none">FILES_TMPNAMES</literal></title>
2953 <para>Collection. Contains a collection of temporary files' names on the
2954 disk. Useful when used together with <literal
2955 moreinfo="none">@inspectFile.</literal> Note: only available if files
2956 were extracted from the request body. Example:</para>
2958 <programlisting format="linespecific">SecRule <emphasis>FILES_TMPNAMES</emphasis> "@inspectFile /path/to/inspect_script.pl"</programlisting>
2962 <title><literal moreinfo="none">GEO</literal></title>
2964 <para><literal>GEO</literal> is a collection populated by the results of
2965 the last <literal moreinfo="none">@geoLookup</literal> operator. The
2966 collection can be used to match geographical fields looked from an IP
2967 address or hostname.</para>
2969 <para>Available since ModSecurity 2.5.0.</para>
2971 <para>Fields:</para>
2975 <para><emphasis>COUNTRY_CODE:</emphasis> Two character country code.
2976 EX: US, GB, etc.</para>
2980 <para><emphasis>COUNTRY_CODE3:</emphasis> Up to three character
2981 country code.</para>
2985 <para><emphasis>COUNTRY_NAME:</emphasis> The full country
2990 <para><emphasis>COUNTRY_CONTINENT:</emphasis> The two character
2991 continent that the country is located. EX: EU</para>
2995 <para><emphasis>REGION:</emphasis> The two character region. For US,
2996 this is state. For Canada, providence, etc.</para>
3000 <para><emphasis>CITY:</emphasis> The city name if supported by the
3005 <para><emphasis>POSTAL_CODE:</emphasis> The postal code if supported
3006 by the database.</para>
3010 <para><emphasis>LATITUDE:</emphasis> The latitude if supported by
3011 the database.</para>
3015 <para><emphasis>LONGITUDE:</emphasis> The longitude if supported by
3016 the database.</para>
3020 <para><emphasis>DMA_CODE:</emphasis> The metropolitan area code if
3021 supported by the database. (US only)</para>
3025 <para><emphasis>AREA_CODE:</emphasis> The phone system area code.
3030 <para>Example:</para>
3032 <programlisting format="linespecific">SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat
3034 SecRule REMOTE_ADDR "<emphasis>@geoLookup</emphasis>" "chain,drop,msg:'Non-GB IP address'"
3035 SecRule GEO:COUNTRY_CODE "!@streq GB"</programlisting>
3039 <title><literal moreinfo="none">HIGHEST_SEVERITY</literal></title>
3041 <para>This variable holds the highest severity of any rules that have
3042 matched so far. Severities are numeric values and thus can be used with
3043 comparison operators such as <literal moreinfo="none">@lt</literal>,
3047 <para>Higher severities have a lower numeric value.</para>
3049 <para>A value of 255 indicates no severity has been set.</para>
3052 <programlisting format="linespecific">SecRule HIGHEST_SEVERITY "@le 2" "phase:2,deny,status:500,msg:'severity %{HIGHEST_SEVERITY}'"</programlisting>
3056 <title><literal moreinfo="none">MATCHED_VAR</literal></title>
3058 <para>This variable holds the value of the variable that was matched
3059 against. It is similar to the TX:0, except it can be used for all
3060 operators and does not require that the <literal
3061 moreinfo="none">capture</literal> action be specified.</para>
3063 <programlisting format="linespecific">SecRule ARGS pattern chain,deny
3065 SecRule <emphasis>MATCHED_VAR</emphasis> "further scrutiny"</programlisting>
3069 <title><literal moreinfo="none">MATCHED_VAR_NAME</literal></title>
3071 <para>This variable holds the full name of the variable that was matched
3074 <programlisting format="linespecific">SecRule ARGS pattern setvar:tx.mymatch=%{MATCHED_VAR_NAME}
3076 SecRule <emphasis>TX:MYMATCH</emphasis> "@eq ARGS:param" deny</programlisting>
3080 <title><literal moreinfo="none">MODSEC_BUILD</literal></title>
3082 <para>This variable holds the ModSecurity build number. This variable is
3083 intended to be used to check the build number prior to using a feature
3084 that is available only in a certain build. Example:</para>
3086 <programlisting format="linespecific">SecRule <emphasis>MODSEC_BUILD</emphasis> "!@ge 02050102" skipAfter:12345
3087 SecRule ARGS "@pm some key words" id:12345,deny,status:500</programlisting>
3091 <title><literal>MULTIPART_CRLF_LF_LINES</literal></title>
3093 <para>This flag variable will be set to <literal>1</literal> whenever a
3094 multi-part request uses mixed line terminators. The
3095 <literal>multipart/form-data</literal> RFC requires
3096 <literal>CRLF</literal> sequence to be used to terminate lines. Since
3097 some client implementations use only <literal>LF</literal> to terminate
3098 lines you might want to allow them to proceed under certain
3099 circumstances (if you want to do this you will need to stop using
3100 <literal>MULTIPART_STRICT_ERROR</literal> and check each multi-part flag
3101 variable individually, avoiding <literal>MULTIPART_LF_LINE</literal>).
3102 However, mixing <literal>CRLF</literal> and <literal>LF</literal> line
3103 terminators is dangerous as it can allow for evasion. Therefore, in such
3104 cases, you will have to add a check for
3105 <literal>MULTIPART_CRLF_LF_LINES</literal>.</para>
3109 <title><literal>MULTIPART_STRICT_ERROR</literal></title>
3111 <para><literal>MULTIPART_STRICT_ERROR</literal> will be set to
3112 <literal>1</literal> when any of the following variables is also set to
3113 <literal>1</literal>: <literal>REQBODY_PROCESSOR_ERROR</literal>,
3114 <literal>MULTIPART_BOUNDARY_QUOTED</literal>,
3115 <literal>MULTIPART_BOUNDARY_WHITESPACE</literal>,
3116 <literal>MULTIPART_DATA_BEFORE</literal>,
3117 <literal>MULTIPART_DATA_AFTER</literal>,
3118 <literal>MULTIPART_HEADER_FOLDING</literal>,
3119 <literal>MULTIPART_LF_LINE</literal>,
3120 <literal>MULTIPART_SEMICOLON_MISSING</literal>
3121 <literal>MULTIPART_INVALID_QUOTING</literal>. Each of these variables
3122 covers one unusual (although sometimes legal) aspect of the request body
3123 in <literal>multipart/form-data format</literal>. Your policies should
3124 <emphasis>always</emphasis> contain a rule to check either this variable
3125 (easier) or one or more individual variables (if you know exactly what
3126 you want to accomplish). Depending on the rate of false positives and
3127 your default policy you should decide whether to block or just warn when
3128 the rule is triggered.</para>
3130 <para>The best way to use this variable is as in the example
3133 <programlisting>SecRule MULTIPART_STRICT_ERROR "!@eq 0" \
3134 "phase:2,t:none,log,deny,msg:'Multipart request body \
3135 failed strict validation: \
3136 PE %{REQBODY_PROCESSOR_ERROR}, \
3137 BQ %{MULTIPART_BOUNDARY_QUOTED}, \
3138 BW %{MULTIPART_BOUNDARY_WHITESPACE}, \
3139 DB %{MULTIPART_DATA_BEFORE}, \
3140 DA %{MULTIPART_DATA_AFTER}, \
3141 HF %{MULTIPART_HEADER_FOLDING}, \
3142 LF %{MULTIPART_LF_LINE}, \
3143 SM %{MULTIPART_SEMICOLON_MISSING}, \
3144 IQ %{MULTIPART_INVALID_QUOTING}'"</programlisting>
3146 <para>The <literal>multipart/form-data</literal> parser was upgraded in
3147 ModSecurity v2.1.3 to actively look for signs of evasion. Many variables
3148 (as listed above) were added to expose various facts discovered during
3149 the parsing process. The <literal>MULTIPART_STRICT_ERROR</literal>
3150 variable is handy to check on all abnormalities at once. The individual
3151 variables allow detection to be fine-tuned according to your
3152 circumstances in order to reduce the number of false positives. Detailed
3153 analysis of various evasion techniques covered will be released as a
3154 separated document at a later date.</para>
3158 <title><literal>MULTIPART_UNMATCHED_BOUNDARY</literal></title>
3160 <para>Set to <literal>1</literal> when, during the parsing phase of a
3161 <literal>multipart/request-body</literal>, ModSecurity encounters what
3162 feels like a boundary but it is not. Such an event may occur when
3163 evasion of ModSecurity is attempted.</para>
3165 <para>The best way to use this variable is as in the example
3168 <programlisting>SecRule MULTIPART_UNMATCHED_BOUNDARY "!@eq 0" \
3169 "phase:2,t:none,log,deny,msg:'Multipart parser detected a possible unmatched boundary.'"</programlisting>
3171 <para>Change the rule from blocking to logging-only if many false
3172 positives are encountered.</para>
3176 <title><literal moreinfo="none">PATH_INFO</literal></title>
3178 <para>Besides passing query information to a script/handler, you can
3179 also pass additional data, known as extra path information, as part of
3180 the URL. Example:</para>
3182 <programlisting format="linespecific">SecRule<emphasis> PATH_INFO</emphasis> "^/(bin|etc|sbin|opt|usr)"</programlisting>
3186 <title><literal moreinfo="none">QUERY_STRING</literal></title>
3188 <para>This variable holds form data passed to the script/handler by
3189 appending data after a question mark. Warning: Not URL-decoded.
3192 <programlisting format="linespecific">SecRule <emphasis>QUERY_STRING</emphasis> "attack"</programlisting>
3196 <title><literal moreinfo="none">REMOTE_ADDR</literal></title>
3198 <para>This variable holds the IP address of the remote client.
3201 <programlisting format="linespecific">SecRule <emphasis>REMOTE_ADDR</emphasis> "^192\.168\.1\.101$"</programlisting>
3205 <title><literal moreinfo="none">REMOTE_HOST</literal></title>
3207 <para>If HostnameLookUps are set to On, then this variable will hold the
3208 DNS resolved remote host name. If it is set to Off, then it will hold
3209 the remote IP address. Possible uses for this variable would be to deny
3210 known bad client hosts or network blocks, or conversely, to allow in
3211 authorized hosts. Example:</para>
3213 <programlisting format="linespecific">SecRule <emphasis>REMOTE_HOST</emphasis> "\.evil\.network\org$"</programlisting>
3217 <title><literal moreinfo="none">REMOTE_PORT</literal></title>
3219 <para>This variable holds information on the source port that the client
3220 used when initiating the connection to our web server. Example: in this
3221 example, we are evaluating to see if the <literal>REMOTE_PORT</literal>
3222 is less than 1024, which would indicate that the user is a privileged
3225 <programlisting format="linespecific">SecRule <emphasis>REMOTE_PORT</emphasis> "@lt 1024" phase:1,log,pass,setenv:remote_port=privileged</programlisting>
3229 <title><literal moreinfo="none">REMOTE_USER</literal></title>
3231 <para>This variable holds the username of the authenticated user. If
3232 there are no password (basic|digest) access controls in place, then this
3233 variable will be empty. Example:</para>
3235 <programlisting format="linespecific">SecRule <emphasis>REMOTE_USER</emphasis> "admin"</programlisting>
3237 <para><emphasis>Note</emphasis></para>
3239 <para>This data will not be available in a proxy-mode deployment as the
3240 authentication is not local.</para>
3244 <title><literal moreinfo="none">REQBODY_PROCESSOR</literal></title>
3246 <para>Built-in processors are <literal
3247 moreinfo="none">URLENCODED</literal>,<literal moreinfo="none">
3248 MULTIPART</literal>, and <literal moreinfo="none">XML</literal>.
3251 <programlisting format="linespecific">SecRule<emphasis> REQBODY_PROCESSOR</emphasis> "^XML$ chain
3252 SecRule XML "@validateDTD /opt/apache-frontend/conf/xml.dtd"</programlisting>
3257 moreinfo="none">REQBODY_PROCESSOR_ERROR</literal></title>
3259 <para>Possible values are 0 (no error) or 1 (error). This variable will
3260 be set by request body processors (typically the
3261 <classname>multipart/request-data</classname> parser or the XML parser)
3262 when they fail to properly parse a request payload.</para>
3264 <para>Example:</para>
3266 <programlisting format="linespecific">SecRule<emphasis> REQBODY_PROCESSOR_ERROR</emphasis> "@eq 1" deny,phase:2</programlisting>
3269 <para>Your policies <emphasis>must</emphasis> have a rule to check
3270 REQBODY_PROCESSOR_ERROR at the beginning of phase 2. Failure to do so
3271 will leave the door open for impedance mismatch attacks. It is
3272 possible, for example, that a payload that cannot be parsed by
3273 ModSecurity can be successfully parsed by more tolerant parser
3274 operating in the application. If your policy dictates blocking then
3275 you should reject the request if error is detected. When operating in
3276 detection-only mode your rule should alert with high severity when
3277 request body processing fails.</para>
3283 moreinfo="none">REQBODY_PROCESSOR_ERROR_MSG</literal></title>
3285 <para>Empty, or contains the error message from the processor.
3288 <programlisting format="linespecific">SecRule<emphasis> REQBODY_PROCESSOR_ERROR_MSG</emphasis> "failed to parse" t:lowercase</programlisting>
3292 <title><literal moreinfo="none">REQUEST_BASENAME</literal></title>
3294 <para>This variable holds just the filename part of
3295 <literal>REQUEST_FILENAME</literal> (e.g. index.php).</para>
3297 <para>Example:</para>
3299 <programlisting format="linespecific">SecRule <emphasis>REQUEST_BASENAME</emphasis> "^login\.php$" phase:2,t:none,t:lowercase</programlisting>
3302 <para>Please note that anti-evasion transformations are not applied to
3303 this variable by default. <literal>REQUEST_BASENAME</literal> will
3304 recognise both <literal>/</literal> and <literal>\</literal> as path
3310 <title><literal moreinfo="none">REQUEST_BODY</literal></title>
3312 <para>This variable holds the data in the request body (including
3313 <literal>POST_PAYLOAD</literal> data). <literal>REQUEST_BODY</literal>
3314 should be used if the original order of the arguments is important
3315 (<literal>ARGS</literal> should be used in all other cases).
3318 <programlisting format="linespecific">SecRule <emphasis>REQUEST_BODY</emphasis> "^username=\w{25,}\&password=\w{25,}\&Submit\=login$"</programlisting>
3321 <para>This variable is only available if the
3322 <literal>URLENCODED</literal> request body processor parsed a request
3323 body. This will occur by default when an
3324 <literal>application/x-www-form-urlencoded</literal> is detected, or
3325 the <literal>URLENCODED</literal> request body parser is forced. As of
3326 2.5.7 it is possible to force the presence of the
3327 <literal>REQUEST_BODY</literal> variable, but only when there is no
3328 request body processor defined, using the
3329 <literal>ctl:forceRequestBodyVariable</literal> option in the
3330 <literal>REQUEST_HEADERS</literal> phase.</para>
3335 <title><literal moreinfo="none">REQUEST_COOKIES</literal></title>
3337 <para>This variable is a collection of all of the cookie data. Example:
3338 the following example is using the Ampersand special operator to count
3339 how many variables are in the collection. In this rule, it would trigger
3340 if the request does not include any Cookie headers.</para>
3342 <programlisting format="linespecific">SecRule<emphasis> &REQUEST_COOKIES</emphasis> "@eq 0"</programlisting>
3346 <title><literal moreinfo="none">REQUEST_COOKIES_NAMES</literal></title>
3348 <para>This variable is a collection of the cookie names in the request
3349 headers. Example: the following rule will trigger if the JSESSIONID
3350 cookie is not present.</para>
3352 <programlisting format="linespecific">SecRule<emphasis> &REQUEST_COOKIES_NAMES:JSESSIONID</emphasis> "@eq 0"</programlisting>
3356 <title><literal moreinfo="none">REQUEST_FILENAME</literal></title>
3358 <para>This variable holds the relative <literal>REQUEST_URI</literal>
3359 minus the <literal>QUERY_STRING</literal> part (e.g. /index.php).
3362 <programlisting format="linespecific">SecRule <emphasis>REQUEST_FILENAME</emphasis> "^/cgi-bin/login\.php$" phase:2,t:none,t:normalisePath</programlisting>
3365 <para>Please note that anti-evasion transformations are not used on
3366 <literal>REQUEST_FILENAME</literal> by default.</para>
3371 <title><literal moreinfo="none">REQUEST_HEADERS</literal></title>
3373 <para>This variable can be used as either a collection of all of the
3374 request headers or can be used to specify individual headers (by using
3375 REQUEST_HEADERS<emphasis>:Header-Name</emphasis>). Example: the first
3376 example uses <literal>REQUEST_HEADERS</literal> as a collection and is
3377 applying the <literal>validateUrlEncoding</literal> operator against all
3380 <programlisting format="linespecific">SecRule <emphasis>REQUEST_HEADERS</emphasis> "@validateUrlEncoding"</programlisting>
3382 <para>Example: the second example is targeting only the
3383 <literal>Host</literal> header.</para>
3385 <programlisting format="linespecific">SecRule <emphasis>REQUEST_HEADERS:Host</emphasis> "^[\d\.]+$" \
3386 "deny,log,status:400,msg:'Host header is a numeric IP address'"</programlisting>
3390 <title><literal moreinfo="none">REQUEST_HEADERS_NAMES</literal></title>
3392 <para>This variable is a collection of the names of all of the request
3393 headers. Example:</para>
3395 <programlisting format="linespecific">SecRule <emphasis>REQUEST_HEADERS_NAMES</emphasis> "^x-forwarded-for" \
3396 "log,deny,status:403,t:lowercase,msg:'Proxy Server Used'"</programlisting>
3400 <title><literal moreinfo="none">REQUEST_LINE</literal></title>
3402 <para>This variable holds the complete request line sent to the server
3403 (including the REQUEST_METHOD and HTTP version data). Example: this
3404 example rule will trigger if the request method is something other than
3405 GET, HEAD, POST or if the HTTP is something other than HTTP/0.9, 1.0 or
3408 <programlisting format="linespecific">SecRule <emphasis>REQUEST_LINE</emphasis> "!(^((?:(?:pos|ge)t|head))|http/(0\.9|1\.0|1\.1)$)" t:none,t:lowercase</programlisting>
3412 <title><literal moreinfo="none">REQUEST_METHOD</literal></title>
3414 <para>This variable holds the request method used by the client.</para>
3416 <para>The following example will trigger if the request method is either
3417 <literal>CONNECT</literal> or TRACE.</para>
3419 <programlisting format="linespecific">SecRule <emphasis>REQUEST_METHOD</emphasis> "^((?:connect|trace))$" t:none,t:lowercase</programlisting>
3423 <title><literal moreinfo="none">REQUEST_PROTOCOL</literal></title>
3425 <para>This variable holds the request protocol version information.
3428 <programlisting format="linespecific">SecRule <emphasis>REQUEST_PROTOCOL</emphasis> "!^http/(0\.9|1\.0|1\.1)$" t:none,t:lowercase</programlisting>
3432 <title><literal moreinfo="none">REQUEST_URI</literal></title>
3434 <para>This variable holds the full URL including the
3435 <literal>QUERY_STRING</literal> data (e.g. /index.php?p=X), however it
3436 will never contain a domain name, even if it was provided on the request
3437 line. It also does not include either the
3438 <literal>REQUEST_METHOD</literal> or the HTTP version info.</para>
3440 <para>Example:</para>
3442 <programlisting format="linespecific">SecRule <emphasis>REQUEST_URI</emphasis> "attack" phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath</programlisting>
3445 <para>Please note that anti-evasion transformations are not used on
3446 <literal>REQUEST_URI</literal> by default.</para>
3451 <title><literal moreinfo="none">REQUEST_URI_RAW</literal></title>
3453 <para>Same as <literal>REQUEST_URI</literal> but will contain the domain
3454 name if it was provided on the request line (e.g.
3455 http://www.example.com/index.php?p=X).</para>
3457 <para>Example:</para>
3459 <programlisting format="linespecific">SecRule<emphasis> REQUEST_URI_RAW</emphasis> "http:/" phase:1,t:none,t:urlDecode,t:lowercase,t:normalisePath</programlisting>
3462 <para>Please note that anti-evasion transformations are not used on
3463 <literal>REQUEST_URI_RAW</literal> by default.</para>
3468 <title><literal moreinfo="none">RESPONSE_BODY</literal></title>
3470 <para>This variable holds the data for the response payload.</para>
3472 <para>Example:</para>
3474 <programlisting format="linespecific">SecRule<emphasis> RESPONSE_BODY</emphasis> "ODBC Error Code"</programlisting>
3478 <title><literal>RESPONSE_CONTENT_LENGTH</literal></title>
3480 <para>Response body length in bytes. Can be available starting with
3481 phase 3 but it does not have to be (as the length of response body is
3482 not always known in advance.) If the size is not known this variable
3483 will contain a zero. If <literal>RESPONSE_CONTENT_LENGTH</literal>
3484 contains a zero in phase 5 that means the actual size of the response
3487 <para>The value of this variable can change between phases if the body
3488 is modified. For example, in embedded mode
3489 <literal>mod_deflate</literal> can compress the response body between
3490 phases 4 and 5.</para>
3494 <title><literal>RESPONSE_CONTENT_TYPE</literal></title>
3496 <para>Response content type. Only available starting with phase
3501 <title><literal moreinfo="none">RESPONSE_HEADERS</literal></title>
3503 <para>This variable is similar to the REQUEST_HEADERS variable and can
3504 be used in the same manner. Example:</para>
3506 <programlisting format="linespecific">SecRule<emphasis> RESPONSE_HEADERS</emphasis><emphasis>:X-Cache</emphasis> "MISS"</programlisting>
3508 <para><emphasis>Note</emphasis></para>
3510 <para>This variable may not have access to some headers when running in
3511 embedded-mode. Headers such as Server, Date, Connection and Content-Type
3512 are added during a later Apache hook just prior to sending the data to
3513 the client. This data should be available, however, either during
3514 ModSecurity phase:5 (logging) or when running in proxy-mode.</para>
3518 <title><literal moreinfo="none">RESPONSE_HEADERS_NAMES</literal></title>
3520 <para>This variable is a collection of the response header names.
3523 <programlisting format="linespecific">SecRule <emphasis>RESPONSE_HEADERS_NAMES</emphasis> "Set-Cookie"</programlisting>
3525 <para><emphasis>Note</emphasis></para>
3527 <para>Same limitations as RESPONSE_HEADERS with regards to access to
3528 some headers in embedded-mode.</para>
3532 <title><literal moreinfo="none">RESPONSE_PROTOCOL</literal></title>
3534 <para>This variable holds the HTTP response protocol information.
3537 <programlisting format="linespecific">SecRule <emphasis>RESPONSE_PROTOCOL</emphasis> "^HTTP\/0\.9"</programlisting>
3541 <title><literal moreinfo="none">RESPONSE_STATUS</literal></title>
3543 <para>This variable holds the HTTP response status code as generated by
3544 Apache. Example:</para>
3546 <programlisting format="linespecific">SecRule <emphasis>RESPONSE_STATUS</emphasis> "^[45]"</programlisting>
3548 <para><emphasis>Note</emphasis></para>
3550 <para>This directive may not work as expected in embedded-mode as Apache
3551 handles many of the stock response codes (404, 401, etc...) earlier in
3552 Phase 2. This variable should work as expected in a proxy-mode
3557 <title><literal moreinfo="none">RULE</literal></title>
3559 <para>This variable provides access to the <literal
3560 moreinfo="none">id</literal>, <literal moreinfo="none">rev</literal>,
3561 <literal moreinfo="none">severity</literal>, <literal
3562 moreinfo="none">logdata</literal>, and <literal
3563 moreinfo="none">msg</literal> fields of the rule that triggered the
3564 action. Only available for expansion in action strings (e.g.<literal
3565 moreinfo="none">setvar:tx.varname=%{rule.id}</literal>). Example:</para>
3567 <programlisting format="linespecific">SecRule &REQUEST_HEADERS:Host "@eq 0" "log,deny,setvar:tx.varname=<emphasis>%{rule.id}</emphasis>"</programlisting>
3571 <title><literal moreinfo="none">SCRIPT_BASENAME</literal></title>
3573 <para>This variable holds just the local filename part of
3574 SCRIPT_FILENAME. Example:</para>
3576 <programlisting format="linespecific">SecRule <emphasis>SCRIPT_BASENAME</emphasis> "^login\.php$"</programlisting>
3578 <para><emphasis>Note</emphasis></para>
3580 <para>This variable is not available in proxy mode.</para>
3584 <title><literal moreinfo="none">SCRIPT_FILENAME</literal></title>
3586 <para>This variable holds the full path on the server to the requested
3587 script. (e.g. SCRIPT_NAME plus the server path). Example:</para>
3589 <programlisting format="linespecific">SecRule <emphasis>SCRIPT_FILENAME</emphasis> "^/usr/local/apache/cgi-bin/login\.php$"</programlisting>
3591 <para><emphasis>Note</emphasis></para>
3593 <para>This variable is not available in proxy mode.</para>
3597 <title><literal moreinfo="none">SCRIPT_GID</literal></title>
3599 <para>This variable holds the group id (numerical value) of the group
3600 owner of the script. Example:</para>
3602 <programlisting format="linespecific">SecRule <emphasis>SCRIPT_GID</emphasis> "!^46$"</programlisting>
3604 <para><emphasis>Note</emphasis></para>
3606 <para>This variable is not available in proxy mode.</para>
3610 <title><literal moreinfo="none">SCRIPT_GROUPNAME</literal></title>
3612 <para>This variable holds the group name of the group owner of the
3613 script. Example:</para>
3615 <programlisting format="linespecific">SecRule<emphasis> SCRIPT_GROUPNAME</emphasis> "!^apache$"</programlisting>
3617 <para><emphasis>Note</emphasis></para>
3619 <para>This variable is not available in proxy mode.</para>
3623 <title><literal moreinfo="none">SCRIPT_MODE</literal></title>
3625 <para>This variable holds the script's permissions mode data (numerical
3626 - 1=execute, 2=write, 4=read and 7=read/write/execute). Example: will
3627 trigger if the script has the WRITE permissions set.</para>
3629 <programlisting format="linespecific">SecRule <emphasis>SCRIPT_MODE</emphasis> "^(2|3|6|7)$"</programlisting>
3631 <para><emphasis>Note</emphasis></para>
3633 <para>This variable is not available in proxy mode.</para>
3637 <title><literal moreinfo="none">SCRIPT_UID</literal></title>
3639 <para>This variable holds the user id (numerical value) of the owner of
3640 the script. Example: the example rule below will trigger if the UID is
3641 not 46 (the Apache user).</para>
3643 <programlisting format="linespecific">SecRule<emphasis> SCRIPT_UID</emphasis> "!^46$"</programlisting>
3645 <para><emphasis>Note</emphasis></para>
3647 <para>This variable is not available in proxy mode.</para>
3651 <title><literal moreinfo="none">SCRIPT_USERNAME</literal></title>
3653 <para>This variable holds the username of the owner of the script.
3656 <programlisting format="linespecific">SecRule <emphasis>SCRIPT_USERNAME</emphasis> "!^apache$"</programlisting>
3658 <para><emphasis>Note</emphasis></para>
3660 <para>This variable is not available in proxy mode.</para>
3664 <title><literal moreinfo="none">SERVER_ADDR</literal></title>
3666 <para>This variable contains the IP address of the server.
3669 <programlisting format="linespecific">SecRule<emphasis> SERVER_ADDR</emphasis> "^192\.168\.1\.100$"</programlisting>
3673 <title><literal moreinfo="none">SERVER_NAME</literal></title>
3675 <para>This variable contains the server's hostname or IP address.
3678 <programlisting format="linespecific">SecRule <emphasis>SERVER_NAME</emphasis> "hostname\.com$"</programlisting>
3680 <para><emphasis>Note</emphasis></para>
3682 <para>This data is taken from the Host header submitted in the client
3687 <title><literal moreinfo="none">SERVER_PORT</literal></title>
3689 <para>This variable contains the local port that the web server is
3690 listening on. Example:</para>
3692 <programlisting format="linespecific">SecRule <emphasis>SERVER_PORT</emphasis> "^80$"</programlisting>
3696 <title><literal moreinfo="none">SESSION</literal></title>
3698 <para>This variable is a collection, available only after <literal
3699 moreinfo="none">setsid</literal> is executed. Example: the following
3700 example shows how to initialize a SESSION collection with setsid, how to
3701 use setvar to increase the session.score values, how to set the
3702 session.blocked variable and finally how to deny the connection based on
3703 the session:blocked value.</para>
3705 <programlisting format="linespecific">SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
3706 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}
3707 SecRule REQUEST_URI "^/cgi-bin/finger$" \
3708 "phase:2,t:none,t:lowercase,t:normalisePath,pass,log,setvar:<emphasis>session.score</emphasis>=+10"
3709 SecRule<emphasis> SESSION:SCORE</emphasis> "@gt 50" "pass,log,setvar:<emphasis>session.blocked</emphasis>=1"
3710 SecRule<emphasis> SESSION:BLOCKED</emphasis> "@eq 1" "log,deny,status:403"</programlisting>
3714 <title><literal moreinfo="none">SESSIONID</literal></title>
3716 <para>This variable is the value set with <literal
3717 moreinfo="none">setsid</literal>. Example:</para>
3719 <programlisting format="linespecific">SecRule <emphasis>SESSIONID</emphasis> !^$ chain,nolog,pass
3720 SecRule REQUEST_COOKIES:PHPSESSID !^$
3721 SecAction setsid:%{REQUEST_COOKIES.PHPSESSID}</programlisting>
3725 <title><literal moreinfo="none">TIME</literal></title>
3727 <para>This variable holds a formatted string representing the time
3728 (hour:minute:second). Example:</para>
3730 <programlisting format="linespecific">SecRule<emphasis> TIME</emphasis> "^(([1](8|9))|([2](0|1|2|3))):\d{2}:\d{2}$"</programlisting>
3734 <title><literal moreinfo="none">TIME_DAY</literal></title>
3736 <para>This variable holds the current date (1-31). Example: this rule
3737 would trigger anytime between the 10th and 20th days of the
3740 <programlisting format="linespecific">SecRule <emphasis>TIME_DAY</emphasis> "^(([1](0|1|2|3|4|5|6|7|8|9))|20)$"</programlisting>
3744 <title><literal moreinfo="none">TIME_EPOCH</literal></title>
3746 <para>This variable holds the time in seconds since 1970.
3749 <programlisting format="linespecific">SecRule <emphasis>TIME_EPOCH</emphasis> "@gt 1000"</programlisting>
3753 <title><literal moreinfo="none">TIME_HOUR</literal></title>
3755 <para>This variable holds the current hour (0-23). Example: this rule
3756 would trigger during "off hours".</para>
3758 <programlisting format="linespecific">SecRule<emphasis> TIME_HOUR</emphasis> "^(0|1|2|3|4|5|6|[1](8|9)|[2](0|1|2|3))$"</programlisting>
3762 <title><literal moreinfo="none">TIME_MIN</literal></title>
3764 <para>This variable holds the current minute (0-59). Example: this rule
3765 would trigger during the last half hour of every hour.</para>
3767 <programlisting format="linespecific">SecRule <emphasis>TIME_MIN</emphasis> "^(3|4|5)"</programlisting>
3771 <title><literal moreinfo="none">TIME_MON</literal></title>
3773 <para>This variable holds the current month (0-11). Example: this rule
3774 would match if the month was either November (10) or December
3777 <programlisting format="linespecific">SecRule<emphasis> TIME_MON</emphasis> "^1"</programlisting>
3781 <title><literal moreinfo="none">TIME_SEC</literal></title>
3783 <para>This variable holds the current second count (0-59).
3786 <programlisting format="linespecific">SecRule <emphasis>TIME_SEC</emphasis> "@gt 30"</programlisting>
3790 <title><literal moreinfo="none">TIME_WDAY</literal></title>
3792 <para>This variable holds the current weekday (0-6). Example: this rule
3793 would trigger only on week-ends (Saturday and Sunday).</para>
3795 <programlisting format="linespecific">SecRule <emphasis>TIME_WDAY</emphasis> "^(0|6)$"</programlisting>
3799 <title><literal moreinfo="none">TIME_YEAR</literal></title>
3801 <para>This variable holds the current four-digit year data.
3804 <programlisting format="linespecific">SecRule <emphasis>TIME_YEAR</emphasis> "^2006$"</programlisting>
3808 <title><literal moreinfo="none">TX</literal></title>
3810 <para>Transaction Collection. This is used to store pieces of data,
3811 create a transaction anomaly score, and so on. Transaction variables are
3812 set for 1 request/response cycle. The scoring and evaluation will not
3813 last past the current request/response process. Example: In this
3814 example, we are using setvar to increase the tx.score value by 5 points.
3815 We then have a follow-up run that will evaluate the transactional score
3816 this request and then it will decided whether or not to allow/deny the
3817 request through.</para>
3819 <para>The following is a list of reserved names in the TX
3824 <para><literal moreinfo="none">TX:0</literal> - The matching value
3825 when using the <literal moreinfo="none">@rx</literal> or <literal
3826 moreinfo="none">@pm</literal> operator with the <literal
3827 moreinfo="none">capture</literal> action.</para>
3831 <para><literal moreinfo="none">TX:1-TX:9</literal> - The captured
3832 subexpression value when using the <literal
3833 moreinfo="none">@rx</literal> operator with capturing parens and the
3834 <literal moreinfo="none">capture</literal> action.</para>
3838 <programlisting format="linespecific">SecRule WEBSERVER_ERROR_LOG "does not exist" "phase:5,pass,<emphasis>setvar:tx.score=+5</emphasis>"
3839 SecRule<emphasis> TX:SCORE</emphasis> "@gt 20" deny,log</programlisting>
3843 <title><literal moreinfo="none">USERID</literal></title>
3845 <para>This variable is the value set with <literal
3846 moreinfo="none">setuid</literal>. Example:</para>
3848 <programlisting format="linespecific">SecAction setuid:%{REMOTE_USER},nolog
3849 SecRule<emphasis> USERID</emphasis> "Admin"</programlisting>
3853 <title><literal moreinfo="none">WEBAPPID</literal></title>
3855 <para>This variable is the value set with <literal
3856 moreinfo="none">SecWebAppId</literal>. Example:</para>
3858 <programlisting format="linespecific">SecWebAppId "WebApp1"
3859 SecRule<emphasis> WEBAPPID</emphasis> "WebApp1" "chain,log,deny,status:403"
3860 SecRule REQUEST_HEADERS:Transfer-Encoding "!^$"</programlisting>
3864 <title><literal moreinfo="none">WEBSERVER_ERROR_LOG</literal></title>
3866 <para>Contains zero or more error messages produced by the web server.
3867 Access to this variable is in phase:5 (logging). Example:</para>
3869 <programlisting format="linespecific">SecRule<emphasis> WEBSERVER_ERROR_LOG</emphasis> "File does not exist" "phase:5,setvar:tx.score=+5"</programlisting>
3873 <title><literal moreinfo="none">XML</literal></title>
3875 <para>Can be used standalone (as a target for
3876 <literal>validateDTD</literal> and <literal>validateSchema</literal>) or
3877 with an XPath expression parameter (which makes it a valid target for
3878 any function that accepts plain text). Example using XPath:</para>
3880 <programlisting format="linespecific">SecDefaultAction log,deny,status:403,phase:2
3881 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
3882 phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=<emphasis>XML</emphasis>
3883 SecRule REQBODY_PROCESSOR "<emphasis>!^XML$</emphasis>" skipAfter:12345
3884 SecRule <emphasis>XML:/employees/employee/name/text()</emphasis> Fred
3885 SecRule <emphasis>XML:/xq:employees/employee/name/text()</emphasis> Fred \
3886 id:12345,xmlns:xq=http://www.example.com/employees</programlisting>
3888 <para>The first XPath expression does not use namespaces. It would match
3889 against payload such as this one:</para>
3891 <programlisting><employees>
3893 <name>Fred Jones</name>
3894 <address location="home">
3895 <street>900 Aurora Ave.</street>
3896 <city>Seattle</city>
3897 <state>WA</state>
3898 <zip>98115</zip>
3900 <address location="work">
3901 <street>2011 152nd Avenue NE</street>
3902 <city>Redmond</city>
3903 <state>WA</state>
3904 <zip>98052</zip>
3906 <phone location="work">(425)555-5665</phone>
3907 <phone location="home">(206)555-5555</phone>
3908 <phone location="mobile">(206)555-4321</phone>
3910 </employees></programlisting>
3912 <para>The second XPath expression does use namespaces. It would match
3913 the following payload:</para>
3915 <programlisting><xq:employees xmlns:xq="http://www.example.com/employees">
3917 <name>Fred Jones</name>
3918 <address location="home">
3919 <street>900 Aurora Ave.</street>
3920 <city>Seattle</city>
3921 <state>WA</state>
3922 <zip>98115</zip>
3924 <address location="work">
3925 <street>2011 152nd Avenue NE</street>
3926 <city>Redmond</city>
3927 <state>WA</state>
3928 <zip>98052</zip>
3930 <phone location="work">(425)555-5665</phone>
3931 <phone location="home">(206)555-5555</phone>
3932 <phone location="mobile">(206)555-4321</phone>
3934 </xq:employees></programlisting>
3936 <para>Note the different namespace used in the second example.</para>
3938 <para>To learn more about XPath we suggest the following
3943 <para><ulink url="http://www.w3.org/TR/xpath">XPath
3944 Standard</ulink></para>
3949 url="http://www.zvon.org/xxl/XPathTutorial/General/examples.html">XPath
3950 Tutorial</ulink></para>
3956 <section id="transformation-functions">
3957 <title>Transformation functions</title>
3959 <para>When ModSecurity receives request or response information, it makes
3960 a copy of this data and places it into memory. It is on this data in
3961 memory that transformation functions are applied. The raw request/response
3962 data is never altered. Transformation functions are used to transform a
3963 variable before testing it in a rule.</para>
3965 <para><emphasis>Note</emphasis></para>
3967 <para>There are no default transformation functions as there were in
3968 previous versions of ModSecurity.</para>
3970 <para>The following rule will ensure that an attacker does not use mixed
3971 case in order to evade the ModSecurity rule:</para>
3973 <para><programlisting format="linespecific">SecRule ARGS:p "xp_cmdshell" <emphasis>"t:lowercase"</emphasis></programlisting>
3974 multiple transformation actions can be used in the same rule, for example
3975 the following rule also ensures that an attacker does not use URL encoding
3976 (%xx encoding) for evasion. Note the order of the transformation
3977 functions, which ensures that a URL encoded letter is first decoded and
3978 than translated to lower case.</para>
3980 <para><programlisting format="linespecific">SecRule ARGS:p "xp_cmdshell" <emphasis>"t:urlDecode,t:lowercase"</emphasis></programlisting></para>
3982 <para>One can use the SecDefaultAction command to ensure the translation
3983 occurs for every rule until the next. Note that transformation actions are
3984 additive, so if a rule explicitly list actions, the translation actions
3985 set by SecDefaultAction are still performed.</para>
3987 <para><programlisting format="linespecific">SecDefaultAction <emphasis>t:urlDecode,t:lowercase</emphasis></programlisting></para>
3989 <para>The following transformation functions are supported:</para>
3992 <title><literal>base64Decode</literal></title>
3994 <para>This function decodes a base64-encoded string.</para>
3998 <title><literal>base64Encode</literal></title>
4000 <para>This function encodes input string using base64 encoding.</para>
4004 <title><literal>compressWhitespace</literal></title>
4006 <para>It converts whitespace characters (32, \f, \t, \n, \r, \v, 160) to
4007 spaces (ASCII 32) and then compresses multiple consecutive space
4008 characters into one.</para>
4012 <title>cssDecode</title>
4014 <para>Decodes CSS-encoded characters, as specified at <ulink
4015 url="http://www.w3.org/TR/REC-CSS2/syndata.html">http://www.w3.org/TR/REC-CSS2/syndata.html</ulink>.
4016 This function uses only up to two bytes in the decoding process, meaning
4017 it is useful to uncover ASCII characters (that wouldn't normally be
4018 encoded) encoded using CSS encoding, or to counter evasion which is a
4019 combination of a backslash and non-hexadecimal characters (e.g.
4020 <literal>ja\vascript</literal> is equivalent to
4021 <literal>javascript</literal>).</para>
4025 <title><literal>escapeSeqDecode</literal></title>
4027 <para>This function decode ANSI C escape sequences:<literal
4028 moreinfo="none"> \a</literal>,<literal moreinfo="none"> \b</literal>,
4029 <literal moreinfo="none">\f</literal>, <literal
4030 moreinfo="none">\n</literal>, <literal moreinfo="none">\r</literal>,
4031 <literal moreinfo="none">\t</literal>, <literal
4032 moreinfo="none">\v</literal>, <literal moreinfo="none">\\</literal>,
4033 <literal moreinfo="none">\?</literal>, <literal
4034 moreinfo="none">\'</literal>, <literal moreinfo="none">\"</literal>,
4035 <literal moreinfo="none">\xHH</literal> (hexadecimal), <literal
4036 moreinfo="none">\0OOO</literal> (octal). Invalid encodings are left in
4041 <title><literal>hexDecode</literal></title>
4043 <para>This function decodes a hex-encoded string.</para>
4047 <title><literal>hexEncode</literal></title>
4049 <para>This function encodes input as hex-encoded string.</para>
4053 <title><literal>htmlEntityDecode</literal></title>
4055 <para>This function decodes HTML entities present in input. The
4056 following variants are supported:</para>
4060 <para><literal moreinfo="none">&#xHH</literal> and <literal
4061 moreinfo="none">&#xHH;</literal> (where H is any hexadecimal
4066 <para><literal moreinfo="none">&#DDD</literal> and <literal
4067 moreinfo="none">&#DDD;</literal> (where D is any decimal
4072 <para><literal moreinfo="none">&quot</literal> and <literal
4073 moreinfo="none">&quot;</literal></para>
4077 <para><literal moreinfo="none">&nbsp</literal> and <literal
4078 moreinfo="none">&nbsp;</literal></para>
4082 <para><literal moreinfo="none">&lt</literal> and <literal
4083 moreinfo="none">&lt;</literal></para>
4087 <para><literal moreinfo="none">&gt</literal> and <literal
4088 moreinfo="none">&gt;</literal></para>
4092 <para>This function will convert any entity into a single byte only,
4093 possibly resulting in a loss of information. It is thus useful to
4094 uncover bytes that would otherwise not need to be encoded, but it cannot
4095 do anything with the characters from the range above 255.</para>
4099 <title><literal>jsDecode</literal></title>
4101 <para>Decodes JavaScript escape sequences. If a
4102 <literal>\uHHHH</literal> code is in the range of
4103 <literal>FF01</literal>-<literal>FF5E</literal> (the full width ASCII
4104 codes), then the higher byte is used to detect and adjust the lower
4105 byte. Otherwise, only the lower byte will be used and the higher byte
4110 <title><literal>length</literal></title>
4112 <para>This function converts the input to its numeric length (count of
4117 <title><literal>lowercase</literal></title>
4119 <para>This function converts all characters to lowercase using the
4120 current C locale.</para>
4124 <title><literal>md5</literal></title>
4126 <para>This function calculates an MD5 hash from input. Note that the
4127 computed hash is in a raw binary form and may need encoded into text to
4128 be usable (for example: <literal>t:md5,t:hexEncode</literal>).</para>
4132 <title><literal><literal>none</literal></literal></title>
4134 <para>Not an actual transformation function, but an instruction to
4135 ModSecurity to remove all transformation functions associated with the
4136 current rule.</para>
4140 <title><literal>normalisePath</literal></title>
4142 <para>This function will remove multiple slashes, self-references and
4143 directory back-references (except when they are at the beginning of the
4148 <title><literal>normalisePathWin</literal></title>
4150 <para>Same as <literal>normalisePath</literal>, but will first convert
4151 backslash characters to forward slashes.</para>
4155 <title><literal>parityEven7bit</literal></title>
4157 <para>This function calculates even parity of 7-bit data replacing the
4158 8th bit of each target byte with the calculated parity bit.</para>
4162 <title><literal>parityOdd7bit</literal></title>
4164 <para>This function calculates odd parity of 7-bit data replacing the
4165 8th bit of each target byte with the calculated parity bit.</para>
4169 <title><literal>parityZero7bit</literal></title>
4171 <para>This function calculates zero parity of 7-bit data replacing the
4172 8th bit of each target byte with a zero parity bit which allows
4173 inspection of even/odd parity 7bit data as ASCII7 data.</para>
4177 <title><literal>removeNulls</literal></title>
4179 <para>This function removes NULL bytes from input.</para>
4183 <title><literal>removeWhitespace</literal></title>
4185 <para>This function removes all whitespace characters from input.</para>
4189 <title><literal>replaceComments</literal></title>
4191 <para>This function replaces each occurrence of a C-style comments
4192 (<literal moreinfo="none">/* ... */</literal>) with a single space
4193 (multiple consecutive occurrences of a space will not be compressed).
4194 Unterminated comments will too be replaced with a space (ASCII 32).
4195 However, a standalone termination of a comment (<literal
4196 moreinfo="none">*/</literal>) will not be acted upon.</para>
4200 <title><literal>replaceNulls</literal></title>
4202 <para>This function is enabled by default. It replaces NULL bytes in
4203 input with spaces (ASCII 32).</para>
4207 <title><literal>urlDecode</literal></title>
4209 <para>This function decodes an URL-encoded input string. Invalid
4210 encodings (i.e. the ones that use non-hexadecimal characters, or the
4211 ones that are at the end of string and have one or two characters
4212 missing) will not be converted. If you want to detect invalid encodings
4213 use the <literal moreinfo="none">@validateUrlEncoding</literal>
4214 operator. The transformation function should not be used against
4215 variables that have already been URL-decoded unless it is your intention
4216 to perform URL decoding twice!</para>
4220 <title><literal>urlDecodeUni</literal></title>
4222 <para>In addition to decoding <literal>%xx</literal> like <literal
4223 moreinfo="none">urlDecode, urlDecodeUni</literal> also decodes <literal
4224 moreinfo="none">%uXXXX</literal> encoding. If the code is in the range
4225 of <literal>FF01</literal>-<literal>FF5E</literal> (the full width ASCII
4226 codes), then the higher byte is used to detect and adjust the lower
4227 byte. Otherwise, only the lower byte will be used and the higher byte
4232 <title><literal>urlEncode</literal></title>
4234 <para>This function encodes input using URL encoding.</para>
4238 <title><literal>sha1</literal></title>
4240 <para>This function calculates a SHA1 hash from input. Note that the
4241 computed hash is in a raw binary form and may need encoded to be usable
4242 (for example: <literal>t:sha1,t:hexEncode</literal>).</para>
4246 <title><literal>trimLeft</literal></title>
4248 <para>This function removes whitespace from the left side of
4253 <title><literal>trimRight</literal></title>
4255 <para>This function removes whitespace from the right side of
4260 <title><literal>trim</literal></title>
4262 <para>This function removes whitespace from both the left and right
4263 sides of input.</para>
4267 <section id="actions">
4268 <title>Actions</title>
4270 <para>Each action belongs to one of five groups:</para>
4274 <term>Disruptive actions</term>
4277 <para>Cause ModSecurity to do something. In many cases something
4278 means block transaction, but not in all. For example, the allow
4279 action is classified as a disruptive action, but it does the
4280 opposite of blocking. There can only be one disruptive action per
4281 rule (if there are multiple disruptive actions present, or
4282 inherited, only the last one will take effect), or rule chain (in a
4283 chain, a disruptive action can only appear in the first
4289 <term>Non-disruptive actions</term>
4292 <para>Do something, but that something does not and cannot affect
4293 the rule processing flow. Setting a variable, or changing its value
4294 is an example of a non-disruptive action. Non-disruptive action can
4295 appear in any rule, including each rule belonging to a chain.</para>
4300 <term>Flow actions</term>
4303 <para>These actions affect the rule flow (for example
4304 <literal>skip</literal> or <literal>skipAfter</literal>).</para>
4309 <term>Meta-data actions</term>
4312 <para>Meta-data actions are used to provide more information about
4313 rules. Examples include <literal>id</literal>,
4314 <literal>rev</literal>, <literal>severity</literal> and
4315 <literal>msg</literal>.</para>
4320 <term>Data actions</term>
4323 <para>Not really actions, these are mere containers that hold data
4324 used by other actions. For example, the <literal>status</literal>
4325 action holds the status that will be used for blocking (if it takes
4332 <title><literal>allow</literal></title>
4334 <para><emphasis>Description:</emphasis> Stops rule processing on a
4335 successful match and allows the transaction to proceed.</para>
4337 <para><emphasis>Action Group:</emphasis> Disruptive</para>
4339 <para>Example:</para>
4341 <programlisting format="linespecific">SecRule REMOTE_ADDR "^192\.168\.1\.100$" nolog,phase:1,<emphasis>allow</emphasis></programlisting>
4343 <para>Prior to ModSecurity 2.5 the <literal>allow</literal> action would
4344 only affect the current phase. An <literal>allow</literal> in phase 1
4345 would skip processing the remaining rules in phase 1 but the rules from
4346 phase 2 would execute. Starting with v2.5.0 <literal>allow</literal> was
4347 enhanced to allow for fine-grained control of what is done. The
4348 following rules now apply:</para>
4352 <para>If used one its own, like in the example above,
4353 <literal>allow</literal> will affect the entire transaction,
4354 stopping processing of the current phase but also skipping over all
4355 other phases apart from the logging phase. (The logging phase is
4356 special; it is designed to always execute.)</para>
4360 <para>If used with parameter "phase", <literal>allow</literal> will
4361 cause the engine to stop processing the current phase. Other phases
4362 will continue as normal.</para>
4366 <para>If used with parameter "request", <literal>allow</literal>
4367 will cause the engine to stop processing the current phase. The next
4368 phase to be processed will be phase
4369 <literal>RESPONSE_HEADERS</literal>.</para>
4373 <para>Examples:</para>
4375 <programlisting># Do not process request but process response.
4376 SecAction phase:1,allow:request
4378 # Do not process transaction (request and response).
4379 SecAction phase:1,allow
4382 <para>If you want to allow a response through, put a rule in phase
4383 <literal>RESPONSE_HEADERS</literal> and simply use
4384 <literal>allow</literal> on its own:</para>
4386 <programlisting># Allow response through.
4387 SecAction phase:3,allow</programlisting>
4391 <title>append</title>
4393 <para><emphasis>Description:</emphasis> Appends text given as parameter
4394 to the end of response body. For this action to work content injection
4395 must be enabled by setting <literal>SecContentInjection</literal> to
4396 <literal>On</literal>. Also make sure you check the content type of the
4397 response before you make changes to it (e.g. you don't want to inject
4398 stuff into images).</para>
4400 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4402 <para><emphasis>Processing Phases:</emphasis> 3 and 4.</para>
4404 <para>Example:</para>
4406 <programlisting>SecRule RESPONSE_CONTENT_TYPE "^text/html" "nolog,pass,<emphasis>append:'<hr>Footer'</emphasis>"</programlisting>
4409 <para>While macro expansion is allowed in the additional content, you
4410 are strongly cautioned against inserting user defined data
4416 <title><literal>auditlog</literal></title>
4418 <para><emphasis>Description:</emphasis> Marks the transaction for
4419 logging in the audit log.</para>
4421 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4423 <para>Example:</para>
4425 <programlisting format="linespecific">SecRule REMOTE_ADDR "^192\.168\.1\.100$" <emphasis>auditlog</emphasis>,phase:1,allow</programlisting>
4427 <para><emphasis>Note</emphasis></para>
4429 <para>The auditlog action is now explicit if log is already
4434 <title><literal>block</literal></title>
4436 <para><emphasis>Description:</emphasis> Performs the default disruptive
4439 <para><emphasis>Action Group:</emphasis> Disruptive</para>
4441 <para>It is intended to be used by ruleset writers to signify that the
4442 rule was intended to block and leaves the "how" up to the administrator.
4443 This action is currently a placeholder which will just be replaced by
4444 the action from the last <literal>SecDefaultAction</literal> in the same
4445 context. Using the <literal>block</literal> action with the
4446 <literal>SecRuleUpdateActionById</literal> directive allows a rule to be
4447 reverted back to the previous <literal>SecDefaultAction</literal>
4448 disruptive action.</para>
4450 <para>In future versions of ModSecurity, more control and functionality
4451 will be added to define "how" to block.</para>
4453 <para>Examples:</para>
4455 <para>In the following example, the second rule will "deny" because of
4456 the SecDefaultAction disruptive action. The intent being that the
4457 administrator could easily change this to another disruptive action
4458 without editing the actual rules.</para>
4460 <programlisting format="linespecific">### Administrator defines "how" to block (deny,status:403)...
4461 SecDefaultAction phase:2,deny,status:403,log,auditlog
4463 ### Included from a rulest...
4464 # Intent is to warn for this User Agent
4465 SecRule REQUEST_HEADERS:User-Agent "perl" "phase:2,<emphasis>pass</emphasis>,msg:'Perl based user agent identified'"
4466 # Intent is to block for this User Agent, "how" described in SecDefaultAction
4467 SecRule REQUEST_HEADERS:User-Agent "nikto" "phase:2,<emphasis>block</emphasis>,msg:'Nikto Scanners Identified'"</programlisting>
4469 <para>In the following example, The rule is reverted back to the
4470 <literal>pass</literal> action defined in the SecDefaultAction directive
4471 by using the <literal>SecRuleUpdateActionById</literal> directive in
4472 conjuction with the <literal>block</literal> action. This allows an
4473 administrator to override an action in a 3rd party rule without
4474 modifying the rule itself.</para>
4476 <programlisting format="linespecific">### Administrator defines "how" to block (deny,status:403)...
4477 SecDefaultAction phase:2,pass,log,auditlog
4479 ### Included from a rulest...
4480 SecRule REQUEST_HEADERS:User-Agent "nikto" "id:1,phase:2,<emphasis>deny</emphasis>,msg:'Nikto Scanners Identified'"
4482 ### Added by the administrator
4483 SecRuleUpdateActionById 1 "<emphasis>block</emphasis>"</programlisting>
4487 <title><literal>capture</literal></title>
4489 <para><emphasis>Description:</emphasis> When used together with the
4490 regular expression operator, capture action will create copies of
4491 regular expression captures and place them into the transaction variable
4492 collection. Up to ten captures will be copied on a successful pattern
4493 match, each with a name consisting of a digit from 0 to 9.</para>
4495 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4497 <para>Example:</para>
4499 <programlisting format="linespecific">SecRule REQUEST_BODY "^username=(\w{25,})" phase:2,<emphasis>capture</emphasis>,t:none,chain
4500 SecRule TX:1 "(?:(?:a(dmin|nonymous)))"</programlisting>
4502 <para><emphasis>Note</emphasis></para>
4504 <para>The 0 data captures the entire REGEX match and 1 captures the data
4505 in the first parens, etc...</para>
4509 <title><literal>chain</literal></title>
4511 <para><emphasis>Description:</emphasis> Chains the rule where the action
4512 is placed with the rule that immediately follows it. The result is
4513 called a<emphasis> rule chain</emphasis>. Chained rules allow for more
4514 complex rule matches where you want to use a number of different
4515 VARIABLES to create a better rule and to help prevent false
4518 <para><emphasis>Action Group:</emphasis> Flow</para>
4520 <para>Example:</para>
4522 <programlisting format="linespecific"># Refuse to accept POST requests that do
4523 # not specify request body length. Do note that
4524 # this rule should be preceeded by a rule that verifies
4525 # only valid request methods (e.g. GET, HEAD and POST) are used.
4526 SecRule REQUEST_METHOD ^POST$<emphasis> chain</emphasis>,t:none
4527 SecRule REQUEST_HEADERS:Content-Length ^$ t:none</programlisting>
4530 <para>In programming language concepts, think of chained rules
4531 somewhat similar to AND conditional statements. The actions specified
4532 in the first portion of the chained rule will only be triggered if all
4533 of the variable checks return positive hits. If one aspect of the
4534 chained rule is negative, then the entire rule chain is negative. Also
4535 note that disruptive actions, execution phases, metadata actions (id,
4536 rev, msg), skip and skipAfter actions can only be specified on by the
4537 chain starter rule.</para>
4542 <title><literal>ctl</literal></title>
4544 <para><emphasis>Description:</emphasis> The ctl action allows
4545 configuration options to be updated for the transaction.</para>
4547 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4549 <para>Example:</para>
4551 <programlisting format="linespecific"># Parse requests with Content-Type "text/xml" as XML
4552 SecRule REQUEST_CONTENT_TYPE ^text/xml nolog,pass,<emphasis>ctl:requestBodyProcessor=XML</emphasis></programlisting>
4554 <para><emphasis>Note</emphasis></para>
4556 <para>The following configuration options are supported:</para>
4558 <orderedlist continuation="restarts" inheritnum="ignore">
4560 <para><literal moreinfo="none">auditEngine</literal></para>
4564 <para><literal moreinfo="none">auditLogParts</literal></para>
4568 <para><literal moreinfo="none">debugLogLevel</literal></para>
4572 <para><literal moreinfo="none">ruleRemoveById</literal> (single rule
4573 ID, or a single rule ID range accepted as parameter)</para>
4577 <para><literal moreinfo="none">requestBodyAccess</literal></para>
4582 moreinfo="none">forceRequestBodyVariable</literal></para>
4586 <para><literal moreinfo="none">requestBodyLimit</literal></para>
4590 <para><literal moreinfo="none">requestBodyProcessor</literal></para>
4594 <para><literal moreinfo="none">responseBodyAccess</literal></para>
4598 <para><literal moreinfo="none">responseBodyLimit</literal></para>
4602 <para><literal moreinfo="none">ruleEngine</literal></para>
4606 <para>With the exception of<literal moreinfo="none">
4607 requestBodyProcessor</literal> and <literal moreinfo="none">
4608 forceRequestBodyVariable</literal>, each configuration option
4609 corresponds to one configuration directive and the usage is
4612 <para>The <literal>requestBodyProcessor</literal> option allows you to
4613 configure the request body processor. By default ModSecurity will use
4614 the <literal moreinfo="none">URLENCODED</literal> and<literal
4615 moreinfo="none"> MULTIPART</literal> processors to process an <literal
4616 moreinfo="none">application/x-www-form-urlencoded</literal> and a
4617 <literal moreinfo="none">multipart/form-data</literal> bodies,
4618 respectively. A third processor, <literal>XML</literal>, is also
4619 supported, but it is never used implicitly. Instead you must tell
4620 ModSecurity to use it by placing a few rules in the<literal
4621 moreinfo="none"> REQUEST_HEADERS</literal> processing phase. After the
4622 request body was processed as XML you will be able to use the
4623 XML-related features to inspect it.</para>
4625 <para>Request body processors will not interrupt a transaction if an
4626 error occurs during parsing. Instead they will set variables<literal
4627 moreinfo="none"> REQBODY_PROCESSOR_ERROR</literal> and<literal
4628 moreinfo="none"> REQBODY_PROCESSOR_ERROR_MSG</literal>. These variables
4629 should be inspected in the <literal
4630 moreinfo="none">REQUEST_BODY</literal> phase and an appropriate action
4633 <para>The <literal>forceRequestBodyVariable</literal> option allows you
4634 to configure the <literal>REQUEST_BODY</literal> variable to be set when
4635 there is no request body processor configured. This allows for
4636 inspection of request bodies of unknown types.</para>
4640 <title><literal>deny</literal></title>
4642 <para><emphasis>Description:</emphasis> Stops rule processing and
4643 intercepts transaction.</para>
4645 <para><emphasis>Action Group:</emphasis> Disruptive</para>
4647 <para>Example:</para>
4649 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "nikto" "log,<emphasis>deny</emphasis>,msg:'Nikto Scanners Identified'"</programlisting>
4653 <title><literal>deprecatevar</literal></title>
4655 <para><emphasis>Description:</emphasis> Decrement counter based on its
4658 <para><emphasis>Action Group:</emphasis> Non-Disruptive</para>
4660 <para>Example: The following example will decrement the counter by 60
4661 every 300 seconds.</para>
4663 <programlisting format="linespecific">SecAction deprecatevar:session.score=60/300</programlisting>
4665 <para><emphasis>Note</emphasis></para>
4667 <para>Counter values are always positive, meaning the value will never
4668 go below zero.</para>
4672 <title><literal>drop</literal></title>
4674 <para><emphasis>Description:</emphasis> Immediately initiate a
4675 "connection close" action to tear down the TCP connection by sending a
4678 <para><emphasis>Action Group:</emphasis> Disruptive</para>
4680 <para>Example: The following example initiates an IP collection for
4681 tracking Basic Authentication attempts. If the client goes over the
4682 threshold of more than 25 attempts in 2 minutes, it will DROP subsequent
4685 <programlisting format="linespecific">SecAction phase:1,initcol:ip=%{REMOTE_ADDR},nolog
4686 SecRule ARGS:login "!^$" \
4687 nolog,phase:1,setvar:ip.auth_attempt=+1,deprecatevar:ip.auth_attempt=20/120
4688 SecRule IP:AUTH_ATTEMPT "@gt 25" \
4689 "log,<emphasis>drop</emphasis>,phase:1,msg:'Possible Brute Force Attack'"</programlisting>
4691 <para><emphasis>Note</emphasis></para>
4693 <para>This action is currently not available on Windows based builds.
4694 This action is extremely useful when responding to both Brute Force and
4695 Denial of Service attacks in that, in both cases, you want to minimize
4696 both the network bandwidth and the data returned to the client. This
4697 action causes error message to appear in the log "(9)Bad file
4698 descriptor: core_output_filter: writing data to the network"</para>
4702 <title><literal>exec</literal></title>
4704 <para><emphasis>Description:</emphasis> Executes an external
4705 script/binary supplied as parameter. As of v2.5.0, if the parameter
4706 supplied to <literal>exec</literal> is a Lua script (detected by the
4707 <filename>.lua</filename> extension) the script will be processed
4708 <emphasis>internally</emphasis>. This means you will get direct access
4709 to the internal request context from the script. Please read the
4710 <literal>SecRuleScript</literal> documentation for more details on how
4711 to write Lua scripts.</para>
4713 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4715 <para>Example:</para>
4717 <programlisting format="linespecific"># The following is going to execute /usr/local/apache/bin/test.sh
4718 # as a shell script on rule match.
4719 SecRule REQUEST_URI "^/cgi-bin/script\.pl" \
4720 "phase:2,t:none,t:lowercase,t:normalisePath,log,<emphasis>exec:/usr/local/apache/bin/test.sh</emphasis>"
4722 # The following is going to process /usr/local/apache/conf/exec.lua
4723 # internally as a Lua script on rule match.
4724 SecRule ARGS:p attack log,<emphasis>exec:/usr/local/apache/conf/exec.lua</emphasis></programlisting>
4727 <para>The exec action is executed independently from any disruptive
4728 actions. External scripts will always be called with no parameters.
4729 Some transaction information will be placed in environment variables.
4730 All the usual CGI environment variables will be there. You should be
4731 aware that forking a threaded process results in all threads being
4732 replicated in the new process. Forking can therefore incur larger
4733 overhead in multi-threaded operation. The script you execute must
4734 write something (anything) to stdout. If it doesn't ModSecurity will
4735 assume execution didn't work.</para>
4740 <title><literal>expirevar</literal></title>
4742 <para><emphasis>Description:</emphasis> Configures a collection variable
4743 to expire after the given time in seconds.</para>
4745 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4747 <para>Example:</para>
4749 <programlisting format="linespecific">SecRule REQUEST_COOKIES:JSESSIONID "!^$" nolog,phase:1,pass,chain
4750 SecAction setsid:%{REQUEST_COOKIES:JSESSIONID}
4751 SecRule REQUEST_URI "^/cgi-bin/script\.pl" \
4752 "phase:2,t:none,t:lowercase,t:normalisePath,log,allow,\
4753 setvar:session.suspicious=1,<emphasis>expirevar:session.suspicious=3600</emphasis>,phase:1"</programlisting>
4755 <para><emphasis>Note</emphasis></para>
4757 <para>You should use expirevar actions at the same time that you use
4758 setvar actions in order to keep the indented expiration time. If they
4759 are used on their own (perhaps in a SecAction directive) the expire time
4760 could get re-set. When variables are removed from collections, and there
4761 are no other changes, collections are not written to disk at the end of
4762 request. This is because the variables can always be expired again when
4763 the collection is read again on a subsequent request.</para>
4767 <title><literal>id</literal></title>
4769 <para><emphasis>Description:</emphasis> Assigns a unique ID to the rule
4772 <para><emphasis>Action Group:</emphasis> Meta-data</para>
4774 <para>Example:</para>
4776 <programlisting format="linespecific">SecRule &REQUEST_HEADERS:Host "@eq 0" \
4777 "log,<emphasis>id:60008</emphasis>,severity:2,msg:'Request Missing a Host Header'"</programlisting>
4779 <para><emphasis>Note</emphasis></para>
4781 <para>These are the reserved ranges:</para>
4785 <para>1-99,999; reserved for local (internal) use. Use as you see
4786 fit but do not use this range for rules that are distributed to
4791 <para>100,000-199,999; reserved for internal use of the engine, to
4792 assign to rules that do not have explicit IDs.</para>
4796 <para>200,000-299,999; reserved for rules published at
4797 modsecurity.org.</para>
4801 <para>300,000-399,999; reserved for rules published at
4806 <para>400,000-419,999; unused (available for reservation).</para>
4810 <para>420,000-429,999; reserved for <ulink type=""
4811 url="http://projects.otaku42.de/wiki/ScallyWhack">ScallyWhack</ulink>.</para>
4815 <para>430,000-899,999; unused (available for reservation).</para>
4819 <para>900,000-999,999; reserved for the <ulink
4820 url="http://www.modsecurity.org/projects/rules/">Core Rules</ulink>
4825 <para>1,000,000 and above; unused (available for
4826 reservation).</para>
4832 <title><literal>initcol</literal></title>
4834 <para><emphasis>Description:</emphasis> Initialises a named persistent
4835 collection, either by loading data from storage or by creating a new
4836 collection in memory.</para>
4838 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4840 <para>Example: The following example initiates IP address
4843 <programlisting format="linespecific">SecAction <emphasis>phase:1,initcol:ip=%{REMOTE_ADDR}</emphasis>,nolog</programlisting>
4845 <para><emphasis>Note</emphasis></para>
4847 <para>Normally you will want to use <emphasis>phase:1</emphasis> along
4848 with <emphasis>initcol</emphasis> so that the collection is available in
4851 <para>Collections are loaded into memory when the initcol action is
4852 encountered. The collection in storage will be persisted (and the
4853 appropriate counters increased) <emphasis>only</emphasis> if it was
4854 changed during transaction processing.</para>
4856 <para>See the "Persistant Storage" section for further details.</para>
4860 <title><literal>log</literal></title>
4862 <para><emphasis>Description:</emphasis> Indicates that a successful
4863 match of the rule needs to be logged.</para>
4865 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4867 <para>Example:</para>
4869 <programlisting format="linespecific">SecAction phase:1,initcol:ip=%{REMOTE_ADDR},<emphasis>log</emphasis></programlisting>
4871 <para><emphasis>Note</emphasis></para>
4873 <para>This action will log matches to the Apache error log file and the
4874 ModSecurity audit log.</para>
4878 <title><literal>logdata</literal></title>
4880 <para><emphasis>Description:</emphasis> Allows a data fragment to be
4881 logged as part of the alert message.</para>
4883 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4885 <para>Example:</para>
4887 <programlisting format="linespecific">SecRule &ARGS:p "@eq 0" "log,<emphasis>logdata:'%{TX.0}'"</emphasis></programlisting>
4889 <para><emphasis>Note</emphasis></para>
4891 <para>The logdata information appears in the error and/or audit log
4892 files and is not sent back to the client in response headers. Macro
4893 expansion is preformed so you may use variable names such as %{TX.0},
4894 etc. The information is properly escaped for use with logging binary
4899 <title><literal>msg</literal></title>
4901 <para><emphasis>Description:</emphasis> Assigns a custom message to the
4902 rule or chain.</para>
4904 <para><emphasis>Action Group:</emphasis> Meta-data</para>
4906 <para>Example:</para>
4908 <programlisting format="linespecific">SecRule &REQUEST_HEADERS:Host "@eq 0" \
4909 "log,id:60008<emphasis>,</emphasis>severity:2,<emphasis>msg:'Request Missing a Host Header'"</emphasis></programlisting>
4911 <para><emphasis>Note</emphasis></para>
4913 <para>The msg information appears in the error and/or audit log files
4914 and is not sent back to the client in response headers.</para>
4918 <title><literal>multiMatch</literal></title>
4920 <para><emphasis>Description:</emphasis> If enabled ModSecurity will
4921 perform multiple operator invocations for every target, before and after
4922 every anti-evasion transformation is performed.</para>
4924 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4926 <para>Example:</para>
4928 <programlisting format="linespecific">SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase
4929 SecRule ARGS "attack" <emphasis>multiMatch</emphasis></programlisting>
4931 <para><emphasis>Note</emphasis></para>
4933 <para>Normally, variables are evaluated once, only after all
4934 transformation functions have completed. With multiMatch, variables are
4935 checked against the operator before and after every transformation
4936 function that changes the input.</para>
4940 <title><literal>noauditlog</literal></title>
4942 <para><emphasis>Description:</emphasis> Indicates that a successful
4943 match of the rule should not be used as criteria whether the transaction
4944 should be logged to the audit log.</para>
4946 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4948 <para>Example:</para>
4950 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "Test" allow,<emphasis>noauditlog</emphasis></programlisting>
4952 <para><emphasis>Note</emphasis></para>
4954 <para>If the SecAuditEngine is set to On, all of the transactions will
4955 be logged. If it is set to RelevantOnly, then you can control it with
4956 the noauditlog action. Even if the noauditlog action is applied to a
4957 specific rule and a rule either before or after triggered an audit
4958 event, then the transaction will be logged to the audit log. The correct
4959 way to disable audit logging for the entire transaction is to use
4960 "<literal moreinfo="none">ctl:auditEngine=Off</literal>"</para>
4964 <title><literal>nolog</literal></title>
4966 <para><emphasis>Description:</emphasis> Prevents rule matches from
4967 appearing in both the error and audit logs.</para>
4969 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
4971 <para>Example:</para>
4973 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "Test" allow,<emphasis>nolog</emphasis></programlisting>
4975 <para><emphasis>Note</emphasis></para>
4977 <para>The nolog action also implies noauditlog.</para>
4981 <title><literal>pass</literal></title>
4983 <para><emphasis>Description:</emphasis> Continues processing with the
4984 next rule in spite of a successful match.</para>
4986 <para><emphasis>Action Group:</emphasis> Disruptive</para>
4988 <para>Example1:</para>
4990 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "Test" log,<emphasis>pass</emphasis></programlisting>
4992 <para>When using <emphasis>pass</emphasis> with SecRule with multiple
4993 targets, <emphasis>all</emphasis> targets will be processed and
4994 <emphasis>all</emphasis> non-disruptive actions will trigger for
4995 <emphasis>every</emphasis> match found. In the second example the
4996 TX:test target would be incremented by 1 for each matching
4999 <para>Example2:</para>
5001 <programlisting format="linespecific">SecRule ARGS "test" log,<emphasis>pass</emphasis>,setvar:TX.test=+1</programlisting>
5003 <para><emphasis>Note</emphasis></para>
5005 <para>The transaction will not be interrupted but a log will be
5006 generated for each matching target (unless logging has been
5011 <title><literal>pause</literal></title>
5013 <para><emphasis>Description:</emphasis> Pauses transaction processing
5014 for the specified number of milliseconds.</para>
5016 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5018 <para>Example:</para>
5020 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "Test" log,deny,status:403,<emphasis>pause:5000</emphasis></programlisting>
5022 <para><emphasis>Note</emphasis></para>
5024 <para>This feature can be of limited benefit for slowing down Brute
5025 Force Scanners, however use with care. If you are under a Denial of
5026 Service type of attack, the pause feature may make matters worse as this
5027 feature will cause child processes to sit idle until the pause is
5032 <title><literal>phase</literal></title>
5034 <para><emphasis>Description:</emphasis> Places the rule (or the rule
5035 chain) into one of five available processing phases.</para>
5037 <para><emphasis>Action Group:</emphasis> Meta-data</para>
5039 <para>Example:</para>
5041 <programlisting format="linespecific">SecDefaultAction log,deny,<emphasis>phase:1</emphasis>,t:removeNulls,t:lowercase
5042 SecRule REQUEST_HEADERS:User-Agent "Test" log,deny,status:403</programlisting>
5044 <para><emphasis>Note</emphasis></para>
5046 <para>Keep in mind that is you specify the incorrect phase, the target
5047 variable that you specify may be empty. This could lead to a false
5048 negative situation where your variable and operator (RegEx) may be
5049 correct, but it misses malicious data because you specified the wrong
5054 <title>prepend</title>
5056 <para><emphasis>Description:</emphasis> Prepends text given as parameter
5057 to the response body. For this action to work content injection must be
5058 enabled by setting <literal>SecContentInjection</literal> to
5059 <literal>On</literal>. Also make sure you check the content type of the
5060 response before you make changes to it (e.g. you don't want to inject
5061 stuff into images).</para>
5063 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5065 <para><emphasis>Processing Phases:</emphasis> 3 and 4.</para>
5067 <para>Example:</para>
5069 <programlisting>SecRule RESPONSE_CONTENT_TYPE ^text/html "phase:3,nolog,pass,<emphasis>prepend:'Header<br>'</emphasis>"</programlisting>
5072 <para>While macro expansion is allowed in the additional content, you
5073 are strongly cautioned against inserting user defined data
5079 <title><literal>proxy</literal></title>
5081 <para><emphasis>Description:</emphasis> Intercepts transaction by
5082 forwarding request to another web server using the proxy backend.</para>
5084 <para><emphasis>Action Group:</emphasis> Disruptive</para>
5086 <para>Example:</para>
5088 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "Test" log,<emphasis>proxy:http://www.honeypothost.com/</emphasis></programlisting>
5090 <para><emphasis>Note</emphasis></para>
5092 <para>For this action to work, mod_proxy must also be installed. This
5093 action is useful if you would like to proxy matching requests onto a
5094 honeypot webserver.</para>
5098 <title><literal>redirect</literal></title>
5100 <para><emphasis>Description:</emphasis> Intercepts transaction by
5101 issuing a redirect to the given location.</para>
5103 <para><emphasis>Action Group:</emphasis> Disruptive</para>
5105 <para>Example:</para>
5107 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "Test" \
5108 log,<emphasis>redirect:http://www.hostname.com/failed.html</emphasis></programlisting>
5110 <para><emphasis>Note</emphasis></para>
5112 <para>If the <literal moreinfo="none">status</literal> action is present
5113 and its value is acceptable (301, 302, 303, or 307) it will be used for
5114 the redirection. Otherwise status code 302 will be used.</para>
5118 <title><literal>rev</literal></title>
5120 <para><emphasis>Description:</emphasis> Specifies rule revision.</para>
5122 <para><emphasis>Action Group:</emphasis> Meta-data</para>
5124 <para>Example:</para>
5126 <programlisting format="linespecific">SecRule REQUEST_METHOD "^PUT$" "id:340002,<emphasis>rev:1</emphasis>,severity:2,msg:'Restricted HTTP function'"</programlisting>
5128 <para><emphasis>Note</emphasis></para>
5130 <para>This action is used in combination with the <literal
5131 moreinfo="none">id</literal> action to allow the same rule ID to be used
5132 after changes take place but to still provide some indication the rule
5137 <title><literal>sanitiseArg</literal></title>
5139 <para><emphasis>Description:</emphasis> Sanitises (replaces each byte
5140 with an asterisk) a named request argument prior to audit
5143 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5145 <para>Example:</para>
5147 <programlisting format="linespecific">SecAction nolog,phase:2,<emphasis>sanitiseArg:password</emphasis></programlisting>
5149 <para><emphasis>Note</emphasis></para>
5151 <para>The sanitize actions do not sanitize any data within the actual
5152 raw requests but only on the copy of data within memory that is set to
5153 log to the audit log. It will not sanitize the data in the
5154 modsec_debug.log file (if the log level is set high enough to capture
5159 <title><literal>sanitiseMatched</literal></title>
5161 <para><emphasis>Description:</emphasis> Sanitises the variable (request
5162 argument, request header, or response header) that caused a rule
5165 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5167 <para>Example: This action can be used to sanitise arbitrary transaction
5168 elements when they match a condition. For example, the example below
5169 will sanitise any argument that contains the word<emphasis>
5170 password</emphasis> in the name.</para>
5172 <programlisting format="linespecific">SecRule ARGS_NAMES password nolog,pass,<emphasis>sanitiseMatched</emphasis></programlisting>
5174 <para><emphasis>Note</emphasis></para>
5176 <para>Same note as sanitiseArg.</para>
5180 <title><literal>sanitiseRequestHeader</literal></title>
5182 <para><emphasis>Description:</emphasis> Sanitises a named request
5185 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5187 <para>Example: This will sanitise the data in the Authorization
5190 <programlisting format="linespecific">SecAction log,phase:1,<emphasis>sanitiseRequestHeader:Authorization</emphasis></programlisting>
5192 <para><emphasis>Note</emphasis></para>
5194 <para>Same note as sanitiseArg.</para>
5198 <title><literal>sanitiseResponseHeader</literal></title>
5200 <para><emphasis>Description:</emphasis> Sanitises a named response
5203 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5205 <para>Example: This will sanitise the Set-Cookie data sent to the
5208 <programlisting format="linespecific">SecAction log,phase:3,<emphasis>sanitiseResponseHeader:Set-Cookie</emphasis></programlisting>
5210 <para><emphasis>Note</emphasis></para>
5212 <para>Same note as sanitiseArg.</para>
5216 <title><literal>severity</literal></title>
5218 <para><emphasis>Description:</emphasis> Assigns severity to the rule it
5219 is placed with.</para>
5221 <para><emphasis>Action Group:</emphasis> Meta-data</para>
5223 <para>Example:</para>
5225 <programlisting format="linespecific">SecRule REQUEST_METHOD "^PUT$" "id:340002,rev:1,<emphasis>severity:CRITICAL</emphasis>,msg:'Restricted HTTP function'"</programlisting>
5227 <para><emphasis>Note</emphasis></para>
5229 <para>Severity values in ModSecurity follow those of syslog, as
5234 <para>0 - EMERGENCY</para>
5238 <para>1 - ALERT</para>
5242 <para>2 - CRITICAL</para>
5246 <para>3 - ERROR</para>
5250 <para>4 - WARNING</para>
5254 <para>5 - NOTICE</para>
5258 <para>6 - INFO</para>
5262 <para>7 - DEBUG</para>
5266 <para>It is possible to specify severity levels using either the
5267 numerical values or the text values. You should always specify severity
5268 levels using the text values. The use of the numerical values is
5269 deprecated (as of v2.5.0) and may be removed in one of the susequent
5270 major updates.</para>
5274 <title><literal>setuid</literal></title>
5276 <para><emphasis>Description:</emphasis> Special-purpose action that
5277 initialises the <literal moreinfo="none">USER</literal>
5280 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5282 <para>Example:</para>
5284 <programlisting format="linespecific">SecAction <emphasis>setuid:%{REMOTE_USER}</emphasis>,nolog</programlisting>
5286 <para><emphasis>Note</emphasis></para>
5288 <para>After initialisation takes place the variable <literal
5289 moreinfo="none">USERID</literal> will be available for use in the
5290 subsequent rules.</para>
5294 <title><literal>setsid</literal></title>
5296 <para><emphasis>Description:</emphasis> Special-purpose action that
5297 initialises the <literal moreinfo="none">SESSION</literal>
5300 <para><emphasis>Action Group: </emphasis>Non-disruptive</para>
5302 <para>Example:</para>
5304 <programlisting format="linespecific"># Initialise session variables using the session cookie value
5305 SecRule REQUEST_COOKIES:PHPSESSID !^$ chain,nolog,pass
5306 SecAction <emphasis>setsid:%{REQUEST_COOKIES.PHPSESSID}</emphasis></programlisting>
5308 <para><emphasis>Note</emphasis></para>
5310 <para>On first invocation of this action the collection will be empty
5311 (not taking the predefined variables into account - see <literal
5312 moreinfo="none">initcol</literal> for more information). On subsequent
5313 invocations the contents of the collection (session, in this case) will
5314 be retrieved from storage. After initialisation takes place the
5315 variable<literal moreinfo="none"> SESSIONID</literal> will be available
5316 for use in the subsequent rules.This action understands each application
5317 maintains its own set of sessions. It will utilise the current web
5318 application ID to create a session namespace.</para>
5322 <title><literal>setenv</literal></title>
5324 <para><emphasis>Description:</emphasis> Creates, removes, or updates an
5325 environment variable.</para>
5327 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5329 <para>Examples:</para>
5331 <para>To create a new variable (if you omit the value <literal
5332 moreinfo="none">1</literal> will be used):</para>
5334 <programlisting format="linespecific">setenv:name=value</programlisting>
5336 <para>To remove a variable:</para>
5338 <programlisting format="linespecific">setenv:!name</programlisting>
5340 <para><emphasis>Note</emphasis></para>
5342 <para>This action can be used to establish communication with other
5343 Apache modules.</para>
5347 <title><literal>setvar</literal></title>
5349 <para><emphasis>Description:</emphasis> Creates, removes, or updates a
5350 variable in the specified collection.</para>
5352 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5354 <para>Examples:</para>
5356 <para>To create a new variable:</para>
5358 <programlisting format="linespecific">setvar:tx.score=10</programlisting>
5360 <para>To remove a variable prefix the name with exclamation mark:</para>
5362 <programlisting format="linespecific">setvar:!tx.score</programlisting>
5364 <para>To increase or decrease variable value use <literal
5365 moreinfo="none">+</literal> and <literal moreinfo="none">-</literal>
5366 characters in front of a numerical value:</para>
5368 <programlisting format="linespecific">setvar:tx.score=+5</programlisting>
5372 <title><literal>skip</literal></title>
5374 <para><emphasis>Description:</emphasis> Skips one or more rules (or
5375 chains) on successful match.</para>
5377 <para><emphasis>Action Group:</emphasis> Flow</para>
5379 <para>Example:</para>
5381 <para><programlisting format="linespecific">SecRule REQUEST_URI "^/$" \
5382 "phase:2,chain,t:none<emphasis>,skip:2</emphasis>"
5383 SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
5384 SecRule REQUEST_HEADERS:User-Agent "^Apache \(internal dummy connection\)$" "t:none"
5385 SecRule &REQUEST_HEADERS:Host "@eq 0" \
5386 "deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'"
5387 SecRule &REQUEST_HEADERS:Accept "@eq 0" \
5388 "log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'"</programlisting></para>
5390 <para><emphasis>Note</emphasis></para>
5392 <para>Skip only applies to the current processing phase and not
5393 necessarily the order in which the rules appear in the configuration
5394 file. If you group rules by processing phases, then skip should work as
5395 expected. This action can not be used to skip rules within one chain.
5396 Accepts a single parameter denoting the number of rules (or chains) to
5401 <title><literal>skipAfter</literal></title>
5403 <para><emphasis>Description:</emphasis> Skips rules (or chains) on
5404 successful match resuming rule execution after the specified rule ID or
5405 marker (see <literal>SecMarker</literal>) is found.</para>
5407 <para><emphasis>Action Group:</emphasis> Flow</para>
5409 <para>Example:</para>
5411 <para><programlisting format="linespecific">SecRule REQUEST_URI "^/$" "chain,t:none,<emphasis>skipAfter:960015</emphasis>"
5412 SecRule REMOTE_ADDR "^127\.0\.0\.1$" "chain"
5413 SecRule REQUEST_HEADERS:User-Agent "^Apache \(internal dummy connection\)$" "t:none"
5414 SecRule &REQUEST_HEADERS:Host "@eq 0" \
5415 "deny,log,status:400,id:960008,severity:4,msg:'Request Missing a Host Header'"
5416 SecRule &REQUEST_HEADERS:Accept "@eq 0" \
5417 "log,deny,log,status:400,id:960015,msg:'Request Missing an Accept Header'"</programlisting></para>
5419 <para><emphasis>Note</emphasis></para>
5421 <para><literal>SkipAfter</literal> only applies to the current
5422 processing phase and not necessarily the order in which the rules appear
5423 in the configuration file. If you group rules by processing phases, then
5424 skip should work as expected. This action can not be used to skip rules
5425 within one chain. Accepts a single parameter denoting the last rule ID
5430 <title><literal>status</literal></title>
5432 <para><emphasis>Description:</emphasis> Specifies the response status
5433 code to use with actions<literal moreinfo="none"> deny</literal>
5434 and<literal moreinfo="none"> redirect</literal>.</para>
5436 <para><emphasis>Action Group:</emphasis> Data</para>
5438 <para>Example:</para>
5440 <programlisting format="linespecific">SecDefaultAction log,deny,<emphasis>status:403</emphasis>,phase:1</programlisting>
5442 <para><emphasis>Note</emphasis></para>
5444 <para>Status actions defined in Apache scope locations (such as
5445 Directory, Location, etc...) may be superseded by phase:1 action
5446 settings. The Apache ErrorDocument directive will be triggered if
5447 present in the configuration. Therefore if you have previously defined a
5448 custom error page for a given status then it will be executed and its
5449 output presented to the user.</para>
5453 <title><literal>t</literal></title>
5455 <para><emphasis>Description:</emphasis> This action can be used which
5456 transformation function should be used against the specified variables
5457 before they (or the results, rather) are run against the operator
5458 specified in the rule.</para>
5460 <para><emphasis>Action Group:</emphasis> Non-disruptive</para>
5462 <para>Example:</para>
5464 <programlisting format="linespecific">SecDefaultAction log,deny,phase:1,t:removeNulls,t:lowercase
5465 SecRule REQUEST_COOKIES:SESSIONID "47414e81cbbef3cf8366e84eeacba091" \
5466 log,deny,status:403,<emphasis>t:md5,t:hexEncode</emphasis></programlisting>
5468 <para><emphasis>Note</emphasis></para>
5470 <para>Any transformation functions that you specify in a SecRule will be
5471 in addition to previous ones specified in SecDefaultAction. Use of
5472 "t:none" will remove all transformation functions for the specified
5477 <title><literal>tag</literal></title>
5479 <para><emphasis>Description:</emphasis> Assigns custom text to a rule or
5482 <para><emphasis>Action Group:</emphasis> Meta-data</para>
5484 <para>Example:</para>
5486 <programlisting format="linespecific">SecRule REQUEST_FILENAME "\b(?:n(?:map|et|c)|w(?:guest|sh)|cmd(?:32)?|telnet|rcmd|ftp)\.exe\b" \
5487 "t:none,t:lowercase,deny,msg:'System Command Access',id:'950002',<emphasis>\
5488 tag:'WEB_ATTACK/FILE_INJECTION',tag:'OWASP/A2'</emphasis>,severity:'2'"</programlisting>
5490 <para><emphasis>Note</emphasis></para>
5492 <para>The tag information appears in the error and/or audit log files.
5493 Its intent is to be used to automate classification of rules and the
5494 alerts generated by rules. Multiple tags can be used per
5499 <title><literal>xmlns</literal></title>
5501 <para><emphasis>Description:</emphasis> This action should be used
5502 together with an XPath expression to register a namespace.</para>
5504 <para><emphasis>Action Group:</emphasis> Data</para>
5506 <para>Example:</para>
5508 <programlisting format="linespecific">SecRule REQUEST_HEADERS:Content-Type "text/xml" \
5509 "phase:1,pass,ctl:requestBodyProcessor=XML,ctl:requestBodyAccess=On,<emphasis> \
5510 xmlns:xsd="http://www.w3.org/2001/XMLSchema"</emphasis>
5511 SecRule XML:/soap:Envelope/soap:Body/q1:getInput/id() "123" phase:2,deny</programlisting>
5515 <section id="operators">
5516 <title>Operators</title>
5518 <para>A number of operators can be used in rules, as documented below. The
5519 operator syntax uses the <literal>@</literal> symbol followed by the
5520 specific operator name.</para>
5523 <title><literal>beginsWith</literal></title>
5525 <para><emphasis>Description:</emphasis> This operator is a string
5526 comparison and returns true if the parameter value is found at the
5527 beginning of the input. Macro expansion is performed so you may use
5528 variable names such as <literal>%{TX.1}</literal>, etc.</para>
5530 <para>Example:</para>
5532 <programlisting format="linespecific">SecRule REQUEST_LINE "!<emphasis>@beginsWith GET</emphasis>" t:none,deny,status:403
5533 SecRule REQUEST_ADDR "^(.*)\.\d+$" deny,status:403,capture,chain
5534 SecRule ARGS:gw "!<emphasis>@beginsWith %{TX.1}</emphasis>"</programlisting>
5538 <title><literal>contains</literal></title>
5540 <para><emphasis>Description:</emphasis> This operator is a string
5541 comparison and returns true if the parameter value is found anywhere in
5542 the input. Macro expansion is performed so you may use variable names
5543 such as %{TX.1}, etc.</para>
5545 <para>Example:</para>
5547 <programlisting format="linespecific">SecRule REQUEST_LINE "!<emphasis>@contains .php</emphasis>" t:none,deny,status:403
5548 SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain
5549 SecRule ARGS:ip "!<emphasis>@contains %{TX.1}</emphasis>"</programlisting>
5553 <title><literal>endsWith</literal></title>
5555 <para><emphasis>Description:</emphasis> This operator is a string
5556 comparison and returns true if the parameter value is found at the end
5557 of the input. Macro expansion is performed so you may use variable names
5558 such as %{TX.1}, etc.</para>
5560 <para>Example:</para>
5562 <programlisting format="linespecific">SecRule REQUEST_LINE "!<emphasis>@endsWith HTTP/1.1</emphasis>" t:none,deny,status:403
5563 SecRule ARGS:route "!<emphasis>@endsWith %{REQUEST_ADDR}</emphasis>" t:none,deny,status:403</programlisting>
5567 <title><literal>eq</literal></title>
5569 <para><emphasis>Description:</emphasis> This operator is a numerical
5570 comparison and stands for "equal to."</para>
5572 <para>Example:</para>
5574 <programlisting format="linespecific">SecRule &REQUEST_HEADERS_NAMES "<emphasis>@eq</emphasis> 15"</programlisting>
5578 <title><literal>ge</literal></title>
5580 <para><emphasis>Description:</emphasis> This operator is a numerical
5581 comparison and stands for "greater than or equal to."</para>
5583 <para>Example:</para>
5585 <programlisting format="linespecific">SecRule &REQUEST_HEADERS_NAMES "<emphasis>@ge</emphasis> 15"</programlisting>
5589 <title><literal>geoLookup</literal></title>
5591 <para><emphasis>Description:</emphasis> This operator looks up various
5592 data fields from an IP address or hostname in the target data. The
5593 results will be captured in the <literal moreinfo="none">GEO</literal>
5596 <para>You must provide a database via <literal
5597 moreinfo="none">SecGeoLookupDb</literal> before this operator can be
5601 <para>This operator matches and the action is executed on a <emphasis>
5602 successful</emphasis> lookup. For this reason, you probably want to
5603 use the <emphasis>pass,nolog</emphasis> actions. This allows for
5604 <literal moreinfo="none">setvar</literal> and other non-disruptive
5605 actions to be executed on a match. If you wish to block on a failed
5606 lookup, then do something like this (look for an empty GEO
5609 <programlisting format="linespecific">SecGeoLookupDb /usr/local/geo/data/GeoLiteCity.dat
5611 SecRule REMOTE_ADDR "@geoLookup" "pass,nolog"
5612 SecRule &GEO "@eq 0" "deny,status:403,msg:'Failed to lookup IP'"</programlisting>
5615 <para>See the <literal moreinfo="none">GEO</literal> variable for an
5616 example and more information on various fields available.</para>
5620 <title><literal>gt</literal></title>
5622 <para><emphasis>Description:</emphasis> This operator is a numerical
5623 comparison and stands for "greater than."</para>
5625 <para>Example:</para>
5627 <programlisting format="linespecific">SecRule &REQUEST_HEADERS_NAMES "<emphasis>@gt</emphasis> 15"</programlisting>
5631 <title><literal>inspectFile</literal></title>
5633 <para><emphasis>Description:</emphasis> Executes the external
5634 script/binary given as parameter to the operator against every file
5635 extracted from the request. As of v2.5.0, if the supplied filename is
5636 not absolute it is treated as relative to the directory in which the
5637 configuration file resides. Also as of v2.5.0, if the filename is
5638 determined to be a Lua script (based on its extension) the script will
5639 be processed by the internal engine. As such it will have full access to
5640 the ModSecurity context.</para>
5642 <para>Example of using an external binary/script:</para>
5644 <programlisting format="linespecific"># Execute external script to validate uploaded files.
5645 SecRule FILES_TMPNAMES "<emphasis>@inspectFile</emphasis> /opt/apache/bin/inspect_script.pl"</programlisting>
5647 <para>Example of using Lua script:</para>
5649 <programlisting>SecRule FILES_TMPNANMES "@inspectFile <emphasis>inspect.lua</emphasis>"</programlisting>
5651 <para>Script <filename>inspect.lua</filename>:</para>
5653 <programlisting>function main(filename)
5654 -- Do something to the file to verify it. In this example, we
5655 -- read up to 10 characters from the beginning of the file.
5656 local f = io.open(filename, "rb");
5657 local d = f:read(10);
5660 -- Return null if there is no reason to believe there is ansything
5661 -- wrong with the file (no match). Returning any text will be taken
5662 -- to mean a match should be trigerred.
5664 end</programlisting>
5668 <title><literal>le</literal></title>
5670 <para><emphasis>Description:</emphasis> This operator is a numerical
5671 comparison and stands for "less than or equal to."</para>
5673 <para>Example:</para>
5675 <programlisting format="linespecific">SecRule &REQUEST_HEADERS_NAMES "<emphasis>@le</emphasis> 15"</programlisting>
5679 <title><literal>lt</literal></title>
5681 <para><emphasis>Description:</emphasis> This operator is a numerical
5682 comparison and stands for "less than."</para>
5684 <para>Example:</para>
5686 <programlisting format="linespecific">SecRule &REQUEST_HEADERS_NAMES "<emphasis>@lt</emphasis> 15"</programlisting>
5690 <title><literal>pm</literal></title>
5692 <para><emphasis>Description:</emphasis> Phrase Match operator. This
5693 operator uses a set based matching engine (Aho-Corasick) for faster
5694 matches of keyword lists. It will match any one of its arguments
5695 anywhere in the target value. The match is case insensitive.</para>
5697 <para>Example:</para>
5699 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "<emphasis>@pm</emphasis> WebZIP WebCopier Webster WebStripper SiteSnagger ProWebWalker CheeseBot" "deny,status:403</programlisting>
5701 <para>The above would deny access with 403 if any of the words matched
5702 within the User-Agent HTTP header value.</para>
5706 <title><literal>pmFromFile</literal></title>
5708 <para><emphasis>Description:</emphasis> Phrase Match operator. This
5709 operator uses a set based matching engine (Aho-Corasick) for faster
5710 matches of keyword lists. This operator is the same as
5711 <literal>@pm</literal> except that it takes a list of files as
5712 arguments. It will match any one of the phrases listed in the file(s)
5713 anywhere in the target value.</para>
5717 <orderedlist continuation="restarts" inheritnum="ignore">
5719 <para>The contents of the files should be one phrase per line. End
5720 of line markers will be stripped from the phrases, however,
5721 whitespace will not be trimmed from phrases in the file. Empty lines
5722 and comment lines (beginning with a '#') are ignored.</para>
5726 <para>To allow easier inclusion of phrase files with rulesets,
5727 relative paths may be used to the phrase files. In this case, the
5728 path of the file containing the rule is prepended to the phrase file
5733 <para>Example:</para>
5735 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "<emphasis>@pm</emphasis> /path/to/blacklist1 blacklist2" "deny,status:403</programlisting>
5737 <para>The above would deny access with 403 if any of the patterns in the
5738 two files matched within the User-Agent HTTP header value. The
5739 <literal>blacklist2</literal> file would need to be placed in the same
5740 path as the file containing the rule.</para>
5744 <title><literal>rbl</literal></title>
5746 <para><emphasis>Description:</emphasis> Look up the parameter in the RBL
5747 given as parameter. Parameter can be an IPv4 address, or a
5750 <para>Example:</para>
5752 <programlisting format="linespecific">SecRule REMOTE_ADDR "<emphasis>@rbl</emphasis> sc.surbl.org"</programlisting>
5756 <title><literal>rx</literal></title>
5758 <para><emphasis>Description:</emphasis> Regular expression operator.
5759 This is the default operator, so if the "@" operator is not defined, it
5760 is assumed to be rx.</para>
5762 <para>Example:</para>
5764 <programlisting format="linespecific">SecRule REQUEST_HEADERS:User-Agent "<emphasis>@rx</emphasis> nikto"</programlisting>
5766 <para><emphasis>Note</emphasis></para>
5768 <para>Regular expressions are handled by the PCRE library (<ulink
5769 url="http://www.pcre.org">http://www.pcre.org</ulink>). ModSecurity
5770 compiles its regular expressions with the following settings:</para>
5772 <orderedlist continuation="restarts" inheritnum="ignore">
5774 <para>The entire input is treated as a single line, even when there
5775 are newline characters present.</para>
5779 <para>All matches are case-sensitive. If you do not care about case
5780 sensitivity you either need to implement the <literal
5781 moreinfo="none">lowercase</literal> transformation function, or use
5782 the per-pattern<literal moreinfo="none">(?i)</literal>modifier, as
5783 allowed by PCRE.</para>
5787 <para>The <literal moreinfo="none">PCRE_DOTALL</literal> and
5788 <literal moreinfo="none">PCRE_DOLLAR_ENDONLY</literal> flags are set
5789 during compilation, meaning a single dot will match any character,
5790 including the newlines and a <literal moreinfo="none">$</literal>
5791 end anchor will not match a trailing newline character.</para>
5797 <title><literal>streq</literal></title>
5799 <para><emphasis>Description:</emphasis> This operator is a string
5800 comparison and returns true if the parameter value matches the input
5801 exactly. Macro expansion is performed so you may use variable names such
5802 as %{TX.1}, etc.</para>
5804 <para>Example:</para>
5806 <programlisting format="linespecific">SecRule ARGS:foo "!<emphasis>@streq bar</emphasis>" t:none,deny,status:403
5807 SecRule REQUEST_ADDR "^(.*)$" deny,status:403,capture,chain
5808 SecRule REQUEST_HEADERS:Ip-Address "!<emphasis>@streq %{TX.1}</emphasis>"</programlisting>
5812 <title><literal>validateByteRange</literal></title>
5814 <para><emphasis>Description:</emphasis> Validates the byte range used in
5815 the variable falls into the specified range.</para>
5817 <para>Example:</para>
5819 <programlisting format="linespecific">SecRule ARGS:text "<emphasis>@validateByteRange</emphasis> 10, 13, 32-126"</programlisting>
5821 <para><emphasis>Note</emphasis></para>
5823 <para>You can force requests to consist only of bytes from a certain
5824 byte range. This can be useful to avoid stack overflow attacks (since
5825 they usually contain "random" binary content). Default range values are
5826 0 and 255, i.e. all byte values are allowed. This directive does not
5827 check byte range in a POST payload when
5828 <literal>multipart/form-data</literal> encoding (file upload) is used.
5829 Doing so would prevent binary files from being uploaded. However, after
5830 the parameters are extracted from such request they are checked for a
5833 <para>validateByteRange is similar to the ModSecurity 1.X
5834 SecFilterForceByteRange Directive however since it works in a rule
5835 context, it has the following differences:</para>
5839 <para>You can specify a different range for different
5844 <para>It has an "event" context (id, msg....)</para>
5848 <para>It is executed in the flow of rules rather than being a built
5849 in pre-check.</para>
5855 <title><literal>validateDTD</literal></title>
5857 <para><emphasis>Description:</emphasis> Validates the DOM tree generated
5858 by the XML request body processor against the supplied DTD.</para>
5860 <para>Example:</para>
5862 <programlisting format="linespecific">SecDefaultAction log,deny,status:403,phase:2
5863 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
5864 phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML
5865 SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345
5866 SecRule XML "<emphasis>@validateDTD /path/to/apache2/conf/xml.dtd</emphasis>" "deny,id:12345"</programlisting>
5869 <para>This operator requires request body to be processed as
5875 <title><literal>validateSchema</literal></title>
5877 <para><emphasis>Description:</emphasis> Validates the DOM tree generated
5878 by the XML request body processor against the supplied XML
5881 <para>Example:</para>
5883 <programlisting format="linespecific">SecDefaultAction log,deny,status:403,phase:2
5884 SecRule REQUEST_HEADERS:Content-Type ^text/xml$ \
5885 phase:1,t:lowercase,nolog,pass,ctl:requestBodyProcessor=XML
5886 SecRule REQBODY_PROCESSOR "!^XML$" nolog,pass,skipAfter:12345
5887 SecRule XML "<emphasis>@validateSchema /path/to/apache2/conf/xml.xsd</emphasis>" "deny,id:12345"</programlisting>
5890 <para>This operator requires request body to be processed as
5896 <title><literal>validateUrlEncoding</literal></title>
5898 <para><emphasis>Description:</emphasis> Verifies the encodings used in
5899 the variable (if any) are valid.</para>
5901 <para>Example:</para>
5903 <programlisting format="linespecific">SecRule ARGS "<emphasis>@validateUrlEncoding</emphasis>"</programlisting>
5905 <para><emphasis>Note</emphasis></para>
5907 <para>URL encoding is an HTTP standard for encoding byte values within a
5908 URL. The byte is escaped with a % followed by two hexadecimal values
5909 (0-F). This directive does not check encoding in a POST payload when the
5910 <literal>multipart/form-data</literal> encoding (file upload) is used.
5911 It is not necessary to do so because URL encoding is not used for this
5916 <title><literal>validateUtf8Encoding</literal></title>
5918 <para><emphasis>Description:</emphasis> Verifies the variable is a valid
5919 UTF-8 encoded string.</para>
5921 <para>Example:</para>
5923 <programlisting format="linespecific">SecRule ARGS "<emphasis>@validateUtf8Encoding</emphasis>"</programlisting>
5925 <para><emphasis>Note</emphasis></para>
5927 <para>UTF-8 encoding is valid on most web servers. Integer values
5928 between 0-65535 are encoded in a UTF-8 byte sequence that is escaped by
5929 percents. The short form is two bytes in length.</para>
5931 <para>check for three types of errors:</para>
5935 <para>Not enough bytes. UTF-8 supports two, three, four, five, and
5936 six byte encodings. ModSecurity will locate cases when a byte or
5937 more is missing.</para>
5941 <para>Invalid encoding. The two most significant bits in most
5942 characters are supposed to be fixed to 0x80. Attackers can use this
5943 to subvert Unicode decoders.</para>
5947 <para>Overlong characters. ASCII characters are mapped directly into
5948 the Unicode space and are thus represented with a single byte.
5949 However, most ASCII characters can also be encoded with two, three,
5950 four, five, and six characters thus tricking the decoder into
5951 thinking that the character is something else (and, presumably,
5952 avoiding the security check).</para>
5958 <title><literal>verifyCC</literal></title>
5960 <para><emphasis>Description:</emphasis> This operator verifies a given
5961 regular expression as a potential credit card number. It first matches
5962 with a single generic regular expression then runs the resulting match
5963 through a Luhn checksum algorithm to further verify it as a potential
5964 credit card number.</para>
5966 <para>Example:</para>
5968 <programlisting format="linespecific">SecRule ARGS "<emphasis>@verifyCC \d{13,16}</emphasis>" \
5969 "phase:2,sanitiseMatched,log,auditlog,pass,msg:'Potential credit card number'"</programlisting>
5973 <title><literal>within</literal></title>
5975 <para><emphasis>Description:</emphasis> This operator is a string
5976 comparison and returns true if the input value is found anywhere within
5977 the parameter value. Note that this is similar to
5978 <literal>@contains</literal>, except that the target and match values
5979 are reversed. Macro expansion is performed so you may use variable names
5980 such as %{TX.1}, etc.</para>
5982 <para>Example:</para>
5984 <programlisting format="linespecific">SecRule REQUEST_METHOD "!<emphasis>@within get,post,head</emphasis>" t:lowercase,deny,status:403
5986 SecAction "pass,setvar:'tx.allowed_methods=get,post,head'"
5987 SecRule REQUEST_METHOD "!<emphasis>@within %{tx.allowed_methods}</emphasis>" t:lowercase,deny,status:403</programlisting>
5992 <title>Macro Expansion</title>
5994 <para>Macros allow for using place holders in rules that will be expanded
5995 out to their values at runtime. Currently only variable expansion is
5996 supported, however more options may be added in future versions of
5999 <para>Format:</para>
6001 <programlisting format="linespecific">%{VARIABLE}
6002 %{COLLECTION.VARIABLE}</programlisting>
6004 <para>Macro expansion can be used in actions such as initcol, setsid,
6005 setuid, setvar, setenv, logdata. Operators that are evaluated at runtime
6006 support expansion and are noted above. Such operators include @beginsWith,
6007 @endsWith, @contains, @within and @streq. You cannot use macro expansion
6008 for operators that are "compiled" such as @pm, @rx, etc. as these
6009 operators have their values fixed at configure time for efficiency.</para>
6011 <para>Some values you may want to expand include: TX, REMOTE_ADDR, USERID,
6012 HIGHEST_SEVERITY, MATCHED_VAR, MATCHED_VAR_NAME, MULTIPART_STRICT_ERROR,
6013 RULE, SESSION, USERID, among others.</para>
6017 <title>Persistant Storage</title>
6019 <para>At this time it is only possible to have three collections in which
6020 data is stored persistantly (i.e. data available to multiple requests).
6021 These are: <literal moreinfo="none">IP</literal>, <literal
6022 moreinfo="none"> SESSION</literal> and <literal
6023 moreinfo="none">USER</literal>.</para>
6025 <para>Every collection contains several built-in variables that are
6026 available and are read-only unless otherwise specified:</para>
6028 <orderedlist continuation="restarts" inheritnum="ignore">
6030 <para><literal moreinfo="none">CREATE_TIME</literal> - date/time of
6031 the creation of the collection.</para>
6035 <para><literal moreinfo="none">IS_NEW</literal> - set to 1 if the
6036 collection is new (not yet persisted) otherwise set to 0.</para>
6040 <para><literal moreinfo="none">KEY</literal> - the value of the
6041 initcol variable (the client's IP address in the example).</para>
6045 <para><literal moreinfo="none">LAST_UPDATE_TIME</literal> - date/time
6046 of the last update to the collection.</para>
6050 <para><literal moreinfo="none">TIMEOUT</literal> - date/time in
6051 seconds when the collection will be updated on disk from memory (if no
6052 other updates occur). This variable may be set if you wish to specifiy
6053 an explicit expiration time (default is 3600 seconds).</para>
6057 <para><literal moreinfo="none">UPDATE_COUNTER</literal> - how many
6058 times the collection has been updated since creation.</para>
6062 <para><literal moreinfo="none">UPDATE_RATE</literal> - is the average
6063 rate updates per minute since creation.</para>
6067 <para>To create a collection to hold session variables (<literal
6068 moreinfo="none">SESSION</literal>) use action <literal
6069 moreinfo="none">setsid</literal>. To create a collection to hold user
6070 variables (<literal moreinfo="none">USER</literal>) use action <literal
6071 moreinfo="none">setuid</literal>. To create a collection to hold client
6072 address variables (<literal moreinfo="none">IP</literal>) use action
6073 <literal moreinfo="none">initcol</literal>.</para>
6076 <para>ModSecurity implements atomic updates of persistent variables only
6077 for integer variables (counters) at this time. Variables are read from
6078 storage whenever <literal>initcol</literal> is encountered in the rules
6079 and persisted at the end of request processing. Counters are adjusted by
6080 applying a delta generated by re-reading the persisted data just before
6081 being persisted. This keeps counter data consistent even if the counter
6082 was modified and persisted by another thread/process during the
6087 <para>ModSecurity uses a Berkley Database (SDBM) for persistant storage.
6088 This type of database is generally limited to storing a maximum of 1008
6089 bytes per key. This may be a limitation if you are attempting to store a
6090 considerable amount of data in variables for a single key. Some of this
6091 limitation is planned to be reduced in a future version of
6097 <title>Miscellaneous Topics</title>
6102 <title>Impedance Mismatch</title>
6104 <para>Web application firewalls have a difficult job trying to make
6105 sense of data that passes by, without any knowledge of the application
6106 and its business logic. The protection they provide comes from having an
6107 independent layer of security on the outside. Because data validation is
6108 done twice, security can be increased without having to touch the
6109 application. In some cases, however, the fact that everything is done
6110 twice brings problems. Problems can arise in the areas where the
6111 communication protocols are not well specified, or where either the
6112 device or the application do things that are not in the specification.
6113 In such cases it may be possible to design payload that will be
6114 interpreted in one way by one device and in another by the other device.
6115 This problem is better known as Impedance Mismatch. It can be exploited
6116 to evade the security devices.</para>
6118 <para>While we will continue to enhance ModSecurity to deal with various
6119 evasion techniques the problem can only be minimized, but never solved.
6120 With so many different application backend chances are some will always
6121 do something completely unexpected. The only solution is to be aware of
6122 the technologies in the backend when writing rules, adapting the rules
6123 to remove the mismatch. See the next section for some examples.</para>
6126 <title>PHP Peculiarities for ModSecurity Users</title>
6128 <para>When writing rules to protect PHP applications you need to pay
6129 attention to the following facts:</para>
6133 <para>When "register_globals" is set to "On" request parameters
6134 are automatically converted to script variables. In some PHP
6135 versions it is even possible to override the $GLOBALS
6140 <para>Whitespace at the beginning of parameter names is ignored.
6141 (This is very dangerous if you are writing rules to target
6142 specific named variables.)</para>
6146 <para>The remaining whitespace (in parameter names) is converted
6147 to underscores. The same applies to dots and to a "[" if the
6148 variable name does not contain a matching closing bracket.
6149 (Meaning that if you want to exploit a script through a variable
6150 that contains an underscore in the name you can send a parameter
6151 with a whitespace or a dot instead.)</para>
6155 <para>Cookies can be treated as request parameters.</para>
6159 <para>The discussion about variable names applies equally to the
6160 cookie names.</para>
6164 <para>The order in which parameters are taken from the request and
6165 the environment is EGPCS (environment, GET, POST, Cookies,
6166 built-in variables). This means that a POST parameter will
6167 overwrite the parameters transported on the request line (in
6168 QUERY_STRING).</para>
6172 <para>When "magic_quotes_gpc" is set to "On" PHP will use
6173 backslash to escape the following characters: single quote, double
6174 quote, backslash, and the nul byte.</para>
6178 <para>If "magic_quotes_sybase" is set to "On" only the single
6179 quote will be escaped using another single quote. In this case the
6180 "magic_quotes_gpc" setting becomes irrelevant. The
6181 "magic_quotes_sybase" setting completely overrides the
6182 "magic_quotes_gpc" behaviour but "magic_quotes_gpc" still must be
6183 set to "On" for the Sybase-specific quoting to be work.</para>
6187 <para>PHP will also automatically create nested arrays for you.
6188 For example "p[x][y]=1" results in a total of three