Pull request #3562: http_inspect: add doc for http_num_cookies

Merge in SNORT/snort3 from ~ADMAMOLE/snort3:doc_num_cookies to master

Squashed commit of the following:

commit e83e4def10dd889341a635c28c2b80a2db0afcd2
Author: Adrian Mamolea <admamole@cisco.com>
Date:   Thu Aug 18 10:50:14 2022 -0400

    http_inspect: add doc for http_num_cookies

diff --git a/doc/user/http_inspect.txt b/doc/user/http_inspect.txt
index badafdd738df9fdeaa7c15c03a07bcf10c0cae9e..298bedec0760ca03a42abf6a6d0ff1086cce1361 100755 (executable)
--- a/doc/user/http_inspect.txt
+++ b/doc/user/http_inspect.txt
@@ -563,6 +563,43 @@ thrown off by extra spaces or other languages in the list.
 In addition to the headers there are rule options for virtually every part
 of the HTTP message.
 
+Occasionally one needs a rule that looks for the count of some variable. For
+example, to alert when a message has more than 100 headers use this rule:
+
+    alert tcp any any -> any any ( msg:"more that 100 headers";
+    http_num_headers: > 100; sid:25; rev:1; )
+
+This is a range-based rule. It is matching when the expression in the rule
+option is true. The general format is "option operator value". To compare for
+equality, use operator "=". This is the default operator and may be omitted.
+Both rules below will alert when the message has 100 headers:
+
+    alert tcp any any -> any any ( msg:"100 headers";
+    http_num_headers: = 100; sid:26; rev:1; )
+
+    alert tcp any any -> any any ( msg:"100 headers";
+    http_num_headers: 100; sid:27; rev:1; )
+
+Compare for non-equality using operator "!" or "!=", compare for less than
+using operator "<", compare for greater than using operator ">", compare for
+less or equal using operator "<=", and compare for greater or equal using
+operator ">=".
+
+To alert when a message has strictly more than 100 headers and strictly less
+than 200 headers use this rule:
+
+    alert tcp any any -> any any ( msg:"between (100,200) headers";
+    http_num_headers: 100<>200; sid:28; rev:1; )
+
+This is a range-based rule with an interval. The general format is
+"option value1 operator value2". Use operator "<>" to match if the option
+is in the interval excluding the endpoints, or operator "<=>" to
+include the endpoints. This rule will alert when a message has 100 headers
+or more and 200 headers or less:
+
+    alert tcp any any -> any any ( msg:"between [100,200] headers";
+    http_num_headers: 100<=>200; sid:95; rev:1; )
+
 ===== http_uri and http_raw_uri
 
 These provide the URI of the request message. The raw form is exactly as it
@@ -740,10 +777,26 @@ and decompress_vba options enabled.
 
 ===== http_num_headers and http_num_trailers
 
-These rule options are used to check the number of headers and
-trailers, respectively. Checks available: equal to "=" or just value,
-not "!" or "!=",  less than "<", greater than ">", less or equal to "<=",
-less or greater than ">=", in range "<>", in range or equal to "<=>".
+These are range-based rule options used to check the number of headers and
+trailers, respectively.
+
+===== http_num_cookies
+
+This is a range-based rule option that checks the number of cookies. In a
+request all the individual cookies found in Cookie header are counted. For
+example, in this request there are 2 cookies:
+
+    GET /send/in/some/cookies HTTP/1.1
+    Host: www.cookie-store.com
+    Cookie: SID=31d4d96e407aad42; lang=en-US
+
+In a response Set-Cookie headers are counted. For example, in this response
+there are 2 cookies:
+
+    HTTP/1.0 540 Too much sugar
+    Content-Length: 5
+    Set-Cookie: lang=en-US; Path=/; Domain=example.com
+    Set-Cookie: id=a3fWa; Expires=Thu, 21 Oct 2021 07:28:00 GMT; Secure; HttpOnly
 
 ===== http_version_match