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 3dadd40a0f..254bade35c 100644 --- a/docs/detections/api/exceptions/api-create-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-container.asciidoc @@ -41,10 +41,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 +* `detection`: Shared rule exception +* `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 faa6d8192f..c4b9f9e9d8 100644 --- a/docs/detections/api/exceptions/api-create-exception-item.asciidoc +++ b/docs/detections/api/exceptions/api-create-exception-item.asciidoc @@ -1,24 +1,24 @@ [[exceptions-api-create-exception-item]] -=== Create exception item +=== Create exceptions used by multiple rules -Creates an exception item and associates it with the specified -<>. +Creates an exception item that you can add to a shared exception list or endpoint exception list. -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 @@ -32,11 +32,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 @@ -55,22 +55,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 |============================================== @@ -83,10 +83,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 e8aaa0edfd..64dc82ee0c 100644 --- a/docs/detections/api/exceptions/api-update-exception-container.asciidoc +++ b/docs/detections/api/exceptions/api-update-exception-container.asciidoc @@ -29,8 +29,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 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..f0505c628a --- /dev/null +++ b/docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc @@ -0,0 +1,105 @@ +[[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. + +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. + +==== 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 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 list that belongs to a single rule + +|Yes + +|============================================== + +===== Example requests + +Creates an exception container 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 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` 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..ac2ed83198 --- /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, 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` + +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 eebf54add1..9a043a9ead 100644 --- a/docs/detections/api/rules/rules-api-overview.asciidoc +++ b/docs/detections/api/rules/rules-api-overview.asciidoc @@ -27,6 +27,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 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 a0a2f8e930..d0c26a2b78 100644 --- a/docs/siem-apis.asciidoc +++ b/docs/siem-apis.asciidoc @@ -8,8 +8,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