Create exception item
editCreate exception item
editCreates an exception item and associates it with the specified exception container.
See Lists API for information about creating exception items from lists, such as a list of IP addresses or host names.
Before creating exception items, you must create an exception container.
Endpoint rule exception items cannot use
lists (the list
in the entries
array), and the
following fields cannot be used in exception queries (as field
values in the
entries
object):
-
file.Ext.quarantine_path
-
file.Ext.quarantine_result
-
process.entity_id
-
process.parent.entity_id
-
process.ancestry
Request URL
editPOST <kibana host>:<port>/api/exception_lists/items
Request body
editA JSON object with these fields:
Name | Type | Description | Required |
---|---|---|---|
|
comments[] |
Array of
|
No, defaults to empty array. |
|
String |
Describes the exception item. |
Yes |
|
Array containing the
exception queries. Boolean |
Yes |
|
|
String |
ID of the associated exception container. |
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 exception item’s name. |
Yes. |
|
String |
Determines whether the exception item is available in all Kibana spaces or just the space in which it is created, where:
Must be the same value as its associated exception container. |
No, defaults to |
|
String[] |
String array containing words and phrases to help categorize exception items. |
No |
|
String |
Exception query type, must be |
Yes |
|
String[] |
For endpoint rules only, defines the OS on which the exception is implemented. Valid values are:
The array must also include an |
For endpoint exceptions, yes. For detection exceptions, no. |
entries
schema
editName | Type | Description | Required |
---|---|---|---|
|
String |
The source event field used to define the exception. Cannot be an empty string. |
Yes |
|
list |
Object containing the
list container’s |
No, except when using a list to define detection exceptions. |
|
String |
The operator used to determine when the exception is used. Can be:
|
Yes |
|
String |
The
|
Yes |
|
String String[] |
Field value or values:
|
Yes, except when |
When you use list containers
("type": "list"
), you cannot use other types in the entries
array (match
,
match_any
, exists
, or nested
).
For endpoint exceptions, you cannot create exception items based on excluded
values ("operator": "excluded"
).
Example requests
editExample 1
Adds the maintenance-job
process to the trusted-linux-processes
exception
container:
POST api/lists/exception_lists/items { "description": "Excludes the weekly maintenance job", "entries": [ { "field": "process.name", "operator": "included", "type": "match", "value": "maintenance-job" } ], "list_id": "trusted-linux-processes", "name": "Linux maintenance job", "namespace_type": "single", "tags": [ "in-house processes", "linux" ], "type": "simple" }
Example 2
Adds hosts on which the maintenance
process is allowed to run to the
allowed-processes
exception container:
POST api/lists/exception_lists/items { "comments": [ {"comment": "Allows maintenance process to run on the specified machines"} ], "description": "Process allowlist", "entries": [ { "field": "process.name", "operator": "included", "type": "match", "value": "maintenance" }, { "field": "host.name", "operator": "included", "type": "match_any", "value": [ "liv-win-anf", "livw-win-mel", "linux-anfield" ] } ], "list_id": "allowed-processes", "item_id": "allow-process-on-machines", "name": "Host-process exclusions", "namespace_type": "single", "tags": [ "hosts", "processes" ], "type": "simple" }
Example 3
Creates an endpoint exception item for files with the specified SHA-1 hash value on Windows OS:
POST api/lists/exception_lists/items { "_tags": [ "endpoint", "os:windows" ], "comments": [ ] "description": "File exception for Windows", "entries": [ { "field": "file.hash.sha1", "operator": "included", "type": "match", "value": "27fb21cf5db95ffca43b234affa99becc4023b9d" } ], "item_id": "trusted-windows-file", "list_id": "endpoint-exception-container", "name": "Trusted Windows file", "namespace_type": "agnostic", "tags": [ ] "type": "simple" }
Example 4
Associates the external-ip-excludes
list container
as an exception item to the trusted-IPs
exception container:
POST api/lists/exception_lists/items { "description": "Uses the external-ip-container list to exclude trusted external IPs.", "entries": [ { "field": "destination.ip", "list": { "id": "external-ip-excludes", "type": "ip" }, "operator": "included", "type": "list" } ], "list_id": "trusted-IPs", "item_id": "external-IPs", "name": "Trusted external IPs", "namespace_type": "single", "tags": [ "network", "trusted IPs" ], "type": "simple" }
The list container that holds IP address list items. |
|
The exception container’s ID. |
Adds an exception for nested Endpoint fields:
POST api/lists/exception_lists/items { "description": "Excludes all processes signed by Liverpool FC", "entries": [ { "field": "process.Ext.code_signature", "type": "nested", "entries": [ { "field": "trusted", "type": "match", "operator": "included", "value": "true" }, { "field": "subject_name", "type": "match", "operator": "included", "value": "Liverpool FC" } ] } ], "list_id": "trusted-self-signed-processes", "name": "In-house processes", "namespace_type": "single", "tags": [ "in-house processes", "linux" ], "type": "simple" }
Response code
edit-
200
- Indicates a successful call.
Response payload
edit{ "_tags": [], "comments": [ { "comment": "Allows maintenance process to run on the specified machines", "created_at": "2020-07-14T08:36:33.172Z", "created_by": "LiverpoolFC", "id": "f6c61b4d-31dd-4a5d-8c73-f64787d03b4d" } ], "created_at": "2020-07-14T08:36:33.172Z", "created_by": "LiverpoolFC", "description": "Process allowlist", "entries": [ { "field": "process.name", "operator": "included", "type": "match", "value": "maintenance" }, { "field": "host.name", "operator": "included", "type": "match_any", "value": [ "liv-win-anf", "livw-win-mel", "linux-anfield" ] } ], "id": "1f4d38b0-c5ad-11ea-a3d8-a5b753aeeb9e", "item_id": "allow-process-on-machines", "list_id": "allowed-processes", "name": "Host-process exclusions", "namespace_type": "single", "tags": [ "hosts", "processes" ], "tie_breaker_id": "bb04f1c7-2537-47c1-aaca-40a7c8f771d3", "type": "simple", "updated_at": "2020-07-14T08:36:33.339Z", "updated_by": "LiverpoolFC" }