From e1cdd1f19944837233822c63330d122a7b3353bb Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 22 Jul 2022 08:49:37 -0400 Subject: [PATCH 1/8] Add `matches`, revise condition steps --- .../detections-ui-exceptions.asciidoc | 41 +++++++++++-------- 1 file changed, 24 insertions(+), 17 deletions(-) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index 15fd1bb28e..8e882a504a 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -117,27 +117,34 @@ The *Add Rule Exception* flyout opens (the example below was opened from the Ale + [role="screenshot"] image::images/add-exception-ui.png[] -. Add conditions that define when the exception prevents alerts. You can define -multiple conditions with `OR` and `AND` relationships. In the example above, -the exception prevents the rule from generating alerts when the +. Use the following settings to add conditions that define when the exception prevents alerts. In the example above, the exception prevents the rule from generating alerts when the `svchost.exe` process runs on agent hostname `siem-kibana`. -+ -[IMPORTANT] -============ -* You can use nested conditions. However, this is only required for -<>. For all other fields, nested conditions -should not be used. -* Wildcards are not supported in rule exceptions or value lists. Values must be literal values. -============ + .. *Field*: Select a field to identify the event being filtered. + + .. *Operator*: Select an operator to define the condition. Available options are: + * `is`, `is not` — Must be an exact match of the defined value. + * `is one of`, `is not one of` — Matches any of the defined values. + * `exists`, `does not exist` — The defined field exists. + * `is in list`, `is not in list` — The field matches values in a value list. + -If you have created value lists, you can use them to exclude or include all -values in a list with `is in list` and `is not in list` operators: +[NOTE] +======= +* When using a list, all conditions in an exception must use the `is in list` or `is not in list` operator. +* Wildcards are not supported in value lists. +======= + * `matches`: Allows you to use wildcards in *Value*, such as `C:\path\*\app.exe`. Available wildcards are `?` (match one character) and `*` (match zero or more characters). + -[role="screenshot"] -image::images/exceptions-ui-list.png[] -NOTE: When using a list, all exception statements must use `is in list` and -`is not in list` operators. +IMPORTANT: Using wildcards in file paths can impact performance. To create a more efficient exception using wildcards, use multiple conditions and make them as specific as possible. For example, adding conditions using `process.name` or `file.name` can help limit the scope of wildcard matching. + + .. *Value*: Enter the value associated with the *Field*. To enter multiple values (when using `is one of` or `is not one of`), enter each value, then press **Return**. + +. Click *AND* or *OR* to create multiple conditions and define their relationships. + +. Click *Add nested condition* to create conditions using nested fields. This is only required for +<>. For all other fields, nested conditions should not be used. + +. (Optional) Enter a comment describing the exception. . Select one of the following alert actions: From a6819995b4434fc26cf30bf1a75ee4baf8b5989e Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Mon, 25 Jul 2022 16:06:11 -0400 Subject: [PATCH 2/8] Various edits --- docs/detections/detections-ui-exceptions.asciidoc | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index 8e882a504a..de7f562d36 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -122,20 +122,20 @@ image::images/add-exception-ui.png[] .. *Field*: Select a field to identify the event being filtered. - .. *Operator*: Select an operator to define the condition. Available options are: + .. *Operator*: Select an operator to define the condition: * `is`, `is not` — Must be an exact match of the defined value. - * `is one of`, `is not one of` — Matches any of the defined values. - * `exists`, `does not exist` — The defined field exists. - * `is in list`, `is not in list` — The field matches values in a value list. + * `is one of`, `is not one of` — Matches any of the defined values. + * `exists`, `does not exist` — The defined field exists. + * `is in list`, `is not in list` — Matches values in a value list. + [NOTE] ======= * When using a list, all conditions in an exception must use the `is in list` or `is not in list` operator. * Wildcards are not supported in value lists. ======= - * `matches`: Allows you to use wildcards in *Value*, such as `C:\path\*\app.exe`. Available wildcards are `?` (match one character) and `*` (match zero or more characters). + * `matches`, `does not match` — Allows you to use wildcards in *Value*, such as `C:\path\*\app.exe`. Available wildcards are `?` (match one character) and `*` (match zero or more characters). The selected *Field* data type must be a {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. + -IMPORTANT: Using wildcards in file paths can impact performance. To create a more efficient exception using wildcards, use multiple conditions and make them as specific as possible. For example, adding conditions using `process.name` or `file.name` can help limit the scope of wildcard matching. +IMPORTANT: Using wildcards can impact performance. To create a more efficient exception using wildcards, use multiple conditions and make them as specific as possible. For example, adding conditions using `process.name` or `file.name` can help limit the scope of wildcard matching. .. *Value*: Enter the value associated with the *Field*. To enter multiple values (when using `is one of` or `is not one of`), enter each value, then press **Return**. From 1f7672d0a59117d42040ec2284b527a7efb10fd0 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 2 Aug 2022 15:43:19 -0400 Subject: [PATCH 3/8] Update API, other adjustments --- .../api/exceptions/api-create-exception-item.asciidoc | 9 +++++---- docs/detections/detections-ui-exceptions.asciidoc | 10 +++++----- 2 files changed, 10 insertions(+), 9 deletions(-) diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 6f994935fc..9a539ae613 100644 --- a/docs/detections/api/exceptions/api-create-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-item.asciidoc @@ -4,7 +4,7 @@ Creates an exception item and associates it with the specified <>. -See <> for information about creating exception items from +Refer to <> for information about creating exception items from lists, such as a list of IP addresses or host names. NOTE: Before creating exception items, you must create an exception container. @@ -98,10 +98,11 @@ Can be: * `match`: Must be an exact match of the defined value. * `match_any`: Matches any of the defined values. -* `exists`: The `field` exists. +* `exists`: The field exists. * `list`: The field matches values in a list container. +* `wildcard`: Matches `value` using wildcards, such as `C:\path\*\app.exe`. Use `?` to match one character and `*` to match zero or more characters. The `field` data type must be a {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. * `nested`: Array of `entries` objects. Nested conditions are required for -excluding some Endpoint fields (<>). +excluding some Endpoint fields (<>). <> lists all Endpoint fields that require the `nested` type. @@ -114,7 +115,7 @@ String[] a|Field value or values: -* String: When the `type` is `match`. +* String: When the `type` is `match` or `wildcard`. * String[]: When the `type` is `match_any`. |Yes, except when `type` is `exists` or `list`. diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index de7f562d36..c9f8f3709a 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -123,17 +123,17 @@ image::images/add-exception-ui.png[] .. *Field*: Select a field to identify the event being filtered. .. *Operator*: Select an operator to define the condition: - * `is`, `is not` — Must be an exact match of the defined value. - * `is one of`, `is not one of` — Matches any of the defined values. - * `exists`, `does not exist` — The defined field exists. - * `is in list`, `is not in list` — Matches values in a value list. + * `is` | `is not` — Must be an exact match of the defined value. + * `is one of` | `is not one of` — Matches any of the defined values. + * `exists` | `does not exist` — The defined field exists. + * `is in list` | `is not in list` — Matches values in a value list. + [NOTE] ======= * When using a list, all conditions in an exception must use the `is in list` or `is not in list` operator. * Wildcards are not supported in value lists. ======= - * `matches`, `does not match` — Allows you to use wildcards in *Value*, such as `C:\path\*\app.exe`. Available wildcards are `?` (match one character) and `*` (match zero or more characters). The selected *Field* data type must be a {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. + * `matches` | `does not match` — Allows you to use wildcards in *Value*, such as `C:\path\*\app.exe`. Available wildcards are `?` (match one character) and `*` (match zero or more characters). The selected *Field* data type must be a {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. + IMPORTANT: Using wildcards can impact performance. To create a more efficient exception using wildcards, use multiple conditions and make them as specific as possible. For example, adding conditions using `process.name` or `file.name` can help limit the scope of wildcard matching. From 69c68b1e099bce688d4238405e776d30ff799982 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 2 Aug 2022 15:46:20 -0400 Subject: [PATCH 4/8] Consolidate stacked admonitions --- docs/detections/detections-ui-exceptions.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index c9f8f3709a..3db90a886e 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -77,15 +77,15 @@ You can add exceptions to a rule from the rule details page or the Alerts table. When you add an exception, you can also close all alerts that meet the exception's criteria. -IMPORTANT: To ensure an exception is successfully applied, make sure that the fields you've defined for the exception query are correctly and consistently mapped in their respective indices. Refer to {ecs-ref}[ECS] to learn more about supported mappings. - [IMPORTANT] ============== -Be careful when adding exceptions to event correlation rules. Exceptions are evaluated against every event in the sequence, and when the exception matches _all_ event(s) in the sequence, alerts _are not_ generated. If the exception only matches _some_ of the events in the sequence, alerts _are_ generated. +* To ensure an exception is successfully applied, make sure that the fields you've defined for the exception query are correctly and consistently mapped in their respective indices. Refer to {ecs-ref}[ECS] to learn more about supported mappings. +* Be careful when adding exceptions to event correlation rules. Exceptions are evaluated against every event in the sequence, and when the exception matches _all_ event(s) in the sequence, alerts _are not_ generated. If the exception only matches _some_ of the events in the sequence, alerts _are_ generated. ++ To exclude values from a specific event in the sequence, update the rule's EQL statement. For example: - ++ [source,eql] ---- `sequence From 13200856dc2fcb6fc94d1bb55ed4736e2f3f21f1 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Tue, 2 Aug 2022 15:50:08 -0400 Subject: [PATCH 5/8] Revise ableist language --- docs/detections/detections-ui-exceptions.asciidoc | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index 3db90a886e..b7d4449995 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -67,7 +67,7 @@ To view, delete, or export existing value lists: [role="screenshot"] image::images/manage-value-list.png[] -TIP: You can also use value lists as the indicator match index when creating an indicator match rule. See <> for more information. +TIP: You can also use value lists as the indicator match index when creating an indicator match rule. Refer to <> for more information. [float] [[detection-rule-exceptions]] @@ -204,7 +204,7 @@ The *Add Endpoint Exception* flyout opens, from either the rule details page or image::images/endpoint-add-exp.png[] . If required, modify the conditions. + -NOTE: See <> for more information on when nested conditions are required. +NOTE: Refer to <> for more information on when nested conditions are required. . You can select any of the following: @@ -304,8 +304,8 @@ If no attribute is selected, the app searches the list name by default. To export or delete an exception list, select the required action button on the appropriate list. Note that: * Exception lists are exported to `.ndjson` files. -* Exception lists are also exported as part of any exported detection rules configured with exceptions. See <>. -* If a list is linked to any rules, you'll see a warning appear that asks you to confirm the deletion. If no rules are linked to a list, it is deleted without confirmation. +* Exception lists are also exported as part of any exported detection rules configured with exceptions. Refer to <>. +* If a list is linked to any rules, you'll get a warning appear asking you to confirm the deletion. If no rules are linked to a list, it is deleted without confirmation. [role="screenshot"] image::images/actions-exception-list.png[Detail of Exception lists table with export and delete buttons highlighted,400] From 2b2fdf8fb4927d1bf765522384fe76b455d7bdf2 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Wed, 3 Aug 2022 12:44:12 -0400 Subject: [PATCH 6/8] Revise for new grouped navigation UI --- docs/detections/detections-ui-exceptions.asciidoc | 14 +++++++------- 1 file changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index b7d4449995..f63a783a9f 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -41,7 +41,7 @@ act as value delimiters. * Wildcards are not supported in rule exceptions or value lists. Values must be literal values. ========================= -. Go to *Detect* -> *Rules*. +. Go to *Manage* -> *Rules*. . Click *Upload value lists*. The *Upload value lists* window opens. + [role="screenshot"] @@ -60,7 +60,7 @@ the new file are appended to the previously uploaded values. To view, delete, or export existing value lists: -. Go to *Detect* -> *Rules*. +. Go to *Manage* -> *Rules*. . Click *Upload value lists*. The *Upload value lists* window opens. . In the *Value lists* table, click the required action button. @@ -101,7 +101,7 @@ specific event in the sequence, update the rule's EQL statement. For example: -- * To add an exception from the rule details page: .. Go to the rule details page of the rule to which you want to add an -exception (*Detect* -> *Rules* -> *__*). +exception (*Manage* -> *Rules* -> *__*). .. Scroll down below the rule details and select the *Exceptions* tab. + [role="screenshot"] @@ -109,7 +109,7 @@ image::images/exception-histogram.png[Detail of Exceptions tab, 75%] .. Click *Add new exception* -> *Add rule exception*. * To add an exception from the Alerts table: -.. Go to *Detect* -> *Alerts*. +.. Go to *Alerts*. .. Scroll down to the Alerts table, go to the alert you want to create an exception for, click the *More Actions* menu (*...*), then select *Add rule exception*. The *Add Rule Exception* flyout opens (the example below was opened from the Alerts table): @@ -189,11 +189,11 @@ Additionally, to add an Endpoint exception to the Elastic Endpoint Security rule + -- * To add an Endpoint exception from the rule details page: -.. Go to the rule details page (*Detect* -> *Rules*), and then search for and select the Elastic *Endpoint Security* rule. +.. Go to the rule details page (*Manage* -> *Rules*), and then search for and select the Elastic *Endpoint Security* rule. .. Scroll down to the *Trend* histogram and select the *Exceptions* tab. .. Click *Add new exception* -> *Add Endpoint exception*. * To add an Endpoint exception from the Alerts table: -.. Go to *Detect* -> *Alerts*. +.. Go to *Alerts*. .. Scroll down to the Alerts table, and from an {elastic-endpoint} alert, click the *More actions* menu (*...*), then select *Add Endpoint exception*. -- @@ -282,7 +282,7 @@ image::images/nested-exp.png[] [[manage-exceptions]] === View and manage exception lists -The Exception lists table enables you to view and manage all exceptions that have been assigned to rules. To view the Exception lists table, go to *Detect* -> *Exception lists*. +The Exception lists table enables you to view and manage all exceptions that have been assigned to rules. To view the Exception lists table, go to *Manage* -> *Exception lists*. [role="screenshot"] image::images/exceptions-page.png[] From 3f034c4b8b41117168ad55715f8187b660044322 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 5 Aug 2022 11:32:56 -0400 Subject: [PATCH 7/8] Apply suggestions from Ben's review Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- .../api/exceptions/api-create-exception-item.asciidoc | 2 +- docs/detections/detections-ui-exceptions.asciidoc | 8 ++++---- 2 files changed, 5 insertions(+), 5 deletions(-) diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 9a539ae613..8c780066bd 100644 --- a/docs/detections/api/exceptions/api-create-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-item.asciidoc @@ -100,7 +100,7 @@ Can be: * `match_any`: Matches any of the defined values. * `exists`: The field exists. * `list`: The field matches values in a list container. -* `wildcard`: Matches `value` using wildcards, such as `C:\path\*\app.exe`. Use `?` to match one character and `*` to match zero or more characters. The `field` data type must be a {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. +* `wildcard`: Matches `value` using wildcards, such as `C:\path\*\app.exe`. Use `?` to match one character and `*` to match zero or more characters. The `field` data type must be {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. * `nested`: Array of `entries` objects. Nested conditions are required for excluding some Endpoint fields (<>). <> lists all Endpoint fields that require the `nested` diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index f63a783a9f..4470fad1e3 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -67,7 +67,7 @@ To view, delete, or export existing value lists: [role="screenshot"] image::images/manage-value-list.png[] -TIP: You can also use value lists as the indicator match index when creating an indicator match rule. Refer to <> for more information. +TIP: You can also use a value list as the indicator match index when creating an indicator match rule. Refer to <> for more information. [float] [[detection-rule-exceptions]] @@ -81,7 +81,7 @@ exception's criteria. ============== * To ensure an exception is successfully applied, make sure that the fields you've defined for the exception query are correctly and consistently mapped in their respective indices. Refer to {ecs-ref}[ECS] to learn more about supported mappings. -* Be careful when adding exceptions to event correlation rules. Exceptions are evaluated against every event in the sequence, and when the exception matches _all_ event(s) in the sequence, alerts _are not_ generated. If the exception only matches _some_ of the events in the sequence, alerts _are_ generated. +* Be careful when adding exceptions to <> rules. Exceptions are evaluated against every event in the sequence, and when the exception matches _all_ event(s) in the sequence, alerts _are not_ generated. If the exception only matches _some_ of the events in the sequence, alerts _are_ generated. + To exclude values from a specific event in the sequence, update the rule's EQL statement. For example: @@ -125,7 +125,7 @@ image::images/add-exception-ui.png[] .. *Operator*: Select an operator to define the condition: * `is` | `is not` — Must be an exact match of the defined value. * `is one of` | `is not one of` — Matches any of the defined values. - * `exists` | `does not exist` — The defined field exists. + * `exists` | `does not exist` — The field exists. * `is in list` | `is not in list` — Matches values in a value list. + [NOTE] @@ -133,7 +133,7 @@ image::images/add-exception-ui.png[] * When using a list, all conditions in an exception must use the `is in list` or `is not in list` operator. * Wildcards are not supported in value lists. ======= - * `matches` | `does not match` — Allows you to use wildcards in *Value*, such as `C:\path\*\app.exe`. Available wildcards are `?` (match one character) and `*` (match zero or more characters). The selected *Field* data type must be a {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. + * `matches` | `does not match` — Allows you to use wildcards in *Value*, such as `C:\path\*\app.exe`. Available wildcards are `?` (match one character) and `*` (match zero or more characters). The selected *Field* data type must be {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. + IMPORTANT: Using wildcards can impact performance. To create a more efficient exception using wildcards, use multiple conditions and make them as specific as possible. For example, adding conditions using `process.name` or `file.name` can help limit the scope of wildcard matching. From 9a094636d903721314f4dc640f494afb994dd468 Mon Sep 17 00:00:00 2001 From: Joe Peeples Date: Fri, 12 Aug 2022 09:02:12 -0400 Subject: [PATCH 8/8] Apply suggestions from review --- docs/detections/detections-ui-exceptions.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index 4470fad1e3..4eea9c36aa 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -130,7 +130,7 @@ image::images/add-exception-ui.png[] + [NOTE] ======= -* When using a list, all conditions in an exception must use the `is in list` or `is not in list` operator. +* An exception defined by a value list must use `is in list` or `is not in list` in all conditions. * Wildcards are not supported in value lists. ======= * `matches` | `does not match` — Allows you to use wildcards in *Value*, such as `C:\path\*\app.exe`. Available wildcards are `?` (match one character) and `*` (match zero or more characters). The selected *Field* data type must be {ref}/keyword.html#keyword-field-type[keyword], {ref}/text.html#text-field-type[text], or {ref}/keyword.html#wildcard-field-type[wildcard]. @@ -305,7 +305,7 @@ To export or delete an exception list, select the required action button on the * Exception lists are exported to `.ndjson` files. * Exception lists are also exported as part of any exported detection rules configured with exceptions. Refer to <>. -* If a list is linked to any rules, you'll get a warning appear asking you to confirm the deletion. If no rules are linked to a list, it is deleted without confirmation. +* If an exception list is linked to any rules, you'll get a warning asking you to confirm the deletion. If no rules are linked, the list is deleted without confirmation. [role="screenshot"] image::images/actions-exception-list.png[Detail of Exception lists table with export and delete buttons highlighted,400]