next/508/20240628/v1

doc/userguide/configuration/global-thresholds.rst

@@ -6,6 +6,9 @@ Thresholds can be configured in the rules themselves, see
 their intelligence for creating a rule combined with a judgement on how often
 a rule will alert.
 
+Thresholds are tracked in a hash table that is sized according to configuration, see:
+:ref:`suricata-yaml-thresholds`.
+
 Threshold Config
 ----------------
 
@@ -20,7 +23,7 @@ Syntax:
 ::
 
   threshold gen_id <gid>, sig_id <sid>, type <threshold|limit|both>, \
-    track <by_src|by_dst|by_rule|by_both>, count <N>, seconds <T>
+    track <by_src|by_dst|by_rule|by_both|by_flow>, count <N>, seconds <T>
 
 rate_filter
 ~~~~~~~~~~~
@@ -55,6 +58,7 @@ done per IP-address. The Host table is used for storage. When using by_rule
 it's done globally for the rule.
 Option by_both used to track per IP pair of source and destination. Packets
 going to opposite directions between same addresses tracked as the same pair.
+The by_flow option tracks the rule matches in the flow.
 
 count
 ^^^^^

doc/userguide/configuration/suricata-yaml.rst

@@ -739,6 +739,22 @@ To let Suricata make these decisions set default to 'auto':
     prefilter:
       default: auto
 
+.. _suricata-yaml-thresholds:
+
+Thresholding Settings
+~~~~~~~~~~~~~~~~~~~~~
+
+Thresholding uses a central hash table for tracking thresholds of the types: by_src, by_dst, by_both.
+
+::
+
+  detect:
+    thresholds:
+      hash-size: 16384
+      memcap: 16mb
+
+``detect.thresholds.hash-size`` controls the number of hash rows in the hash table.
+``detect.thresholds.memcap`` controls how much memory can be used for the hash table and the data stored in it.
 
 Pattern matcher settings
 ~~~~~~~~~~~~~~~~~~~~~~~~

doc/userguide/rules/thresholding.rst

@@ -4,6 +4,9 @@ Thresholding Keywords
 Thresholding can be configured per rule and also globally, see
 :doc:`../configuration/global-thresholds`.
 
+Thresholds are tracked in a hash table that is sized according to configuration, see:
+:ref:`suricata-yaml-thresholds`.
+
 *Note: mixing rule and global thresholds is not supported in 1.3 and
 before. See bug #425.* For the state of the support in 1.4 see
 :ref:`global-thresholds-vs-rule-thresholds`
@@ -16,7 +19,7 @@ frequency. It has 3 modes: threshold, limit and both.
 
 Syntax::
 
-  threshold: type <threshold|limit|both>, track <by_src|by_dst|by_rule|by_both>, count <N>, seconds <T>
+  threshold: type <threshold|limit|both|backoff>, track <by_src|by_dst|by_rule|by_both|by_flow>, count <N>, <seconds <T>|multiplier <M>>
 
 type "threshold"
 ~~~~~~~~~~~~~~~~
@@ -85,6 +88,65 @@ performed for each of the matches.
 
   *Rule actions drop (IPS mode) and reject are applied to each packet.*
 
+type "backoff"
+~~~~~~~~~~~~~~
+
+Allow limiting of alert output by using a backoff algorithm.
+
+Syntax::
+
+    threshold: type backoff, track by_flow, count <C>, multiplier <M>;
+
+``track``: backoff is only supported for ``by_flow``
+``count``: number of alerts before the first match is logged
+``multiplier``: value to multiply ``count`` with each time the next value is reached
+
+A count of 1 with a multiplier of 10 would generate alerts for matching packets::
+
+    1, 10, 100, 1000, 10000, 100000, etc.
+
+A count of 1 with a multiplier of 2 would generate alerts for matching packets::
+
+    1, 2, 4, 8, 16, 32, 64, etc.
+
+A count of 5 with multiplier 5 would generate alerts for matching packets::
+
+    5, 25, 125, 625, 3125, 15625, etc
+
+In the following example, the ``pkt_invalid_ack`` would only lead to alerts the 1st, 10th, 100th, etc.
+
+.. container:: example-rule
+
+    alert tcp any any -> any any (stream-event:pkt_invalid_ack; \
+        :example-rule-options:`threshold:type backoff, track by_flow, count 1, multiplier 10;`
+        sid:2210045; rev:2;)
+
+If a signature sets a flowbit, flowint, etc. those actions are still
+performed for each of the matches.
+
+  *Rule actions drop (IPS mode) and reject are applied to each matching packet.*
+
+
+track
+~~~~~
+
+.. table::
+
+   +------------------+--------------------------+
+   |Option            |Tracks By                 |
+   +==================+==========================+
+   |by_src            |source IP                 |
+   +------------------+--------------------------+
+   |by_dst            |destination IP            |
+   +------------------+--------------------------+
+   |by_both           |pair of src IP and dst IP |
+   +------------------+--------------------------+
+   |by_rule           |signature id              |
+   +------------------+--------------------------+
+   |by_flow           |flow                      |
+   +------------------+--------------------------+
+
+
 detection_filter
 ----------------
 
@@ -97,7 +159,7 @@ again.
 
 Syntax::
 
-  detection_filter: track <by_src|by_dst|by_rule|by_both>, count <N>, seconds <T>
+  detection_filter: track <by_src|by_dst|by_rule|by_both|by_flow>, count <N>, seconds <T>
 
 Example::