diff --git a/doc/modsecurity2-apache-reference.xml b/doc/modsecurity2-apache-reference.xml index 388e8622..0b9c1e9e 100644 --- a/doc/modsecurity2-apache-reference.xml +++ b/doc/modsecurity2-apache-reference.xml @@ -3,7 +3,7 @@ ModSecurity Reference Manual - Version 2.1.3 / (Sep 5, 2007) + Version 2.1.3 / (September 7, 2007) 2004-2007 @@ -622,8 +622,7 @@ SecAuditLogStorageDir logs/audit - B - request - headers + B - request headers @@ -649,14 +648,14 @@ SecAuditLogStorageDir logs/audit - F - final response - headers (excluding the Date and Server headers, which are always - added by Apache in the late stage of content delivery). + F - final response headers + (excluding the Date and Server headers, which are always added by + Apache in the late stage of content delivery). - G - RESERVED for the - actual response body, not implemented yet. + G - RESERVED for the actual + response body, not implemented yet. @@ -667,9 +666,9 @@ SecAuditLogStorageDir logs/audit I - This part is a replacement for part C. It will log the same data as C in all cases - except whenmultipart/form-data + except when multipart/form-data encoding in used. In this case it will log a fake application/x-www-form-urlencoded body + moreinfo="none">application/x-www-form-urlencoded body that contains the information about parameters but not about the files. This is handy if you don't want to have (often large) files stored in your audit logs. @@ -678,7 +677,7 @@ SecAuditLogStorageDir logs/audit J - RESERVED. This part, when implemented, will contain information about the files uploaded - using multipart/form-data encoding. + using multipart/form-data encoding. @@ -1753,16 +1752,17 @@ SecRule REQUEST_HEADERS:Host "!^$" "deny,phase:1 - application/x-www-form-urlencoded - used to transfer form - data + application/x-www-form-urlencoded - used to + transfer form data - multipart/form-data - used for file transfers + multipart/form-data - used for file + transfers - text/xml - used for passing XML data + text/xml - used for passing XML data @@ -1972,6 +1972,72 @@ SecRule ENV:tag "suspicious" (REQUEST_HEADERS:Headername) +
+ <literal>MULTIPART_STRICT_ERROR</literal> + + MULTIPART_STRICT_ERROR will be set to + 1 when any of the following variables is also set to + 1: REQBODY_PROCESSOR_ERROR, + MULTIPART_BOUNDARY_QUOTED, + MULTIPART_BOUNDARY_WHITESPACE, + MULTIPART_DATA_BEFORE, + MULTIPART_DATA_AFTER, + MULTIPART_HEADER_FOLDING, + MULTIPART_LF_LINE, + MULTIPART_SEMICOLON_MISSING. Each of these variables + covers one unusual (although sometimes legal) aspect of the request body + in multipart/form-data format. Your policies should + always contain a rule to check either this variable + (easier) or one or more individual variables (if you know exactly what + you want to accomplish). Depending on the rate of false positives and + your default policy you should decide whether to block or just warn when + the rule is triggered. + + The best way to use this variable is as in the example + below: + + SecRule MULTIPART_STRICT_ERROR "!@eq 0" \ +"phase:2,t:none,log,deny,msg:'Multipart request body \ +failed strict validation: \ +PE %{REQBODY_PROCESSOR_ERROR}, \ +BQ %{MULTIPART_BOUNDARY_QUOTED}, \ +BW %{MULTIPART_BOUNDARY_WHITESPACE}, \ +DB %{MULTIPART_DATA_BEFORE}, \ +DA %{MULTIPART_DATA_AFTER}, \ +HF %{MULTIPART_HEADER_FOLDING}, \ +LF %{MULTIPART_LF_LINE}, \ +SM %{MULTIPART_SEMICOLON_MISSING}'" + + The multipart/form-data parser has been + upgraded in ModSecurity v2.1.3 to actively look for signs of evasion. + Many variables (as listed above) were added to expose various facts + discovered during the parsing process. The + MULTIPART_STRICT_ERROR variable is handy to check on + all abnormalities at once. The individual variables allow detection to + be fine-tuned according to your circumstances in order to reduce the + number of false positives. Detailed analysis of various evasion + techniques covered will be released as a separated document at a later + date. +
+ +
+ <literal>MULTIPART_UNMATCHED_BOUNDARY</literal> + + Set to 1 when, during the parsing phase of a + multipart/request-body, ModSecurity encounters what + feels like a boundary but it is not. Such an event may occur when + evasion of ModSecurity is attempted. + + The best wasy to use this variable is as in the example + below: + + SecRule MULTIPART_UNMATCHED_BOUNDARY "!@eq 0" \ +"phase:2,t:none,log,deny,msg:'Multipart parser detected a possible unmatched boundary.'" + + Change the rule from blocking to logging-only if many false + positives are encountered. +
+
<literal moreinfo="none">PATH_INFO</literal> @@ -3276,8 +3342,8 @@ SecRule REQUEST_URI "^/cgi-bin/script\.pl" \ - 1-99,999; reserved for local (internal) use. Use as you - see fit but do not use this range for rules that are distributed to + 1-99,999; reserved for local (internal) use. Use as you see + fit but do not use this range for rules that are distributed to others. @@ -4122,10 +4188,11 @@ SecRule XML:/soap:Envelope/soap:Body/q1:getInput/id() "123" phase:2,deny + check byte range in a POST payload when + multipart/form-data encoding (file upload) is used. + Doing so would prevent binary files from being uploaded. However, after + the parameters are extracted from such request they are checked for a + valid range. validateByteRange is similar to the ModSecurity 1.X SecFilterForceByteRange Directive however since it works in a rule @@ -4196,8 +4263,9 @@ SecRule XML "@validateSchema /path/to/apache2/conf/xml.xsd URL encoding is an HTTP standard for encoding byte values within a URL. The byte is escaped with a % followed by two hexadecimal values (0-F). This directive does not check encoding in a POST payload when the - multipart/form-data encoding (file upload) is used. It is not necessary - to do so because URL encoding is not used for this encoding. + multipart/form-data encoding (file upload) is used. + It is not necessary to do so because URL encoding is not used for this + encoding.
@@ -4243,4 +4311,104 @@ SecRule XML "@validateSchema /path/to/apache2/conf/xml.xsd
- + +
+ Miscellaneous Topics + + + +
+ Impedance Mismatch + + Web application firewalls have a difficult job trying to make + sense of data that passes by, without any knowledge of the application + and its business logic. The protection they provide comes from having an + independent layer of security on the outside. Because data validation is + done twice, security can be increased without having to touch the + application. In some cases, however, the fact that everything is done + twice brings problems. Problems can arise in the areas where the + communication protocols are not well specified, or where either the + device or the application do things that are not in the specification. + In such cases it may be possible to design payload that will be + interpreted in one way by one device and in another by the other device. + This problem is better known as Impedance Mismatch. It can be exploited + to evade the security devices. + + While we will continue to enhance ModSecurity to deal with various + evasion techniques the problem can only be minimized, but never solved. + With so many different application backends chances are some will always + do something completely unexpected. The only solution is to be aware of + the technologies in the backend when writing rules, adapting the rules + to remove the mismatch. See the next section for some examples. + +
+ PHP Peculiarities for ModSecurity Users + + When writing rules to protect PHP applications you need to pay + attention to the following facts: + + + + When "register_globals" is set to "On" request parameters + are automatically converted to script variables. In some PHP + versions it is even possible to override the $GLOBALS + array. + + + + Whitespace at the beginning of parameter names is ignored. + (This is very dangerous if you are writing rules to target + specific named variables.) + + + + The remaining whitespace (in parameter names) is converted + to underscores. The same applies to dots and to a "[" if the + variable name does not contain a matching closing bracket. + (Meaning that if you want to exploit a script through a variable + that contains an underscore in the name you can send a parameter + with a whitespace or a dot instead.) + + + + Cookies can be treated as request parameters. + + + + The discussion about variable names applies equally to the + cookie names. + + + + The order in which parameters are taken from the request and + the environment is EGPCS (environment, GET, POST, Cookies, + built-in variables). This means that a POST parameter will + overwrite the parameters transported on the request line (in + QUERY_STRING). + + + + When "magic_quotes_gpc" is set to "On" PHP will use + backslash to escape the following characters: single quote, double + quote, backslash, and the nul byte. + + + + If "magic_quotes_sybase" is set to "On" only the single + quote will be escaped using another single quote. In this case the + "magic_quotes_gpc" setting becomes irrelevant. The + "magic_quotes_sybase" setting completely overrides the + "magic_quotes_gpc" behaviour but "magic_quotes_gpc" still must be + set to "On" for the Sybase-specific quoting to be work. + + + + PHP will also automatically create nested arrays for you. + For example "p[x][y]=1" results in a total of three + variables. + + +
+
+
+ \ No newline at end of file