Blocklistedit
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 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_blocklists
. -
The
namespace_type
value must beagnostic
. -
The
type
value must beendpoint
.
Name | Type | Description | Required |
---|---|---|---|
|
String |
Describes the blocklist entries container. |
Yes |
|
String |
Must be set to |
Yes |
|
Object |
Placeholder for metadata about the list container. |
No |
|
String |
The blocklist entries container’s name. |
Yes |
|
String |
Must be set to |
Yes |
|
String[] |
String array containing words and phrases to help categorize the blocklist entries container. |
No |
|
String |
Must be set to |
Yes |
Example requestedit
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 codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "_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 entryedit
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_blocklists
. -
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 blocklist entry item. |
Yes |
|
entry[] |
Array containing the blocklist entry 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 blocklist entry 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 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 |
|
String |
Must be set to |
Yes |
Example requestedit
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 codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "_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 entryedit
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_blocklists
. -
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 blocklist entry. |
Yes |
|
entry[] |
Array containing the blocklist entry 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 blocklist entry 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 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 |
|
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": "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 codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "_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 entryedit
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 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 codeedit
-
200
- Indicates a successful call.
Response payloadedit
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 entryedit
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": [], "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 entriesedit
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_blocklists&namespace_type=agnostic
Response codeedit
-
200
- Indicates a successful call.
Response payloadedit
{ "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 typesedit
The following describes the types that can be defined when using the create or update blocklist entries 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 blocklist entries:
-
windows
-
linux
-
macos
Scope assignmentedit
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 otherpolicy:
tag is allowed. -
policy:<endpoint-policy-id>
: Blocklist entry is assigned to a policy. Multipleper policy
tags can be used to associate the blocklist entry to multiple policies.
entry
object schemaedit
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 hashesedit
File hashes are supported by all OS types. A file hash entry has the following structure:
-
field
: Thefile.hash.md5
,file.hash.sha1
orfile.hash.sha256
values are supported. -
value
: An array of hash values associated with thefield
. -
type
: Must bematch_any
. -
operator
: Must beincluded
.
{ "field": "file.hash.md5", "value": [ "741462ab431a22233C787BAAB9B653C7" ], "type": "match_any", "operator": "included" }
Process file pathedit
Process file paths are supported by all OS types. A file path entry has the following structure:
-
field
: Must befile.path
. -
value
: An array of file paths to match on. -
type
: Must bematch_any
. -
operator
: Must beincluded
.
{ "field": "file.path", "value": "c:/path/to/file.exe", "type": "match_any", "operator": "included" }
Process signatureedit
Process signature is supported for Windows OS type only. A signature entry has the following structure:
-
field
: Must be set toprocess.Ext.code_signature
. -
type
: Must be set tonested
. -
entries
: An array with 1entry
item. -
entries[0]
: The entry defining the signature to be matched upon:-
field
: Must be set tosubject_name
. -
value
: An array of signature names to match on. -
type
: Must be set tomatch_any
. -
operator
: Must be set toincluded
.
-
{ "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" } ]