From 3bb68526ba17d33c2f0da39dac27f291e3c20ef8 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 23 Apr 2024 09:27:21 -0400 Subject: [PATCH 1/7] First draft --- docs/detections/rules-ui-create.asciidoc | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index c854a77edf..43e8808cd5 100644 --- a/docs/detections/rules-ui-create.asciidoc +++ b/docs/detections/rules-ui-create.asciidoc @@ -476,6 +476,10 @@ also affect this rule. .. *Building block* (optional): Select to create a building-block rule. By default, alerts generated from a building-block rule are not displayed in the UI. See <> for more information. +.. **Max alerts per run** (optional): Specify the maximum number of alerts the rule will create each time it runs. Default is 100. ++ +NOTE: Do not set this value higher than the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. + .. *Indicator prefix override*: Define the location of indicator data within the structure of indicator documents. When the indicator match rule executes, it queries specified indicator indices and references this setting to locate fields with indicator data. This data is used to enrich indicator match alerts with metadata about matched threat indicators. The default value for this setting is `threat.indicator`. + IMPORTANT: If your threat indicator data is at a different location, update this setting accordingly to ensure alert enrichment can still be performed. From dbaa59ee388f30639b67e846a8c21793e805ce65 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 23 Apr 2024 10:37:18 -0400 Subject: [PATCH 2/7] Update docs/detections/rules-ui-create.asciidoc --- docs/detections/rules-ui-create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index 43e8808cd5..708f4a60b5 100644 --- a/docs/detections/rules-ui-create.asciidoc +++ b/docs/detections/rules-ui-create.asciidoc @@ -476,7 +476,7 @@ also affect this rule. .. *Building block* (optional): Select to create a building-block rule. By default, alerts generated from a building-block rule are not displayed in the UI. See <> for more information. -.. **Max alerts per run** (optional): Specify the maximum number of alerts the rule will create each time it runs. Default is 100. +.. **Max alerts per run** (optional): Specify the maximum number of alerts the rule can create each time it runs. Default is 100. + NOTE: Do not set this value higher than the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. From 57bf43bfa0796b35cae7c7fda3cf157ed312e15d Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Thu, 25 Apr 2024 14:23:49 -0400 Subject: [PATCH 3/7] Revise note (in API docs too) --- docs/detections/api/rules/rules-api-create.asciidoc | 2 +- docs/detections/rules-ui-create.asciidoc | 2 +- 2 files changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 1a27e02c7a..60301d1a49 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -333,7 +333,7 @@ means the rule runs every hour. Defaults to `5m` (5 minutes). |max_signals |Integer a|Maximum number of alerts the rule can create during a single execution. Defaults to `100`. -*NOTE*: To avoid rule failures, do not set the `max_signals` value higher than the value of {kibana-ref}/alert-action-settings-kb.html#alert-settings[`xpack.alerting.rules.run.alerts.max`]. +NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if `max_signals` is set higher. |meta |Object a|Placeholder for metadata about the rule. diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index b6340209d5..5e47b355b4 100644 --- a/docs/detections/rules-ui-create.asciidoc +++ b/docs/detections/rules-ui-create.asciidoc @@ -461,7 +461,7 @@ default, alerts generated from a building-block rule are not displayed in the UI. See <> for more information. .. **Max alerts per run** (optional): Specify the maximum number of alerts the rule can create each time it runs. Default is 100. + -NOTE: Do not set this value higher than the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. +NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if **Max alerts per run** is set higher. .. *Indicator prefix override*: Define the location of indicator data within the structure of indicator documents. When the indicator match rule executes, it queries specified indicator indices and references this setting to locate fields with indicator data. This data is used to enrich indicator match alerts with metadata about matched threat indicators. The default value for this setting is `threat.indicator`. + From f1aa5b13f7b0dd230615f857c6e04f0135d7c2a1 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Thu, 9 May 2024 12:36:29 -0400 Subject: [PATCH 4/7] Update ESQL rule steps per https://github.com/elastic/staging-serverless-security-docs/pull/340#issuecomment-2103001892 --- docs/detections/rules-ui-create.asciidoc | 6 ++---- 1 file changed, 2 insertions(+), 4 deletions(-) diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index 4d37a7df5d..b0bca4d456 100644 --- a/docs/detections/rules-ui-create.asciidoc +++ b/docs/detections/rules-ui-create.asciidoc @@ -367,11 +367,9 @@ FROM logs-* [metadata _id, _index, _version] When writing your query, consider the following: -- The {ref}/esql-commands.html#esql-limit[`LIMIT`] command specifies the number of rows an {esql} query returns and the number of alerts created per rule execution. Similarly, a detection rule's <> setting specifies the maximum number of alerts it can create every time it runs. +- The {ref}/esql-commands.html#esql-limit[`LIMIT`] command specifies the number of rows an {esql} query returns and the number of alerts created per rule run. Similarly, a detection rule's **Max alerts per run** setting specifies the maximum number of alerts it can create every time it runs. + -If the `LIMIT` value is lower than the `max_signals` value, the rule uses the `LIMIT` value to determine the maximum number of alerts the rule generates. If the `LIMIT` value is higher than the `max_signals` value, the rule uses the `max_signals` value. -+ -NOTE: The `max_signals` default value is 100. You can modify it using the <>. +If the `LIMIT` value and **Max alerts per run** value are different, the rule uses the lower value to determine the maximum number of alerts the rule generates. + - 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. From ad24226b3c906382b0da58b3963f677a16c45028 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 10 May 2024 11:41:51 -0400 Subject: [PATCH 5/7] Revise alert suppression refs to max_signals --- docs/detections/alert-suppression.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/detections/alert-suppression.asciidoc b/docs/detections/alert-suppression.asciidoc index 9bf79afce9..944c0d5bf2 100644 --- a/docs/detections/alert-suppression.asciidoc +++ b/docs/detections/alert-suppression.asciidoc @@ -111,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 and event correlation (non-sequence queries only)** - The maximum number of alerts is the value you choose for the <> setting, which is `100` by default. -* **Indicator match and new terms** - The maximum number is five times the value you choose for the <> setting. The default `max_signals` 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 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 From 785967a6d40f52a16ae27699901f15a5f6b53203 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 10 May 2024 11:52:17 -0400 Subject: [PATCH 6/7] Explain max_signals = Max alerts per run --- docs/detections/api/rules/rules-api-create.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index a2f8585ce5..85eb16c391 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -329,7 +329,7 @@ means the rule runs every hour. Defaults to `5m` (5 minutes). |license |String |The rule's license. |max_signals |Integer a|Maximum number of alerts the rule can create during a -single execution. Defaults to `100`. +single run (the rule's **Max alerts per run** <> value). Defaults to `100`. NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if `max_signals` is set higher. From 728150640da3bdc704fd96c46cd1554c9653f7fe Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 10 May 2024 11:52:55 -0400 Subject: [PATCH 7/7] Add updates to "update rule" API too --- docs/detections/api/rules/rules-api-update.asciidoc | 6 ++++-- 1 file changed, 4 insertions(+), 2 deletions(-) diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 06d267226b..17dbb05521 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -232,8 +232,10 @@ means the rule runs every hour. Defaults to `5m` (5 minutes). |license |String |The rule's license. -|max_signals |Integer |Maximum number of alerts the rule can create during a -single execution. Defaults to `100`. +|max_signals |Integer a|Maximum number of alerts the rule can create during a +single run (the rule's **Max alerts per run** <> value). Defaults to `100`. + +NOTE: This setting can be superseded by the {kibana-ref}/alert-action-settings-kb.html#alert-settings[{kib} configuration setting] `xpack.alerting.rules.run.alerts.max`, which determines the maximum alerts generated by _any_ rule in the {kib} alerting framework. For example, if `xpack.alerting.rules.run.alerts.max` is set to `1000`, the rule can generate no more than 1000 alerts even if `max_signals` is set higher. |meta |Object a|Placeholder for metadata about the rule.