doc/html-multipage/processing-phases.html

   1 <html><head><META http-equiv="Content-Type" content="text/html; charset=ISO-8859-1"><title>Processing Phases</title><link href="modsecurity-reference.css" rel="stylesheet" type="text/css"><meta content="DocBook XSL Stylesheets V1.69.1" name="generator"><link rel="start" href="index.html" title="ModSecurity&reg; Reference
   2   Manual"><link rel="up" href="index.html" title="ModSecurity&reg; Reference
   3   Manual"><link rel="prev" href="configuration-directives.html" title="Configuration Directives"><link rel="next" href="variables.html" title="Variables"></head><body bgcolor="white" text="black" link="#0000FF" vlink="#840084" alink="#0000FF"><div style="background:#F5F5F5;width:100%;border-top:1px solid #DDDDDD;border-bottom:1px solid #DDDDDD"><table width="100%" cellspacing="0" cellpadding="0"><tr><td><a href="http://www.modsecurity.org"><img style="margin:4px" src="modsecurity.gif" width="120" height="36" alt="ModSecurity" border="0"></a></td><td align="right"><a href="http://www.breach.com"><img style="margin:6px" src="breach-logo-small.gif" height="36" width="100" border="0"></a></td></tr></table></div><div id="navheader"><table summary="Navigation header" width="100%"><tr><th align="center" colspan="3">Processing Phases</th></tr><tr><td align="left" width="20%"><a accesskey="p" href="configuration-directives.html">Prev</a>&nbsp;</td><td align="center" width="60%">&nbsp;<a accesskey="h" href="index.html">Home</a></td><td align="right" width="20%">&nbsp;<a accesskey="n" href="variables.html">Next</a></td></tr></table><hr size="1"></div><div class="section" lang="en"><div class="titlepage"><div><div><h2 class="title" style="clear: both"><a name="processing-phases"></a>Processing Phases</h2></div></div><div></div></div><p>ModSecurity 2.x allows rules to be placed in one of the following
   4     five phases:</p><div class="orderedlist"><ol type="1"><li><p>Request headers (<code class="literal">REQUEST_HEADERS</code>)</p></li><li><p>Request body (<code class="literal">REQUEST_BODY</code>)</p></li><li><p>Response headers (<code class="literal">RESPONSE_HEADERS</code>)</p></li><li><p>Response body (<code class="literal">RESPONSE_BODY</code>)</p></li><li><p>Logging (<code class="literal">LOGGING</code>)</p></li></ol></div><p>Below is a diagram of the standard Apache Request Cycle. In the
   5     diagram, the 5 ModSecurity processing phases are shown.</p><p><div><img src="apache_request_cycle-modsecurity.jpg" width="495"></div></p><p>In order to select the phase a rule executes during, use the phase
   6     action either directly in the rule or in using the
   7     <code class="literal">SecDefaultAction</code> directive:</p><pre class="programlisting">SecDefaultAction "log,pass,<span class="emphasis"><em>phase:2</em></span>"
   8 SecRule REQUEST_HEADERS:Host "!^$" "deny,<span class="emphasis"><em>phase:1</em></span>"</pre><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>Keep in mind that rules are executed according to phases, so even
   9       if two rules are adjacent in a configuration file, but are set to
  10       execute in different phases, they would not happen one after the other.
  11       The order of rules in the configuration file is important only within
  12       the rules of each phase. This is especially important when using the
  13       <code class="literal">skip</code> and <code class="literal">skipAfter</code> actions.</p></div><div class="note" style="margin-left: 0.5in; margin-right: 0.5in;"><h3 class="title">Note</h3><p>The <code class="literal">LOGGING</code> phase is special. It is executed at
  14       the end of each transaction no matter what happened in the previous
  15       phases. This means it will be processed even if the request was
  16       intercepted or the <code class="literal">allow</code> action was used to pass the
  17       transaction through.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D73"></a>Phase Request Headers</h3></div></div><div></div></div><p>Rules in this phase are processed immediately after Apache
  18       completes reading the request headers (post-read-request phase). At this
  19       point the request body has not been read yet, meaning not all request
  20       arguments are available. Rules should be placed in this phase if you
  21       need to have them run early (before Apache does something with the
  22       request), to do something before the request body has been read,
  23       determine whether or not the request body should be buffered, or decide
  24       how you want the request body to be processed (e.g. whether to parse it
  25       as XML or not).</p><p><span class="emphasis"><em>Note</em></span></p><p>Rules in this phase can not leverage Apache scope directives
  26       (Directory, Location, LocationMatch, etc...) as the post-read-request
  27       hook does not have this information yet. The exception here is the
  28       VirtualHost directive. If you want to use ModSecurity rules inside
  29       Apache locations, then they should run in Phase 2. Refer to the Apache
  30       Request Cycle/ModSecurity Processing Phases diagram.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D7D"></a>Phase Request Body</h3></div></div><div></div></div><p>This is the general-purpose input analysis phase. Most of the
  31       application-oriented rules should go here. In this phase you are
  32       guaranteed to have received the request arguments (provided the request
  33       body has been read). ModSecurity supports three encoding types for the
  34       request body phase:</p><div class="itemizedlist"><ul type="disc"><li><p><code class="literal">application/x-www-form-urlencoded</code> - used to
  35           transfer form data</p></li><li><p><code class="literal">multipart/form-data</code> - used for file
  36           transfers</p></li><li><p><code class="literal">text/xml</code> - used for passing XML data</p></li></ul></div><p>Other encodings are not used by most web applications.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D97"></a>Phase Response Headers</h3></div></div><div></div></div><p>This phase takes place just before response headers are sent back
  37       to the client. Run here if you want to observe the response before that
  38       happens, and if you want to use the response headers to determine if you
  39       want to buffer the response body. Note that some response status codes
  40       (such as 404) are handled earlier in the request cycle by Apache and my
  41       not be able to be triggered as expected. Additionally, there are some
  42       response headers that are added by Apache at a later hook (such as Date,
  43       Server and Connection) that we would not be able to trigger on or
  44       sanitize. This should work appropriately in a proxy setup or within
  45       phase:5 (logging).</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10D9C"></a>Phase Response Body</h3></div></div><div></div></div><p>This is the general-purpose output analysis phase. At this point
  46       you can run rules against the response body (provided it was buffered,
  47       of course). This is the phase where you would want to inspect the
  48       outbound HTML for information disclosure, error messages or failed
  49       authentication text.</p></div><div class="section" lang="en"><div class="titlepage"><div><div><h3 class="title"><a name="N10DA1"></a>Phase Logging</h3></div></div><div></div></div><p>This phase is run just before logging takes place. The rules
  50       placed into this phase can only affect how the logging is performed.
  51       This phase can be used to inspect the error messages logged by Apache.
  52       You cannot deny/block connections in this phase as it is too late. This
  53       phase also allows for inspection of other response headers that weren't
  54       available during phase:3 or phase:4. Note that you must be careful not
  55       to inherit a disruptive action into a rule in this phase as this is a
  56       configuration error in ModSecurity 2.5.0 and later versions.</p></div></div><div id="navfooter"><hr size="1"><table summary="Navigation footer" width="100%"><tr><td align="left" width="40%"><a accesskey="p" href="configuration-directives.html">Prev</a>&nbsp;</td><td align="center" width="20%">&nbsp;</td><td align="right" width="40%">&nbsp;<a accesskey="n" href="variables.html">Next</a></td></tr><tr><td valign="top" align="left" width="40%">Configuration Directives&nbsp;</td><td align="center" width="20%"><a accesskey="h" href="index.html">Home</a></td><td valign="top" align="right" width="40%">&nbsp;Variables</td></tr></table></div><div align="center" class="copyright">Copyright (C) 2004-2009 <a href="http://www.breach.com">Breach Security</a></div></body></html>