From 93d001ba7c844ed1dbe7176e2c6b5f20bb969dbc Mon Sep 17 00:00:00 2001 From: Ryland Herrick Date: Thu, 23 Jun 2022 17:03:19 -0500 Subject: [PATCH 1/3] [DOCS] Adds warning about exceptions requiring mappings (#2110) * Move callout about endpoint exceptions to more appropriate section This not was previously at the top-level exceptions section, when it really only applies when adding to the Endpoint rule. * Add note about mappings being required for exceptions Wording is subject to change; just throwing something at the wall for now. * Apply suggestions from code review Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> Co-authored-by: nastasha-solomon <79124755+nastasha-solomon@users.noreply.github.com> (cherry picked from commit aeb69a60c27bdf3da3acc8696d8526ee4b0aaab4) # Conflicts: # docs/detections/detections-ui-exceptions.asciidoc --- .../detections-ui-exceptions.asciidoc | 52 +++++++++++++++++++ 1 file changed, 52 insertions(+) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index 7e1ebde02a..b4e7b7dae0 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -9,6 +9,7 @@ processes and network activity to function without producing unnecessary noise. You can add multiple exceptions to one rule. +<<<<<<< HEAD IMPORTANT: When you add an exception to the <> rule, you can select to add the exception to the Endpoint. When selected, the exception is added to @@ -16,6 +17,10 @@ both the detection rule *and* the Elastic Endpoint agent on your hosts. In addition to defining exception queries for source event values, rule exceptions can be used with value lists. Value lists are lists of items with +======= +In addition to defining exception queries for source event values, you can use rule +exceptions with value lists. Value lists are lists of items with +>>>>>>> aeb69a6 ([DOCS] Adds warning about exceptions requiring mappings (#2110)) the same {es} {ref}/mapping-types.html[data type]. You can create value lists with these types: @@ -67,9 +72,46 @@ You can add exceptions to a rule via 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. +<<<<<<< HEAD IMPORTANT: When you select to close all alerts that meet the exception's criteria, all matching alerts are closed, *including* alerts generated by other rules. +======= +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 exclude values from a +specific event in the sequence, update the rule's EQL statement. For example: + +[source,eql] +---- +`sequence + [file where file.extension == "exe" + and file.name != "app-name.exe"] + [process where true + and process.name != "process-name.exe"]` +---- +============== + +. Do one of the following: ++ +-- +* 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* -> *__*). +.. Scroll down below the rule details and select the *Exceptions* tab. ++ +[role="screenshot"] +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*. +.. 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*. +>>>>>>> aeb69a6 ([DOCS] Adds warning about exceptions requiring mappings (#2110)) . To add an exception via the Rule details page: .. Go to the Rule details page of the rule to which you want to add the @@ -134,6 +176,16 @@ with Elastic endpoint rule exceptions. To associate rules, when creating or editing a rule select the <> option. +[IMPORTANT] +===== +When you add an exception to the +<> rule, you can select to +add the exception to the endpoint. When selected, the exception is added to +both the detection rule *and* the {elastic-endpoint} agent on your hosts. + +{ref}/binary.html[Binary fields] are not supported in detection rule exceptions. +===== + [IMPORTANT] ============= Exceptions added to the Elastic Endpoint Security rule affect all alerts sent From 24ca1a9f4e27dec93dbd6add9f96bc9275f42f55 Mon Sep 17 00:00:00 2001 From: Ryland Herrick Date: Thu, 23 Jun 2022 17:39:15 -0500 Subject: [PATCH 2/3] Fix conflicts with 7.9 branch --- .../detections-ui-exceptions.asciidoc | 49 +------------------ 1 file changed, 1 insertion(+), 48 deletions(-) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index b4e7b7dae0..e7441742f7 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -9,18 +9,8 @@ processes and network activity to function without producing unnecessary noise. You can add multiple exceptions to one rule. -<<<<<<< HEAD -IMPORTANT: When you add an exception to the -<> rule, you can select to -add the exception to the Endpoint. When selected, the exception is added to -both the detection rule *and* the Elastic Endpoint agent on your hosts. - In addition to defining exception queries for source event values, rule exceptions can be used with value lists. Value lists are lists of items with -======= -In addition to defining exception queries for source event values, you can use rule -exceptions with value lists. Value lists are lists of items with ->>>>>>> aeb69a6 ([DOCS] Adds warning about exceptions requiring mappings (#2110)) the same {es} {ref}/mapping-types.html[data type]. You can create value lists with these types: @@ -72,46 +62,9 @@ You can add exceptions to a rule via 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. -<<<<<<< HEAD IMPORTANT: When you select to close all alerts that meet the exception's criteria, all matching alerts are closed, *including* alerts generated by other rules. -======= -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 exclude values from a -specific event in the sequence, update the rule's EQL statement. For example: - -[source,eql] ----- -`sequence - [file where file.extension == "exe" - and file.name != "app-name.exe"] - [process where true - and process.name != "process-name.exe"]` ----- -============== - -. Do one of the following: -+ --- -* 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* -> *__*). -.. Scroll down below the rule details and select the *Exceptions* tab. -+ -[role="screenshot"] -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*. -.. 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*. ->>>>>>> aeb69a6 ([DOCS] Adds warning about exceptions requiring mappings (#2110)) . To add an exception via the Rule details page: .. Go to the Rule details page of the rule to which you want to add the @@ -286,4 +239,4 @@ correctly: Creates an exception that excludes all LFC-signed trusted processes: [role="screenshot"] -image::images/nested-exp.png[] \ No newline at end of file +image::images/nested-exp.png[] From df06e03780d2bb01ef863ebf79524196e2888096 Mon Sep 17 00:00:00 2001 From: Ryland Herrick Date: Thu, 23 Jun 2022 17:56:07 -0500 Subject: [PATCH 3/3] Adds back the new callout Conflicts ended up deleting this previously. --- docs/detections/detections-ui-exceptions.asciidoc | 5 +++++ 1 file changed, 5 insertions(+) diff --git a/docs/detections/detections-ui-exceptions.asciidoc b/docs/detections/detections-ui-exceptions.asciidoc index e7441742f7..f43a53ca72 100644 --- a/docs/detections/detections-ui-exceptions.asciidoc +++ b/docs/detections/detections-ui-exceptions.asciidoc @@ -66,6 +66,11 @@ IMPORTANT: When you select to close all alerts that meet the exception's criteria, all matching alerts are closed, *including* alerts generated by other rules. +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. + . To add an exception via the Rule details page: .. Go to the Rule details page of the rule to which you want to add the exception (*Security* -> *Detections* -> *Manage detection rules* ->