« Host isolation exceptions Get action details »
Elastic Docs ›Elastic Security Solution [8.16] ›Elastic Security APIs ›Endpoint management API

Blocklist

edit

Blocklist

edit

New API Reference

For the most up-to-date API details, refer to endpoint management APIs.

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 : To match multiple signatures, specify an array of signature names. To match a single signature, specify the signature name as a string.
    • type : To match multiple signatures, set to match_any. To match a single signature, set to match.
    • 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 »