From 8b32dfe3c162e46aaa5bdcd02e50d5e0af9d59f4 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Mon, 9 Oct 2023 15:42:57 -0400 Subject: [PATCH 01/37] First draft --- .../api/exceptions-api-index.asciidoc | 2 + .../api-create-exception-container.asciidoc | 1 + ...reate-rule-default-exception-list.asciidoc | 103 ++++++++++++++++++ 3 files changed, 106 insertions(+) create mode 100644 docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc diff --git a/docs/detections/api/exceptions-api-index.asciidoc b/docs/detections/api/exceptions-api-index.asciidoc index 8e82ae32f9..4405d85629 100644 --- a/docs/detections/api/exceptions-api-index.asciidoc +++ b/docs/detections/api/exceptions-api-index.asciidoc @@ -4,6 +4,8 @@ include::exceptions/api-create-exception-container.asciidoc[] include::exceptions/api-create-exception-item.asciidoc[] +include::api-create-rule-default-exception-list.asciidoc[] + include::exceptions/api-create-shared-exception-list.asciidoc[] include::exceptions/api-find-exception-containers.asciidoc[] diff --git a/docs/detections/api/exceptions/api-create-exception-container.asciidoc b/docs/detections/api/exceptions/api-create-exception-container.asciidoc index 1e1c367f63..cb0b327386 100644 --- a/docs/detections/api/exceptions/api-create-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-container.asciidoc @@ -51,6 +51,7 @@ exception containers. |No * `detection`: Detection rule exception * `endpoint`: Endpoint alert exception +* `rule_default`: Exception that belongs to a single rule |Yes diff --git a/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc b/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc new file mode 100644 index 0000000000..2e91db3e61 --- /dev/null +++ b/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc @@ -0,0 +1,103 @@ +[[exceptions-api-create-rule-default-exception-list]] +=== Create exception list for an individual rule + +Creates a rule default exception list. + +An exception list groups <> and a rule default list is associated with a single rule. When an exception item’s query evaluates to true, the associated rule does not issue alerts even when its other criteria are met. + +A rule default exception list can apply to a single detection rule. To add to a rule's default exception list, simply pass in the exception items you would like to be applied to the rule. If a default exception list does not yet exist for the rule, one will be created and the exception added. + +==== Request URL + +`POST :/api/exception_lists` + +==== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`description` |String |Describes the exception container. |Yes +|`list_id` |String |Unique identifier. |No, automatically created when it is not +provided. +|`meta` |Object |Placeholder for metadata about the list container. |No +|`name` |String |The exception container's name. |Yes +|`namespace_type` |String a|Determines whether the exception container is available in all {kib} spaces or just the space in which it is created, where: + +* `single`: Only available in the {kib} space in which it is created. +* `agnostic`: Available in all {kib} spaces. + +|No, defaults to `single`. +|`tags` |String[] |String array containing words and phrases to help categorize +exception containers. |No +|`type` |String a|The type of exception, which must be: + +* `rule_default`: Exception that belongs to a single rule + +|Yes + +|============================================== + +===== Example requests + +Creates an exception container for holding trusted Linux process exception +items: + +[source,console] +-------------------------------------------------- +POST api/exception_lists +{ + "description": "Excludes Linux trusted processes", + "name": "Linux process exceptions", + "list_id": "trusted-linux-processes", + "type": "detection", + "namespace_type": "single", + "tags": [ + "linux", + "processes" + ] +} +-------------------------------------------------- +// KIBANA + +==== Response code + +`200`:: + Indicates a successful call. + + +==== Response payload + +The exception container object with a unique ID. + +[source,json] +-------------------------------------------------- +{ + "_tags": [], + "created_at": "2020-07-13T09:33:46.187Z", + "created_by": "elastic", + "description": "Excludes Linux trusted processes", + "id": "f320c070-c4eb-11ea-80bb-11861bae2798", <1> + "list_id": "trusted-linux-processes", <2> + "name": "Linux process exceptions", + "namespace_type": "single", <3> + "tags": [ + "linux", + "processes" + ], + "tie_breaker_id": "2c08d5a5-2ecc-4d5a-acfb-0a367f25b3f3", + "type": "detection", <4> + "updated_at": "2020-07-13T09:33:46.359Z", + "updated_by": "elastic" +} +-------------------------------------------------- + +These values are required to associate the exception container with detection +rules: + +<1> `id` +<2> `list_id` +<3> `namespace_type` +<4> `type` From b5dbd1eb7f3937d6e228fba6af032723b7f9abaa Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Mon, 9 Oct 2023 16:08:39 -0400 Subject: [PATCH 02/37] Fixed include --- docs/detections/api/exceptions-api-index.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/exceptions-api-index.asciidoc b/docs/detections/api/exceptions-api-index.asciidoc index 4405d85629..b6af5a4fe0 100644 --- a/docs/detections/api/exceptions-api-index.asciidoc +++ b/docs/detections/api/exceptions-api-index.asciidoc @@ -4,7 +4,7 @@ include::exceptions/api-create-exception-container.asciidoc[] include::exceptions/api-create-exception-item.asciidoc[] -include::api-create-rule-default-exception-list.asciidoc[] +include::exceptions/api-create-rule-default-exception-list.asciidoc[] include::exceptions/api-create-shared-exception-list.asciidoc[] From 81371007224ca7d07863cbc2a6fc73fb6b1eee2e Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Sun, 29 Oct 2023 17:59:19 -0400 Subject: [PATCH 03/37] Update/create exception changes --- .../exceptions/api-create-exception-container.asciidoc | 8 ++++---- .../exceptions/api-update-exception-container.asciidoc | 7 +++++-- 2 files changed, 9 insertions(+), 6 deletions(-) diff --git a/docs/detections/api/exceptions/api-create-exception-container.asciidoc b/docs/detections/api/exceptions/api-create-exception-container.asciidoc index cb0b327386..a490443413 100644 --- a/docs/detections/api/exceptions/api-create-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-container.asciidoc @@ -47,11 +47,11 @@ provided. |No, defaults to `single`. |`tags` |String[] |String array containing words and phrases to help categorize exception containers. |No -|`type` |String a|The type of exception, which must be one of these: +|`type` |String a|The type of exception list, which must be one of these: -* `detection`: Detection rule exception -* `endpoint`: Endpoint alert exception -* `rule_default`: Exception that belongs to a single rule +* `detection`: Shared rule exception +* `endpoint`: Endpoint rule exception +* `rule_default`: Single rule exception |Yes diff --git a/docs/detections/api/exceptions/api-update-exception-container.asciidoc b/docs/detections/api/exceptions/api-update-exception-container.asciidoc index 5afead7f7a..3b71dd741c 100644 --- a/docs/detections/api/exceptions/api-update-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-update-exception-container.asciidoc @@ -35,8 +35,11 @@ the container's `id` field is not used. exception containers. |No |`type` |String a|The type of exception, which must be one of these: -* `detection`: Detection rule exception -* `endpoint`: Endpoint alert exception +|`type` |String a|The type of exception list, which must be one of these: + +* `detection`: Shared rule exception +* `endpoint`: Endpoint rule exception +* `rule_default`: Single rule exception |Yes From a2807ce2edf59feffee432bdcff156145860ea1e Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Sun, 29 Oct 2023 18:04:08 -0400 Subject: [PATCH 04/37] Update docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc --- .../exceptions/api-create-rule-default-exception-list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc b/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc index 2e91db3e61..26e67e4413 100644 --- a/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc @@ -9,7 +9,7 @@ A rule default exception list can apply to a single detection rule. To add to a ==== Request URL -`POST :/api/exception_lists` +`POST :/api/detection_engine//exceptions` ==== Request body From d68218b815c37cc6189c6e4cc30561002d51c825 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Wed, 13 Mar 2024 15:59:46 -0400 Subject: [PATCH 05/37] Revising intro --- .../api-create-exception-item.asciidoc | 22 ++++++++++--------- 1 file changed, 12 insertions(+), 10 deletions(-) diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 1e4aa5be29..0abe59f27e 100644 --- a/docs/detections/api/exceptions/api-create-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-item.asciidoc @@ -10,21 +10,23 @@ For the most up-to-date API details, refer to {api-kibana}/group/endpoint-securi Creates an exception item and associates it with the specified <>. -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. - -IMPORTANT: Endpoint rule exception items cannot use +[IMPORTANT] +===== +* Before creating exception items, you must create an <>. After creating the container, you can associate exception items with it. +* Endpoint rule exception items cannot use <> (the `list` in the `entries` array), and the following fields cannot be used in exception queries (as `field` values in the `entries` object): -* `file.Ext.quarantine_path` -* `file.Ext.quarantine_result` -* `process.entity_id` -* `process.parent.entity_id` -* `process.ancestry` +** `file.Ext.quarantine_path` +** `file.Ext.quarantine_result` +** `process.entity_id` +** `process.parent.entity_id` +** `process.ancestry` +===== + +NOTE: Refer to <> for information about creating exception items from lists, such as a list of IP addresses or host names. ==== Request URL From af1e0239c7fccc863fe9c29cd5ec8d3bdfc12e3c Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 19 Mar 2024 17:17:50 -0400 Subject: [PATCH 06/37] Adding new topic --- .../api/exceptions-api-index.asciidoc | 2 + ...reate-rule-default-exception-item.asciidoc | 393 ++++++++++++++++++ 2 files changed, 395 insertions(+) create mode 100644 docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc diff --git a/docs/detections/api/exceptions-api-index.asciidoc b/docs/detections/api/exceptions-api-index.asciidoc index b6af5a4fe0..efb11f3768 100644 --- a/docs/detections/api/exceptions-api-index.asciidoc +++ b/docs/detections/api/exceptions-api-index.asciidoc @@ -1,5 +1,7 @@ include::exceptions/exceptions-api-overview.asciidoc[] +include::exceptions/api-create-rule-default-exception-item.asciidoc[] + include::exceptions/api-create-exception-container.asciidoc[] include::exceptions/api-create-exception-item.asciidoc[] diff --git a/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc new file mode 100644 index 0000000000..355b051eca --- /dev/null +++ b/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc @@ -0,0 +1,393 @@ +[[exceptions-api-create-rule-default-exception-item]] +=== Create exception item for individual rules + +Creates an exception item for a specific rule. Allows a user to create exception items to be associated with the specified rule id. + +==== Request URL + +`POST :/api/detection_engine/rules/{id}/exceptions` + +==== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`comments` |comments[] a|Array of `comment` fields: + +* `comment` (string): Comments about the exception item. + +|No, defaults to empty array. + +|`description` |String |Describes the exception item. |Yes +|`entries` |<> |Array containing the +exception queries. Boolean `AND` logic is used to evaluate the relationship +between array elements. If you want to use `OR` logic, create a separate +exception item. |Yes +|`expire_time` |String |The exception item's expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. |No +|`id` |String |ID of the associated rule. |Yes +//Keep `list_id` and `item_id`? +|`list_id` |String |ID of the associated <>. |Yes +|`item_id` |String |Unique identifier of the exception item. |No, automatically +created when it is not provided. +|`meta` |Object |Placeholder for metadata about the exception item. |No +|`name` |String |The exception item's name. |Yes +|`namespace_type` |String a|Determines whether the exception item is available +in all {kib} spaces or just the space in which it is created, where: + +* `single`: Only available in the {kib} space in which it is created. +* `agnostic`: Available in all {kib} spaces. + +Must be the same value as its associated exception container. + +|No, defaults to `single`. +|`tags` |String[] |String array containing words and phrases to help categorize +exception items. |No +|`type` |String a|Exception query type, must be `simple`. |Yes +|`_tags` |String[] a|For endpoint rules only, defines the OS on which the +exception is implemented. Valid values are: + +* `os:windows`: Windows OS +* `os:linux`: Linux OS +* `os:macos`: Mac OS + +The array must also include an `endpoint` element (to implement the exception on Linux hosts, use: `["endpoint", "os:linux"]`). + +|For endpoint exceptions, yes. For detection exceptions, no. + +|============================================== + +[[entries-object-schema]] +===== `entries` schema + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`field` |String |The source event field used to define the exception. Cannot +be an empty string. |Yes +|`list` |list |Object containing the +<> `id` and `type`. Only valid for +detection exception items.|No, except when using a list to define detection +exceptions. +|`operator` |String a|The operator used to determine when the exception is used. +Can be: + +* `included`: The `field` has the specified value or values. +* `excluded`: The `field` does not have specified value or values. + +|Yes + +|`type` |String a|The `type` of query: + +* `match`: Must be an exact match of the defined value. +* `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 {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` +type. + +|Yes + +|`value` +a|String + +String[] + +a|Field value or values: + +* String: When the `type` is `match` or `wildcard`. +* String[]: When the `type` is `match_any`. + +|Yes, except when `type` is `exists` or `list`. + +|============================================== + +IMPORTANT: When you use <> +(`"type": "list"`), you cannot use other types in the `entries` array (`match`, +`match_any`, `exists`, or `nested`). + +For endpoint exceptions, you cannot create exception items based on excluded +values (`"operator": "excluded"`). + +//Do we need to update these examples at all? +===== Example requests + +*Example 1* + +Adds the `maintenance-job` process to the `trusted-linux-processes` exception +container: + +[source,console] +-------------------------------------------------- +POST api/exception_lists/items +{ + "description": "Excludes the weekly maintenance job", + "entries": [ + { + "field": "process.name", + "operator": "included", + "type": "match", + "value": "maintenance-job" + } + ], + "list_id": "trusted-linux-processes", + "name": "Linux maintenance job", + "namespace_type": "single", + "tags": [ + "in-house processes", + "linux" + ], + "type": "simple" +} +-------------------------------------------------- +// KIBANA + +*Example 2* + +Adds hosts on which the `maintenance` process is allowed to run to the +`allowed-processes` exception container: + +[source,console] +-------------------------------------------------- +POST api/exception_lists/items +{ + "comments": [ + {"comment": "Allows maintenance process to run on the specified machines"} + ], + "description": "Process allowlist", + "entries": [ + { + "field": "process.name", + "operator": "included", + "type": "match", + "value": "maintenance" + }, + { <1> + "field": "host.name", + "operator": "included", + "type": "match_any", + "value": [ + "liv-win-anf", + "livw-win-mel", + "linux-anfield" + ] + } + ], + "list_id": "allowed-processes", + "item_id": "allow-process-on-machines", + "name": "Host-process exclusions", + "namespace_type": "single", + "tags": [ + "hosts", + "processes" + ], + "type": "simple" +} +-------------------------------------------------- +// KIBANA + +<1> Multiple array elements are evaluated using `AND` operators. + +*Example 3* + +[[endpoint-item-example]] +Creates an endpoint exception item for files with the specified SHA-1 hash +value on Windows OS: + +[source,console] +-------------------------------------------------- +POST api/exception_lists/items +{ + "_tags": [ + "endpoint", <1> + "os:windows" <2> + ], + "comments": [ + ] + "description": "File exception for Windows", + "entries": [ + { + "field": "file.hash.sha1", + "operator": "included", + "type": "match", + "value": "27fb21cf5db95ffca43b234affa99becc4023b9d" + } + ], + "item_id": "trusted-windows-file", + "list_id": "endpoint-exception-container", + "name": "Trusted Windows file", + "namespace_type": "agnostic", <3> + "tags": [ + ] + "type": "simple" +} +-------------------------------------------------- + +<1> Indicates this item is for endpoint rules. +<2> Relevant OS. +<3> Item accessible from all {kib} spaces. + +*Example 4* + +[[list-item-example]] +Associates the `external-ip-excludes` <> +as an exception item to the `trusted-IPs` exception container: + +[source,console] +-------------------------------------------------- +POST api/exception_lists/items +{ + "description": "Uses the external-ip-container list to exclude trusted external IPs.", + "entries": [ + { + "field": "destination.ip", + "list": { + "id": "external-ip-excludes", <1> + "type": "ip" + }, + "operator": "included", + "type": "list" + } + ], + "list_id": "trusted-IPs", <2> + "item_id": "external-IPs", + "name": "Trusted external IPs", + "namespace_type": "single", + "tags": [ + "network", + "trusted IPs" + ], + "type": "simple" +} +-------------------------------------------------- +// KIBANA + +<1> The list container that holds IP address +<>. +<2> The exception container's ID. + +[[nested-field-ex-api]] +*Example 5* + +Adds an exception for nested Endpoint fields: + +[source,console] +-------------------------------------------------- +POST api/exception_lists/items +{ + "description": "Excludes all processes signed by Trusted Signer, Inc.", + "entries": [ + { + "field": "process.Ext.code_signature", + "type": "nested", + "entries": [ + { + "field": "trusted", + "type": "match", + "operator": "included", + "value": "true" + }, + { + "field": "subject_name", + "type": "match", + "operator": "included", + "value": "Trusted Signer, Inc." + } + ] + } + ], + "list_id": "trusted-self-signed-processes", + "name": "In-house processes", + "namespace_type": "single", + "tags": [ + "in-house processes", + "linux" + ], + "type": "simple" +} +-------------------------------------------------- + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +[source,json] +-------------------------------------------------- + +{ + "comments": [], + "created_by": "elastic", + "description": "Exception item for rule default exception list", + "entries": [ + { + "field": "host.name", + "operator": "included", + "type": "match", + "value": "foo", + }, + ], + "name": "Sample exception item", + "list_id": "e6c44050-c661-11ea-bab5-9d6ae015701b", + "namespace_type": "single", + "os_types": [], + "tags": [], + "type": "simple", + "updated_by": "elastic" +} + +} +{ + "_tags": [], + "comments": [ + { + "comment": "Allows maintenance process to run on the specified machines", + "created_at": "2020-07-14T08:36:33.172Z", + "created_by": "elastic", + "id": "f6c61b4d-31dd-4a5d-8c73-f64787d03b4d" + } + ], + "created_at": "2020-07-14T08:36:33.172Z", + "created_by": "elastic", + "description": "Process allowlist", + "entries": [ + { + "field": "process.name", + "operator": "included", + "type": "match", + "value": "maintenance" + }, + { + "field": "host.name", + "operator": "included", + "type": "match_any", + "value": [ + "liv-win-anf", + "livw-win-mel", + "linux-anfield" + ] + } + ], + "id": "1f4d38b0-c5ad-11ea-a3d8-a5b753aeeb9e", + "item_id": "allow-process-on-machines", + "list_id": "allowed-processes", + "name": "Host-process exclusions", + "namespace_type": "single", + "tags": [ + "hosts", + "processes" + ], + "tie_breaker_id": "bb04f1c7-2537-47c1-aaca-40a7c8f771d3", + "type": "simple", + "updated_at": "2020-07-14T08:36:33.339Z", + "updated_by": "elastic" +} +-------------------------------------------------- From 7b8e8c32e60414e1eb5e9eb5c1fc4e2aa1f3f987 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Wed, 20 Mar 2024 15:01:00 -0400 Subject: [PATCH 07/37] Fixing refs --- .../api-create-rule-default-exception-item.asciidoc | 10 +++++----- .../api/exceptions/api-update-exception-item.asciidoc | 1 + 2 files changed, 6 insertions(+), 5 deletions(-) diff --git a/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc index 355b051eca..efea858449 100644 --- a/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc @@ -22,7 +22,7 @@ A JSON object with these fields: |No, defaults to empty array. |`description` |String |Describes the exception item. |Yes -|`entries` |<> |Array containing the +|`entries` |<> |Array containing the exception queries. Boolean `AND` logic is used to evaluate the relationship between array elements. If you want to use `OR` logic, create a separate exception item. |Yes @@ -59,7 +59,7 @@ The array must also include an `endpoint` element (to implement the exception on |============================================== -[[entries-object-schema]] +[[entries-object-schema-default-exception]] ===== `entries` schema [width="100%",options="header"] @@ -196,7 +196,7 @@ POST api/exception_lists/items *Example 3* -[[endpoint-item-example]] +[[endpoint-item-example-default-exception]] Creates an endpoint exception item for files with the specified SHA-1 hash value on Windows OS: @@ -235,7 +235,7 @@ POST api/exception_lists/items *Example 4* -[[list-item-example]] +[[list-item-example-default-exception]] Associates the `external-ip-excludes` <> as an exception item to the `trusted-IPs` exception container: @@ -272,7 +272,7 @@ POST api/exception_lists/items <>. <2> The exception container's ID. -[[nested-field-ex-api]] +[[nested-field-ex-api-default-exception]] *Example 5* Adds an exception for nested Endpoint fields: diff --git a/docs/detections/api/exceptions/api-update-exception-item.asciidoc b/docs/detections/api/exceptions/api-update-exception-item.asciidoc index 5db11fcf94..e14b76296d 100644 --- a/docs/detections/api/exceptions/api-update-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-update-exception-item.asciidoc @@ -1,5 +1,6 @@ [[exceptions-api-update-item]] === Update exception item +//Check if this endpoint can also be used to update rule default exceptions. .New API Reference [sidebar] From a772774252a202593fb9c1ffcdf032130960be9c Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Wed, 20 Mar 2024 15:26:52 -0400 Subject: [PATCH 08/37] Removed duplicate entry --- docs/detections/api/exceptions-api-index.asciidoc | 2 -- 1 file changed, 2 deletions(-) diff --git a/docs/detections/api/exceptions-api-index.asciidoc b/docs/detections/api/exceptions-api-index.asciidoc index efb11f3768..0557c25c41 100644 --- a/docs/detections/api/exceptions-api-index.asciidoc +++ b/docs/detections/api/exceptions-api-index.asciidoc @@ -6,8 +6,6 @@ include::exceptions/api-create-exception-container.asciidoc[] include::exceptions/api-create-exception-item.asciidoc[] -include::exceptions/api-create-rule-default-exception-list.asciidoc[] - include::exceptions/api-create-shared-exception-list.asciidoc[] include::exceptions/api-find-exception-containers.asciidoc[] From d1070c9c2eca4fba4d3e4bf1b7d8c89c8d601676 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 2 Apr 2024 18:36:21 -0400 Subject: [PATCH 09/37] Yara's input --- docs/detections/api/det-api-index.asciidoc | 2 + .../api/exceptions-api-index.asciidoc | 2 - ...reate-rule-default-exception-item.asciidoc | 393 ------------------ ...reate-rule-default-exception-item.asciidoc | 76 ++++ .../api/rules/rules-api-overview.asciidoc | 1 + 5 files changed, 79 insertions(+), 395 deletions(-) delete mode 100644 docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc create mode 100644 docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc diff --git a/docs/detections/api/det-api-index.asciidoc b/docs/detections/api/det-api-index.asciidoc index f9ce608488..37c4f2d73e 100644 --- a/docs/detections/api/det-api-index.asciidoc +++ b/docs/detections/api/det-api-index.asciidoc @@ -12,6 +12,8 @@ include::rules/rules-api-delete.asciidoc[] include::rules/rules-api-bulk-actions.asciidoc[] +include::rules/rules-api-create-rule-default-exception-item.asciidoc[] + include::rules/index-api-overview.asciidoc[] include::rules/tags-api-overview.asciidoc[] diff --git a/docs/detections/api/exceptions-api-index.asciidoc b/docs/detections/api/exceptions-api-index.asciidoc index 0557c25c41..8e82ae32f9 100644 --- a/docs/detections/api/exceptions-api-index.asciidoc +++ b/docs/detections/api/exceptions-api-index.asciidoc @@ -1,7 +1,5 @@ include::exceptions/exceptions-api-overview.asciidoc[] -include::exceptions/api-create-rule-default-exception-item.asciidoc[] - include::exceptions/api-create-exception-container.asciidoc[] include::exceptions/api-create-exception-item.asciidoc[] diff --git a/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc deleted file mode 100644 index efea858449..0000000000 --- a/docs/detections/api/exceptions/api-create-rule-default-exception-item.asciidoc +++ /dev/null @@ -1,393 +0,0 @@ -[[exceptions-api-create-rule-default-exception-item]] -=== Create exception item for individual rules - -Creates an exception item for a specific rule. Allows a user to create exception items to be associated with the specified rule id. - -==== Request URL - -`POST :/api/detection_engine/rules/{id}/exceptions` - -==== Request body - -A JSON object with these fields: - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`comments` |comments[] a|Array of `comment` fields: - -* `comment` (string): Comments about the exception item. - -|No, defaults to empty array. - -|`description` |String |Describes the exception item. |Yes -|`entries` |<> |Array containing the -exception queries. Boolean `AND` logic is used to evaluate the relationship -between array elements. If you want to use `OR` logic, create a separate -exception item. |Yes -|`expire_time` |String |The exception item's expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. |No -|`id` |String |ID of the associated rule. |Yes -//Keep `list_id` and `item_id`? -|`list_id` |String |ID of the associated <>. |Yes -|`item_id` |String |Unique identifier of the exception item. |No, automatically -created when it is not provided. -|`meta` |Object |Placeholder for metadata about the exception item. |No -|`name` |String |The exception item's name. |Yes -|`namespace_type` |String a|Determines whether the exception item is available -in all {kib} spaces or just the space in which it is created, where: - -* `single`: Only available in the {kib} space in which it is created. -* `agnostic`: Available in all {kib} spaces. - -Must be the same value as its associated exception container. - -|No, defaults to `single`. -|`tags` |String[] |String array containing words and phrases to help categorize -exception items. |No -|`type` |String a|Exception query type, must be `simple`. |Yes -|`_tags` |String[] a|For endpoint rules only, defines the OS on which the -exception is implemented. Valid values are: - -* `os:windows`: Windows OS -* `os:linux`: Linux OS -* `os:macos`: Mac OS - -The array must also include an `endpoint` element (to implement the exception on Linux hosts, use: `["endpoint", "os:linux"]`). - -|For endpoint exceptions, yes. For detection exceptions, no. - -|============================================== - -[[entries-object-schema-default-exception]] -===== `entries` schema - -[width="100%",options="header"] -|============================================== -|Name |Type |Description |Required - -|`field` |String |The source event field used to define the exception. Cannot -be an empty string. |Yes -|`list` |list |Object containing the -<> `id` and `type`. Only valid for -detection exception items.|No, except when using a list to define detection -exceptions. -|`operator` |String a|The operator used to determine when the exception is used. -Can be: - -* `included`: The `field` has the specified value or values. -* `excluded`: The `field` does not have specified value or values. - -|Yes - -|`type` |String a|The `type` of query: - -* `match`: Must be an exact match of the defined value. -* `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 {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` -type. - -|Yes - -|`value` -a|String - -String[] - -a|Field value or values: - -* String: When the `type` is `match` or `wildcard`. -* String[]: When the `type` is `match_any`. - -|Yes, except when `type` is `exists` or `list`. - -|============================================== - -IMPORTANT: When you use <> -(`"type": "list"`), you cannot use other types in the `entries` array (`match`, -`match_any`, `exists`, or `nested`). - -For endpoint exceptions, you cannot create exception items based on excluded -values (`"operator": "excluded"`). - -//Do we need to update these examples at all? -===== Example requests - -*Example 1* - -Adds the `maintenance-job` process to the `trusted-linux-processes` exception -container: - -[source,console] --------------------------------------------------- -POST api/exception_lists/items -{ - "description": "Excludes the weekly maintenance job", - "entries": [ - { - "field": "process.name", - "operator": "included", - "type": "match", - "value": "maintenance-job" - } - ], - "list_id": "trusted-linux-processes", - "name": "Linux maintenance job", - "namespace_type": "single", - "tags": [ - "in-house processes", - "linux" - ], - "type": "simple" -} --------------------------------------------------- -// KIBANA - -*Example 2* - -Adds hosts on which the `maintenance` process is allowed to run to the -`allowed-processes` exception container: - -[source,console] --------------------------------------------------- -POST api/exception_lists/items -{ - "comments": [ - {"comment": "Allows maintenance process to run on the specified machines"} - ], - "description": "Process allowlist", - "entries": [ - { - "field": "process.name", - "operator": "included", - "type": "match", - "value": "maintenance" - }, - { <1> - "field": "host.name", - "operator": "included", - "type": "match_any", - "value": [ - "liv-win-anf", - "livw-win-mel", - "linux-anfield" - ] - } - ], - "list_id": "allowed-processes", - "item_id": "allow-process-on-machines", - "name": "Host-process exclusions", - "namespace_type": "single", - "tags": [ - "hosts", - "processes" - ], - "type": "simple" -} --------------------------------------------------- -// KIBANA - -<1> Multiple array elements are evaluated using `AND` operators. - -*Example 3* - -[[endpoint-item-example-default-exception]] -Creates an endpoint exception item for files with the specified SHA-1 hash -value on Windows OS: - -[source,console] --------------------------------------------------- -POST api/exception_lists/items -{ - "_tags": [ - "endpoint", <1> - "os:windows" <2> - ], - "comments": [ - ] - "description": "File exception for Windows", - "entries": [ - { - "field": "file.hash.sha1", - "operator": "included", - "type": "match", - "value": "27fb21cf5db95ffca43b234affa99becc4023b9d" - } - ], - "item_id": "trusted-windows-file", - "list_id": "endpoint-exception-container", - "name": "Trusted Windows file", - "namespace_type": "agnostic", <3> - "tags": [ - ] - "type": "simple" -} --------------------------------------------------- - -<1> Indicates this item is for endpoint rules. -<2> Relevant OS. -<3> Item accessible from all {kib} spaces. - -*Example 4* - -[[list-item-example-default-exception]] -Associates the `external-ip-excludes` <> -as an exception item to the `trusted-IPs` exception container: - -[source,console] --------------------------------------------------- -POST api/exception_lists/items -{ - "description": "Uses the external-ip-container list to exclude trusted external IPs.", - "entries": [ - { - "field": "destination.ip", - "list": { - "id": "external-ip-excludes", <1> - "type": "ip" - }, - "operator": "included", - "type": "list" - } - ], - "list_id": "trusted-IPs", <2> - "item_id": "external-IPs", - "name": "Trusted external IPs", - "namespace_type": "single", - "tags": [ - "network", - "trusted IPs" - ], - "type": "simple" -} --------------------------------------------------- -// KIBANA - -<1> The list container that holds IP address -<>. -<2> The exception container's ID. - -[[nested-field-ex-api-default-exception]] -*Example 5* - -Adds an exception for nested Endpoint fields: - -[source,console] --------------------------------------------------- -POST api/exception_lists/items -{ - "description": "Excludes all processes signed by Trusted Signer, Inc.", - "entries": [ - { - "field": "process.Ext.code_signature", - "type": "nested", - "entries": [ - { - "field": "trusted", - "type": "match", - "operator": "included", - "value": "true" - }, - { - "field": "subject_name", - "type": "match", - "operator": "included", - "value": "Trusted Signer, Inc." - } - ] - } - ], - "list_id": "trusted-self-signed-processes", - "name": "In-house processes", - "namespace_type": "single", - "tags": [ - "in-house processes", - "linux" - ], - "type": "simple" -} --------------------------------------------------- - -==== Response code - -`200`:: - Indicates a successful call. - -==== Response payload - -[source,json] --------------------------------------------------- - -{ - "comments": [], - "created_by": "elastic", - "description": "Exception item for rule default exception list", - "entries": [ - { - "field": "host.name", - "operator": "included", - "type": "match", - "value": "foo", - }, - ], - "name": "Sample exception item", - "list_id": "e6c44050-c661-11ea-bab5-9d6ae015701b", - "namespace_type": "single", - "os_types": [], - "tags": [], - "type": "simple", - "updated_by": "elastic" -} - -} -{ - "_tags": [], - "comments": [ - { - "comment": "Allows maintenance process to run on the specified machines", - "created_at": "2020-07-14T08:36:33.172Z", - "created_by": "elastic", - "id": "f6c61b4d-31dd-4a5d-8c73-f64787d03b4d" - } - ], - "created_at": "2020-07-14T08:36:33.172Z", - "created_by": "elastic", - "description": "Process allowlist", - "entries": [ - { - "field": "process.name", - "operator": "included", - "type": "match", - "value": "maintenance" - }, - { - "field": "host.name", - "operator": "included", - "type": "match_any", - "value": [ - "liv-win-anf", - "livw-win-mel", - "linux-anfield" - ] - } - ], - "id": "1f4d38b0-c5ad-11ea-a3d8-a5b753aeeb9e", - "item_id": "allow-process-on-machines", - "list_id": "allowed-processes", - "name": "Host-process exclusions", - "namespace_type": "single", - "tags": [ - "hosts", - "processes" - ], - "tie_breaker_id": "bb04f1c7-2537-47c1-aaca-40a7c8f771d3", - "type": "simple", - "updated_at": "2020-07-14T08:36:33.339Z", - "updated_by": "elastic" -} --------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc new file mode 100644 index 0000000000..b75398733e --- /dev/null +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc @@ -0,0 +1,76 @@ +[[exceptions-api-create-rule-default-exception-item]] +=== Create exception item for individual rules + +Allows you to create exception items that are associated with a specified rule `id`. + +==== Request URL + +`POST :/api/detection_engine/rules/{id}/exceptions` + +//include a tip on how to find a rule's ID + +==== Request body + +A JSON object with an array of exception items, where each exception item contains the <>. + +[width="100%",options="header"] +|============================================== + +|`items` |String | An array of exception list items to be created. |Yes + +===== Example requests + +[source,console] +-------------------------------------------------- +POST api/detection_engine/rules/_bulk_create +[ +{ + "items": [ TBD + { + + } +} +] +-------------------------------------------------- + + +==== Response code + +`200`:: + Indicates a successful call. + +==== Response payload + +The returned exception item. + +Example response: + +[source,json] +-------------------------------------------------- +[ +{ + body: [ + { + comments: [], + created_by: "elastic", + description: "Exception item for rule default exception list", + entries: [ + { + field: "host.name", + operator: "included", + type: "match", + value: "foo", + }, + ], + name: "Sample exception item", + list_id: "e6c44050-c661-11ea-bab5-9d6ae015701b", + namespace_type: "single", + os_types: [], + tags: [], + type: "simple", + updated_by: "elastic" + } + ] +} +] +-------------------------------------------------- diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc index 85be0089f8..b5e7bdccc0 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -33,6 +33,7 @@ tags returns alerts, and updates their statuses * `:/api/detection_engine/rules/prepackaged` - Loads and retrieves the status of Elastic <> +* `:/api/detection_engine/rules/{id}/exceptions` - Create an exception item for a specified rule TIP: You can view and download a Detections API Postman collection https://github.com/elastic/examples/tree/master/Security%20Analytics/SIEM-examples/Detections-API[here]. From 007e759cf08dadbc1d8981b25a31defe206454ad Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 2 Apr 2024 18:40:19 -0400 Subject: [PATCH 10/37] Minor wording changes --- .../rules-api-create-rule-default-exception-item.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc index b75398733e..a94a2ee975 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc @@ -11,12 +11,12 @@ Allows you to create exception items that are associated with a specified rule ` ==== Request body -A JSON object with an array of exception items, where each exception item contains the <>. +A JSON object with an array of exception items, where each exception item has the <>. [width="100%",options="header"] |============================================== -|`items` |String | An array of exception list items to be created. |Yes +|`items` |String | Specify an array of exception list items to create. |Yes ===== Example requests From 0ad87bdb800127aa4199ad1cef3ef38aefc5ba79 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 2 Apr 2024 18:43:50 -0400 Subject: [PATCH 11/37] Title update --- .../rules/rules-api-create-rule-default-exception-item.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc index a94a2ee975..8358a778f3 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc @@ -1,5 +1,5 @@ [[exceptions-api-create-rule-default-exception-item]] -=== Create exception item for individual rules +=== Create exceptions for individual rules Allows you to create exception items that are associated with a specified rule `id`. From d4da17a15485fb0d890c00a0684affd969b46c69 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 2 Apr 2024 18:46:05 -0400 Subject: [PATCH 12/37] Modifies title for shared exceptions --- .../api/exceptions/api-create-exception-item.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 0abe59f27e..55c66c2618 100644 --- a/docs/detections/api/exceptions/api-create-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-item.asciidoc @@ -1,5 +1,5 @@ [[exceptions-api-create-exception-item]] -=== Create exception item +=== Create exceptions used by multiple rules .New API Reference [sidebar] @@ -11,6 +11,8 @@ Creates an exception item and associates it with the specified <>. +TIP: Refer to <> for information about creating exceptions for a single rule. + [IMPORTANT] ===== * Before creating exception items, you must create an <>. After creating the container, you can associate exception items with it. From 6c3747c52af1217770303b5a8dd3f5428d71df8c Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 2 Apr 2024 22:19:36 -0400 Subject: [PATCH 13/37] Fixing conflicts --- ...reate-rule-default-exception-item.asciidoc | 36 +++++++++---------- 1 file changed, 17 insertions(+), 19 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc index 8358a778f3..d0dbfbc994 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc @@ -25,7 +25,7 @@ A JSON object with an array of exception items, where each exception item has th POST api/detection_engine/rules/_bulk_create [ { - "items": [ TBD + "items": [] { } @@ -47,30 +47,28 @@ Example response: [source,json] -------------------------------------------------- -[ { - body: [ + "body": [ { - comments: [], - created_by: "elastic", - description: "Exception item for rule default exception list", - entries: [ + "comments": [], + "created_by": "elastic", + "description": "Exception item for rule default exception list", + "entries": [ { - field: "host.name", - operator: "included", - type: "match", - value: "foo", + "field": "host.name", + "operator": "included", + "type": "match", + "value": "foo", }, ], - name: "Sample exception item", - list_id: "e6c44050-c661-11ea-bab5-9d6ae015701b", - namespace_type: "single", - os_types: [], - tags: [], - type: "simple", - updated_by: "elastic" + "name": "Sample exception item", + "list_id": "e6c44050-c661-11ea-bab5-9d6ae015701b", + "namespace_type": "single", + "os_types": [], + "tags": [], + "type": "simple", + "updated_by": "elastic" } ] } -] -------------------------------------------------- From 8e765188f71bebdda9200134299d659cd70ede97 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 2 Apr 2024 23:47:07 -0400 Subject: [PATCH 14/37] attempt number 2 --- docs/detections/api/det-api-index.asciidoc | 2 +- ...reate-rule-default-exception-list.asciidoc | 12 ++++++----- ...reate-single-rule-exception-item.asciidoc} | 20 ++++++++++++++----- 3 files changed, 23 insertions(+), 11 deletions(-) rename docs/detections/api/rules/{rules-api-create-rule-default-exception-item.asciidoc => rules-api-create-single-rule-exception-item.asciidoc} (84%) diff --git a/docs/detections/api/det-api-index.asciidoc b/docs/detections/api/det-api-index.asciidoc index 37c4f2d73e..f18dd76294 100644 --- a/docs/detections/api/det-api-index.asciidoc +++ b/docs/detections/api/det-api-index.asciidoc @@ -12,7 +12,7 @@ include::rules/rules-api-delete.asciidoc[] include::rules/rules-api-bulk-actions.asciidoc[] -include::rules/rules-api-create-rule-default-exception-item.asciidoc[] +include::rules/rules-api-create-single-rule-exception-item.asciidoc[] include::rules/index-api-overview.asciidoc[] diff --git a/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc b/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc index 26e67e4413..7a38a1001b 100644 --- a/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc @@ -1,11 +1,13 @@ [[exceptions-api-create-rule-default-exception-list]] -=== Create exception list for an individual rule +=== Create a default exception list for a rule -Creates a rule default exception list. +Creates a default exception list for the rule you specify. Default exception lists can only be associated with a single rule. -An exception list groups <> and a rule default list is associated with a single rule. When an exception item’s query evaluates to true, the associated rule does not issue alerts even when its other criteria are met. +To add exception items to a default exception list, pass in exceptions items that you want applied to the rule. Refer to <> for more information. -A rule default exception list can apply to a single detection rule. To add to a rule's default exception list, simply pass in the exception items you would like to be applied to the rule. If a default exception list does not yet exist for the rule, one will be created and the exception added. +When an exception item’s query evaluates to `true`, the associated rule does not issue alerts even when its other criteria are met. + +NOTE: Default exception lists do not display on the <> page in the {security-app} UI. ==== Request URL @@ -34,7 +36,7 @@ provided. exception containers. |No |`type` |String a|The type of exception, which must be: -* `rule_default`: Exception that belongs to a single rule +* `rule_default`: Exception list that belongs to a single rule |Yes diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc similarity index 84% rename from docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc rename to docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index d0dbfbc994..3544b47e2c 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -23,14 +23,24 @@ A JSON object with an array of exception items, where each exception item has th [source,console] -------------------------------------------------- POST api/detection_engine/rules/_bulk_create -[ { - "items": [] + "items": [ { - - } + "field": "process.name", + "operator": "included", + "type": "match", + "value": "maintenance-job" + } + ], + "list_id": "trusted-linux-processes", + "name": "Linux maintenance job", + "namespace_type": "single", + "tags": [ + "in-house processes", + "linux" + ], + "type": "simple" } -] -------------------------------------------------- From 356b9c6da9a840bc122cb1b710f62e438d6d9992 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Wed, 3 Apr 2024 00:14:27 -0400 Subject: [PATCH 15/37] Added file ext to index file --- docs/detections/api/det-api-index.asciidoc | 2 ++ .../rules-api-create-rule-default-exception-list.asciidoc} | 0 .../rules/rules-api-create-single-rule-exception-item.asciidoc | 2 +- docs/detections/api/rules/rules-api-overview.asciidoc | 3 ++- 4 files changed, 5 insertions(+), 2 deletions(-) rename docs/detections/api/{exceptions/api-create-rule-default-exception-list.asciidoc => rules/rules-api-create-rule-default-exception-list.asciidoc} (100%) diff --git a/docs/detections/api/det-api-index.asciidoc b/docs/detections/api/det-api-index.asciidoc index f18dd76294..aea3c3b548 100644 --- a/docs/detections/api/det-api-index.asciidoc +++ b/docs/detections/api/det-api-index.asciidoc @@ -12,6 +12,8 @@ include::rules/rules-api-delete.asciidoc[] include::rules/rules-api-bulk-actions.asciidoc[] +include::rules/rules-api-create-rule-default-exception-list.asciidoc[] + include::rules/rules-api-create-single-rule-exception-item.asciidoc[] include::rules/index-api-overview.asciidoc[] diff --git a/docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc similarity index 100% rename from docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc rename to docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index 3544b47e2c..b43cb3f625 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -5,7 +5,7 @@ Allows you to create exception items that are associated with a specified rule ` ==== Request URL -`POST :/api/detection_engine/rules/{id}/exceptions` +`POST :/api/detection_engine/rules//exceptions` //include a tip on how to find a rule's ID diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc index b5e7bdccc0..f5a8aceccd 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -33,7 +33,8 @@ tags returns alerts, and updates their statuses * `:/api/detection_engine/rules/prepackaged` - Loads and retrieves the status of Elastic <> -* `:/api/detection_engine/rules/{id}/exceptions` - Create an exception item for a specified rule +* :/api/detection_engine//exceptions` - Creates a default exception list for the rule you specify. +* `:/api/detection_engine/rules//exceptions` - Creates an exception item for a specified rule TIP: You can view and download a Detections API Postman collection https://github.com/elastic/examples/tree/master/Security%20Analytics/SIEM-examples/Detections-API[here]. From 8b765a8da6eca2c1b1c9e7e2d05f3142d21d1c3a Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Wed, 3 Apr 2024 00:37:04 -0400 Subject: [PATCH 16/37] Closing table --- .../rules/rules-api-create-single-rule-exception-item.asciidoc | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index b43cb3f625..0851a4335c 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -18,6 +18,8 @@ A JSON object with an array of exception items, where each exception item has th |`items` |String | Specify an array of exception list items to create. |Yes +|============================================== + ===== Example requests [source,console] @@ -43,7 +45,6 @@ POST api/detection_engine/rules/_bulk_create } -------------------------------------------------- - ==== Response code `200`:: From fa50009117394c0ba87a40ba9889262f60ebb99a Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Wed, 3 Apr 2024 00:15:26 -0400 Subject: [PATCH 17/37] Update docs/detections/api/rules/rules-api-overview.asciidoc --- docs/detections/api/rules/rules-api-overview.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc index f5a8aceccd..9cecaefac1 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -33,7 +33,7 @@ tags returns alerts, and updates their statuses * `:/api/detection_engine/rules/prepackaged` - Loads and retrieves the status of Elastic <> -* :/api/detection_engine//exceptions` - Creates a default exception list for the rule you specify. +* `:/api/detection_engine//exceptions` - Creates a default exception list for the rule you specify. * `:/api/detection_engine/rules//exceptions` - Creates an exception item for a specified rule TIP: You can view and download a Detections API Postman collection From 7083f94aa94fa51d9510b7cc29d7fce58167f631 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Wed, 3 Apr 2024 00:37:15 -0400 Subject: [PATCH 18/37] Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc --- .../rules/rules-api-create-rule-default-exception-list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index 7a38a1001b..f0ebda9133 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -7,7 +7,7 @@ To add exception items to a default exception list, pass in exceptions items tha When an exception item’s query evaluates to `true`, the associated rule does not issue alerts even when its other criteria are met. -NOTE: Default exception lists do not display on the <> page in the {security-app} UI. +NOTE: Default exception lists do not display on the <> page in the {security-app} UI. ==== Request URL From b836b6d89f9381f53b96eb2ed23d3ed5268dc80e Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Wed, 3 Apr 2024 01:03:19 -0400 Subject: [PATCH 19/37] Minor changes and notes --- docs/detections/api/rules/rules-api-overview.asciidoc | 4 ++-- docs/siem-apis.asciidoc | 1 + 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc index 9cecaefac1..2cc56313ae 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -33,8 +33,8 @@ tags returns alerts, and updates their statuses * `:/api/detection_engine/rules/prepackaged` - Loads and retrieves the status of Elastic <> -* `:/api/detection_engine//exceptions` - Creates a default exception list for the rule you specify. -* `:/api/detection_engine/rules//exceptions` - Creates an exception item for a specified rule +* `:/api/detection_engine//exceptions` - Creates a default exception list for the rule you specify +* `:/api/detection_engine/rules//exceptions` - Creates exception items for the rule you specify TIP: You can view and download a Detections API Postman collection https://github.com/elastic/examples/tree/master/Security%20Analytics/SIEM-examples/Detections-API[here]. diff --git a/docs/siem-apis.asciidoc b/docs/siem-apis.asciidoc index 3d3971fbf6..b13e1fd834 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -14,6 +14,7 @@ NOTE: Console supports sending requests to {kib} APIs. Prepend any {kib} API end `GET kbn:/api/index_management/indices` * <>: Manage detection rules and alerts +//Might need to udpdate this description since there are now exception endpoints under the detection rule API. * <>: Create and manage rule exceptions * <>: Create source event value lists for use with rule exceptions * <>: Import and export timelines From 52424a4baf12989e14f1a07d387de4cace0d557c Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Wed, 3 Apr 2024 17:14:27 -0400 Subject: [PATCH 20/37] Fixed route in example --- .../rules/rules-api-create-single-rule-exception-item.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index 0851a4335c..db35b089a7 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -24,7 +24,7 @@ A JSON object with an array of exception items, where each exception item has th [source,console] -------------------------------------------------- -POST api/detection_engine/rules/_bulk_create +POST api/detection_engine/rules//exceptions { "items": [ { From 580f43309225cb73644d50e8570986a78c942785 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Wed, 3 Apr 2024 17:07:50 -0400 Subject: [PATCH 21/37] Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc --- .../rules/rules-api-create-rule-default-exception-list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index f0ebda9133..47ffec7a8b 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -1,5 +1,5 @@ [[exceptions-api-create-rule-default-exception-list]] -=== Create a default exception list for a rule +=== Create default exception list for a rule Creates a default exception list for the rule you specify. Default exception lists can only be associated with a single rule. From 80f7417ab3b7bab1417d68b77d426f6048324072 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Wed, 3 Apr 2024 17:07:59 -0400 Subject: [PATCH 22/37] Update docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc --- .../rules/rules-api-create-single-rule-exception-item.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index db35b089a7..66b21c6775 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -1,5 +1,5 @@ [[exceptions-api-create-rule-default-exception-item]] -=== Create exceptions for individual rules +=== Create exceptions for a rule Allows you to create exception items that are associated with a specified rule `id`. From 1ab1940d10db8de82446f4c0e6a1c5abc8c1e5df Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Wed, 3 Apr 2024 17:09:35 -0400 Subject: [PATCH 23/37] Update docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc --- .../rules/rules-api-create-single-rule-exception-item.asciidoc | 1 + 1 file changed, 1 insertion(+) diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index 66b21c6775..35b3c5e598 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -15,6 +15,7 @@ A JSON object with an array of exception items, where each exception item has th [width="100%",options="header"] |============================================== +|Name |Type |Description |Required |`items` |String | Specify an array of exception list items to create. |Yes From 9317b588d4eb05589048dd9943784e9906fc4388 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Wed, 3 Apr 2024 17:28:04 -0400 Subject: [PATCH 24/37] Remove comment chars --- .../api/exceptions/api-update-exception-item.asciidoc | 1 - docs/siem-apis.asciidoc | 6 +++--- 2 files changed, 3 insertions(+), 4 deletions(-) diff --git a/docs/detections/api/exceptions/api-update-exception-item.asciidoc b/docs/detections/api/exceptions/api-update-exception-item.asciidoc index e14b76296d..5db11fcf94 100644 --- a/docs/detections/api/exceptions/api-update-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-update-exception-item.asciidoc @@ -1,6 +1,5 @@ [[exceptions-api-update-item]] === Update exception item -//Check if this endpoint can also be used to update rule default exceptions. .New API Reference [sidebar] diff --git a/docs/siem-apis.asciidoc b/docs/siem-apis.asciidoc index b13e1fd834..771cb12354 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -13,9 +13,9 @@ You can use these APIs to interface with {elastic-sec} features: NOTE: Console supports sending requests to {kib} APIs. Prepend any {kib} API endpoint with `kbn:` and send the request via Console. For example: `GET kbn:/api/index_management/indices` -* <>: Manage detection rules and alerts -//Might need to udpdate this description since there are now exception endpoints under the detection rule API. -* <>: Create and manage rule exceptions +* <>: Manage detection rules, rule exceptions for individual rules, and alerts +* <>: Create and manage shared rule exceptions +//Will finalize descriptions once get confirmation from Yara about exception API endpoints * <>: Create source event value lists for use with rule exceptions * <>: Import and export timelines * <>: Open and manage cases From a32204d8313e33e96ec600c805e02a37687711a7 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Mon, 19 Aug 2024 18:29:18 -0400 Subject: [PATCH 25/37] Input from Yara --- ...reate-rule-default-exception-list.asciidoc | 2 +- ...create-single-rule-exception-item.asciidoc | 46 +++++++++++++------ docs/siem-apis.asciidoc | 3 +- 3 files changed, 33 insertions(+), 18 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index 47ffec7a8b..25b0ec443e 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -7,7 +7,7 @@ To add exception items to a default exception list, pass in exceptions items tha When an exception item’s query evaluates to `true`, the associated rule does not issue alerts even when its other criteria are met. -NOTE: Default exception lists do not display on the <> page in the {security-app} UI. +NOTE: Default exception lists do not display on the **Shared Exception Lists page in the {security-app} UI. They only appear in the Rule exceptions on the rule details page. Refer to <> to learn more. ==== Request URL diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index 35b3c5e598..8a5cf42f8f 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -1,13 +1,26 @@ [[exceptions-api-create-rule-default-exception-item]] === Create exceptions for a rule -Allows you to create exception items that are associated with a specified rule `id`. +Adds specified exception items to a rule's default exception list. +A default exception list contains exceptions that are associated with a single rule, as opposed to a shared exception list, which contains exceptions that are associated with multiple rules. + +If a default exception list doesn't exist, one is automatically created associated with the rule. ==== Request URL `POST :/api/detection_engine/rules//exceptions` -//include a tip on how to find a rule's ID +Allows you to create exception items that are associated with a specified rule `id`. + +===== URL query parameters + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`id` |String |Specify the rule ID. |Yes. + +|============================================== ==== Request body @@ -29,20 +42,23 @@ POST api/detection_engine/rules//exceptions { "items": [ { - "field": "process.name", - "operator": "included", - "type": "match", - "value": "maintenance-job" + "description": "Excludes the weekly maintenance job", + "entries": [ + { + "field": "process.name", + "operator": "included", + "type": "match", + "value": "maintenance-job" + } + ], + "name": "Linux maintenance job", + "tags": [ + "in-house processes", + "linux" + ], + "type": "simple" } - ], - "list_id": "trusted-linux-processes", - "name": "Linux maintenance job", - "namespace_type": "single", - "tags": [ - "in-house processes", - "linux" - ], - "type": "simple" + ] } -------------------------------------------------- diff --git a/docs/siem-apis.asciidoc b/docs/siem-apis.asciidoc index 771cb12354..f95d663da4 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -14,8 +14,7 @@ NOTE: Console supports sending requests to {kib} APIs. Prepend any {kib} API end `GET kbn:/api/index_management/indices` * <>: Manage detection rules, rule exceptions for individual rules, and alerts -* <>: Create and manage shared rule exceptions -//Will finalize descriptions once get confirmation from Yara about exception API endpoints +* <>: Create and manage rule exceptions * <>: Create source event value lists for use with rule exceptions * <>: Import and export timelines * <>: Open and manage cases From 600fec07c3e9c28ec4ecf50e6c8f9fac39621d8d Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 20 Aug 2024 09:32:26 -0400 Subject: [PATCH 26/37] Refreshed params --- .../api-create-exception-item.asciidoc | 30 +++--- ...create-single-rule-exception-item.asciidoc | 96 ++++++++++++++++++- 2 files changed, 107 insertions(+), 19 deletions(-) diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 55c66c2618..411617401f 100644 --- a/docs/detections/api/exceptions/api-create-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-item.asciidoc @@ -11,8 +11,6 @@ Creates an exception item and associates it with the specified <>. -TIP: Refer to <> for information about creating exceptions for a single rule. - [IMPORTANT] ===== * Before creating exception items, you must create an <>. After creating the container, you can associate exception items with it. @@ -28,7 +26,7 @@ following fields cannot be used in exception queries (as `field` values in the ** `process.ancestry` ===== -NOTE: Refer to <> for information about creating exception items from lists, such as a list of IP addresses or host names. +TIP: For more information about creating exceptions for a single rule, refer to <>. For more information about creating exception items from a list, such as a list of IP addresses or hosts names, refer to <>. ==== Request URL @@ -42,11 +40,11 @@ A JSON object with these fields: |============================================== |Name |Type |Description |Required -|`comments` |comments[] a|Array of `comment` fields: +|`comments` |String[] a|Array of `comment` fields. Default value is [] (empty): * `comment` (string): Comments about the exception item. -|No, defaults to empty array. +|No |`description` |String |Describes the exception item. |Yes |`entries` |<> |Array containing the @@ -65,22 +63,22 @@ in all {kib} spaces or just the space in which it is created, where: * `single`: Only available in the {kib} space in which it is created. * `agnostic`: Available in all {kib} spaces. -Must be the same value as its associated exception container. +Must be the same value as its associated exception container. Default value is `single`. -|No, defaults to `single`. -|`tags` |String[] |String array containing words and phrases to help categorize -exception items. |No -|`type` |String a|Exception query type, must be `simple`. |Yes -|`_tags` |String[] a|For endpoint rules only, defines the OS on which the +|No +|`os_types` |String[] a|Defines the OS on which the exception is implemented. Valid values are: * `os:windows`: Windows OS * `os:linux`: Linux OS -* `os:macos`: Mac OS +* `os:macos`: Mac OS -The array must also include an `endpoint` element (to implement the exception on Linux hosts, use: `["endpoint", "os:linux"]`). +Default value is [] (empty). -|For endpoint exceptions, yes. For detection exceptions, no. +|No +|`tags` |String[] |String array containing words and phrases to help categorize +exception items. |No +|`type` |String a|Exception query type, must be `simple`. |Yes |============================================== @@ -93,10 +91,6 @@ The array must also include an `endpoint` element (to implement the exception on |`field` |String |The source event field used to define the exception. Cannot be an empty string. |Yes -|`list` |list |Object containing the -<> `id` and `type`. Only valid for -detection exception items.|No, except when using a list to define detection -exceptions. |`operator` |String a|The operator used to determine when the exception is used. Can be: diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index 8a5cf42f8f..178914cf2a 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -6,6 +6,8 @@ A default exception list contains exceptions that are associated with a single r If a default exception list doesn't exist, one is automatically created associated with the rule. +TIP: For more information about creating exceptions that are used by multiple rules, refer to <>. For more information about creating exception items from a list, such as a list of IP addresses or hosts names, refer to <>. + ==== Request URL `POST :/api/detection_engine/rules//exceptions` @@ -30,9 +32,101 @@ A JSON object with an array of exception items, where each exception item has th |============================================== |Name |Type |Description |Required -|`items` |String | Specify an array of exception list items to create. |Yes +|`items` |String[] | Specify an array of exception list items to create. |Yes +|`comments` |Object[] a|Array of `comment` fields. Default value is [] (empty): + +* `comment` (string): Comments about the exception item. + +|No + +|`description` |String |Describes the exception item. |Yes +|`entries` |<> |Array containing the +exception queries. Boolean `AND` logic is used to evaluate the relationship +between array elements. If you want to use `OR` logic, create a separate +exception item. |Yes +|`expire_time` |String |The exception item's expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. |No +|`list_id` |String |ID of the associated <>. |Yes +|`item_id` |String |Unique identifier of the exception item. |No, automatically +created when it is not provided. +|`meta` |Object |Placeholder for metadata about the exception item. |No +|`name` |String |The exception item's name. |Yes +|`namespace_type` |String a|Determines whether the exception item is available +in all {kib} spaces or just the space in which it is created, where: + +* `single`: Only available in the {kib} space in which it is created. +* `agnostic`: Available in all {kib} spaces. + +Must be the same value as its associated exception container. Default value is `single`. + +|No +|`os_types` |String[] a|Defines the OS on which the +exception is implemented. Valid values are: + +* `os:windows`: Windows OS +* `os:linux`: Linux OS +* `os:macos`: Mac OS +Default value is [] (empty). + +|No +|`tags` |String[] |String array containing words and phrases to help categorize +exception items. |No +|`type` |String a|Exception query type, must be `simple`. |Yes + +|============================================== + + +[[entries-object-schema-single-rule-exceptions]] +===== `entries` schema + +[width="100%",options="header"] |============================================== +|Name |Type |Description |Required + +|`field` |String |The source event field used to define the exception. Cannot +be an empty string. |Yes +|`operator` |String a|The operator used to determine when the exception is used. +Can be: + +* `included`: The `field` has the specified value or values. +* `excluded`: The `field` does not have specified value or values. + +|Yes + +|`type` |String a|The `type` of query: + +* `match`: Must be an exact match of the defined value. +* `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 {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` +type. + +|Yes + +|`value` +a|String + +String[] + +a|Field value or values: + +* String: When the `type` is `match` or `wildcard`. +* String[]: When the `type` is `match_any`. + +|Yes, except when `type` is `exists` or `list`. + +|============================================== + +IMPORTANT: When you use <> +(`"type": "list"`), you cannot use other types in the `entries` array (`match`, +`match_any`, `exists`, or `nested`). + +For endpoint exceptions, you cannot create exception items based on excluded +values (`"operator": "excluded"`). ===== Example requests From f301ba1b10f27edded7b178dcb2268f867854d2a Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 20 Aug 2024 11:04:29 -0400 Subject: [PATCH 27/37] minor style fixes --- .../api/exceptions/api-create-exception-item.asciidoc | 4 ++-- .../rules-api-create-single-rule-exception-item.asciidoc | 2 +- 2 files changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 411617401f..f2cf2c7c4f 100644 --- a/docs/detections/api/exceptions/api-create-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-item.asciidoc @@ -40,7 +40,7 @@ A JSON object with these fields: |============================================== |Name |Type |Description |Required -|`comments` |String[] a|Array of `comment` fields. Default value is [] (empty): +|`comments` |String[] a|Array of `comment` fields. Default value is `[]` (empty): * `comment` (string): Comments about the exception item. @@ -73,7 +73,7 @@ exception is implemented. Valid values are: * `os:linux`: Linux OS * `os:macos`: Mac OS -Default value is [] (empty). +Default value is `[]` (empty). |No |`tags` |String[] |String array containing words and phrases to help categorize diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index 178914cf2a..ac2ed83198 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -66,7 +66,7 @@ exception is implemented. Valid values are: * `os:linux`: Linux OS * `os:macos`: Mac OS -Default value is [] (empty). +Default value is `[]` (empty). |No |`tags` |String[] |String array containing words and phrases to help categorize From bf3a09f8bc7427ed5b18d7436e97657ae4f2bd7f Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Thu, 10 Oct 2024 13:37:56 -0400 Subject: [PATCH 28/37] Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc --- .../rules/rules-api-create-rule-default-exception-list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index 25b0ec443e..f0505c628a 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -49,7 +49,7 @@ items: [source,console] -------------------------------------------------- -POST api/exception_lists +POST api/detection_engine//exceptions { "description": "Excludes Linux trusted processes", "name": "Linux process exceptions", From ed6e91418b28a0db46aa87747f719da79805ec78 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Mon, 13 Jan 2025 16:50:17 -0500 Subject: [PATCH 29/37] Update docs/detections/api/exceptions/api-create-exception-container.asciidoc Co-authored-by: Yara Tercero --- .../api/exceptions/api-create-exception-container.asciidoc | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/docs/detections/api/exceptions/api-create-exception-container.asciidoc b/docs/detections/api/exceptions/api-create-exception-container.asciidoc index a490443413..ac83a4a37f 100644 --- a/docs/detections/api/exceptions/api-create-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-container.asciidoc @@ -49,7 +49,9 @@ provided. exception containers. |No |`type` |String a|The type of exception list, which must be one of these: -* `detection`: Shared rule exception +* `detection`: Shared rule exception list +* `endpoint`: Endpoint rule exception list +* `rule_default`: Single rule exception list * `endpoint`: Endpoint rule exception * `rule_default`: Single rule exception From f9529863eff6a863c5cdf64a0ec6d398da6ca241 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 14 Jan 2025 09:22:00 -0500 Subject: [PATCH 30/37] Update docs/detections/api/exceptions/api-update-exception-container.asciidoc --- .../api/exceptions/api-update-exception-container.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/exceptions/api-update-exception-container.asciidoc b/docs/detections/api/exceptions/api-update-exception-container.asciidoc index 3b71dd741c..b799c0b697 100644 --- a/docs/detections/api/exceptions/api-update-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-update-exception-container.asciidoc @@ -35,7 +35,7 @@ the container's `id` field is not used. exception containers. |No |`type` |String a|The type of exception, which must be one of these: -|`type` |String a|The type of exception list, which must be one of these: +|`type` |String a|The type of exception list. Valid values are: * `detection`: Shared rule exception * `endpoint`: Endpoint rule exception From 4b45ed190a2a631d3f393d6aa8a49f30026a9db4 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 14 Jan 2025 09:22:50 -0500 Subject: [PATCH 31/37] Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- .../rules/rules-api-create-rule-default-exception-list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index f0505c628a..e55e754560 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -7,7 +7,7 @@ To add exception items to a default exception list, pass in exceptions items tha When an exception item’s query evaluates to `true`, the associated rule does not issue alerts even when its other criteria are met. -NOTE: Default exception lists do not display on the **Shared Exception Lists page in the {security-app} UI. They only appear in the Rule exceptions on the rule details page. Refer to <> to learn more. +NOTE: Default exception lists do not display on the **Shared Exception Lists** page in the {security-app} UI. They only appear in the Rule exceptions on the rule details page. Refer to <> to learn more. ==== Request URL From 8275775933334ccd53899d56a98a2374570ff7c1 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 14 Jan 2025 09:41:06 -0500 Subject: [PATCH 32/37] Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- .../rules/rules-api-create-rule-default-exception-list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index e55e754560..a61c084305 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -36,7 +36,7 @@ provided. exception containers. |No |`type` |String a|The type of exception, which must be: -* `rule_default`: Exception list that belongs to a single rule +* `rule_default`: Exception list that belongs to a single rule. |Yes From 2b85ddb1111f6171e64abc927bf680ade0d75050 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 14 Jan 2025 09:51:17 -0500 Subject: [PATCH 33/37] Ben's suggestion --- .../rules-api-create-rule-default-exception-list.asciidoc | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index a61c084305..536ddb681e 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -1,13 +1,13 @@ [[exceptions-api-create-rule-default-exception-list]] === Create default exception list for a rule -Creates a default exception list for the rule you specify. Default exception lists can only be associated with a single rule. +Creates a default exception list for the rule you specify. To add exception items to a default exception list, pass in exceptions items that you want applied to the rule. Refer to <> for more information. When an exception item’s query evaluates to `true`, the associated rule does not issue alerts even when its other criteria are met. -NOTE: Default exception lists do not display on the **Shared Exception Lists** page in the {security-app} UI. They only appear in the Rule exceptions on the rule details page. Refer to <> to learn more. +NOTE: Default exception lists do not display on the **Shared Exception Lists** page in the {security-app} UI; they only appear in the Rule exceptions on the rule details page. This is because default exception lists can only be associated with a single rule. Refer to <> to learn more. ==== Request URL From 404bc9dce509f0c8b597da7a86ce1a852866012d Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 14 Jan 2025 10:08:05 -0500 Subject: [PATCH 34/37] Update docs/detections/api/rules/rules-api-overview.asciidoc --- docs/detections/api/rules/rules-api-overview.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-overview.asciidoc b/docs/detections/api/rules/rules-api-overview.asciidoc index 2cc56313ae..14ec399be2 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -34,7 +34,7 @@ returns alerts, and updates their statuses * `:/api/detection_engine/rules/prepackaged` - Loads and retrieves the status of Elastic <> * `:/api/detection_engine//exceptions` - Creates a default exception list for the rule you specify -* `:/api/detection_engine/rules//exceptions` - Creates exception items for the rule you specify +* `:/api/detection_engine/rules//exceptions` - Creates exception items for a rule's default exception list. TIP: You can view and download a Detections API Postman collection https://github.com/elastic/examples/tree/master/Security%20Analytics/SIEM-examples/Detections-API[here]. From af5b3517db62ebd3d9b2663a9c87e964c2c02011 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 14 Jan 2025 10:10:19 -0500 Subject: [PATCH 35/37] Update docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> --- .../rules/rules-api-create-single-rule-exception-item.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc index ac2ed83198..f3ef5a4072 100644 --- a/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -4,7 +4,7 @@ Adds specified exception items to a rule's default exception list. A default exception list contains exceptions that are associated with a single rule, as opposed to a shared exception list, which contains exceptions that are associated with multiple rules. -If a default exception list doesn't exist, one is automatically created associated with the rule. +If a default exception list doesn't exist for a rule, one is automatically created when you try to add an exception to it. TIP: For more information about creating exceptions that are used by multiple rules, refer to <>. For more information about creating exception items from a list, such as a list of IP addresses or hosts names, refer to <>. From 68d3cb3078a6526ae5bc8b625905cd7fa2110bfa Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 14 Jan 2025 17:02:07 -0500 Subject: [PATCH 36/37] Replaced container with list --- ...-create-rule-default-exception-list.asciidoc | 17 ++++++++--------- 1 file changed, 8 insertions(+), 9 deletions(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index 536ddb681e..a69dca31f5 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -21,19 +21,19 @@ A JSON object with these fields: |============================================== |Name |Type |Description |Required -|`description` |String |Describes the exception container. |Yes +|`description` |String |Describes the exception list. |Yes |`list_id` |String |Unique identifier. |No, automatically created when it is not provided. -|`meta` |Object |Placeholder for metadata about the list container. |No -|`name` |String |The exception container's name. |Yes -|`namespace_type` |String a|Determines whether the exception container is available in all {kib} spaces or just the space in which it is created, where: +|`meta` |Object |Placeholder for metadata about the list lit. |No +|`name` |String |The exception list's name. |Yes +|`namespace_type` |String a|Determines whether the exception list is available in all {kib} spaces or just the space in which it is created, where: * `single`: Only available in the {kib} space in which it is created. * `agnostic`: Available in all {kib} spaces. |No, defaults to `single`. |`tags` |String[] |String array containing words and phrases to help categorize -exception containers. |No +exception lists. |No |`type` |String a|The type of exception, which must be: * `rule_default`: Exception list that belongs to a single rule. @@ -44,7 +44,7 @@ exception containers. |No ===== Example requests -Creates an exception container for holding trusted Linux process exception +Creates an exception list for holding trusted Linux process exception items: [source,console] @@ -72,7 +72,7 @@ POST api/detection_engine//exceptions ==== Response payload -The exception container object with a unique ID. +The exception list object with a unique ID. [source,json] -------------------------------------------------- @@ -96,8 +96,7 @@ The exception container object with a unique ID. } -------------------------------------------------- -These values are required to associate the exception container with detection -rules: +The highlighted values can help you identify detection rules associated with the exception list: <1> `id` <2> `list_id` From 1cca3ee16835eb38da1cf536eee45500243a8a71 Mon Sep 17 00:00:00 2001 From: "nastasha.solomon" Date: Tue, 14 Jan 2025 17:29:09 -0500 Subject: [PATCH 37/37] fixed typo --- .../rules/rules-api-create-rule-default-exception-list.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc index a69dca31f5..334a233557 100644 --- a/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -24,7 +24,7 @@ A JSON object with these fields: |`description` |String |Describes the exception list. |Yes |`list_id` |String |Unique identifier. |No, automatically created when it is not provided. -|`meta` |Object |Placeholder for metadata about the list lit. |No +|`meta` |Object |Placeholder for metadata about the exception list. |No |`name` |String |The exception list's name. |Yes |`namespace_type` |String a|Determines whether the exception list is available in all {kib} spaces or just the space in which it is created, where: