ExceptionListsClient¶

Client for the Kibana Security Exceptions API.

Exception lists group exception items that prevent Elastic Security detection rules from generating alerts when their conditions match. This client covers the exception list containers and their items, shared exception lists, rule default exceptions and the Elastic Endpoint exception list.

Exception lists with namespace_type="single" are space-scoped resources, while namespace_type="agnostic" lists are shared across all Kibana spaces. Every method accepts an optional space_id to target a specific space.

class kibana._sync.client.exception_lists.ExceptionListsClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: NamespaceClient

Client for the Kibana Security Exceptions API.

Exception lists group exception items that prevent Elastic Security detection rules from generating alerts when their conditions match. An exception list container (/api/exception_lists) holds items (/api/exception_lists/items), each of which defines the field entries (match, match_any, exists, list, nested, wildcard) that suppress rule alerts.

This client also covers:

Shared exception lists (POST /api/exceptions/shared)
Rule default exception items (POST /api/detection_engine/rules/{id}/exceptions)
The Elastic Endpoint exception list (/api/endpoint_list and /api/endpoint_list/items), an agnostic list applied to all Elastic Endpoint agents

Exception lists with namespace_type="single" are space-scoped, while namespace_type="agnostic" lists are shared across all Kibana spaces. Every method accepts an optional space_id to target a specific space (None targets the default space or the space the client is scoped to).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a detection exception list with one item
>>> created = client.exception_lists.create(
...     name="Trusted hosts",
...     description="Hosts that never alert",
...     type="detection",
...     list_id="trusted-hosts",
... )
>>> client.exception_lists.create_item(
...     list_id="trusted-hosts",
...     name="Trusted host",
...     description="Ignore the build server",
...     entries=[{
...         "field": "host.name",
...         "operator": "included",
...         "type": "match",
...         "value": "build-server-01",
...     }],
... )
>>>
>>> # Clean up
>>> client.exception_lists.delete(list_id="trusted-hosts")

Managing Exception Lists and Items

from kibana import Kibana

client = Kibana("http://localhost:5601", api_key="your_api_key")

# Create a detection exception list
created = client.exception_lists.create(
    name="Trusted hosts",
    description="Hosts that never alert",
    type="detection",
    list_id="trusted-hosts",
)

# Add an exception item to it
item = client.exception_lists.create_item(
    list_id="trusted-hosts",
    name="Trusted build server",
    description="Suppress alerts from the CI build server",
    entries=[{
        "field": "host.name",
        "operator": "included",
        "type": "match",
        "value": "build-server-01",
    }],
)

# Inspect the list
items = client.exception_lists.find_items(list_id="trusted-hosts")
summary = client.exception_lists.get_summary(list_id="trusted-hosts")

# Clean up (items are deleted with their list)
client.exception_lists.delete(list_id="trusted-hosts")

Duplicating, Exporting and Importing

# Duplicate a list together with its items
duplicate = client.exception_lists.duplicate(
    list_id="trusted-hosts", namespace_type="single"
)

# Export as NDJSON (requires BOTH id and list_id)
exported = client.exception_lists.export(
    id=created.body["id"],
    list_id="trusted-hosts",
    namespace_type="single",
)

# Re-import; as_new_list generates fresh list_id/item_id values
result = client.exception_lists.import_lists(
    file=exported.body, as_new_list=True
)
print(result.body["success"])

Shared Exception Lists and Rule Default Exceptions

# Create a shared exception list (detection type, generated list_id)
shared = client.exception_lists.create_shared_list(
    name="Shared exceptions",
    description="Exceptions shared across rules",
)

# Attach exception items directly to a detection rule's default list
# (pass the rule's UUID id, not the human readable rule_id)
client.exception_lists.create_rule_exceptions(
    id="4656dc92-5832-11ea-8e2d-0242ac130003",
    items=[{
        "name": "Rule exception",
        "description": "Suppress the build server",
        "type": "simple",
        "entries": [{
            "field": "host.name",
            "operator": "included",
            "type": "match",
            "value": "build-server-01",
        }],
    }],
)

The Elastic Endpoint Exception List

The endpoint exception list (fixed list_id "endpoint_list") is space agnostic and applies to all Elastic Endpoint agents. Creating it is idempotent: if it already exists the API returns an empty object.

client.exception_lists.create_endpoint_list()

ep_item = client.exception_lists.create_endpoint_item(
    name="Trusted process",
    description="Ignore the backup agent",
    os_types=["linux"],
    entries=[{
        "field": "process.executable.caseless",
        "operator": "included",
        "type": "match",
        "value": "/opt/backup/agent",
    }],
)

found = client.exception_lists.find_endpoint_items(per_page=50)
client.exception_lists.delete_endpoint_item(
    item_id=ep_item.body["item_id"]
)

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the ExceptionListsClient.

Parameters:

client (Kibana) – The parent Kibana client instance to delegate requests to.
default_space_id (str | None) – Optional default space ID for all operations.
validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> exception_lists_client = ExceptionListsClient(kibana_client)

create(*, name, description, type, list_id=None, meta=None, namespace_type=None, os_types=None, tags=None, version=None, space_id=None, validate_spaces=None)[source]¶

Create an exception list.

POST /api/exception_lists

An exception list groups exception items and can be associated with detection rules. You can associate multiple exception lists with a single rule; an exception list must exist before its items can be created.

Parameters:

name (str) – The name of the exception list.
description (str) – Describes the exception list.
type (str) – The type of exception list. One of "detection", "rule_default", "endpoint", "endpoint_trusted_apps", "endpoint_trusted_devices", "endpoint_events", "endpoint_host_isolation_exceptions" or "endpoint_blocklists".
list_id (str | None) – Human readable string identifier (e.g. "trusted-linux-processes"). Generated if omitted.
meta (dict[str, Any] | None) – Placeholder for metadata about the list.
namespace_type (str | None) – Determines whether the list is available in the current Kibana space only ("single", the server default) or in all spaces ("agnostic").
os_types (list[str] | None) – Operating systems the list applies to. Entries must be one of "linux", "macos" or "windows".
tags (list[str] | None) – String array containing words and phrases to help categorize exception lists.
version (int | None) – The document version (server default: 1).
space_id (str | None) – Optional space ID to create the exception list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created exception list, including the generated id, list_id, _version, tie_breaker_id and audit fields.

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
ConflictError – If a list with the same list_id already exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> created = client.exception_lists.create(
...     name="Trusted processes",
...     description="Processes that never alert",
...     type="detection",
...     list_id="trusted-processes",
...     tags=["linux"],
... )
>>> print(created.body["id"])

get(*, id=None, list_id=None, namespace_type=None, space_id=None, validate_spaces=None)[source]¶

Get exception list details.

GET /api/exception_lists

Gets the details of an exception list using the id or list_id field.

Parameters:

id (str | None) – Exception list’s identifier. Either id or list_id must be specified.
list_id (str | None) – Human readable exception list string identifier, e.g. "trusted-linux-processes". Either id or list_id must be specified.
namespace_type (str | None) – Determines whether the list is scoped to the current space ("single", the server default) or shared across spaces ("agnostic").
space_id (str | None) – Optional space ID to get the exception list from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the exception list.

Raises:

ValueError – If neither id nor list_id is provided.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> found = client.exception_lists.get(list_id="trusted-processes")
>>> print(found.body["name"])

update(*, name, description, type, id=None, list_id=None, _version=None, meta=None, namespace_type=None, os_types=None, tags=None, version=None, space_id=None, validate_spaces=None)[source]¶

Update an exception list.

PUT /api/exception_lists

Updates an exception list using the id or list_id field. The name, description and type fields are required by the API and replace the stored values.

Parameters:

name (str) – The (new) name of the exception list.
description (str) – The (new) description of the exception list.
type (str) – The type of exception list (see create()).
id (str | None) – Exception list’s identifier. Either id or list_id must be specified.
list_id (str | None) – Human readable exception list string identifier. Either id or list_id must be specified.
_version (str | None) – The version id (returned when the list was created or fetched), used for optimistic concurrency control.
meta (dict[str, Any] | None) – Placeholder for metadata about the list.
namespace_type (str | None) – "single" (server default) or "agnostic".
os_types (list[str] | None) – Operating systems the list applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array containing words and phrases to help categorize exception lists.
version (int | None) – The document version to set.
space_id (str | None) – Optional space ID to update the exception list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the updated exception list.

Raises:

NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = client.exception_lists.update(
...     list_id="trusted-processes",
...     name="Trusted processes (updated)",
...     description="Updated description",
...     type="detection",
... )
>>> print(updated.body["name"])

delete(*, id=None, list_id=None, namespace_type=None, space_id=None, validate_spaces=None)[source]¶

Delete an exception list.

DELETE /api/exception_lists

Deletes an exception list using the id or list_id field.

Parameters:

id (str | None) – Exception list’s identifier. Either id or list_id must be specified.
list_id (str | None) – Human readable exception list string identifier. Either id or list_id must be specified.
namespace_type (str | None) – "single" (server default) or "agnostic".
space_id (str | None) – Optional space ID to delete the exception list from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the deleted exception list.

Raises:

ValueError – If neither id nor list_id is provided.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> client.exception_lists.delete(list_id="trusted-processes")

find(*, filter=None, namespace_type=None, page=None, per_page=None, sort_field=None, sort_order=None, space_id=None, validate_spaces=None)[source]¶

Get a paginated subset of exception lists.

GET /api/exception_lists/_find

By default, the first page is returned, with 20 results per page.

Parameters:

filter (str | None) – Filters the returned results according to the value of the specified field, using the exception-list.attributes.<field>:<value> / exception-list-agnostic.attributes.<field>:<value> KQL syntax (e.g. "exception-list.attributes.name:Trusted*").
namespace_type (str | list[str] | None) – Determines whether the returned containers are associated with the current Kibana space ("single", the server default) or available in all spaces ("agnostic"). Accepts a single value or a list of both.
page (int | None) – The page number to return.
per_page (int | None) – The number of exception lists to return per page.
sort_field (str | None) – Determines which field is used to sort the results.
sort_order (str | None) – Sort order, "asc" or "desc".
space_id (str | None) – Optional space ID to search in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with data (the exception lists), page, per_page and total.

Raises:

BadRequestError – If the filter syntax is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> found = client.exception_lists.find(per_page=50)
>>> for exception_list in found.body["data"]:
...     print(exception_list["list_id"], exception_list["name"])

duplicate(*, list_id, namespace_type, include_expired_exceptions=True, space_id=None, validate_spaces=None)[source]¶

Duplicate an exception list.

POST /api/exception_lists/_duplicate

Duplicates an existing exception list and all of its items into a new list (named "<name> [Duplicate]" with a generated list_id).

Parameters:

list_id (str) – Human readable string identifier of the exception list to duplicate.
namespace_type (str) – "single" or "agnostic".
include_expired_exceptions (bool) – Whether to include expired exception items (as defined by their expire_time) in the duplicated list (default: True).
space_id (str | None) – Optional space ID to duplicate the exception list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the newly created duplicate exception list.

Raises:

NotFoundError – If the source exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> duplicate = client.exception_lists.duplicate(
...     list_id="trusted-processes",
...     namespace_type="single",
... )
>>> print(duplicate.body["name"])
Trusted processes [Duplicate]

export(*, id, list_id, namespace_type, include_expired_exceptions=True, space_id=None, validate_spaces=None)[source]¶

Export an exception list as NDJSON.

POST /api/exception_lists/_export

Exports an exception list and its associated items. The response body is NDJSON: one line for the list container, one line per exception item and a final export-details line. The parsed response body is a list of dicts (one per NDJSON line) and can be passed straight to import_lists().

Note: unlike the read APIs, the export API requires both id and list_id.

Parameters:

id (str) – Exception list’s identifier (generated upon creation).
list_id (str) – Human readable exception list string identifier.
namespace_type (str) – "single" or "agnostic".
include_expired_exceptions (bool) – Whether to include expired exception items (as defined by their expire_time) in the export (default: True).
space_id (str | None) – Optional space ID to export the exception list from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

Response whose body is the NDJSON export (exception list, its items and an export-details summary line).

Raises:

BadRequestError – If id or list_id is missing or invalid.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> created = client.exception_lists.get(list_id="trusted-processes")
>>> exported = client.exception_lists.export(
...     id=created.body["id"],
...     list_id=created.body["list_id"],
...     namespace_type="single",
... )
>>> ndjson = exported.body

import_lists(*, file, overwrite=None, as_new_list=None, filename='import.ndjson', space_id=None, validate_spaces=None)[source]¶

Import an exception list and its items from an NDJSON file.

POST /api/exception_lists/_import

Imports exception lists and items from an NDJSON export (uploaded as multipart/form-data).

Parameters:

file (bytes | str | list[dict[str, Any]]) – NDJSON export content: raw bytes/str (e.g. the body returned by export()), or a list of dicts (one per exported line), which is NDJSON-encoded automatically.
overwrite (bool | None) – Determines whether existing exception lists with the same list_id are overwritten. If any exception items have the same item_id, those are also overwritten (server default: False).
as_new_list (bool | None) – Determines whether the list being imported will have a new list_id generated. Additional item_id’s are generated for each exception item. Both the exception list and its items are overwritten (server default: False).
filename (str) – Filename advertised in the multipart upload.
space_id (str | None) – Optional space ID to import the exception list into.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

success, success_count, success_exception_lists, success_count_exception_lists, success_exception_list_items, success_count_exception_list_items and an errors array.

Return type:

ObjectApiResponse with the import summary

Raises:

ValueError – If file is empty.
BadRequestError – If the NDJSON payload is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> exported = client.exception_lists.export(
...     id="...", list_id="trusted-processes",
...     namespace_type="single",
... )
>>> result = client.exception_lists.import_lists(
...     file=exported.body, as_new_list=True,
... )
>>> print(result.body["success"])
True

get_summary(*, id=None, list_id=None, namespace_type=None, filter=None, space_id=None, validate_spaces=None)[source]¶

Get an exception list summary.

GET /api/exception_lists/summary

Retrieves a per-OS summary of the number of exception items in an exception list.

Parameters:

id (str | None) – Exception list’s identifier generated upon creation. Either id or list_id must be specified.
list_id (str | None) – Exception list’s human readable identifier. Either id or list_id must be specified.
namespace_type (str | None) – "single" (server default) or "agnostic".
filter (str | None) – Search filter clause (KQL over the exception list item saved object attributes).
space_id (str | None) – Optional space ID to read the summary from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

windows, linux, macos and total. Note: the counts are grouped by the items’ os_types, so items without an os_types value are not reflected in total.

Return type:

ObjectApiResponse with the per-OS item counts

Raises:

ValueError – If neither id nor list_id is provided.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> summary = client.exception_lists.get_summary(
...     list_id="trusted-processes"
... )
>>> print(summary.body["total"])

create_item(*, list_id, name, description, entries, type='simple', comments=None, expire_time=None, item_id=None, meta=None, namespace_type=None, os_types=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Create an exception list item.

POST /api/exception_lists/items

Creates an exception item and associates it with the specified exception list (which must already exist). Each entry describes a field condition; when a rule’s conditions and an item’s entries both match an event, no alert is generated.

Parameters:

list_id (str) – Human readable string identifier of the exception list this item belongs to.
name (str) – Exception item’s name.
description (str) – Describes the exception item.
entries (list[dict[str, Any]]) – The item’s entries. Each entry is a dict with field, operator ("included"/"excluded") and type ("match", "match_any", "exists", "list", "nested" or "wildcard"), plus a value where applicable.
type (str) – Exception item’s type. Only "simple" is supported (default: "simple").
comments (list[dict[str, Any]] | None) – Array of {"comment": "..."} dicts attached to the item.
expire_time (str | None) – ISO 8601 date-time after which the item expires and no longer suppresses alerts.
item_id (str | None) – Human readable string identifier for the item. Generated if omitted.
meta (dict[str, Any] | None) – Placeholder for metadata about the item.
namespace_type (str | None) – "single" (server default) or "agnostic". Must match the parent list’s namespace_type.
os_types (list[str] | None) – Operating systems the item applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array of words and phrases to help categorize items.
space_id (str | None) – Optional space ID to create the item in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created exception list item.

Raises:

BadRequestError – If the request body is invalid.
NotFoundError – If the parent exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
ConflictError – If an item with the same item_id already exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> item = client.exception_lists.create_item(
...     list_id="trusted-processes",
...     name="Trusted host",
...     description="Ignore the build server",
...     entries=[{
...         "field": "host.name",
...         "operator": "included",
...         "type": "match",
...         "value": "build-server-01",
...     }],
... )
>>> print(item.body["item_id"])

get_item(*, id=None, item_id=None, namespace_type=None, space_id=None, validate_spaces=None)[source]¶

Get an exception list item.

GET /api/exception_lists/items

Gets the details of an exception list item using the id or item_id field.

Parameters:

id (str | None) – Exception list item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
namespace_type (str | None) – "single" (server default) or "agnostic".
space_id (str | None) – Optional space ID to get the item from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the exception list item.

Raises:

ValueError – If neither id nor item_id is provided.
NotFoundError – If the exception list item does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> item = client.exception_lists.get_item(item_id="trusted-host")
>>> print(item.body["name"])

update_item(*, name, description, entries, type='simple', id=None, item_id=None, list_id=None, _version=None, comments=None, expire_time=None, meta=None, namespace_type=None, os_types=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Update an exception list item.

PUT /api/exception_lists/items

Updates an exception list item using the id or item_id field. The name, description, type and entries fields are required by the API and replace the stored values.

Parameters:

name (str) – The (new) exception item’s name.
description (str) – The (new) description of the exception item.
entries (list[dict[str, Any]]) – The (new) item’s entries (see create_item()).
type (str) – Exception item’s type. Only "simple" is supported (default: "simple").
id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
list_id (str | None) – Human readable string identifier of the parent exception list.
_version (str | None) – The version id (returned when the item was created or fetched), used for optimistic concurrency control.
comments (list[dict[str, Any]] | None) – Array of {"comment": "..."} dicts. Include existing comments (with their id) to preserve them.
expire_time (str | None) – ISO 8601 date-time after which the item expires.
meta (dict[str, Any] | None) – Placeholder for metadata about the item.
namespace_type (str | None) – "single" (server default) or "agnostic".
os_types (list[str] | None) – Operating systems the item applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array of words and phrases to help categorize items.
space_id (str | None) – Optional space ID to update the item in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the updated exception list item.

Raises:

NotFoundError – If the exception list item does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = client.exception_lists.update_item(
...     item_id="trusted-host",
...     name="Trusted host (updated)",
...     description="Updated entry",
...     entries=[{
...         "field": "host.name",
...         "operator": "included",
...         "type": "match",
...         "value": "build-server-02",
...     }],
... )
>>> print(updated.body["entries"][0]["value"])
build-server-02

delete_item(*, id=None, item_id=None, namespace_type=None, space_id=None, validate_spaces=None)[source]¶

Delete an exception list item.

DELETE /api/exception_lists/items

Deletes an exception list item using the id or item_id field.

Parameters:

id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
namespace_type (str | None) – "single" (server default) or "agnostic".
space_id (str | None) – Optional space ID to delete the item from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the deleted exception list item.

Raises:

ValueError – If neither id nor item_id is provided.
NotFoundError – If the exception list item does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> client.exception_lists.delete_item(item_id="trusted-host")

find_items(*, list_id, filter=None, namespace_type=None, search=None, page=None, per_page=None, sort_field=None, sort_order=None, space_id=None, validate_spaces=None)[source]¶

Get a paginated subset of exception list items.

GET /api/exception_lists/items/_find

Returns the exception items of the specified list(s). By default, the first page is returned, with 20 results per page.

Parameters:

list_id (str | list[str]) – The list_id (or list of list_id’s) of the exception lists whose items to fetch.
filter (str | list[str] | None) – Filters the returned results according to the value of the specified field, using the exception-list.attributes.<field>:<value> KQL syntax. Accepts a single clause or a list of clauses (one per list_id).
namespace_type (str | list[str] | None) – "single" (server default) or "agnostic". Accepts a single value or a list of values (one per list_id).
search (str | None) – Simple query string searched across the items.
page (int | None) – The page number to return.
per_page (int | None) – The number of exception list items to return per page.
sort_field (str | None) – Determines which field is used to sort the results.
sort_order (str | None) – Sort order, "asc" or "desc".
space_id (str | None) – Optional space ID to search in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with data (the exception list items), page, per_page and total.

Raises:

BadRequestError – If the filter syntax is invalid.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> found = client.exception_lists.find_items(
...     list_id="trusted-processes", per_page=50,
... )
>>> print(found.body["total"])

create_shared_list(*, name, description, space_id=None, validate_spaces=None)[source]¶

Create a shared exception list.

POST /api/exceptions/shared

An exception list groups exception items and can be associated with detection rules. A shared exception list can apply to multiple detection rules. This is a convenience endpoint that creates a detection type exception list with a generated list_id.

Parameters:

name (str) – The name of the shared exception list.
description (str) – Describes the shared exception list.
space_id (str | None) – Optional space ID to create the shared exception list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created exception list (type "detection", generated list_id).

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> shared = client.exception_lists.create_shared_list(
...     name="Shared exceptions",
...     description="Exceptions shared across rules",
... )
>>> print(shared.body["type"])
detection

create_rule_exceptions(*, id, items, space_id=None, validate_spaces=None)[source]¶

Create exception items for a detection rule’s default list.

POST /api/detection_engine/rules/{id}/exceptions

Creates exception items and adds them to the rule’s default exception list (creating the rule_default list if it does not exist yet).

Parameters:

id (str) – The detection rule’s identifier — the rule’s UUID id, not the human readable rule_id.
items (list[dict[str, Any]]) – The exception items to create. Each item is a dict with the same fields accepted by create_item(), minus list_id (name, description, type, entries and optionally comments, expire_time, item_id, meta, namespace_type, os_types, tags).
space_id (str | None) – Optional space ID the rule lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

Response whose body is the array of created exception list items.

Raises:

BadRequestError – If the request body is invalid.
NotFoundError – If the detection rule does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> created = client.exception_lists.create_rule_exceptions(
...     id="4656dc92-5832-11ea-8e2d-0242ac130003",
...     items=[{
...         "name": "Rule exception",
...         "description": "Suppress the build server",
...         "type": "simple",
...         "entries": [{
...             "field": "host.name",
...             "operator": "included",
...             "type": "match",
...             "value": "build-server-01",
...         }],
...     }],
... )
>>> print(created.body[0]["list_id"])

create_endpoint_list(*, space_id=None, validate_spaces=None)[source]¶

Create the Elastic Endpoint exception list.

POST /api/endpoint_list

Creates the agnostic Elastic Endpoint rule exception list (fixed list_id "endpoint_list"), which is applied to all Elastic Endpoint agents. The operation is idempotent: if the list already exists, the server responds with 200 and an empty JSON object instead of the list.

Parameters:

space_id (str | None) – Optional space ID to issue the request in (the endpoint list itself is space agnostic).
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created endpoint exception list, or an empty object ({}) if the list already existed.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = client.exception_lists.create_endpoint_list()
>>> # {} means the endpoint list already existed
>>> print(response.body.get("list_id", "already existed"))

create_endpoint_item(*, name, description, entries, type='simple', comments=None, item_id=None, meta=None, os_types=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Create an Elastic Endpoint exception list item.

POST /api/endpoint_list/items

Creates an exception item in the Elastic Endpoint exception list. If the endpoint list does not exist yet, it is created first (see create_endpoint_list()).

Parameters:

name (str) – Exception item’s name.
description (str) – Describes the exception item.
entries (list[dict[str, Any]]) – The item’s entries (see create_item()).
type (str) – Exception item’s type. Only "simple" is supported (default: "simple").
comments (list[dict[str, Any]] | None) – Array of {"comment": "..."} dicts attached to the item.
item_id (str | None) – Human readable string identifier for the item. Generated if omitted.
meta (dict[str, Any] | None) – Placeholder for metadata about the item.
os_types (list[str] | None) – Operating systems the item applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array of words and phrases to help categorize items.
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created endpoint exception list item (list_id is always "endpoint_list", namespace_type "agnostic").

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
ConflictError – If an item with the same item_id already exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> item = client.exception_lists.create_endpoint_item(
...     name="Trusted process",
...     description="Ignore the backup agent",
...     os_types=["windows"],
...     entries=[{
...         "field": "process.executable.caseless",
...         "operator": "included",
...         "type": "match",
...         "value": "C:\\Program Files\\Backup\\agent.exe",
...     }],
... )
>>> print(item.body["list_id"])
endpoint_list

get_endpoint_item(*, id=None, item_id=None, space_id=None, validate_spaces=None)[source]¶

Get an Elastic Endpoint exception list item.

GET /api/endpoint_list/items

Gets the details of an endpoint exception list item using the id or item_id field.

Parameters:

id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the endpoint exception list item.

Raises:

ValueError – If neither id nor item_id is provided.
NotFoundError – If the item (or the endpoint list) does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> item = client.exception_lists.get_endpoint_item(
...     item_id="trusted-process"
... )
>>> print(item.body["name"])

update_endpoint_item(*, name, description, entries, type='simple', id=None, item_id=None, _version=None, comments=None, meta=None, os_types=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Update an Elastic Endpoint exception list item.

PUT /api/endpoint_list/items

Updates an endpoint exception list item using the id or item_id field. The name, description, type and entries fields are required by the API and replace the stored values.

Parameters:

name (str) – The (new) exception item’s name.
description (str) – The (new) description of the exception item.
entries (list[dict[str, Any]]) – The (new) item’s entries (see create_item()).
type (str) – Exception item’s type. Only "simple" is supported (default: "simple").
id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
_version (str | None) – The version id (returned when the item was created or fetched), used for optimistic concurrency control.
comments (list[dict[str, Any]] | None) – Array of {"comment": "..."} dicts. Include existing comments (with their id) to preserve them.
meta (dict[str, Any] | None) – Placeholder for metadata about the item.
os_types (list[str] | None) – Operating systems the item applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array of words and phrases to help categorize items.
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the updated endpoint exception list item.

Raises:

NotFoundError – If the item (or the endpoint list) does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = client.exception_lists.update_endpoint_item(
...     item_id="trusted-process",
...     name="Trusted process (updated)",
...     description="Updated entry",
...     os_types=["windows"],
...     entries=[{
...         "field": "process.executable.caseless",
...         "operator": "included",
...         "type": "match",
...         "value": "C:\\Program Files\\Backup\\agent2.exe",
...     }],
... )
>>> print(updated.body["name"])
Trusted process (updated)

delete_endpoint_item(*, id=None, item_id=None, space_id=None, validate_spaces=None)[source]¶

Delete an Elastic Endpoint exception list item.

DELETE /api/endpoint_list/items

Deletes an endpoint exception list item using the id or item_id field.

Parameters:

id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the deleted endpoint exception list item.

Raises:

ValueError – If neither id nor item_id is provided.
NotFoundError – If the item (or the endpoint list) does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> client.exception_lists.delete_endpoint_item(
...     item_id="trusted-process"
... )

find_endpoint_items(*, filter=None, page=None, per_page=None, sort_field=None, sort_order=None, space_id=None, validate_spaces=None)[source]¶

Get a paginated subset of Elastic Endpoint exception list items.

GET /api/endpoint_list/items/_find

By default, the first page is returned, with 20 results per page.

Parameters:

filter (str | None) – Filters the returned results according to the value of the specified field, using the exception-list-agnostic.attributes.<field>:<value> KQL syntax.
page (int | None) – The page number to return.
per_page (int | None) – The number of exception list items to return per page.
sort_field (str | None) – Determines which field is used to sort the results.
sort_order (str | None) – Sort order, "asc" or "desc".
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with data (the endpoint exception list items), page, per_page and total.

Raises:

BadRequestError – If the filter syntax is invalid.
NotFoundError – If the endpoint list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> found = client.exception_lists.find_endpoint_items(per_page=50)
>>> print(found.body["total"])

perform_request(method, path, *, params=None, headers=None, body=None)¶

Perform an HTTP request via the parent client with space context enhancement.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
path (str) – API endpoint path
params (dict[str, Any] | None) – Query parameters
headers (dict[str, str] | None) – Request headers
body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]

AsyncExceptionListsClient¶

Asynchronous version of the ExceptionListsClient for use with async/await syntax.

class kibana._async.client.exception_lists.AsyncExceptionListsClient(client, default_space_id=None, validate_spaces=True)[source]¶

Bases: AsyncNamespaceClient

Async client for the Kibana Security Exceptions API.

This client also covers:

Shared exception lists (POST /api/exceptions/shared)
Rule default exception items (POST /api/detection_engine/rules/{id}/exceptions)
The Elastic Endpoint exception list (/api/endpoint_list and /api/endpoint_list/items), an agnostic list applied to all Elastic Endpoint agents

Example

>>> from kibana import AsyncKibana
>>> client = AsyncKibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a detection exception list with one item
>>> created = await client.exception_lists.create(
...     name="Trusted hosts",
...     description="Hosts that never alert",
...     type="detection",
...     list_id="trusted-hosts",
... )
>>> await client.exception_lists.create_item(
...     list_id="trusted-hosts",
...     name="Trusted host",
...     description="Ignore the build server",
...     entries=[{
...         "field": "host.name",
...         "operator": "included",
...         "type": "match",
...         "value": "build-server-01",
...     }],
... )
>>>
>>> # Clean up
>>> await client.exception_lists.delete(list_id="trusted-hosts")

Usage

The AsyncExceptionListsClient provides the same methods as ExceptionListsClient but all methods are async and must be awaited:

from kibana import AsyncKibana
import asyncio

async def main():
    async with AsyncKibana("http://localhost:5601") as client:
        created = await client.exception_lists.create(
            name="Trusted hosts",
            description="Hosts that never alert",
            type="detection",
            list_id="trusted-hosts",
        )

        await client.exception_lists.create_item(
            list_id="trusted-hosts",
            name="Trusted build server",
            description="Suppress alerts from the CI build server",
            entries=[{
                "field": "host.name",
                "operator": "included",
                "type": "match",
                "value": "build-server-01",
            }],
        )

        items = await client.exception_lists.find_items(
            list_id="trusted-hosts"
        )
        print(items.body["total"])

        await client.exception_lists.delete(list_id="trusted-hosts")

asyncio.run(main())

__init__(client, default_space_id=None, validate_spaces=True)[source]¶

Initialize the AsyncExceptionListsClient.

Parameters:

client (AsyncKibana) – The parent AsyncKibana client instance to delegate requests to.
default_space_id (str | None) – Optional default space ID for all operations.
validate_spaces (bool) – Whether to validate space existence before space-scoped operations (default: True).

Example

>>> exception_lists_client = AsyncExceptionListsClient(kibana_client)

async create(*, name, description, type, list_id=None, meta=None, namespace_type=None, os_types=None, tags=None, version=None, space_id=None, validate_spaces=None)[source]¶

Create an exception list.

POST /api/exception_lists

Parameters:

name (str) – The name of the exception list.
description (str) – Describes the exception list.
type (str) – The type of exception list. One of "detection", "rule_default", "endpoint", "endpoint_trusted_apps", "endpoint_trusted_devices", "endpoint_events", "endpoint_host_isolation_exceptions" or "endpoint_blocklists".
list_id (str | None) – Human readable string identifier (e.g. "trusted-linux-processes"). Generated if omitted.
meta (dict[str, Any] | None) – Placeholder for metadata about the list.
namespace_type (str | None) – Determines whether the list is available in the current Kibana space only ("single", the server default) or in all spaces ("agnostic").
os_types (list[str] | None) – Operating systems the list applies to. Entries must be one of "linux", "macos" or "windows".
tags (list[str] | None) – String array containing words and phrases to help categorize exception lists.
version (int | None) – The document version (server default: 1).
space_id (str | None) – Optional space ID to create the exception list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created exception list, including the generated id, list_id, _version, tie_breaker_id and audit fields.

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
ConflictError – If a list with the same list_id already exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> created = await client.exception_lists.create(
...     name="Trusted processes",
...     description="Processes that never alert",
...     type="detection",
...     list_id="trusted-processes",
...     tags=["linux"],
... )
>>> print(created.body["id"])

async get(*, id=None, list_id=None, namespace_type=None, space_id=None, validate_spaces=None)[source]¶

Get exception list details.

GET /api/exception_lists

Gets the details of an exception list using the id or list_id field.

Parameters:

id (str | None) – Exception list’s identifier. Either id or list_id must be specified.
list_id (str | None) – Human readable exception list string identifier, e.g. "trusted-linux-processes". Either id or list_id must be specified.
namespace_type (str | None) – Determines whether the list is scoped to the current space ("single", the server default) or shared across spaces ("agnostic").
space_id (str | None) – Optional space ID to get the exception list from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the exception list.

Raises:

ValueError – If neither id nor list_id is provided.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> found = await client.exception_lists.get(list_id="trusted-processes")
>>> print(found.body["name"])

async update(*, name, description, type, id=None, list_id=None, _version=None, meta=None, namespace_type=None, os_types=None, tags=None, version=None, space_id=None, validate_spaces=None)[source]¶

Update an exception list.

PUT /api/exception_lists

Updates an exception list using the id or list_id field. The name, description and type fields are required by the API and replace the stored values.

Parameters:

name (str) – The (new) name of the exception list.
description (str) – The (new) description of the exception list.
type (str) – The type of exception list (see create()).
id (str | None) – Exception list’s identifier. Either id or list_id must be specified.
list_id (str | None) – Human readable exception list string identifier. Either id or list_id must be specified.
_version (str | None) – The version id (returned when the list was created or fetched), used for optimistic concurrency control.
meta (dict[str, Any] | None) – Placeholder for metadata about the list.
namespace_type (str | None) – "single" (server default) or "agnostic".
os_types (list[str] | None) – Operating systems the list applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array containing words and phrases to help categorize exception lists.
version (int | None) – The document version to set.
space_id (str | None) – Optional space ID to update the exception list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the updated exception list.

Raises:

NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = await client.exception_lists.update(
...     list_id="trusted-processes",
...     name="Trusted processes (updated)",
...     description="Updated description",
...     type="detection",
... )
>>> print(updated.body["name"])

async delete(*, id=None, list_id=None, namespace_type=None, space_id=None, validate_spaces=None)[source]¶

Delete an exception list.

DELETE /api/exception_lists

Deletes an exception list using the id or list_id field.

Parameters:

id (str | None) – Exception list’s identifier. Either id or list_id must be specified.
list_id (str | None) – Human readable exception list string identifier. Either id or list_id must be specified.
namespace_type (str | None) – "single" (server default) or "agnostic".
space_id (str | None) – Optional space ID to delete the exception list from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the deleted exception list.

Raises:

ValueError – If neither id nor list_id is provided.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.exception_lists.delete(list_id="trusted-processes")

async find(*, filter=None, namespace_type=None, page=None, per_page=None, sort_field=None, sort_order=None, space_id=None, validate_spaces=None)[source]¶

Get a paginated subset of exception lists.

GET /api/exception_lists/_find

By default, the first page is returned, with 20 results per page.

Parameters:

filter (str | None) – Filters the returned results according to the value of the specified field, using the exception-list.attributes.<field>:<value> / exception-list-agnostic.attributes.<field>:<value> KQL syntax (e.g. "exception-list.attributes.name:Trusted*").
namespace_type (str | list[str] | None) – Determines whether the returned containers are associated with the current Kibana space ("single", the server default) or available in all spaces ("agnostic"). Accepts a single value or a list of both.
page (int | None) – The page number to return.
per_page (int | None) – The number of exception lists to return per page.
sort_field (str | None) – Determines which field is used to sort the results.
sort_order (str | None) – Sort order, "asc" or "desc".
space_id (str | None) – Optional space ID to search in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with data (the exception lists), page, per_page and total.

Raises:

BadRequestError – If the filter syntax is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> found = await client.exception_lists.find(per_page=50)
>>> for exception_list in found.body["data"]:
...     print(exception_list["list_id"], exception_list["name"])

async duplicate(*, list_id, namespace_type, include_expired_exceptions=True, space_id=None, validate_spaces=None)[source]¶

Duplicate an exception list.

POST /api/exception_lists/_duplicate

Duplicates an existing exception list and all of its items into a new list (named "<name> [Duplicate]" with a generated list_id).

Parameters:

list_id (str) – Human readable string identifier of the exception list to duplicate.
namespace_type (str) – "single" or "agnostic".
include_expired_exceptions (bool) – Whether to include expired exception items (as defined by their expire_time) in the duplicated list (default: True).
space_id (str | None) – Optional space ID to duplicate the exception list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the newly created duplicate exception list.

Raises:

NotFoundError – If the source exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> duplicate = await client.exception_lists.duplicate(
...     list_id="trusted-processes",
...     namespace_type="single",
... )
>>> print(duplicate.body["name"])
Trusted processes [Duplicate]

async export(*, id, list_id, namespace_type, include_expired_exceptions=True, space_id=None, validate_spaces=None)[source]¶

Export an exception list as NDJSON.

POST /api/exception_lists/_export

Note: unlike the read APIs, the export API requires both id and list_id.

Parameters:

id (str) – Exception list’s identifier (generated upon creation).
list_id (str) – Human readable exception list string identifier.
namespace_type (str) – "single" or "agnostic".
include_expired_exceptions (bool) – Whether to include expired exception items (as defined by their expire_time) in the export (default: True).
space_id (str | None) – Optional space ID to export the exception list from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

Response whose body is the NDJSON export (exception list, its items and an export-details summary line).

Raises:

BadRequestError – If id or list_id is missing or invalid.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> created = await client.exception_lists.get(list_id="trusted-processes")
>>> exported = await client.exception_lists.export(
...     id=created.body["id"],
...     list_id=created.body["list_id"],
...     namespace_type="single",
... )
>>> ndjson = exported.body

async import_lists(*, file, overwrite=None, as_new_list=None, filename='import.ndjson', space_id=None, validate_spaces=None)[source]¶

Import an exception list and its items from an NDJSON file.

POST /api/exception_lists/_import

Imports exception lists and items from an NDJSON export (uploaded as multipart/form-data).

Parameters:

file (bytes | str | list[dict[str, Any]]) – NDJSON export content: raw bytes/str (e.g. the body returned by export()), or a list of dicts (one per exported line), which is NDJSON-encoded automatically.
overwrite (bool | None) – Determines whether existing exception lists with the same list_id are overwritten. If any exception items have the same item_id, those are also overwritten (server default: False).
as_new_list (bool | None) – Determines whether the list being imported will have a new list_id generated. Additional item_id’s are generated for each exception item. Both the exception list and its items are overwritten (server default: False).
filename (str) – Filename advertised in the multipart upload.
space_id (str | None) – Optional space ID to import the exception list into.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

success, success_count, success_exception_lists, success_count_exception_lists, success_exception_list_items, success_count_exception_list_items and an errors array.

Return type:

ObjectApiResponse with the import summary

Raises:

ValueError – If file is empty.
BadRequestError – If the NDJSON payload is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> exported = await client.exception_lists.export(
...     id="...", list_id="trusted-processes",
...     namespace_type="single",
... )
>>> result = await client.exception_lists.import_lists(
...     file=exported.body, as_new_list=True,
... )
>>> print(result.body["success"])
True

async get_summary(*, id=None, list_id=None, namespace_type=None, filter=None, space_id=None, validate_spaces=None)[source]¶

Get an exception list summary.

GET /api/exception_lists/summary

Retrieves a per-OS summary of the number of exception items in an exception list.

Parameters:

id (str | None) – Exception list’s identifier generated upon creation. Either id or list_id must be specified.
list_id (str | None) – Exception list’s human readable identifier. Either id or list_id must be specified.
namespace_type (str | None) – "single" (server default) or "agnostic".
filter (str | None) – Search filter clause (KQL over the exception list item saved object attributes).
space_id (str | None) – Optional space ID to read the summary from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

windows, linux, macos and total. Note: the counts are grouped by the items’ os_types, so items without an os_types value are not reflected in total.

Return type:

ObjectApiResponse with the per-OS item counts

Raises:

ValueError – If neither id nor list_id is provided.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Example

>>> summary = await client.exception_lists.get_summary(
...     list_id="trusted-processes"
... )
>>> print(summary.body["total"])

async create_item(*, list_id, name, description, entries, type='simple', comments=None, expire_time=None, item_id=None, meta=None, namespace_type=None, os_types=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Create an exception list item.

POST /api/exception_lists/items

Parameters:

list_id (str) – Human readable string identifier of the exception list this item belongs to.
name (str) – Exception item’s name.
description (str) – Describes the exception item.
entries (list[dict[str, Any]]) – The item’s entries. Each entry is a dict with field, operator ("included"/"excluded") and type ("match", "match_any", "exists", "list", "nested" or "wildcard"), plus a value where applicable.
type (str) – Exception item’s type. Only "simple" is supported (default: "simple").
comments (list[dict[str, Any]] | None) – Array of {"comment": "..."} dicts attached to the item.
expire_time (str | None) – ISO 8601 date-time after which the item expires and no longer suppresses alerts.
item_id (str | None) – Human readable string identifier for the item. Generated if omitted.
meta (dict[str, Any] | None) – Placeholder for metadata about the item.
namespace_type (str | None) – "single" (server default) or "agnostic". Must match the parent list’s namespace_type.
os_types (list[str] | None) – Operating systems the item applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array of words and phrases to help categorize items.
space_id (str | None) – Optional space ID to create the item in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created exception list item.

Raises:

BadRequestError – If the request body is invalid.
NotFoundError – If the parent exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
ConflictError – If an item with the same item_id already exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> item = await client.exception_lists.create_item(
...     list_id="trusted-processes",
...     name="Trusted host",
...     description="Ignore the build server",
...     entries=[{
...         "field": "host.name",
...         "operator": "included",
...         "type": "match",
...         "value": "build-server-01",
...     }],
... )
>>> print(item.body["item_id"])

async get_item(*, id=None, item_id=None, namespace_type=None, space_id=None, validate_spaces=None)[source]¶

Get an exception list item.

GET /api/exception_lists/items

Gets the details of an exception list item using the id or item_id field.

Parameters:

id (str | None) – Exception list item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
namespace_type (str | None) – "single" (server default) or "agnostic".
space_id (str | None) – Optional space ID to get the item from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the exception list item.

Raises:

ValueError – If neither id nor item_id is provided.
NotFoundError – If the exception list item does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> item = await client.exception_lists.get_item(item_id="trusted-host")
>>> print(item.body["name"])

async update_item(*, name, description, entries, type='simple', id=None, item_id=None, list_id=None, _version=None, comments=None, expire_time=None, meta=None, namespace_type=None, os_types=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Update an exception list item.

PUT /api/exception_lists/items

Updates an exception list item using the id or item_id field. The name, description, type and entries fields are required by the API and replace the stored values.

Parameters:

name (str) – The (new) exception item’s name.
description (str) – The (new) description of the exception item.
entries (list[dict[str, Any]]) – The (new) item’s entries (see create_item()).
type (str) – Exception item’s type. Only "simple" is supported (default: "simple").
id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
list_id (str | None) – Human readable string identifier of the parent exception list.
_version (str | None) – The version id (returned when the item was created or fetched), used for optimistic concurrency control.
comments (list[dict[str, Any]] | None) – Array of {"comment": "..."} dicts. Include existing comments (with their id) to preserve them.
expire_time (str | None) – ISO 8601 date-time after which the item expires.
meta (dict[str, Any] | None) – Placeholder for metadata about the item.
namespace_type (str | None) – "single" (server default) or "agnostic".
os_types (list[str] | None) – Operating systems the item applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array of words and phrases to help categorize items.
space_id (str | None) – Optional space ID to update the item in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the updated exception list item.

Raises:

NotFoundError – If the exception list item does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = await client.exception_lists.update_item(
...     item_id="trusted-host",
...     name="Trusted host (updated)",
...     description="Updated entry",
...     entries=[{
...         "field": "host.name",
...         "operator": "included",
...         "type": "match",
...         "value": "build-server-02",
...     }],
... )
>>> print(updated.body["entries"][0]["value"])
build-server-02

async delete_item(*, id=None, item_id=None, namespace_type=None, space_id=None, validate_spaces=None)[source]¶

Delete an exception list item.

DELETE /api/exception_lists/items

Deletes an exception list item using the id or item_id field.

Parameters:

id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
namespace_type (str | None) – "single" (server default) or "agnostic".
space_id (str | None) – Optional space ID to delete the item from.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the deleted exception list item.

Raises:

ValueError – If neither id nor item_id is provided.
NotFoundError – If the exception list item does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.exception_lists.delete_item(item_id="trusted-host")

async find_items(*, list_id, filter=None, namespace_type=None, search=None, page=None, per_page=None, sort_field=None, sort_order=None, space_id=None, validate_spaces=None)[source]¶

Get a paginated subset of exception list items.

GET /api/exception_lists/items/_find

Returns the exception items of the specified list(s). By default, the first page is returned, with 20 results per page.

Parameters:

list_id (str | list[str]) – The list_id (or list of list_id’s) of the exception lists whose items to fetch.
filter (str | list[str] | None) – Filters the returned results according to the value of the specified field, using the exception-list.attributes.<field>:<value> KQL syntax. Accepts a single clause or a list of clauses (one per list_id).
namespace_type (str | list[str] | None) – "single" (server default) or "agnostic". Accepts a single value or a list of values (one per list_id).
search (str | None) – Simple query string searched across the items.
page (int | None) – The page number to return.
per_page (int | None) – The number of exception list items to return per page.
sort_field (str | None) – Determines which field is used to sort the results.
sort_order (str | None) – Sort order, "asc" or "desc".
space_id (str | None) – Optional space ID to search in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with data (the exception list items), page, per_page and total.

Raises:

BadRequestError – If the filter syntax is invalid.
NotFoundError – If the exception list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> found = await client.exception_lists.find_items(
...     list_id="trusted-processes", per_page=50,
... )
>>> print(found.body["total"])

async create_shared_list(*, name, description, space_id=None, validate_spaces=None)[source]¶

Create a shared exception list.

POST /api/exceptions/shared

Parameters:

name (str) – The name of the shared exception list.
description (str) – Describes the shared exception list.
space_id (str | None) – Optional space ID to create the shared exception list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created exception list (type "detection", generated list_id).

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> shared = await client.exception_lists.create_shared_list(
...     name="Shared exceptions",
...     description="Exceptions shared across rules",
... )
>>> print(shared.body["type"])
detection

async create_rule_exceptions(*, id, items, space_id=None, validate_spaces=None)[source]¶

Create exception items for a detection rule’s default list.

POST /api/detection_engine/rules/{id}/exceptions

Creates exception items and adds them to the rule’s default exception list (creating the rule_default list if it does not exist yet).

Parameters:

id (str) – The detection rule’s identifier — the rule’s UUID id, not the human readable rule_id.
items (list[dict[str, Any]]) – The exception items to create. Each item is a dict with the same fields accepted by create_item(), minus list_id (name, description, type, entries and optionally comments, expire_time, item_id, meta, namespace_type, os_types, tags).
space_id (str | None) – Optional space ID the rule lives in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

Response whose body is the array of created exception list items.

Raises:

BadRequestError – If the request body is invalid.
NotFoundError – If the detection rule does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> created = await client.exception_lists.create_rule_exceptions(
...     id="4656dc92-5832-11ea-8e2d-0242ac130003",
...     items=[{
...         "name": "Rule exception",
...         "description": "Suppress the build server",
...         "type": "simple",
...         "entries": [{
...             "field": "host.name",
...             "operator": "included",
...             "type": "match",
...             "value": "build-server-01",
...         }],
...     }],
... )
>>> print(created.body[0]["list_id"])

async create_endpoint_list(*, space_id=None, validate_spaces=None)[source]¶

Create the Elastic Endpoint exception list.

POST /api/endpoint_list

Parameters:

space_id (str | None) – Optional space ID to issue the request in (the endpoint list itself is space agnostic).
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created endpoint exception list, or an empty object ({}) if the list already existed.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> response = await client.exception_lists.create_endpoint_list()
>>> # {} means the endpoint list already existed
>>> print(response.body.get("list_id", "already existed"))

async create_endpoint_item(*, name, description, entries, type='simple', comments=None, item_id=None, meta=None, os_types=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Create an Elastic Endpoint exception list item.

POST /api/endpoint_list/items

Creates an exception item in the Elastic Endpoint exception list. If the endpoint list does not exist yet, it is created first (see create_endpoint_list()).

Parameters:

name (str) – Exception item’s name.
description (str) – Describes the exception item.
entries (list[dict[str, Any]]) – The item’s entries (see create_item()).
type (str) – Exception item’s type. Only "simple" is supported (default: "simple").
comments (list[dict[str, Any]] | None) – Array of {"comment": "..."} dicts attached to the item.
item_id (str | None) – Human readable string identifier for the item. Generated if omitted.
meta (dict[str, Any] | None) – Placeholder for metadata about the item.
os_types (list[str] | None) – Operating systems the item applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array of words and phrases to help categorize items.
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created endpoint exception list item (list_id is always "endpoint_list", namespace_type "agnostic").

Raises:

BadRequestError – If the request body is invalid.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
ConflictError – If an item with the same item_id already exists.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> item = await client.exception_lists.create_endpoint_item(
...     name="Trusted process",
...     description="Ignore the backup agent",
...     os_types=["windows"],
...     entries=[{
...         "field": "process.executable.caseless",
...         "operator": "included",
...         "type": "match",
...         "value": "C:\\Program Files\\Backup\\agent.exe",
...     }],
... )
>>> print(item.body["list_id"])
endpoint_list

async get_endpoint_item(*, id=None, item_id=None, space_id=None, validate_spaces=None)[source]¶

Get an Elastic Endpoint exception list item.

GET /api/endpoint_list/items

Gets the details of an endpoint exception list item using the id or item_id field.

Parameters:

id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the endpoint exception list item.

Raises:

ValueError – If neither id nor item_id is provided.
NotFoundError – If the item (or the endpoint list) does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> item = await client.exception_lists.get_endpoint_item(
...     item_id="trusted-process"
... )
>>> print(item.body["name"])

async update_endpoint_item(*, name, description, entries, type='simple', id=None, item_id=None, _version=None, comments=None, meta=None, os_types=None, tags=None, space_id=None, validate_spaces=None)[source]¶

Update an Elastic Endpoint exception list item.

PUT /api/endpoint_list/items

Updates an endpoint exception list item using the id or item_id field. The name, description, type and entries fields are required by the API and replace the stored values.

Parameters:

name (str) – The (new) exception item’s name.
description (str) – The (new) description of the exception item.
entries (list[dict[str, Any]]) – The (new) item’s entries (see create_item()).
type (str) – Exception item’s type. Only "simple" is supported (default: "simple").
id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
_version (str | None) – The version id (returned when the item was created or fetched), used for optimistic concurrency control.
comments (list[dict[str, Any]] | None) – Array of {"comment": "..."} dicts. Include existing comments (with their id) to preserve them.
meta (dict[str, Any] | None) – Placeholder for metadata about the item.
os_types (list[str] | None) – Operating systems the item applies to ("linux", "macos", "windows").
tags (list[str] | None) – String array of words and phrases to help categorize items.
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the updated endpoint exception list item.

Raises:

NotFoundError – If the item (or the endpoint list) does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> updated = await client.exception_lists.update_endpoint_item(
...     item_id="trusted-process",
...     name="Trusted process (updated)",
...     description="Updated entry",
...     os_types=["windows"],
...     entries=[{
...         "field": "process.executable.caseless",
...         "operator": "included",
...         "type": "match",
...         "value": "C:\\Program Files\\Backup\\agent2.exe",
...     }],
... )
>>> print(updated.body["name"])
Trusted process (updated)

async delete_endpoint_item(*, id=None, item_id=None, space_id=None, validate_spaces=None)[source]¶

Delete an Elastic Endpoint exception list item.

DELETE /api/endpoint_list/items

Deletes an endpoint exception list item using the id or item_id field.

Parameters:

id (str | None) – Exception item’s identifier. Either id or item_id must be specified.
item_id (str | None) – Human readable exception item string identifier. Either id or item_id must be specified.
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the deleted endpoint exception list item.

Raises:

ValueError – If neither id nor item_id is provided.
NotFoundError – If the item (or the endpoint list) does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> await client.exception_lists.delete_endpoint_item(
...     item_id="trusted-process"
... )

async find_endpoint_items(*, filter=None, page=None, per_page=None, sort_field=None, sort_order=None, space_id=None, validate_spaces=None)[source]¶

Get a paginated subset of Elastic Endpoint exception list items.

GET /api/endpoint_list/items/_find

By default, the first page is returned, with 20 results per page.

Parameters:

filter (str | None) – Filters the returned results according to the value of the specified field, using the exception-list-agnostic.attributes.<field>:<value> KQL syntax.
page (int | None) – The page number to return.
per_page (int | None) – The number of exception list items to return per page.
sort_field (str | None) – Determines which field is used to sort the results.
sort_order (str | None) – Sort order, "asc" or "desc".
space_id (str | None) – Optional space ID to issue the request in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with data (the endpoint exception list items), page, per_page and total.

Raises:

BadRequestError – If the filter syntax is invalid.
NotFoundError – If the endpoint list does not exist.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ObjectApiResponse[Any]

Example

>>> found = await client.exception_lists.find_endpoint_items(per_page=50)
>>> print(found.body["total"])

async perform_request(method, path, *, params=None, headers=None, body=None)¶

Perform an async HTTP request via the parent client with space context enhancement.

Parameters:

method (str) – HTTP method (GET, POST, PUT, DELETE, etc.)
path (str) – API endpoint path
params (dict[str, Any] | None) – Query parameters
headers (dict[str, str] | None) – Request headers
body (dict[str, Any] | None) – Request body

Returns:

API response

Raises:

ApiError – If the API returns an error response (enhanced with space context)

Return type:

ObjectApiResponse[Any]