diff --git a/docs/detections/alert-suppression.asciidoc b/docs/detections/alert-suppression.asciidoc index d620f7bd4e..73f0537840 100644 --- a/docs/detections/alert-suppression.asciidoc +++ b/docs/detections/alert-suppression.asciidoc @@ -16,6 +16,8 @@ Alert suppression allows you to reduce the number of repeated or duplicate detec * <> * <> (non-sequence queries only) * <> +* <> +* <> 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. @@ -25,16 +27,13 @@ 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 documentation for creating <>, <>, <>, or <> rules for detailed instructions. +You can configure alert suppression when you create or edit a supported rule type. Refer to documentation for creating <>, <>, <>, <>, <>, or <> 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. +* **Custom query, indicator match, threshold, event correlation (non-sequence queries only), new terms, {ml}, and {esql} rules:** 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. -- + @@ -42,14 +41,14 @@ You can configure alert suppression when you create or edit a supported rule typ ====== If you specify a field with multiple values, alerts with that field are handled as follows: -* **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. +* **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, event correlation (non-sequence queries only), new terms, {esql}, or {ml} rules:** 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. +NOTE: Both options are available for custom query, indicator match, event correlation, new terms, {esql}, and {ml} rules. Threshold rules only have the *Per time period* option. + -- * *Per rule execution*: Create an alert each time the rule runs and meets its criteria. @@ -113,5 +112,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 and event correlation (non-sequence queries only)** - The maximum number of alerts is the value you choose for the rule's **Max alerts per run** <>, which is `100` by default. -* **Indicator match and new terms** - The maximum number is five times the value you choose for the rule's **Max alerts per run** <>. The default value is `100`, which means the default maximum limit for indicator match rules and new term rules is `500`. \ No newline at end of file +* **Threshold, event correlation (non-sequence queries only), {esql}, and {ml}:** The maximum number of alerts is the value you choose for the rule's **Max alerts per run** <>, which is `100` by default. +* **Indicator match and new terms:** The maximum number is five times the value you choose for the rule's **Max alerts per run** <>. The default value is `100`, which means the default maximum limit for indicator match rules and new term rules is `500`. \ No newline at end of file diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 82ea9e8ae5..a39dfefb66 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -503,11 +503,11 @@ a detection rule exception (`detection`) or an endpoint exception (`endpoint`). |============================================== [[opt-fields-alert-suppression-create]] -===== Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), and new terms rules +===== Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), new terms, {esql}, and {ml} rules -preview::["Alert suppression is in technical preview for threshold, indicator match, event correlation, and new terms rules. The functionality may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."] +preview::["Alert suppression is in technical preview for threshold, indicator match, event correlation, new terms, {ml}, and {esql} rules. The functionality may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."] -====== Query, indicator match, event correlation (non-sequence queries only), and new terms rules +====== Query, indicator match, event correlation (non-sequence queries only), new terms, {esql}, and {ml} 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 index 3ce24d139c..cac28ad2ff 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -532,11 +532,11 @@ in the UI (*Rules* -> *Detection rules (SIEM)* -> *_Rule name_*). [[opt-fields-alert-suppression-update]] -===== Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), and new terms rules +===== Optional alert suppression fields for query, indicator match, threshold, event correlation (non-sequence queries only), new terms, {esql}, and {ml} rules -preview::["Alert suppression is in technical preview for threshold, indicator match, event correlation, and new terms rules. The functionality may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."] +preview::["Alert suppression is in technical preview for threshold, indicator match, event correlation, new terms, {ml}, and {esql} rules. The functionality may be changed or removed in a future release. Elastic will work to fix any issues, but features in technical preview are not subject to the support SLA of official GA features."] -====== Query, indicator match, event correlation (non-sequence queries only), and new terms rules +====== Query, indicator match, event correlation (non-sequence queries only), new terms, {esql}, and {ml} rules [width="100%",options="header"] |============================================== diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index 3d361f742f..dcb8574274 100644 --- a/docs/detections/rules-ui-create.asciidoc +++ b/docs/detections/rules-ui-create.asciidoc @@ -46,6 +46,10 @@ then select: NOTE: If a required job isn't currently running, it will automatically start when you finish configuring and enable the rule. .. The anomaly score threshold above which alerts are created. + +. 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 <> for more information. ++ +NOTE: Because {ml} rules generate alerts from anomalies, which don't contain source event fields, you can only use anomaly fields when configuring alert suppression. ++ //// The following step is repeated across all rule types. If you change anything @@ -353,6 +357,9 @@ NOTE: Refer to the sections below to learn more about <> for more information. ++ + //// The following steps are repeated across multiple rule types. If you change anything in these steps or sub-steps, apply the change to the other rule types, too. @@ -466,6 +473,8 @@ If the `LIMIT` value and **Max alerts per run** value are different, the rule us - When writing an aggregating query, use the {ref}/esql-commands.html#esql-stats-by[`STATS...BY`] command with fields that you want to search and filter for after alerts are created. For example, using the `host.name`, `user.name`, `process.name` fields with the `BY` operator of the `STATS...BY` command returns these fields in alert documents, and allows you to search and filter for them from the Alerts table. +- When configuring alert suppression on a non-aggregating query, we recommend sorting results by ascending `@timestamp` order. Doing so ensures that alerts are properly suppressed, especially if the number of alerts generated is higher than the **Max alerts per run** value. + [float] [[esql-rule-limitations]] ==== {esql} rule limitations