Event filtersedit
Create, retrieve, update and delete endpoint Event filters via API. Event filters are managed via the Exceptions API using a static container id (list_id
) of endpoint_events
, which must be created prior to adding an event filter. To access these APIs, users must have permission to manage endpoints.
Create event filters containeredit
POST <kibana host>:<port>/api/exception_lists
Request bodyedit
A JSON object containing the fields listed below. The request must have the following:
-
The
list_id
value must beendpoint_events
. -
The
namespace_type
value must beagnostic
. -
The
type
value must beendpoint
.
Name | Type | Description | Required |
---|---|---|---|
|
String |
Describes the event filters container. |
Yes |
|
String |
Must be set to |
Yes |
|
Object |
Placeholder for metadata about the list container. |
No |
|
String |
The event filters container’s name. |
Yes |
|
String |
Must be set to |
Yes |
|
String[] |
String array containing words and phrases to help categorize the event filters container. |
No |
|
String |
Must be set to |
Yes |
Example requestedit
POST api/exception_lists { "description": "Endpoint and Cloud Security Event Filters List", "name": "Endpoint and Cloud Security Event Filters List", "list_id": "endpoint_events", "type": "endpoint", "namespace_type": "agnostic" }
Response codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "_tags": [], "created_at": "2020-07-13T09:33:46.187Z", "created_by": "user", "description": "Endpoint and Cloud Security Event Filters List", "name": "Endpoint and Cloud Security Event Filters List", "list_id": "endpoint_events", "type": "endpoint", "namespace_type": "agnostic", "id": "f320c070-c4eb-11ea-80bb-11861bae2798", "tags": [], "tie_breaker_id": "2c08d5a5-2ecc-4d5a-acfb-0a367f25b3f3", "updated_at": "2020-07-13T09:33:46.359Z", "updated_by": "user" }
Create event filteredit
POST <kibana host>:<port>/api/exception_lists/items
Request bodyedit
A JSON object containing the fields listed below. The request must have the following:
-
The
list_id
value must beendpoint_events
. -
The
namespace_type
value must beagnostic
. -
The
type
value must besimple
.
Name | Type | Description | Required |
---|---|---|---|
|
comment[] |
Array of |
No, defaults to empty array. |
|
String |
Describes the event filter item. |
Yes |
|
entry[] |
Array containing the event filter query conditions. See |
Yes. |
|
String |
Must be set to |
Yes |
|
String |
Unique identifier of the exception item. |
No, automatically created when it is not provided. |
|
Object |
Placeholder for metadata about the exception item. |
No |
|
String |
The event filter name. |
Yes |
|
String |
Must be set to |
Yes |
|
os_type[] |
Array of os_type values. |
Yes |
|
String[] |
An array of strings containing words and phrases to help categorize exception items. Tags can also be used to define the event filter as either globally applicable to all policies or assigned to one or more policies (per policy). See Scope assignment for more details. |
No |
|
String |
Must be set to |
Yes |
Example requestedit
POST api/exception_lists/items { "comments": [ { "comment": "a new comment about this entry" } ], "description": "some description about this entry", "entries": [ { "field": "process.executable", "operator": "included", "type": "match", "value": "c:\\applications\\elastic\\foo.exe" } ], "list_id": "endpoint_events", "name": "Some name for this item", "namespace_type": "agnostic", "os_types": [ "windows" ], "tags": [ "policy:all" ], "type": "simple" }
Response codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "_version": "WzEzNjIsMV0=", "comments": [ { "comment": "a comment", "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "id": "c585d25c-6cb1-43a4-bcfc-919a270c99c1" } ], "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "description": "some description about this entry", "entries": [ { "field": "process.executable", "operator": "included", "type": "match", "value": "c:\\applications\\elastic\\foo.exe" } ], "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f", "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679", "list_id": "endpoint_events", "name": "Some name for this item", "namespace_type": "agnostic", "os_types": [ "windows" ], "tags": [ "policy:all" ], "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519", "type": "simple", "updated_at": "2022-03-01T16:24:39.475Z", "updated_by": "user" }
Update event filteredit
PUT <kibana host>:<port>/api/exception_lists/items
Request bodyedit
A JSON object containing the fields listed below. The request must have the following:
-
The
list_id
value must beendpoint_events
. -
The
namespace_type
value must beagnostic
. -
The
type
value must besimple
.
Name | Type | Description | Required |
---|---|---|---|
|
comment[] |
Array of |
No, defaults to empty array. |
|
String |
Describes the event filter. |
Yes |
|
entry[] |
Array containing the event filter query conditions. See |
Yes. |
|
String |
The item’s unique identifier. |
Yes, when the item’s |
|
String |
The |
Yes, when the item’s |
|
Object |
Placeholder for metadata about the exception item. |
No |
|
String |
The event filter name. |
Yes |
|
String |
Must be set to |
Yes |
|
os_type[] |
Array of os_type values. |
Yes |
|
String[] |
An array of strings containing words and phrases to help categorize exception items. Tags can also be used to define the event filter as either globally applicable to all policies or assigned to one or more policies (per policy). See Scope assignment for more details. |
No |
|
String |
Must be |
Yes |
|
String |
The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. |
No |
Example requestedit
Updates the entries
:
PUT api/exception_lists/items { "_version": "WzEzNjIsMV0=", "name": "Some name for this item updated", "description": "some description about this entry updated", "entries": [ { "field": "process.executable", "operator": "included", "type": "match", "value": "c:\\applications\\elastic\\fooV2.exe" } ], "os_types": [ "windows" ], "tags": [ "policy:all" ], "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f", "comments": [ { "comment": "a comment", "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "id": "c585d25c-6cb1-43a4-bcfc-919a270c99c1" }, { "comment": "new comment" } ], "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679", "namespace_type": "agnostic", "type": "simple" }
Response codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "_version": "WzEzNjcsMV0=", "comments": [ { "comment": "a comment", "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "id": "c585d25c-6cb1-43a4-bcfc-919a270c99c1" }, { "comment": "new comment", "created_at": "2022-03-02T11:22:19.471Z", "created_by": "user", "id": "cd85d25c-6cb1-83a4-bcfc-915a270c19c1" } ] "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "description": "some description about this entry updated", "entries": [ { "field": "process.executable", "operator": "included", "type": "match", "value": "c:\\applications\\elastic\\fooV2.exe" } ], "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f", "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679", "list_id": "endpoint_events", "name": "Some name for this item updated", "namespace_type": "agnostic", "os_types": [ "windows" ], "tags": [ "policy:all" ], "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519", "type": "simple", "updated_at": "2022-03-01T17:21:07.273Z", "updated_by": "user" }
Delete event filteredit
DELETE <kibana host>:<port>/api/exception_lists/items
URL query parametersedit
The URL query must include one of the following:
-
id
- theid
of the item, or -
item_id
- theitem_id
of the item
In addition to the above, namespace_type
URL query parameter is also required with a value of agnostic
.
Example requestedit
Deletes a event filter with item_id
of 29f480e6-6d34-4bc7-9038-f809f11cb679
:
DELETE api/exception_lists/items?item_id=29f480e6-6d34-4bc7-9038-f809f11cb679&namespace_type=agnostic
Response codeedit
-
200
- Indicates a successful call.
Response payloadedit
The item that was deleted:
{ "_version": "WzEzNjcsMV0=", "comments": [ { "comment": "a comment", "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "id": "c585d25c-6cb1-43a4-bcfc-919a270c99c1" }, { "comment": "new comment", "created_at": "2022-03-02T11:22:19.471Z", "created_by": "user", "id": "cd85d25c-6cb1-83a4-bcfc-915a270c19c1" } ] "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "description": "some description about this entry updated", "entries": [ { "field": "process.executable", "operator": "included", "type": "match", "value": "c:\\applications\\elastic\\fooV2.exe" } ], "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f", "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679", "list_id": "endpoint_events", "name": "Some name for this item updated", "namespace_type": "agnostic", "os_types": [ "windows" ], "tags": [ "policy:all" ], "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519", "type": "simple", "updated_at": "2022-03-01T17:21:07.273Z", "updated_by": "user" }
Retrieve single event filteredit
GET <kibana host>:<port>/api/exception_lists/items
URL query parametersedit
The URL query must include one of the following:
-
id
- theid
of the item, or -
item_id
- theitem_id
of the item
In addition to the above, namespace_type
URL query parameter is also required with a value of agnostic
.
Example requestedit
GET api/exception_lists/items?item_id=29f480e6-6d34-4bc7-9038-f809f11cb679&namespace_type=agnostic
Response codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "_version": "WzEzNjcsMV0=", "comments": [ { "comment": "a comment", "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "id": "c585d25c-6cb1-43a4-bcfc-919a270c99c1" }, { "comment": "new comment", "created_at": "2022-03-02T11:22:19.471Z", "created_by": "user", "id": "cd85d25c-6cb1-83a4-bcfc-915a270c19c1" } ] "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "description": "some description about this entry updated", "entries": [ { "field": "process.executable", "operator": "included", "type": "match", "value": "c:\\applications\\elastic\\fooV2.exe" } ], "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f", "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679", "list_id": "endpoint_events", "name": "Some name for this item updated", "namespace_type": "agnostic", "os_types": [ "windows" ], "tags": [ "policy:all" ], "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519", "type": "simple", "updated_at": "2022-03-01T17:21:07.273Z", "updated_by": "user" }
Find event filtersedit
GET <kibana host>:<port>/api/exception_lists/items/_find
URL query parametersedit
Name | Type | Description | Required |
---|---|---|---|
|
String |
Must be set to |
Yes |
|
String |
Must be set to |
Yes |
|
Integer |
The page number to return. |
No |
|
Integer |
The number of items to return per page. |
No |
|
String |
Determines which field is used to sort the results. |
No |
|
String |
Determines the sort order, which can be |
No |
|
String |
A Kibana Query Language (KQL) string to filter the results down. |
No |
Example requestedit
GET api/exception_lists/items/_find?page=1&per_page=10&sort_field=name&sort_order=asc&list_id=endpoint_events&namespace_type=agnostic
Response codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "data": [ { "_version": "WzEzNjcsMV0=", "comments": [ { "comment": "a comment", "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "id": "c585d25c-6cb1-43a4-bcfc-919a270c99c1" }, { "comment": "new comment", "created_at": "2022-03-02T11:22:19.471Z", "created_by": "user", "id": "cd85d25c-6cb1-83a4-bcfc-915a270c19c1" } ] "created_at": "2022-03-01T16:24:39.471Z", "created_by": "user", "description": "some description about this entry updated", "entries": [ { "field": "process.executable", "operator": "included", "type": "match", "value": "c:\\applications\\elastic\\fooV2.exe" } ], "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f", "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679", "list_id": "endpoint_events", "name": "Some name for this item updated", "namespace_type": "agnostic", "os_types": [ "windows" ], "tags": [ "policy:all" ], "tie_breaker_id": "c6bedf22-2292-4d4a-8eb8-e29a50b5b519", "type": "simple", "updated_at": "2022-03-01T17:21:07.273Z", "updated_by": "user" } ], "page": 1, "per_page": 10, "total": 1 }
Value typesedit
The following describes the types that can be defined when using the create or update event filters APIs:
comment
object schemaedit
Comments are JSON objects containing the following structure:
{ "comment": "some comment here" }
When used with the update API, existing comments can be updated by using their associated id
, while any comment without the id
attribute will be added as a new comment:
{ "comment": "some comment here - updated", "id": "1078cf59-5893-4143-acf7-40a40af16bee" }
os_types
valuesedit
The following are the valid OS types that can be used when creating event filters:
-
windows
-
linux
-
macos
Scope assignmentedit
Event filters can be assigned globally across all endpoint policies, or assigned to specific policies. You can assign the event filter by defining one or more tags with a prefix of policy:
. Note that the event filter can be either global or per policy, but not both. The following tags are available for use in order to control the assignment scope:
-
policy:all
: Event filter is global to all policies. If used, no otherpolicy:
tag is allowed. -
policy:<endpoint-policy-id>
: Event filter is assigned to a policy. Multipleper policy
tags can be used to associate the event filter to multiple policies.
entry
object schemaedit
Event filters allow for an unlimited number of conditions to be defined. Each event filter entry contains an entry
object that has type
, value
, field
and operator
keys with values. The following operators are supported in an entry object:
Operator is
edit
Exactly match with the single given value.
{ "field": "process.executable.caseless", "value": "c:/path/to/file.exe", "type": "match", "operator": "included" }
Operator is not
edit
Does not exactly match with the single given value.
{ "field": "process.executable.caseless", "value": "c:/path/to/file.exe", "type": "match", "operator": "excluded" }
Operator is one of
edit
Matches exactly with any of the values in the given list of values.
{ "field": "process.executable.caseless", "value": ["c:/path/to/file.exe", "c:/path/to/file2.exe"], "type": "match_any", "operator": "included" }
Operator is not one of
edit
Does not exactly match with any of the values in the given list of values.
{ "field": "process.executable.caseless", "value": ["c:/path/to/file.exe", "c:/path/to/file2.exe"], "type": "match_any", "operator": "excluded" }
Nested conditionsedit
In the case of a nested
entry, the top-level only has type
, field
, and an entries
array that holds a list of entry
objects:
{ "entries": [ { "field": "exists", "operator": "included", "type": "match", "value": "true" } ], "field": "process.Ext.code_signature", "type": "nested" }