aiden
/
suricata
mirror of https://github.com/OISF/suricata
1
0
Fork 0
Code Issues Packages Projects Releases Wiki Activity

doc/threshold: Threshold keyword clarifications

Browse Source 
Issue: 7129
pull/12514/head
Jeff Lucovsky 1 year ago committed by Victor Julien
parent 123b36b9f5
commit e9128e66e6
1 changed files with 91 additions and 75 deletions
Show Stats Download Patch File Download Diff File

166
doc/userguide/rules/thresholding.rst
Unescape Escape View File

@ -1,3 +1,5 @@
.. role:: example-rule-emphasis
Thresholding Keywords Thresholding Keywords
===================== =====================
@ -7,98 +9,122 @@ Thresholding can be configured per rule and also globally, see
Thresholds are tracked in a hash table that is sized according to configuration, see: Thresholds are tracked in a hash table that is sized according to configuration, see:
:ref:`suricata-yaml-thresholds`. :ref:`suricata-yaml-thresholds`.
*Note: mixing rule and global thresholds is not supported in 1.3 and **IMPORTANT** for both ``threshold`` and ``detection_filter`` keywords
before. See bug #425.* For the state of the support in 1.4 see
:ref:`global-thresholds-vs-rule-thresholds` .. note::
Rules that contain ``flowbits``, ``flowints``, etc will still have those actions performed when the rule
contains one of the ``threshold`` keywords. Those actions are not subject to the threshold limits.
Rule actions ``drop`` (IPS mode) and ``reject`` are applied to each packet
(not only the one that meets the limit condition).
threshold threshold
--------- ---------
The threshold keyword can be used to control the rule's alert The ``threshold`` keyword can be used to control the rule's alert
frequency. It has 3 modes: threshold, limit and both. frequency. There are four threshold modes:
#. threshold
#. limit
#. both
#. backoff
Syntax:: Syntax::
threshold: type <threshold|limit|both|backoff>, track <by_src|by_dst|by_rule|by_both|by_flow>, count <N>, <seconds <T>|multiplier <M>> threshold: type <threshold|limit|both|backoff>, track <by_src|by_dst|by_rule|by_both|by_flow>, count <N>, <seconds <T>|multiplier <M>>
Specify ``seconds`` to control the number of alerts per time period.
type "threshold" type "threshold"
~~~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~~~
This type can be used to set a minimum threshold for a rule before it This type sets a minimum threshold for a rule before it generates alerts.
generates alerts. A threshold setting of N means on the Nth time the
rule matches an alert is generated.
Example:: A threshold setting with a ``count`` value of ``C`` will generate an alert
the ``Cth`` time the alert matches. If ``seconds`` is specified, an
alert is generated when ``count`` matches have occurred within ``N`` seconds.
alert tcp !$HOME_NET any -> $HOME_NET 25 (msg:"ET POLICY Inbound Frequent Emails - Possible Spambot Inbound"; \ Syntax::
flow:established; content:"mail from|3a|"; nocase; \
threshold: type threshold, track by_src, count 10, seconds 60; \ threshold: type threshold, track by_flow, count <C>, seconds <N>;
reference:url,doc.emergingthreats.net/2002087; classtype:misc-activity; sid:2002087; rev:10;)
This signature only generates an alert if we get 10 inbound emails or Example:
more from the same server in a time period of one minute.
If a signature sets a flowbit, flowint, etc. those actions are still .. container:: example-rule
performed for each of the matches.
*Rule actions drop (IPS mode) and reject are applied to each packet alert tcp !$HOME_NET any -> $HOME_NET 25 (msg:"ET POLICY Inbound Frequent Emails - Possible Spambot Inbound";
(not only the one that meets the threshold condition).* flow:established; content:"mail from|3a|"; nocase;
:example-rule-emphasis:`threshold: type threshold, track by_src, count 10, seconds 60;`
reference:url,doc.emergingthreats.net/2002087; classtype:misc-activity; sid:2002087; rev:10;)
This signature generates an alert if there are 10 or more inbound emails from the same server within
one minute.
type "limit" type "limit"
~~~~~~~~~~~~ ~~~~~~~~~~~~
This type can be used to make sure you're not getting flooded with The ``limit`` type prevents a flood of alerts by limiting the number of alerts.
alerts. If set to limit N, it alerts at most N times. A limit with a count of ``N`` won't generate more than ``N`` alerts.
Limit the number of alerts per time period by specifying ``seconds`` with
``count.``
Syntax::
Example:: threshold: type limit, track by_dst, count <C>, seconds <N>;
alert http $HOME_NET any -> any $HTTP_PORTS (msg:"ET USER_AGENTS Internet Explorer 6 in use - Significant Security Risk"; \ Example:
flow:to_server,established; content:"|0d 0a|User-Agent|3a| Mozilla/4.0 (compatible|3b| MSIE 6.0|3b|"; \
threshold: type limit, track by_src, seconds 180, count 1; \
reference:url,doc.emergingthreats.net/2010706; classtype:policy-violation; sid:2010706; rev:7;)
In this example at most 1 alert is generated per host within a period .. container:: example-rule
of 3 minutes if MSIE 6.0 is detected.
If a signature sets a flowbit, flowint, etc. those actions are still alert http $HOME_NET any -> any any (msg:"ET INFO Internet Explorer 6 in use - Significant Security Risk";
performed for each of the matches. flow:established,to_server; http.user_agent; content:"Mozilla/4.0 (compatible|3b| MSIE 6.0|3b|";
:example-rule-emphasis:`threshold: type limit, track by_src, seconds 180, count 1;`
classtype:policy-violation; sid:2010706; rev:10; metadata:created_at 2010_07_30, updated_at 2024_03_16;)
*Rule actions drop (IPS mode) and reject are applied to each packet In this example, at most 1 alert is generated per host within a period
(not only the one that meets the limit condition).* of 3 minutes if "MSIE 6.0" is detected.
type "both" type "both"
~~~~~~~~~~~ ~~~~~~~~~~~
This type is a combination of the "threshold" and "limit" types. It This type combines ``threshold`` and ``limit`` to control when alerts
applies both thresholding and limiting. are generated.
Example:: Syntax::
alert tcp $HOME_NET 5060 -> $EXTERNAL_NET any (msg:"ET VOIP Multiple Unauthorized SIP Responses TCP"; \ threshold: type both, track by_flow, count <C>, multiplier <M>;
flow:established,from_server; content:"SIP/2.0 401 Unauthorized"; depth:24; \
threshold: type both, track by_src, count 5, seconds 360; \ Example:
reference:url,doc.emergingthreats.net/2003194; classtype:attempted-dos; sid:2003194; rev:6;)
.. container:: example-rule
This alert will only generate an alert if within 6 minutes there have alert tcp $HOME_NET 5060 -> $EXTERNAL_NET any (msg:"ET VOIP Multiple Unauthorized SIP Responses TCP";
been 5 or more "SIP/2.0 401 Unauthorized" responses, and it will alert flow:established,from_server; content:"SIP/2.0 401 Unauthorized"; depth:24;
only once in that 6 minutes. :example-rule-emphasis:`threshold: type both, track by_src, count 5, seconds 360;`
reference:url,doc.emergingthreats.net/2003194; classtype:attempted-dos; sid:2003194; rev:6;)
If a signature sets a flowbit, flowint, etc. those actions are still This rule will generate at most one alert every 6 minutes if there have been 5 or more occurrences
performed for each of the matches. of "SIP2.0 401 Unauthorized" responses.
*Rule actions drop (IPS mode) and reject are applied to each packet.* The ``type backoff`` section describes the ``multiplier`` keyword.
type "backoff" type "backoff"
~~~~~~~~~~~~~~ ~~~~~~~~~~~~~~
Allow limiting of alert output by using a backoff algorithm. This type limits the alert output by using a backoff algorithm between alerts.
.. note::
``backoff`` can only be used with ``track by_flow``
Syntax:: Syntax::
threshold: type backoff, track by_flow, count <C>, multiplier <M>; threshold: type backoff, track by_flow, count <C>, multiplier <M>;
``track``: backoff is only supported for ``by_flow`` ``track``: backoff is only supported for ``by_flow``
``count``: number of alerts before the first match is logged ``count``: number of alerts before the first match generates an alert.
``multiplier``: value to multiply ``count`` with each time the next value is reached ``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:: A count of 1 with a multiplier of 10 would generate alerts for matching packets::
@ -117,14 +143,9 @@ In the following example, the ``pkt_invalid_ack`` would only lead to alerts the
.. container:: example-rule .. container:: example-rule
alert tcp any any -> any any (stream-event:pkt_invalid_ack; \ alert tcp any any -> any any (stream-event:pkt_invalid_ack;
:example-rule-options:`threshold:type backoff, track by_flow, count 1, multiplier 10;` :example-rule-emphasis:`threshold:type backoff, track by_flow, count 1, multiplier 10;`
sid:2210045; rev:2;) 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 track
@ -150,31 +171,26 @@ track
detection_filter detection_filter
---------------- ----------------
The detection_filter keyword can be used to alert on every match after The ``detection_filter`` keyword can be used to alert on every match after
a threshold has been reached. It differs from the threshold with type an initial threshold has been reached. It differs from ``threshold`` with type
threshold in that it generates an alert for each rule match after the ``threshold`` in that it generates an alert for each rule match after the
initial threshold has been reached, where the latter will reset it's initial threshold has been reached, where the latter will reset its
internal counter and alert again when the threshold has been reached internal counter and alert each time the threshold has been reached.
again.
Syntax:: Syntax::
detection_filter: track <by_src|by_dst|by_rule|by_both|by_flow>, count <N>, seconds <T> detection_filter: track <by_src|by_dst|by_rule|by_both|by_flow>, count <N>, seconds <T>
Example:: Example:
alert http $EXTERNAL_NET any -> $HOME_NET any \
(msg:"ET WEB_SERVER WebResource.axd access without t (time) parameter - possible ASP padding-oracle exploit"; \
flow:established,to_server; content:"GET"; http_method; content:"WebResource.axd"; http_uri; nocase; \
content:!"&t="; http_uri; nocase; content:!"&amp|3b|t="; http_uri; nocase; \
detection_filter:track by_src,count 15,seconds 2; \
reference:url,netifera.com/research/; reference:url,www.microsoft.com/technet/security/advisory/2416728.mspx; \
classtype:web-application-attack; sid:2011807; rev:5;)
Alerts each time after 15 or more matches have occurred within 2 seconds. .. container:: example-rule
If a signature sets a flowbit, flowint, etc. those actions are still alert http $EXTERNAL_NET any -> $HOME_NET any
performed for each of the matches. (msg:"ET WEB_SERVER WebResource.axd access without t (time) parameter - possible ASP padding-oracle exploit";
flow:established,to_server; content:"GET"; http_method; content:"WebResource.axd"; http_uri; nocase;
content:!"&t="; http_uri; nocase; content:!"&amp|3b|t="; http_uri; nocase;
:example-rule-emphasis:`detection_filter:track by_src,count 15,seconds 2;`
reference:url,netifera.com/research/; reference:url,www.microsoft.com/technet/security/advisory/2416728.mspx;
classtype:web-application-attack; sid:2011807; rev:5;)
*Rule actions drop (IPS mode) and reject are applied to each packet This rule will generate alerts after 15 or more matches have occurred within 2 seconds.
that generate an alert*

Write Preview
Loading…
Cancel
Save