From 5a259fe9e9d81a2c6b1743c458160366c09febc2 Mon Sep 17 00:00:00 2001 From: "mergify[bot]" <37929162+mergify[bot]@users.noreply.github.com> Date: Wed, 3 Jul 2024 16:31:23 -0400 Subject: [PATCH] Edit `max_signals` field for custom rules in UI [classic] (#5106) (#5504) * First draft * Update docs/detections/rules-ui-create.asciidoc * Revise note (in API docs too) * Update ESQL rule steps per https://github.com/elastic/staging-serverless-security-docs/pull/340#issuecomment-2103001892 * Revise alert suppression refs to max_signals * Explain max_signals = Max alerts per run * Add updates to "update rule" API too (cherry picked from commit 3bdfc228543273c4c8ec4ec3f4fcac6265844902) Co-authored-by: Joe Peeples --- docs/detections/alert-suppression.asciidoc | 4 ++-- docs/detections/api/rules/rules-api-create.asciidoc | 4 ++-- docs/detections/api/rules/rules-api-update.asciidoc | 6 ++++-- docs/detections/rules-ui-create.asciidoc | 10 ++++++---- 4 files changed, 14 insertions(+), 10 deletions(-) diff --git a/docs/detections/alert-suppression.asciidoc b/docs/detections/alert-suppression.asciidoc index d1489cb710..d620f7bd4e 100644 --- a/docs/detections/alert-suppression.asciidoc +++ b/docs/detections/alert-suppression.asciidoc @@ -113,5 +113,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 diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 0b60cba3de..440d335a4b 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -329,9 +329,9 @@ 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*: 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/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 6171e426e2..a3fdddf55d 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. diff --git a/docs/detections/rules-ui-create.asciidoc b/docs/detections/rules-ui-create.asciidoc index 74d785d93d..b80de6d82d 100644 --- a/docs/detections/rules-ui-create.asciidoc +++ b/docs/detections/rules-ui-create.asciidoc @@ -435,11 +435,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 maximum number of rows an {esql} query returns and the maximum 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 maximum number of rows an {esql} query returns and the maximum number of alerts created per rule execution. 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. @@ -534,6 +532,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 can create each time it runs. Default is 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 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`. + IMPORTANT: If your threat indicator data is at a different location, update this setting accordingly to ensure alert enrichment can still be performed.