From a220f575794afa8582640c3663a97c3b97564b2d Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Wed, 20 Dec 2023 12:15:42 -0500 Subject: [PATCH 1/4] Add query rule alert suppression to API docs --- .../api/rules/rules-api-update.asciidoc | 25 +++++++++++++++++++ 1 file changed, 25 insertions(+) diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index eb0b156e9c..39c5d89a5f 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -497,6 +497,31 @@ technique: NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed in the UI (*Rules* -> *Detection rules (SIEM)* -> *_Rule name_*). + +[[opt-fields-alert-suppression-update]] +===== Optional alert suppression fields for query rules + +preview::[] + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|alert_suppression |Object a|Defines alert suppression configuration. Available fields: + +* `group_by` (string[], required): An array of 1-3 field names to use for suppressing alerts. + +* `duration` (<>, optional): Defines the time period in which alerts will be suppressed. If absent, alerts will be suppressed on rule execution only. + +* `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Values: + + - `doNotSuppress` - Create a separate alert for each matching event. + + - `suppress` - Create one alert for each group of events with missing fields. + +|============================================== + + ===== Example request Updates the `threat` object: From 49aa8c9e521af39a5cd7878d08d43d63fa8cfdce Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Wed, 20 Dec 2023 12:22:44 -0500 Subject: [PATCH 2/4] Update rules-api-create.asciidoc Somehow the previous commit omitted this file --- .../api/rules/rules-api-create.asciidoc | 92 ++++++++++++++++++- 1 file changed, 87 insertions(+), 5 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 3a58fcf0ee..9ea0985607 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -486,6 +486,29 @@ a detection rule exception (`detection`) or an endpoint exception (`endpoint`). |============================================== +[[opt-fields-alert-suppression-create]] +===== Optional alert suppression fields for query rules + +preview::[] + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|alert_suppression |Object a|Defines alert suppression configuration. Available fields: + +* `group_by` (string[], required): An array of 1-3 field names to use for suppressing alerts. + +* `duration` (<>, optional): Defines the time period in which alerts will be suppressed. If absent, alerts will be suppressed on rule execution only. + +* `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Values: + + - `doNotSuppress`: Create a separate alert for each matching event. + + - `suppress`: Create one alert for each group of events with missing fields. + +|============================================== + [[actions-object-schema]] ===== `actions` schema @@ -712,6 +735,20 @@ All fields are required: NOTE: Only threats described using the MITRE ATT&CK^TM^ framework are displayed in the UI (*Rules* -> *Detection rules (SIEM)* -> *_Rule name_*). +[[alert-suppression-duration-schema]] +===== `alert_suppression.duration` schema + +All fields are required: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description + +|unit |string | Time unit, takes value of `s`(seconds), `m`(minutes), `h`(hours). +|value |number | Positive number + +|============================================== + ===== Example requests *Example 1* @@ -986,11 +1023,6 @@ POST api/detection_engine/rules -------------------------------------------------- // KIBANA -==== Response code - -`200`:: - Indicates a successful call. - *Example 7* {esql} rule that creates alerts from events that match an Excel parent process: @@ -1014,6 +1046,56 @@ POST api/detection_engine/rules } -------------------------------------------------- +*Example 8* + +Query rule that searches for processes started by MS Office and suppress alerts by `process.parent.name` field on 5 hours time period: + +[source,console] +-------------------------------------------------- +POST api/detection_engine/rules +{ + "rule_id": "process_started_by_ms_office_program", + "risk_score": 50, + "description": "Process started by MS Office program - possible payload", + "interval": "1h", + "name": "MS Office child process", + "severity": "low", + "tags": [ + "child process", + "ms office" + ], + "type": "query", + "from": "now-70m", + "query": "process.parent.name:EXCEL.EXE or process.parent.name:MSPUB.EXE or process.parent.name:OUTLOOK.EXE or process.parent.name:POWERPNT.EXE or process.parent.name:VISIO.EXE or process.parent.name:WINWORD.EXE", + "language": "kuery", + "filters": [ + { + "query": { + "match": { + "event.action": { + "query": "Process Create (rule: ProcessCreate)", + "type": "phrase" + } + } + } + } + ], + "enabled": false, + "alert_suppression": { + "duration": { "unit": "h", "value": 5 }, + "group_by": [ + "process.parent.name" + ], + "missing_fields_strategy": "suppress" + } +} +-------------------------------------------------- + +==== Response code + +`200`:: + Indicates a successful call. + ==== Response payload A JSON object that includes a unique ID, the time the rule was created, and its From 7d72f4717f39e0d6f0d2c8947f6701b1dbb722f0 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Wed, 3 Jan 2024 16:54:41 -0500 Subject: [PATCH 3/4] Apply suggestions from Natasha's review Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> --- docs/detections/api/rules/rules-api-create.asciidoc | 8 ++++---- docs/detections/api/rules/rules-api-update.asciidoc | 6 +++--- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 9ea0985607..51c0259b1d 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -501,7 +501,7 @@ preview::[] * `duration` (<>, optional): Defines the time period in which alerts will be suppressed. If absent, alerts will be suppressed on rule execution only. -* `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Values: +* `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Possible values: - `doNotSuppress`: Create a separate alert for each matching event. @@ -744,8 +744,8 @@ All fields are required: |============================================== |Name |Type |Description -|unit |string | Time unit, takes value of `s`(seconds), `m`(minutes), `h`(hours). -|value |number | Positive number +|unit |string | Time unit. Possible values are: `s`(seconds), `m`(minutes), or `h`(hours). +|value |number | Positive number. |============================================== @@ -1048,7 +1048,7 @@ POST api/detection_engine/rules *Example 8* -Query rule that searches for processes started by MS Office and suppress alerts by `process.parent.name` field on 5 hours time period: +Query rule that searches for processes started by MS Office and suppresses alerts by the `process.parent.name` field within a 5-hour time period: [source,console] -------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 39c5d89a5f..d51e7058c1 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -513,11 +513,11 @@ preview::[] * `duration` (<>, optional): Defines the time period in which alerts will be suppressed. If absent, alerts will be suppressed on rule execution only. -* `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Values: +* `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Possible values: - - `doNotSuppress` - Create a separate alert for each matching event. + - `doNotSuppress`: Create a separate alert for each matching event. - - `suppress` - Create one alert for each group of events with missing fields. + - `suppress`: Create one alert for each group of events with missing fields. |============================================== From 11f60845079b4fbb753568c16534571af8acd5f7 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Wed, 3 Jan 2024 17:01:20 -0500 Subject: [PATCH 4/4] Apply `duration` edits from Natasha's review --- docs/detections/api/rules/rules-api-create.asciidoc | 2 +- docs/detections/api/rules/rules-api-update.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 51c0259b1d..c42cfc8268 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -499,7 +499,7 @@ preview::[] * `group_by` (string[], required): An array of 1-3 field names to use for suppressing alerts. -* `duration` (<>, optional): Defines the time period in which alerts will be suppressed. If absent, alerts will be suppressed on rule execution only. +* `duration` (<>, optional): The time period in which alerts will be suppressed, beginning when the rule first meets its criteria and creates the alert. If not specified, alerts will be suppressed on rule execution only. * `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Possible values: diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index d51e7058c1..92982b55f4 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -511,7 +511,7 @@ preview::[] * `group_by` (string[], required): An array of 1-3 field names to use for suppressing alerts. -* `duration` (<>, optional): Defines the time period in which alerts will be suppressed. If absent, alerts will be suppressed on rule execution only. +* `duration` (<>, optional): The time period in which alerts will be suppressed, beginning when the rule first meets its criteria and creates the alert. If not specified, alerts will be suppressed on rule execution only. * `missing_fields_strategy` (string, optional): Defines how to handle events with missing suppression fields. Possible values: