[8.14] [ESS][8.14] Alert suppression docs for EQL (non-seq) and new t…

…erm rule types (backport #5057) (#5142) * Update alert-suppression.asciidoc * Update docs/detections/alert-suppression.asciidoc * Adding more to draft * Minor typo * Aligning with Serverless docs * Update docs/detections/alert-suppression.asciidoc Co-authored-by: Ryland Herrick <[email protected]> * Update docs/detections/api/rules/rules-api-create.asciidoc * Updating update api * Fixed formatting error * Ben's input pt 1 * Ref suppression docs Ref suppression docs in steps for creating new terms and eql rules * Re-adding content to avoid conflict * Update docs/detections/api/rules/rules-api-create.asciidoc * Updating titles * Vitalii's input * ben's input * Update docs/detections/api/rules/rules-api-update.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * Update docs/detections/api/rules/rules-api-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * Update docs/detections/alert-suppression.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * Update docs/detections/api/rules/rules-api-create.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * Update docs/detections/api/rules/rules-api-update.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> --------- Co-authored-by: Ryland Herrick <[email protected]> Co-authored-by: Benjamin Ironside Goldstein <[email protected]> (cherry picked from commit 2fd85dd) Co-authored-by: Nastasha Solomon <[email protected]>
elastic · Apr 30, 2024 · a20a9f7 · a20a9f7
1 parent 961b116
commit a20a9f7
Show file tree

Hide file tree

Showing 4 changed files with 29 additions and 13 deletions.
diff --git a/docs/detections/alert-suppression.asciidoc b/docs/detections/alert-suppression.asciidoc
@@ -14,6 +14,8 @@ Alert suppression allows you to reduce the number of repeated or duplicate detec
 * <<create-custom-rule,Custom query>>
 * <<create-threshold-rule,Threshold>>
 * <<create-indicator-rule,Indicator match>>
+* <<create-eql-rule,Event correlation>> (non-sequence queries only)
+* <<create-new-terms-rule,New terms>>  
 
 Normally, when a rule meets its criteria repeatedly, it creates multiple alerts, one for each time the rule's criteria are met. When alert suppression is configured, duplicate qualifying events are grouped, and only one alert is created for each group. Depending on the rule type, you can configure alert suppression to create alerts each time the rule runs, or once within a specified time window. You can also specify multiple fields to group events by unique combinations of values.
 
@@ -23,37 +25,45 @@ NOTE: Alert suppression is not available for Elastic prebuilt rules. However, if
 
 === Configure alert suppression
 
-You can configure alert suppression when you create or edit a supported rule type. Refer to <<create-custom-rule>>, <<create-threshold-rule>>, or <<create-indicator-rule>> for detailed instructions.
+You can configure alert suppression when you create or edit a supported rule type. Refer to documentation for creating <<create-custom-rule,custom query>>, <<create-threshold-rule, threshold>>, <<create-eql-rule,event correlation>>, or <<create-new-terms-rule,new terms>> rules for detailed instructions.
 
 . When configuring the rule type (the *Define rule* step for a new rule, or the *Definition* tab for an existing rule), specify how you want to group events for alert suppression:
 +
 --
 * Custom query rule: In *Suppress alerts by*, enter 1-3 field names to group events by the fields' values. 
 * Threshold rule: In *Group by*, enter up to 3 field names to group events by the fields' values, or leave the setting empty to group all qualifying events together. 
 * Indicator match rule: In *Suppress alerts by*, enter 1-3 field names to group events by the fields' values. 
+* Event correlation rule (non-sequence queries only): In *Suppress alerts by*, enter 1-3 field names to group events by the fields' values. 
+* New terms rule: In *Suppress alerts by*, enter 1-3 field names to group events by the fields' values.
+
 --
 +
 [NOTE]
 ======
-Fields with multiple values are handled as follows:
+If you specify a field with multiple values, alerts with that field are handled as follows:
 
-* **Custom query or threshold rules** - If you specify a field with multiple values, an alert grouping is created for each value. For example, if you suppress alerts by `destination.ip` of `[127.0.0.1, 127.0.0.2, 127.0.0.3]`, alerts will be suppressed separately for each value of `127.0.0.1`, `127.0.0.2`, and `127.0.0.3`. 
-* **Indicator match rule** - If you specify a field with multiple values, an alert grouping is created for alerts that contain the array you specified. For example, if you suppress alerts by `destination.ip` of `[127.0.0.1, 127.0.0.2, 127.0.0.3]`, alerts that contain this array are grouped and suppressed.
+* **Custom query or threshold rules** - A group of alerts is created for each value. For example, if you suppress alerts by `destination.ip` of `[127.0.0.1, 127.0.0.2, 127.0.0.3]`, alerts will be suppressed separately for each value of `127.0.0.1`, `127.0.0.2`, and `127.0.0.3`. 
+* **Indicator match rule, event correlation (non-sequence queries only), or new terms rule** - Alerts with the specified field name and identical array values are grouped together. For example, if you suppress alerts by `destination.ip` of `[127.0.0.1, 127.0.0.2, 127.0.0.3]`, alerts with the entire array are grouped and only one alert is created for the group.
 
 ======
 
 . If available, select how often to create alerts for duplicate events:
 +
+NOTE: Both options are available for custom query, indicator match, event correlation, and new terms rules. Threshold rules only have the *Per time period* option.
++
 --
-* *Per rule execution*: (Only available for custom query rules and indicator match rules) Create an alert each time the rule runs and meets its criteria.
-* *Per time period*: Create one alert for all qualifying events within a specified time window, beginning when the rule first meets its criteria and creates the alert. (This is the only option available for threshold rules.)
+* *Per rule execution*: Create an alert each time the rule runs and meets its criteria.
+* *Per time period*: Create one alert for all qualifying events that occur within a specified time window, beginning from when an event first meets the rule criteria and creates the alert.
 +
 For example, if a rule runs every 5 minutes but you don't need alerts that frequently, you can set the suppression time period to a longer time, such as 1 hour. If the rule meets its criteria, it creates an alert at that time, and for the next hour, it'll suppress any subsequent qualifying events.
 +
 image::images/alert-suppression-options.png[Alert suppression options,400]
 --
 
-. (Only available for custom query rules and indicator match rules) Under *If a suppression field is missing*, choose how to handle events with missing suppression fields (events in which one or more of the *Suppress alerts by* fields don't exist):
+. Under *If a suppression field is missing*, choose how to handle events with missing suppression fields (events in which one or more of the *Suppress alerts by* fields don't exist):
++
+NOTE: These options are not available for threshold rules. 
+
 * *Suppress and group alerts for events with missing fields*: Create one alert for each group of events with missing fields. Missing fields get a `null` value, which is used to group and suppress alerts. 
 * *Do not suppress alerts for events with missing fields*: Create a separate alert for each matching event. This basically falls back to normal alert creation for events with missing suppression fields.
 
@@ -101,5 +111,5 @@ image::images/timeline-button.png[Investigate in timeline button, 200]
 
 Some rule types have a maximum number of alerts that can be suppressed (custom query rules don't have a suppression limit):
 
-* **Threshold** - The maximum number of alerts is the value specified for the <<opt-fields-all,`max_signals`>> setting, which is `100` by default.
-* **Indicator match** - The maximum number is five times the value specified for the <<opt-fields-all,`max_signals`>> setting. The default `max_signals` value is `100`, which means the default maximum limit for indicator match rules is `500`.
+* **Threshold and event correlation (non-sequence queries only)** - The maximum number of alerts is the value you choose for the <<opt-fields-all,`max_signals`>> setting, which is `100` by default.
+* **Indicator match and new terms** - The maximum number is five times the value you choose for the <<opt-fields-all,`max_signals`>> setting. The default `max_signals` value is `100`, which means the default maximum limit for indicator match rules and new term rules is `500`.
diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc
@@ -491,11 +491,11 @@ a detection rule exception (`detection`) or an endpoint exception (`endpoint`).
 |==============================================
 
 [[opt-fields-alert-suppression-create]]
-===== Optional alert suppression fields for query, indicator match, and threshold rules
+===== Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), and new terms rules
 
 preview::[]
 
-====== Query rule and indicator match rule
+====== Query, indicator match, event correlation (non-sequence queries only), and new terms rules
 
 [width="100%",options="header"]
 |==============================================

diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc
@@ -516,11 +516,11 @@ in the UI (*Rules* -> *Detection rules (SIEM)* -> *_Rule name_*).
 
 
 [[opt-fields-alert-suppression-update]]
-===== Optional alert suppression fields for query, indicator match, and threshold rules
+===== Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), and new terms rules
 
 preview::[]
 
-====== Query rule and indicator match rule
+====== Query, indicator match, event correlation (non-sequence queries only), and new terms rules
 
 [width="100%",options="header"]
 |==============================================

diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc
@@ -157,6 +157,9 @@ NOTE: For sequence events, the {security-app} generates a single alert when all
   * *Tiebreaker field*: Sets a secondary field for sorting events (in ascending, lexicographic order) if they have the same timestamp.
   * *Timestamp field*: Contains the event timestamp used for sorting a sequence of events. This is different from the *Timestamp override* advanced setting, which is used for querying events within a range. Defaults to the `@timestamp` ECS field.
 +
+
+. preview:[] (Optional, https://www.elastic.co/pricing[Platinum or higher subscription] required) Use *Suppress alerts by* to reduce the number of repeated or duplicate alerts created by the rule. Refer to <<alert-suppression>> for more information.
+
 . Click *Continue* to <<rule-ui-basic-params, configure basic rule settings>>.
 
 [discrete]
@@ -254,6 +257,9 @@ IMPORTANT: When checking multiple fields, each unique combination of values from
 .. Use the *History Window Size* menu to specify the time range to search in minutes, hours, or days to determine if a term is new. The history window size must be larger than the rule interval plus additional look-back time, because the rule will look for terms where the only time(s) the term appears within the history window is _also_ within the rule interval and additional look-back time.
 +
 For example, if a rule has an interval of 5 minutes, no additional look-back time, and a history window size of 7 days, a term will be considered new only if the time it appears within the last 7 days is also within the last 5 minutes. Configure the rule interval and additional look-back time when you <<rule-schedule, set the rule's schedule>>.
+
+. preview:[] (Optional, https://www.elastic.co/pricing[Platinum or higher subscription] required) Use *Suppress alerts by* to reduce the number of repeated or duplicate alerts created by the rule. Refer to <<alert-suppression>> for more information.
+
 . Click *Continue* to <<rule-ui-basic-params, configure basic rule settings>>.
 
 [discrete]