Skip to content

Commit 1431a75

Browse files
nastasha-solomonyctercerobenironside
authored and
mergify[bot]
committed
[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 <[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)
1 parent a2f321f commit 1431a75

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
@@ -41,10 +41,13 @@ provided.
4141
|No, defaults to `single`.
4242
|`tags` |String[] |String array containing words and phrases to help categorize
4343
exception containers. |No
44-
|`type` |String a|The type of exception, which must be one of these:
44+
|`type` |String a|The type of exception list, which must be one of these:
4545

46-
* `detection`: Detection rule exception
47-
* `endpoint`: Endpoint alert exception
46+
* `detection`: Shared rule exception list
47+
* `endpoint`: Endpoint rule exception list
48+
* `rule_default`: Single rule exception list
49+
* `endpoint`: Endpoint rule exception
50+
* `rule_default`: Single rule exception
4851

4952
|Yes
5053

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

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

44
Creates an exception item and associates it with the specified
55
<<exceptions-api-create-container, exception container>>.
66

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

10-
NOTE: Before creating exception items, you must create an exception container.
11-
12-
IMPORTANT: Endpoint rule exception items cannot use
8+
[IMPORTANT]
9+
=====
10+
* 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.
11+
* Endpoint rule exception items cannot use
1312
<<lists-api-overview, lists>> (the `list` in the `entries` array), and the
1413
following fields cannot be used in exception queries (as `field` values in the
1514
`entries` object):
1615
17-
* `file.Ext.quarantine_path`
18-
* `file.Ext.quarantine_result`
19-
* `process.entity_id`
20-
* `process.parent.entity_id`
21-
* `process.ancestry`
16+
** `file.Ext.quarantine_path`
17+
** `file.Ext.quarantine_result`
18+
** `process.entity_id`
19+
** `process.parent.entity_id`
20+
** `process.ancestry`
21+
=====
22+
23+
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>>.
2224

2325
==== Request URL
2426

@@ -32,11 +34,11 @@ A JSON object with these fields:
3234
|==============================================
3335
|Name |Type |Description |Required
3436

35-
|`comments` |comments[] a|Array of `comment` fields:
37+
|`comments` |String[] a|Array of `comment` fields. Default value is `[]` (empty):
3638

3739
* `comment` (string): Comments about the exception item.
3840

39-
|No, defaults to empty array.
41+
|No
4042

4143
|`description` |String |Describes the exception item. |Yes
4244
|`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:
5557
* `single`: Only available in the {kib} space in which it is created.
5658
* `agnostic`: Available in all {kib} spaces.
5759

58-
Must be the same value as its associated exception container.
60+
Must be the same value as its associated exception container. Default value is `single`.
5961

60-
|No, defaults to `single`.
61-
|`tags` |String[] |String array containing words and phrases to help categorize
62-
exception items. |No
63-
|`type` |String a|Exception query type, must be `simple`. |Yes
64-
|`_tags` |String[] a|For endpoint rules only, defines the OS on which the
62+
|No
63+
|`os_types` |String[] a|Defines the OS on which the
6564
exception is implemented. Valid values are:
6665

6766
* `os:windows`: Windows OS
6867
* `os:linux`: Linux OS
69-
* `os:macos`: Mac OS
68+
* `os:macos`: Mac OS
7069

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

73-
|For endpoint exceptions, yes. For detection exceptions, no.
72+
|No
73+
|`tags` |String[] |String array containing words and phrases to help categorize
74+
exception items. |No
75+
|`type` |String a|Exception query type, must be `simple`. |Yes
7476

7577
|==============================================
7678

@@ -83,10 +85,6 @@ The array must also include an `endpoint` element (to implement the exception on
8385

8486
|`field` |String |The source event field used to define the exception. Cannot
8587
be an empty string. |Yes
86-
|`list` |list |Object containing the
87-
<<lists-api-create-container, list container's>> `id` and `type`. Only valid for
88-
detection exception items.|No, except when using a list to define detection
89-
exceptions.
9088
|`operator` |String a|The operator used to determine when the exception is used.
9189
Can be:
9290

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

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

32-
* `detection`: Detection rule exception
33-
* `endpoint`: Endpoint alert exception
32+
|`type` |String a|The type of exception list. Valid values are:
33+
34+
* `detection`: Shared rule exception
35+
* `endpoint`: Endpoint rule exception
36+
* `rule_default`: Single rule exception
3437

3538
|Yes
3639

‎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)