From: Jeff Lucovsky <jlucovsky@oisf.net>
Date: Wed, 6 Mar 2024 14:36:05 +0000 (-0500)
Subject: doc: Describe noalert keyword
X-Git-Tag: suricata-8.0.0-beta1~1486
X-Git-Url: http://git.ipfire.org/cgi-bin/gitweb.cgi?a=commitdiff_plain;h=7a5a1e256083188505e729baf9fb9724481d71e3;p=thirdparty%2Fsuricata.git

doc: Describe noalert keyword

Issue: 6685
---

diff --git a/doc/userguide/rules/intro.rst b/doc/userguide/rules/intro.rst
index ab35f8a311..9f87796253 100644
--- a/doc/userguide/rules/intro.rst
+++ b/doc/userguide/rules/intro.rst
@@ -280,6 +280,36 @@ keywords.
 
 Some generic details about keywords follow.
 
+Disabling Alerts
+~~~~~~~~~~~~~~~~
+There is a way to disable alert generation for a rule using the keyword ``noalert``.
+When this keyword is part of a rule, no alert is generated if the other
+portions of the rule match. That is, the other rule actions will *still be
+applied.* Using ``noalert`` can be helpful when a rule is
+collecting or setting state using `flowbits`, `datasets` or other
+state maintenance constructs of the rule language. See :doc:`thresholding`
+for other ways to control alert frequency.
+
+The following rules demonstrate ``noalert`` with a familiar pattern:
+
+* The first rule marks state without generating an alert.
+* The second rule generates an alert if the state is set and additional
+  qualifications are met.
+
+.. container:: example-rule
+
+    :example-rule-action:`alert` :example-rule-header:`http any any -> $HOME_NET any` :example-rule-options:`(msg:"noalert example: set state"; flow:established,to_server; xbits:set,SC.EXAMPLE,track ip_dst, expire 10; noalert; http.method; content:"GET"; sid:1; )`
+
+    :example-rule-action:`alert` :example-rule-header:`http any any -> $HOME_NET any` :example-rule-options:`(msg:"noalert example: state use"; flow:established,to_server; xbits:isset,SC.EXAMPLE,track ip_dst; http.method; content:"POST"; sid: 2; )`
+
+In IPS mode, ``noalert`` is commonly used in when Suricata should `drop` network packets
+without generating alerts (example below).  The following rule is a simplified example
+showing how ``noalert`` could be used with IPS deployments to drop inbound SSH requests.
+
+.. container:: example-rule
+
+    :example-rule-action:`drop` :example-rule-header:`tcp any any -> any 22` :example-rule-options:`(msg:"Drop inbound SSH traffic"; noalert; sid: 3)`
+
 .. _rules-modifiers:
 
 Modifier Keywords