Pull request #4496: doc: add details regarding RTN evaluation

Merge in SNORT/snort3 from ~YVELYKOZ/snort3:ips_eval_doc_upd to master

Squashed commit of the following:

commit d2945e9cf99f3b171cbe8d90e2d3393291128b02
Author: Yehor Velykozhon <yvelykoz@cisco.com>
Date:   Tue Oct 29 17:42:37 2024 +0200

    doc: add details regarding RTN evaluation

diff --git a/doc/user/concepts.txt b/doc/user/concepts.txt
index 63d350c24cca5e220289ccc8f09d2db93f5e5486..e5b82839964edb372abedd24194d140b01f03e95 100644 (file)
--- a/doc/user/concepts.txt
+++ b/doc/user/concepts.txt
@@ -261,14 +261,17 @@ fast pattern searches with search_engine.search_method which defaults to
 expense of significantly more memory, use 'ac_full'.  For best performance
 and reasonable memory, download the hyperscan source from Intel.
 
+Rule group summary is printed at start up under "port rule counts"
+and "service rule counts" sections.
+
 ==== Fast Patterns
 
 Fast patterns are content strings that have the fast_pattern option or
 which have been selected by Snort automatically to be used as a fast
 pattern.  Snort will by default choose the longest pattern in the rule
 since that is likely to be most unique.  That is not always the case so add
-fast_pattern to the appropriate content or regex option for best performance.  The
-ideal fast pattern is one which, if found, is very likely to result in a
+fast_pattern to the appropriate content or regex option for best performance.
+The ideal fast pattern is one which, if found, is very likely to result in a
 rule match.  Fast patterns that match frequently for unrelated traffic will
 cause Snort to work hard with little to show for it.
 
@@ -284,6 +287,48 @@ left-to-right.  Rule evaluation requires checking each detection option in
 a rule and is a fairly costly process which is why fast patterns are so
 important.  Rule evaluation aborts on the first non-matching option.
 
+For a _port-based_ rule, all components of the rule header have to match before
+the rule fires. For a _service-based_ rule, evaluation of the header is skipped.
+A rule becomes _service-based_ in the following cases:
+
+* "service" IPS option is present in the rule body
+* a service specific IPS option is present (like http_param, file_data, dnp3_data)
+* a service protocol is defined in the rule header
+
+Examples:
+
+    # Port group - protocol and ports are evaluated in any case
+    alert tcp any 90 -> any 5321 (msg: "Port group rule";)
+
+    # "any" port group - protocol and ports are evaluated in any case
+    alert tcp (msg: "Port group rule with default header";)
+
+    # "service" option puts the rule to SMTP group and port group.
+    # If the SMTP service is assigned on flow, "tcp" proto and port "90" have no effect.
+    # In other case, header is evaluated - since matched as a part of port group
+    alert tcp any 90 -> any any (service: smtp; msg: "SMTP and port group";)
+
+    # DNP3 service is detected automatically, DNP3 group only.
+    # In a fact, "tcp" proto and port "90" has no effect at all.
+    alert tcp any 90 -> any any (dnp3_data; msg: "DNP3 group";)
+
+    # Service protocol in the header puts the rule to DNP3 group.
+    # In a fact, "tcp" proto and port "90" has no effect at all.
+    alert dnp3 any 90 -> any any (msg: "DNP3 group";)
+
+Note that detection module can extend a rule with more services. For details,
+check `detection.service_extension` option.
+
+In case you need to match the _service-based_ rule with regard to specific protocol,
+take a look at IPS option "ip_proto" - it guarantees that specified protocol is used.
+
+Example when such explicit check is required:
+
+    # Since the rule is added to both "any" port-group and "igmp" service group,
+    # to decrease false-positive due to "any" port-group, ip_proto:2 is used.
+    alert ip ( ip_proto:2; content:"foo";  service:igmp; )
+
+
 When rule evaluation takes place, the fast pattern match will automatically
 be skipped if possible.  Note that this differs from Snort 2 which provided
 the fast_pattern:only option to designate such cases.  This is one less
@@ -306,7 +351,5 @@ Stateful evaluation is supported for the following buffers:
  1. pkt_data -- as a sequence of TCP session bytes with respect to their
  direction (client-to-server, server-to-client)
 
- 2. js_data -- normalized JavaScript text from the same data transfer session
-
- 3. file_data -- the same file bytes, e.g. flows from different files do not
+ 2. file_data -- the same file bytes, e.g. flows from different files do not
  overlap