Skip to content

Commit 3bfaa14

Browse files
mergify[bot]nastasha-solomon
mergify[bot]
and
nastasha-solomon
authored
[8.x] [Detection Engine][Exceptions] - Update docs for single and shared exceptions (backport #4021) (#6441)
* 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 <[email protected]> * 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 <[email protected]> * Update docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc Co-authored-by: Benjamin Ironside Goldstein <[email protected]> * 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 <[email protected]> * Replaced container with list * fixed typo --------- Co-authored-by: Yara Tercero <[email protected]> Co-authored-by: Benjamin Ironside Goldstein <[email protected]> (cherry picked from commit 414527e) Co-authored-by: Nastasha Solomon <[email protected]>
1 parent 8a5741d commit 3bfaa14

8 files changed

+343
-33
lines changed

‎docs/detections/api/det-api-index.asciidoc‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -12,6 +12,10 @@ include::rules/rules-api-delete.asciidoc[]
1212

1313
include::rules/rules-api-bulk-actions.asciidoc[]
1414

15+
include::rules/rules-api-create-rule-default-exception-list.asciidoc[]
16+
17+
include::rules/rules-api-create-single-rule-exception-item.asciidoc[]
18+
1519
include::rules/index-api-overview.asciidoc[]
1620

1721
include::rules/tags-api-overview.asciidoc[]

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

Lines changed: 6 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -47,10 +47,13 @@ provided.
4747
|No, defaults to `single`.
4848
|`tags` |String[] |String array containing words and phrases to help categorize
4949
exception containers. |No
50-
|`type` |String a|The type of exception, which must be one of these:
50+
|`type` |String a|The type of exception list, which must be one of these:
5151

52-
* `detection`: Detection rule exception
53-
* `endpoint`: Endpoint alert exception
52+
* `detection`: Shared rule exception list
53+
* `endpoint`: Endpoint rule exception list
54+
* `rule_default`: Single rule exception list
55+
* `endpoint`: Endpoint rule exception
56+
* `rule_default`: Single rule exception
5457

5558
|Yes
5659

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

Lines changed: 24 additions & 26 deletions
Original file line numberDiff line numberDiff line change
@@ -1,5 +1,5 @@
11
[[exceptions-api-create-exception-item]]
2-
=== Create exception item
2+
=== Create exceptions used by multiple rules
33

44
.New API Reference
55
[sidebar]
@@ -10,21 +10,23 @@ For the most up-to-date API details, refer to {api-kibana}/group/endpoint-securi
1010
Creates an exception item and associates it with the specified
1111
<<exceptions-api-create-container, exception container>>.
1212

13-
Refer to <<lists-api-overview>> for information about creating exception items from
14-
lists, such as a list of IP addresses or host names.
1513

16-
NOTE: Before creating exception items, you must create an exception container.
17-
18-
IMPORTANT: Endpoint rule exception items cannot use
14+
[IMPORTANT]
15+
=====
16+
* 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.
17+
* Endpoint rule exception items cannot use
1918
<<lists-api-overview, lists>> (the `list` in the `entries` array), and the
2019
following fields cannot be used in exception queries (as `field` values in the
2120
`entries` object):
2221
23-
* `file.Ext.quarantine_path`
24-
* `file.Ext.quarantine_result`
25-
* `process.entity_id`
26-
* `process.parent.entity_id`
27-
* `process.ancestry`
22+
** `file.Ext.quarantine_path`
23+
** `file.Ext.quarantine_result`
24+
** `process.entity_id`
25+
** `process.parent.entity_id`
26+
** `process.ancestry`
27+
=====
28+
29+
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>>.
2830

2931
==== Request URL
3032

@@ -38,11 +40,11 @@ A JSON object with these fields:
3840
|==============================================
3941
|Name |Type |Description |Required
4042

41-
|`comments` |comments[] a|Array of `comment` fields:
43+
|`comments` |String[] a|Array of `comment` fields. Default value is `[]` (empty):
4244

4345
* `comment` (string): Comments about the exception item.
4446

45-
|No, defaults to empty array.
47+
|No
4648

4749
|`description` |String |Describes the exception item. |Yes
4850
|`entries` |<<entries-object-schema, entries[]>> |Array containing the
@@ -61,22 +63,22 @@ in all {kib} spaces or just the space in which it is created, where:
6163
* `single`: Only available in the {kib} space in which it is created.
6264
* `agnostic`: Available in all {kib} spaces.
6365

64-
Must be the same value as its associated exception container.
66+
Must be the same value as its associated exception container. Default value is `single`.
6567

66-
|No, defaults to `single`.
67-
|`tags` |String[] |String array containing words and phrases to help categorize
68-
exception items. |No
69-
|`type` |String a|Exception query type, must be `simple`. |Yes
70-
|`_tags` |String[] a|For endpoint rules only, defines the OS on which the
68+
|No
69+
|`os_types` |String[] a|Defines the OS on which the
7170
exception is implemented. Valid values are:
7271

7372
* `os:windows`: Windows OS
7473
* `os:linux`: Linux OS
75-
* `os:macos`: Mac OS
74+
* `os:macos`: Mac OS
7675

77-
The array must also include an `endpoint` element (to implement the exception on Linux hosts, use: `["endpoint", "os:linux"]`).
76+
Default value is `[]` (empty).
7877

79-
|For endpoint exceptions, yes. For detection exceptions, no.
78+
|No
79+
|`tags` |String[] |String array containing words and phrases to help categorize
80+
exception items. |No
81+
|`type` |String a|Exception query type, must be `simple`. |Yes
8082

8183
|==============================================
8284

@@ -89,10 +91,6 @@ The array must also include an `endpoint` element (to implement the exception on
8991

9092
|`field` |String |The source event field used to define the exception. Cannot
9193
be an empty string. |Yes
92-
|`list` |list |Object containing the
93-
<<lists-api-create-container, list container's>> `id` and `type`. Only valid for
94-
detection exception items.|No, except when using a list to define detection
95-
exceptions.
9694
|`operator` |String a|The operator used to determine when the exception is used.
9795
Can be:
9896

‎docs/detections/api/exceptions/api-update-exception-container.asciidoc‎

Lines changed: 5 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -35,8 +35,11 @@ the container's `id` field is not used.
3535
exception containers. |No
3636
|`type` |String a|The type of exception, which must be one of these:
3737

38-
* `detection`: Detection rule exception
39-
* `endpoint`: Endpoint alert exception
38+
|`type` |String a|The type of exception list. Valid values are:
39+
40+
* `detection`: Shared rule exception
41+
* `endpoint`: Endpoint rule exception
42+
* `rule_default`: Single rule exception
4043

4144
|Yes
4245

‎docs/detections/api/rules/rules-api-create-rule-default-exception-list.asciidoc‎

Lines changed: 104 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,104 @@
1+
[[exceptions-api-create-rule-default-exception-list]]
2+
=== Create default exception list for a rule
3+
4+
Creates a default exception list for the rule you specify.
5+
6+
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.
7+
8+
When an exception item’s query evaluates to `true`, the associated rule does not issue alerts even when its other criteria are met.
9+
10+
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.
11+
12+
==== Request URL
13+
14+
`POST <kibana host>:<port>/api/detection_engine/<rule_id>/exceptions`
15+
16+
==== Request body
17+
18+
A JSON object with these fields:
19+
20+
[width="100%",options="header"]
21+
|==============================================
22+
|Name |Type |Description |Required
23+
24+
|`description` |String |Describes the exception list. |Yes
25+
|`list_id` |String |Unique identifier. |No, automatically created when it is not
26+
provided.
27+
|`meta` |Object |Placeholder for metadata about the exception list. |No
28+
|`name` |String |The exception list's name. |Yes
29+
|`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:
30+
31+
* `single`: Only available in the {kib} space in which it is created.
32+
* `agnostic`: Available in all {kib} spaces.
33+
34+
|No, defaults to `single`.
35+
|`tags` |String[] |String array containing words and phrases to help categorize
36+
exception lists. |No
37+
|`type` |String a|The type of exception, which must be:
38+
39+
* `rule_default`: Exception list that belongs to a single rule.
40+
41+
|Yes
42+
43+
|==============================================
44+
45+
===== Example requests
46+
47+
Creates an exception list for holding trusted Linux process exception
48+
items:
49+
50+
[source,console]
51+
--------------------------------------------------
52+
POST api/detection_engine/<rule_id>/exceptions
53+
{
54+
"description": "Excludes Linux trusted processes",
55+
"name": "Linux process exceptions",
56+
"list_id": "trusted-linux-processes",
57+
"type": "detection",
58+
"namespace_type": "single",
59+
"tags": [
60+
"linux",
61+
"processes"
62+
]
63+
}
64+
--------------------------------------------------
65+
// KIBANA
66+
67+
==== Response code
68+
69+
`200`::
70+
Indicates a successful call.
71+
72+
73+
==== Response payload
74+
75+
The exception list object with a unique ID.
76+
77+
[source,json]
78+
--------------------------------------------------
79+
{
80+
"_tags": [],
81+
"created_at": "2020-07-13T09:33:46.187Z",
82+
"created_by": "elastic",
83+
"description": "Excludes Linux trusted processes",
84+
"id": "f320c070-c4eb-11ea-80bb-11861bae2798", <1>
85+
"list_id": "trusted-linux-processes", <2>
86+
"name": "Linux process exceptions",
87+
"namespace_type": "single", <3>
88+
"tags": [
89+
"linux",
90+
"processes"
91+
],
92+
"tie_breaker_id": "2c08d5a5-2ecc-4d5a-acfb-0a367f25b3f3",
93+
"type": "detection", <4>
94+
"updated_at": "2020-07-13T09:33:46.359Z",
95+
"updated_by": "elastic"
96+
}
97+
--------------------------------------------------
98+
99+
The highlighted values can help you identify detection rules associated with the exception list:
100+
101+
<1> `id`
102+
<2> `list_id`
103+
<3> `namespace_type`
104+
<4> `type`

0 commit comments

Comments
 (0)