From 68f9c144d0732a70e2825d87579deef32491be15 Mon Sep 17 00:00:00 2001 From: Nastasha Solomon <79124755+nastasha-solomon@users.noreply.github.com> Date: Tue, 21 Jan 2025 13:01:12 -0500 Subject: [PATCH] [Detection Engine][Exceptions] - Update docs for single and shared exceptions (#4021) * First draft * Fixed include * Update/create exception changes * Update docs/detections/api/exceptions/api-create-rule-default-exception-list.asciidoc * Revising intro * Adding new topic * Fixing refs * Removed duplicate entry * Yara's input * Minor wording changes * Title update * Modifies title for shared exceptions * Fixing conflicts * attempt number 2 * Added file ext to index file * Closing table * Update docs/detections/api/rules/rules-api-overview.asciidoc * Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc * Minor changes and notes * Fixed route in example * Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc * Update docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc * Update docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc * Remove comment chars * Input from Yara * Refreshed params * minor style fixes * Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc * Update docs/detections/api/exceptions/api-create-exception-container.asciidoc Co-authored-by: Yara Tercero * Update docs/detections/api/exceptions/api-update-exception-container.asciidoc * 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> * 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> * Ben's suggestion * Update docs/detections/api/rules/rules-api-overview.asciidoc * 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> * Replaced container with list * fixed typo --------- Co-authored-by: Yara Tercero Co-authored-by: Benjamin Ironside Goldstein <91905639+benironside@users.noreply.github.com> (cherry picked from commit 414527e612e72c36611a4ef87b14c185ecb79f5c) --- docs/detections/api/det-api-index.asciidoc | 4 + .../api-create-exception-container.asciidoc | 9 +- .../api-create-exception-item.asciidoc | 50 +++-- .../api-update-exception-container.asciidoc | 7 +- ...reate-rule-default-exception-list.asciidoc | 104 ++++++++++ ...create-single-rule-exception-item.asciidoc | 196 ++++++++++++++++++ .../api/rules/rules-api-overview.asciidoc | 2 + docs/siem-apis.asciidoc | 4 +- 8 files changed, 343 insertions(+), 33 deletions(-) create mode 100644 docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc create mode 100644 docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc diff --git a/docs/detections/api/det-api-index.asciidoc b/docs/detections/api/det-api-index.asciidoc index f9ce608488..aea3c3b548 100644 --- a/docs/detections/api/det-api-index.asciidoc +++ b/docs/detections/api/det-api-index.asciidoc @@ -12,6 +12,10 @@ 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[] include::rules/tags-api-overview.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..ac83a4a37f 100644 --- a/docs/detections/api/exceptions/api-create-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-container.asciidoc @@ -47,10 +47,13 @@ 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 +* `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 |Yes diff --git a/docs/detections/api/exceptions/api-create-exception-item.asciidoc b/docs/detections/api/exceptions/api-create-exception-item.asciidoc index 1e4aa5be29..f2cf2c7c4f 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] @@ -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` +===== + +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 @@ -38,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 @@ -61,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 |============================================== @@ -89,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/exceptions/api-update-exception-container.asciidoc b/docs/detections/api/exceptions/api-update-exception-container.asciidoc index 5afead7f7a..b799c0b697 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. Valid values are: + +* `detection`: Shared rule exception +* `endpoint`: Endpoint rule exception +* `rule_default`: Single rule exception |Yes 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 new file mode 100644 index 0000000000..334a233557 --- /dev/null +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -0,0 +1,104 @@ +[[exceptions-api-create-rule-default-exception-list]] +=== Create default exception list for a 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. This is because default exception lists can only be associated with a single rule. Refer to <> to learn more. + +==== Request URL + +`POST :/api/detection_engine//exceptions` + +==== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`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 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: + +* `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 lists. |No +|`type` |String a|The type of exception, which must be: + +* `rule_default`: Exception list that belongs to a single rule. + +|Yes + +|============================================== + +===== Example requests + +Creates an exception list for holding trusted Linux process exception +items: + +[source,console] +-------------------------------------------------- +POST api/detection_engine//exceptions +{ + "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 list 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" +} +-------------------------------------------------- + +The highlighted values can help you identify detection rules associated with the exception list: + +<1> `id` +<2> `list_id` +<3> `namespace_type` +<4> `type` 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 new file mode 100644 index 0000000000..f3ef5a4072 --- /dev/null +++ b/docs/detections/api/rules/rules-api-create-single-rule-exception-item.asciidoc @@ -0,0 +1,196 @@ +[[exceptions-api-create-rule-default-exception-item]] +=== Create exceptions for a rule + +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 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 <>. + +==== Request URL + +`POST :/api/detection_engine/rules//exceptions` + +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 + +A JSON object with an array of exception items, where each exception item has the <>. + +[width="100%",options="header"] +|============================================== +|Name |Type |Description |Required + +|`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 + +[source,console] +-------------------------------------------------- +POST api/detection_engine/rules//exceptions +{ + "items": [ + { + "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" + } + ] +} +-------------------------------------------------- + +==== 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..14ec399be2 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -33,6 +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 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]. diff --git a/docs/siem-apis.asciidoc b/docs/siem-apis.asciidoc index 3d3971fbf6..f95d663da4 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -13,8 +13,8 @@ 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 -* <>: Create and manage rule exceptions +* <>: Manage detection rules, rule exceptions for individual rules, and alerts +* <>: Create and manage rule exceptions * <>: Create source event value lists for use with rule exceptions * <>: Import and export timelines * <>: Open and manage cases