IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Host isolation exceptions Get action details »

› › ›

Blocklist

edit

Blocklist

edit

Create, retrieve, update, and delete endpoint Blocklist entries with the Exceptions API. Endpoint blocklist entries are managed using a static container id (list_id) of endpoint_blocklists, which must be created prior to adding the blocklist entries. To use these APIs, you must have privileges to manage endpoints. Refer to Endpoints for more information.

Create blocklist entries container

edit

POST <kibana host>:<port>/api/exception_lists

Request body

edit

A JSON object containing the fields listed below. The request must have the following:

The list_id value must be endpoint_blocklists.
The namespace_type value must be agnostic.
The type value must be endpoint.

Name	Type	Description	Required
`description`	String	Describes the blocklist entries container.	Yes
`list_id`	String	Must be set to `endpoint_blocklists`.	Yes
`meta`	Object	Placeholder for metadata about the list container.	No
`name`	String	The blocklist entries 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 blocklist entries container.	No
`type`	String	Must be set to `endpoint_events`.	Yes

Example request

edit

POST api/exception_lists
{
  "description": "Elastic Defend Blocklists List",
  "name": "Elastic Defend Blocklists List",
  "list_id": "endpoint_blocklists",
  "type": "endpoint_blocklists",
  "namespace_type": "agnostic"
}

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
 "_version": "WzcsMV0=",
  "created_at": "2020-07-13T09:33:46.187Z",
  "created_by": "elastic",
  "description": "Elastic Defend Blocklists List",
  "id": "f320c070-c4eb-11ea-80bb-11861bae2798",
  "immutable": false,
  "list_id": "endpoint_blocklists",
  "name": "Elastic Defend Blocklists List",
  "namespace_type": "agnostic",
  "os_types": [],
  "tags": [],
  "tie_breaker_id": "2c08d5a5-2ecc-4d5a-acfb-0a367f25b3f3",
  "type": "endpoint_blocklists",
  "updated_at": "2020-07-13T09:33:46.359Z",
  "updated_by": "elastic",
  "version": 1
}

Create blocklist entry

edit

POST <kibana host>:<port>/api/exception_lists/items

Request body

edit

A JSON object containing the fields listed below. The request must have the following:

The list_id value must be endpoint_blocklists.
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 blocklist entry item.	Yes
`entries`	entry[]	Array containing the blocklist entry query conditions. See `entry` object schema for more details.	Yes.
`list_id`	String	Must be set to `endpoint_blocklists`.	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 blocklist entry 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 blocklist entry 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 request

edit

POST api/exception_lists/items

{
    "comments": [],
    "description": "some description about this entry",
    "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "list_id": "endpoint_blocklists",
    "name": "Some name for this item",
    "namespace_type": "agnostic",
    "os_types": [
        "windows"
    ],
    "tags": [
        "policy:all"
    ],
    "type": "simple"
}

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
    "_version": "WzEzNjIsMV0=",
    "comments": [],
    "created_at": "2022-03-01T16:24:39.471Z",
    "created_by": "elastic",
    "description": "some description about this entry",
    "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
    "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
    "list_id": "endpoint_blocklists",
    "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": "elastic"
}

Update blocklist entry

edit

PUT <kibana host>:<port>/api/exception_lists/items

Request body

edit

A JSON object containing the fields listed below. The request must have the following:

The list_id value must be endpoint_blocklists.
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 blocklist entry.	Yes
`entries`	entry[]	Array containing the blocklist entry 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 blocklist entry 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 blocklist entry 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 request

edit

Updates the entries:

PUT api/exception_lists/items
{
    "_version": "WzEzNjIsMV0=",
    "name": "ABC blocklist",
    "description": "These applications must be blocked",
    "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "os_types": [
        "windows"
    ],
    "tags": [
        "policy:all"
    ],
    "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
    "comments": [],
    "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
    "namespace_type": "agnostic",
    "type": "simple"
}

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
    "_version": "WzEzNjcsMV0=",
    "comments": [],
    "created_at": "2022-03-01T16:24:39.471Z",
    "created_by": "elastic",
    "description": "These applications must be blocked",
    "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
    "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
    "list_id": "endpoint_blocklists",
    "name": "ABC blocklist",
    "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": "elastic"
}

Delete blocklist entry

edit

DELETE <kibana host>:<port>/api/exception_lists/items

URL query parameters

edit

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 request

edit

Deletes the blocklist entry 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 code

edit

200: Indicates a successful call.

Response payload

edit

The item that was deleted:

{
  "_version": "WzEzNjcsMV0=",
  "comments": [],
  "created_at": "2022-03-01T16:24:39.471Z",
  "created_by": "elastic",
  "description": "These applications must be blocked",
  "entries": [
     {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
      }
  ],
  "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
  "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
  "list_id": "endpoint_blocklists",
  "name": "ABC blocklist",
  "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": "elastic"
}

Retrieve single blocklist entry

edit

GET <kibana host>:<port>/api/exception_lists/items

URL query parameters

edit

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 request

edit

GET api/exception_lists/items?item_id=29f480e6-6d34-4bc7-9038-f809f11cb679&namespace_type=agnostic

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
  "_version": "WzEzNjcsMV0=",
  "comments": [],
  "created_at": "2022-03-01T16:24:39.471Z",
  "created_by": "elastic",
  "description": "These applications must be blocked",
  "entries": [
    {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
      }
  ],
  "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
  "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
  "list_id": "endpoint_blocklists",
  "name": "ABC blocklist",
  "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": "elastic"
}

Find blocklist entries

edit

GET <kibana host>:<port>/api/exception_lists/items/_find

URL query parameters

edit

Name	Type	Description	Required
`list_id`	String	Must be set to `endpoint_blocklists`.	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 request

edit

GET api/exception_lists/items/_find?page=1&per_page=10&sort_field=name&sort_order=asc&list_id=endpoint_blocklists&namespace_type=agnostic

Response code

edit

200: Indicates a successful call.

Response payload

edit

{
  "data": [
    {
      "_version": "WzEzNjcsMV0=",
      "comments": [],
      "created_at": "2022-03-01T16:24:39.471Z",
      "created_by": "elastic",
      "description": "These applications must be blocked",
      "entries": [
        {
            "field": "file.path",
            "value": [
                "c:/path/to/file.exe",
                "c:/path/to/file2.exe"
                "c:/path/to/file3.exe"
            ],
            "type": "match_any",
            "operator": "included"
        }
      ],
      "id": "17ba1bf0-997c-11ec-b212-9f4ed8b5942f",
      "item_id": "29f480e6-6d34-4bc7-9038-f809f11cb679",
      "list_id": "endpoint_blocklists",
      "name": "ABC blocklist",
      "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": "elastic"
    }
  ],
  "page": 1,
  "per_page": 10,
  "total": 1
}

Value types

edit

The following describes the types that can be defined when using the create or update blocklist entries APIs:

`comment` object schema

edit

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` values

edit

The following are the valid OS types that can be used when creating blocklist entries:

windows
linux
macos

Scope assignment

edit

Blocklist entries can be assigned globally across all endpoint policies, or assigned to specific policies. You can assign the blocklist entry by defining one or more tags with a prefix of policy:. Note that the blocklist entry 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 : Blocklist entry is global to all policies. If used, no other policy: tag is allowed.
policy:<endpoint-policy-id> : Blocklist entry is assigned to a policy. Multiple per policy tags can be used to associate the blocklist entry to multiple policies.

`entry` object schema

edit

At least 3 conditions can be defined on an endpoint blocklist entry. Duplicates are not allowed. The following entries are supported by blocklist entries:

File hashes

edit

File hashes are supported by all OS types. A file hash entry has the following structure:

field : The file.hash.md5, file.hash.sha1 or file.hash.sha256 values are supported.
value : An array of hash values associated with the field.
type : Must be match_any.
operator : Must be included.

{
    "field": "file.hash.md5",
    "value": [
        "741462ab431a22233C787BAAB9B653C7"
    ],
    "type": "match_any",
    "operator": "included"
}

Process file path

edit

Process file paths are supported by all OS types. A file path entry has the following structure:

field : Must be file.path.
value : An array of file paths to match on.
type : Must be match_any.
operator : Must be included.

{
  "field": "file.path",
  "value": "c:/path/to/file.exe",
  "type": "match_any",
  "operator": "included"
}

Process file signature

edit

Process signature is supported for Windows OS type only. A signature entry has the following structure:

field : Must be set to file.Ext.code_signature.
type : Must be set to nested.
entries: An array with 1 entry item.
entries[0] : The entry defining the signature to be matched upon:
- field: Must be set to subject_name.
- value : An array of signature names to match on.
- type : Must be set to match_any.
- operator : Must be set to included.

{
    "field": "file.Ext.code_signature",
    "entries": [
        {
            "field": "subject_name",
            "value": [
                "test1",
                "test2"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "type": "nested"
}

Examples for a Windows blocklist entry.

edit

Only one entry of file.path or file.Ext.code_signature is allowed per blocklist item. The file.hash.* entry is also supported and accepts up to three values. The allowed hash types for file.hash.* are md5, sha1, or sha256.

[
 {
      "field": "file.hash.md5",
      "value": [
          "741462ab431a22233C787BAAB9B653C7"
      ],
      "type": "match_any",
      "operator": "included"
  },
  {
      "field": "file.hash.sha1",
      "value": [
          "aedb279e378BED6C2DB3C9DC9e12ba635e0b391c"
      ],
      "type": "match_any",
      "operator": "included"
  },
  {
      "field": "file.hash.sha256",
      "value": [
          "a665a45920422f9d417e4867efdc4fb8a04a1f3fff1fa07e998e86f7f7a27ae3"
      ],
      "type": "match_any",
      "operator": "included"
  }
]

[
 {
    "field": "file.Ext.code_signature",
    "entries": [
        {
            "field": "subject_name",
            "value": [
                "test1",
                "test2"
            ],
            "type": "match_any",
            "operator": "included"
        }
    ],
    "type": "nested"
 }
]

[
  {
    "field": "file.path",
    "value": "c:/path/to/file.exe",
    "type": "match_any",
    "operator": "included"
  }
]

« Host isolation exceptions Get action details »

Blocklist

Blocklist

Create blocklist entries container

Request body

Example request

Response code

Response payload

Create blocklist entry

Request body

Example request

Response code

Response payload

Update blocklist entry

Request body

Example request

Response code

Response payload

Delete blocklist entry

URL query parameters

Example request

Response code

Response payload

Retrieve single blocklist entry

URL query parameters

Example request

Response code

Response payload

Find blocklist entries

URL query parameters

Example request

Response code

Response payload

Value types

comment object schema

os_types values

Scope assignment

entry object schema

File hashes

Process file path

Process file signature

Examples for a Windows blocklist entry.

`comment` object schema

`os_types` values

`entry` object schema