[8.13] [Detection Engine][Exceptions] - Update docs for single and shared exceptions (backport #4021)

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[]

docs/detections/api/exceptions/api-create-exception-container.asciidoc

@@ -41,10 +41,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
 

docs/detections/api/exceptions/api-create-exception-item.asciidoc

@@ -1,24 +1,26 @@
 [[exceptions-api-create-exception-item]]
-=== Create exception item
+=== Create exceptions used by multiple rules
 
 Creates an exception item and associates it with the specified
 <<exceptions-api-create-container, exception container>>.
 
-Refer to <<lists-api-overview>> 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 <<exceptions-api-create-container, exception container>>. After creating the container, you can associate exception items with it.
+* Endpoint rule exception items cannot use
 <<lists-api-overview, lists>> (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 <<exceptions-api-create-rule-default-exception-item>>. For more information about creating exception items from a list, such as a list of IP addresses or hosts names, refer to <<lists-api-overview>>.
 
 ==== Request URL
 
@@ -32,11 +34,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` |<<entries-object-schema, entries[]>> |Array containing the
@@ -55,22 +57,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 +85,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
-<<lists-api-create-container, list container's>> `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:
 

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. Valid values are:
+
+* `detection`: Shared rule exception
+* `endpoint`: Endpoint rule exception
+* `rule_default`: Single rule exception 
 
 |Yes
 

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 <<exceptions-api-create-rule-default-exception-item>> 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 <<manage-exception>> to learn more.
+
+==== Request URL
+
+`POST <kibana host>:<port>/api/detection_engine/<rule_id>/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/<rule_id>/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`