From 32a6313afaf599bfa5cf3f3f5e847f91475247cd Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Thu, 4 Jan 2024 14:16:09 -0500 Subject: [PATCH] Backport query rule alert suppression to API docs (#4496) (#4569) * Add query rule alert suppression to API docs * Update rules-api-create.asciidoc Somehow the previous commit omitted this file * Apply suggestions from Natasha's review Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> * Apply `duration` edits from Natasha's review --------- Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> # Conflicts: # docs/detections/api/rules/rules-api-create.asciidoc --- .../api/rules/rules-api-create.asciidoc | 82 +++++++++++++++++++ .../api/rules/rules-api-update.asciidoc | 25 ++++++ 2 files changed, 107 insertions(+) diff --git a/docs/detections/api/rules/rules-api-create.asciidoc b/docs/detections/api/rules/rules-api-create.asciidoc index 991199dbf3..ecc8612ba8 100644 --- a/docs/detections/api/rules/rules-api-create.asciidoc +++ b/docs/detections/api/rules/rules-api-create.asciidoc @@ -465,6 +465,29 @@ must be an {es} date data type. |============================================== +[[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): 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: + + - `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 @@ -691,6 +714,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. Possible values are: `s`(seconds), `m`(minutes), or `h`(hours). +|value |number | Positive number. + +|============================================== + ===== Example requests *Example 1* @@ -965,6 +1002,51 @@ POST api/detection_engine/rules -------------------------------------------------- // KIBANA +*Example 7* + +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] +-------------------------------------------------- +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`:: diff --git a/docs/detections/api/rules/rules-api-update.asciidoc b/docs/detections/api/rules/rules-api-update.asciidoc index 98acc0d2af..644853de40 100644 --- a/docs/detections/api/rules/rules-api-update.asciidoc +++ b/docs/detections/api/rules/rules-api-update.asciidoc @@ -489,6 +489,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): 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: + + - `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: