ListsClient¶

Client for the Kibana Security Lists API.

Value lists hold values of a single Elasticsearch type (ip, keyword, ip_range, …) that Security detection rule exceptions can reference, e.g. a list of known-bad IP addresses. A value list is a container; the individual values live in list items, which can be managed one by one or imported from a newline-separated text file.

Value lists are stored in per-space .lists-<space> and .items-<space> data streams that must exist before lists can be created. All Lists APIs are space-scoped: every method accepts an optional space_id to target a specific space.

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

Bases: NamespaceClient

Client for the Kibana Security Lists API.

Value lists (/api/lists) hold values of a single Elasticsearch type (ip, keyword, ip_range, …) that Security detection rule exceptions can reference, e.g. a list of malicious IP addresses. A value list is a container; the individual values live in list items (/api/lists/items), which can be managed one by one or imported from a newline-separated text file.

Value lists are stored in per-space .lists-<space> and .items-<space> data streams that must exist before lists can be created; see create_index() and get_index_status().

All Lists APIs are space-scoped: 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="...")
>>>
>>> # Make sure the value list data streams exist
>>> status = client.lists.get_index_status()
>>>
>>> # Create a list of bad IPs and add a value
>>> created = client.lists.create(
...     name="Bad ips", description="Known bad IPs", type="ip"
... )
>>> list_id = created.body["id"]
>>> client.lists.create_item(list_id=list_id, value="192.0.2.1")
>>>
>>> # Export the values and clean up
>>> exported = client.lists.export_items(list_id=list_id)
>>> client.lists.delete(id=list_id)

Preparing the Value List Data Streams

from kibana import Kibana
from kibana.exceptions import NotFoundError

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

# Value lists live in per-space data streams; create them once
try:
    status = client.lists.get_index_status()
except NotFoundError:
    client.lists.create_index()

Managing Value Lists

# Create a list of bad IPs
created = client.lists.create(
    name="Bad ips",
    description="Known bad IP addresses",
    type="ip",
    id="bad-ips",
)

# Read, replace, patch and search
fetched = client.lists.get(id="bad-ips")
client.lists.update(
    id="bad-ips",
    name="Bad ips - updated",
    description="Latest bad IPs",
    _version=fetched.body["_version"],
)
client.lists.patch(id="bad-ips", name="Bad ips - patched")
found = client.lists.find(filter="type:ip", per_page=50)

# Deleting a list also deletes all of its items
client.lists.delete(id="bad-ips")

Managing List Items

# Add individual values
item = client.lists.create_item(
    list_id="bad-ips", value="192.0.2.1", refresh="wait_for"
)

# Look items up by ID, or by list_id + value (returns an array)
by_id = client.lists.get_item(id=item.body["id"])
by_value = client.lists.get_item(list_id="bad-ips", value="192.0.2.1")

# Update / patch / delete
client.lists.update_item(id=item.body["id"], value="192.0.2.2")
client.lists.patch_item(id=item.body["id"], value="192.0.2.3")
client.lists.delete_item(list_id="bad-ips", value="192.0.2.3")

# Paginate through a list's items
page = client.lists.find_items(list_id="bad-ips", per_page=100)

Importing and Exporting Values

# Import values into an existing list (newline-separated upload)
client.lists.import_items(
    file=["198.51.100.1", "198.51.100.2"],
    list_id="bad-ips",
    refresh="wait_for",
)

# Or create a brand-new list from a file: id/name come from filename
client.lists.import_items(
    file="203.0.113.1\n203.0.113.2\n",
    type="ip",
    filename="more-bad-ips.txt",
)

# Export values (one entry per item value)
exported = client.lists.export_items(list_id="bad-ips")
for value in exported:
    print(value)

Privileges

privileges = client.lists.get_privileges()
print(privileges.body["is_authenticated"])

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

Initialize the ListsClient.

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

>>> lists_client = ListsClient(kibana_client)

create(*, name, description, type, id=None, meta=None, version=None, space_id=None, validate_spaces=None)[source]¶

Create a value list.

POST /api/lists

Creates a new value list container. The value list data streams must exist first (see create_index()); otherwise Kibana responds with a 400 error.

Parameters:

name (str) – Value list’s name.
description (str) – Describes the value list.
type (str) – The Elasticsearch data type of the values the list holds, e.g. "ip", "ip_range", "keyword", "text", "date", "integer", "long", "double", and the other types accepted by the API.
id (str | None) – Optional identifier for the list (server-generated when omitted).
meta (dict[str, Any] | None) – Placeholder for metadata about the value list.
version (int | None) – The document version number (defaults to 1).
space_id (str | None) – Optional space ID to create the list in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created list (id, name, description, type, version, _version, created_at/created_by, updated_at/updated_by, tie_breaker_id, immutable).

Raises:

BadRequestError – If the payload is invalid or the value list data streams do not exist yet.
ConflictError – If a list with the same id already exists.
AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.
SpaceNotFoundError – If the space doesn’t exist and validation is enabled.

Return type:

ListsClient¶

AsyncListsClient¶