Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[Detection Engine][Exceptions] - Update docs for single and shared exceptions #4021

Open
wants to merge 45 commits into
base: main
Choose a base branch
from
Open
Show file tree
Hide file tree
Changes from 2 commits
Commits
Show all changes
45 commits
Select commit Hold shift + click to select a range
206f23d
First draft
nastasha-solomon Oct 9, 2023
55fbab7
Fixed include
nastasha-solomon Oct 9, 2023
df3e171
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Oct 13, 2023
cf640b2
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Oct 27, 2023
cc62c0c
Update/create exception changes
nastasha-solomon Oct 29, 2023
692568f
Update docs/detections/api/exceptions/api-create-rule-default-excepti…
nastasha-solomon Oct 29, 2023
c51783a
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Oct 29, 2023
9c31311
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Nov 2, 2023
a41f72e
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Nov 13, 2023
7ec89a2
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Jan 4, 2024
a8cd5c5
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Mar 13, 2024
d5a7b9a
Revising intro
nastasha-solomon Mar 13, 2024
0503015
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Mar 19, 2024
db76cae
Adding new topic
nastasha-solomon Mar 19, 2024
d17654c
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Mar 20, 2024
ee215e5
Fixing refs
nastasha-solomon Mar 20, 2024
f1a983c
Removed duplicate entry
nastasha-solomon Mar 20, 2024
e6788ed
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Mar 20, 2024
eebdef6
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Apr 2, 2024
5353b60
Yara's input
nastasha-solomon Apr 2, 2024
76d7af1
Minor wording changes
nastasha-solomon Apr 2, 2024
1c8efcb
Title update
nastasha-solomon Apr 2, 2024
3e3bea2
Modifies title for shared exceptions
nastasha-solomon Apr 2, 2024
516e652
Fixing conflicts
nastasha-solomon Apr 3, 2024
dfba7d2
attempt number 2
nastasha-solomon Apr 3, 2024
7a4ac5f
Added file ext to index file
nastasha-solomon Apr 3, 2024
4a6e620
Update docs/detections/api/rules/rules-api-overview.asciidoc
nastasha-solomon Apr 3, 2024
8f586d5
Closing table
nastasha-solomon Apr 3, 2024
d6f4967
Update docs/detections/api/rules/rules-api-create-rule-default-except…
nastasha-solomon Apr 3, 2024
7086704
Merge branch 'issue-3491-exception-item-list' of github.com:elastic/s…
nastasha-solomon Apr 3, 2024
7cbe9c8
Minor changes and notes
nastasha-solomon Apr 3, 2024
fb59901
Update docs/detections/api/rules/rules-api-create-rule-default-except…
nastasha-solomon Apr 3, 2024
31e2127
Update docs/detections/api/rules/rules-api-create-single-rule-excepti…
nastasha-solomon Apr 3, 2024
ec9997b
Update docs/detections/api/rules/rules-api-create-single-rule-excepti…
nastasha-solomon Apr 3, 2024
b9589c5
Fixed route in example
nastasha-solomon Apr 3, 2024
845b50d
Merge branch 'issue-3491-exception-item-list' of github.com:elastic/s…
nastasha-solomon Apr 3, 2024
2b47c51
Remove comment chars
nastasha-solomon Apr 3, 2024
94af96d
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon May 28, 2024
585ed2c
Input from Yara
nastasha-solomon Aug 19, 2024
4ca0d5b
Refreshed params
nastasha-solomon Aug 20, 2024
92543bd
minor style fixes
nastasha-solomon Aug 20, 2024
3cca05f
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Aug 20, 2024
cc59ab9
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Aug 22, 2024
547bcd0
Merge branch 'main' into issue-3491-exception-item-list
nastasha-solomon Sep 8, 2024
20bd1da
Update docs/detections/api/rules/rules-api-create-rule-default-except…
nastasha-solomon Oct 10, 2024
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
2 changes: 2 additions & 0 deletions docs/detections/api/exceptions-api-index.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -4,6 +4,8 @@ include::exceptions/api-create-exception-container.asciidoc[]

include::exceptions/api-create-exception-item.asciidoc[]

include::exceptions/api-create-rule-default-exception-list.asciidoc[]

include::exceptions/api-create-shared-exception-list.asciidoc[]

include::exceptions/api-find-exception-containers.asciidoc[]
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -45,6 +45,7 @@ exception containers. |No

* `detection`: Detection rule exception
* `endpoint`: Endpoint alert exception
* `rule_default`: Exception that belongs to a single rule

|Yes

Expand Down
Original file line number Diff line number Diff line change
@@ -0,0 +1,103 @@
[[exceptions-api-create-rule-default-exception-list]]
=== Create exception list for an individual rule

Creates a rule default exception list.

An exception list groups <<exceptions-api-create-exception-item, exception items>> and a rule default list is associated with a single rule. When an exception item’s query evaluates to true, the associated rule does not issue alerts even when its other criteria are met.

A rule default exception list can apply to a single detection rule. To add to a rule's default exception list, simply pass in the exception items you would like to be applied to the rule. If a default exception list does not yet exist for the rule, one will be created and the exception added.

==== Request URL

`POST <kibana host>:<port>/api/exception_lists`
nastasha-solomon marked this conversation as resolved.
Show resolved Hide resolved

==== 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 that belongs to a single rule

|Yes

|==============================================

===== Example requests

Creates an exception container for holding trusted Linux process exception
items:

[source,console]
--------------------------------------------------
POST api/exception_lists
{
"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`