diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 6f994935fc..8c780066bd 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 {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 155662c785..4eea9c36aa 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 a value list as the indicator match index when creating an indicator match rule. Refer to <> for more information. [float] [[detection-rule-exceptions]] @@ -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 <> 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 @@ -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: + * `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 field exists. + * `is in list` | `is not in list` — 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] +======= +* 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]. + -[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 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: @@ -197,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: @@ -297,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 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]