You are looking at preliminary documentation for a future release. Not what you want? See the current release documentation.
Elastic Docs ›Elastic Security Solution [master] ›Elastic Security APIs ›Endpoint management API
« Trusted applications Host isolation exceptions »

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_event_filters, 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 be endpoint_event_filters.
  • The namespace_type value must be agnostic.
  • The type value must be endpoint_events.
Name Type Description Required

description

String

Describes the event filters container.

Yes

list_id

String

Must be set to endpoint_event_filters.

Yes

meta

Object

Placeholder for metadata about the list container.

No

name

String

The event filters container’s name.

Yes

namespace_type

String

Must be set to agnostic.

Yes

tags

String[]

String array containing words and phrases to help categorize the event filters container.

No

type

String

Must be set to endpoint_events.

Yes

Example requestedit

POST api/exception_lists
{
  "description": "Elastic Defend Event Filters List",
  "name": "Elastic Defend Event Filters List",
  "list_id": "endpoint_event_filters",
  "type": "endpoint_events",
  "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": "Elastic Defend Event Filters List",
  "name": "Elastic Defend Event Filters List",
  "list_id": "endpoint_event_filters",
  "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 be endpoint_event_filters.
  • The namespace_type value must be agnostic.
  • The type value must be simple.
Name Type Description Required

comments

comment[]

Array of comment objects.

No, defaults to empty array.

description

String

Describes the event filter item.

Yes

entries

entry[]

Array containing the event filter query conditions. See entry object schema for more details.

Yes.

list_id

String

Must be set to endpoint_event_filters.

Yes

item_id

String

Unique identifier of the exception item.

No, automatically created when it is not provided.

meta

Object

Placeholder for metadata about the exception item.

No

name

String

The event filter name.

Yes

namespace_type

String

Must be set to agnostic for endpoint artifacts.

Yes

os_types

os_type[]

Use this field to specify the operating system. Only enter one value.

Yes

tags

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

type

String

Must be set to simple.

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_event_filters",
    "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_event_filters",
    "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 be endpoint_event_filters.
  • The namespace_type value must be agnostic.
  • The type value must be simple.
Name Type Description Required

comments

comment[]

Array of comment objects.

No, defaults to empty array.

description

String

Describes the event filter.

Yes

entries

entry[]

Array containing the event filter query conditions. See entry object schema for more details.

Yes.

id

String

The item’s unique identifier.

Yes, when the item’s item_id field is not used.

item_id

String

The item_id of the item you are updating.

Yes, when the item’s id field is not used.

meta

Object

Placeholder for metadata about the exception item.

No

name

String

The event filter name.

Yes

namespace_type

String

Must be set to agnostic.

Yes

os_types

os_type[]

Array of os_type values.

Yes

tags

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

type

String

Must be simple.

Yes

_version

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_event_filters",
    "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 - the id of the item, or
  • item_id - the item_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_event_filters",
    "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 - the id of the item, or
  • item_id - the item_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_event_filters",
    "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

list_id

String

Must be set to endpoint_event_filters.

Yes

namespace_type

String

Must be set to agnostic.

Yes

page

Integer

The page number to return.

No

per_page

Integer

The number of items to return per page.

No

sort_field

String

Determines which field is used to sort the results.

No

sort_order

String

Determines the sort order, which can be desc or asc.

No

filter

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_event_filters&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_event_filters",
    "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 other policy: tag is allowed.
  • policy:<endpoint-policy-id> : Event filter is assigned to a policy. Multiple per 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 isedit

Exactly match with the single given value.

{
  "field": "process.executable.caseless",
  "value": "c:/path/to/file.exe",
  "type": "match",
  "operator": "included"
}
Operator is notedit

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 ofedit

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 ofedit

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"
}
« Trusted applications Host isolation exceptions »