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 diff --git a/docs/serverless/alerts/alert-suppression.mdx b/docs/serverless/alerts/alert-suppression.mdx index 1a9d1dd6c3..462c03402e 100644 --- a/docs/serverless/alerts/alert-suppression.mdx +++ b/docs/serverless/alerts/alert-suppression.mdx @@ -20,6 +20,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. @@ -31,28 +33,25 @@ Alert suppression is not available for Elastic prebuilt rules. However, if you w ## 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. 1. 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 rule, indicator match, threshold, event correlation (non-sequence queries only), new terms, ((esql)), or ((ml)) 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. If you specify a field with multiple values, alerts with that field are handled as follows: - * **Custom query or threshold rules** - Alerts are grouped by each unique 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), 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:** Alerts are grouped by each unique 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. 1. If available, select how often to create alerts for duplicate events: - Both options are available for custom query, indicator match, event correlation, and new terms rules. Threshold rules only have the **Per time period** option. + 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 an event meets its criteria. @@ -112,5 +111,5 @@ With alert suppression, detection alerts aren't created for the grouped source e 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 is the value you choose for the rule's **Max alerts per run** advanced setting, which is `100` by default. -* **Indicator match and new terms** - The maximum number is five times the value you choose for the the rule's **Max alerts per run** advanced setting. The default value is `100`, which means the default maximum limit for indicator match rules and new terms rules is `500`. \ No newline at end of file +* **Threshold, event correlation (non-sequence queries only, ((esql)), and ((ml)):** The maximum number is the value you choose for the rule's **Max alerts per run** advanced setting, which is `100` by default. +* **Indicator match and new terms:** The maximum number is five times the value you choose for the the rule's **Max alerts per run** advanced setting. The default value is `100`, which means the default maximum limit for indicator match rules and new terms rules is `500`. \ No newline at end of file diff --git a/docs/serverless/rules/rules-ui-create.mdx b/docs/serverless/rules/rules-ui-create.mdx index 101f63e24a..8adac54f67 100644 --- a/docs/serverless/rules/rules-ui-create.mdx +++ b/docs/serverless/rules/rules-ui-create.mdx @@ -49,6 +49,12 @@ To create or edit ((ml)) rules, you need an appropriate user role. Additionally, 1. The anomaly score threshold above which alerts are created. +1. (Optional) Use **Suppress alerts by** to reduce the number of repeated or duplicate alerts created by the rule. Refer to Suppress detection alerts for more information. + + + 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 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. */} 1. (Optional) Add **Related integrations** to associate the rule with one or more [Elastic integrations](((integrations-docs))). This indicates the rule's dependency on specific integrations and the data they generate, and allows users to confirm each integration's installation status when viewing the rule. @@ -383,6 +389,8 @@ To create an ((esql)) rule: Click the help icon () to open the in-product reference documentation for all ((esql)) commands and functions. +1. (Optional) Use **Suppress alerts by** to reduce the number of repeated or duplicate alerts created by the rule. Refer to Suppress detection alerts 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. */} 1. (Optional) Create a list of **Required fields** that the rule needs to function. This list is informational only, to help users understand the rule; it doesn't affect how the rule actually runs. @@ -500,6 +508,8 @@ When writing your query, consider the following: - When writing an aggregating query, use the [`STATS...BY`](((ref))/esql-commands.html#esql-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. +
### ((esql)) rule limitations