EndpointClient¶

Client for the Kibana Security Endpoint Management API.

The Endpoint Management API (/api/endpoint/...) drives Elastic Defend. It lists enrolled endpoint hosts and their metadata, runs response actions against them (isolate/release a host, terminate or suspend a process, list running processes, retrieve or upload a file, run a command or a script, scan for malware, generate a memory dump, or cancel a pending action), inspects action history/status, reads endpoint policy responses, manages the protection-updates note on a Defend package policy, and manages the reusable scripts library.

Response actions require the target hosts to have the Elastic Defend integration installed and enrolled. Against a stack with no enrolled endpoints those routes return an HTTP 400 (The host does not have Elastic Defend integration installed).

All Endpoint Management APIs are space-scoped resources: every method accepts an optional space_id to target a specific space.

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

Bases: NamespaceClient

Client for the Kibana Security Endpoint Management API.

The Endpoint Management API (/api/endpoint/...) drives Elastic Defend: it lists enrolled endpoint hosts and their metadata, runs response actions against them (isolate/release a host, terminate or suspend a process, list running processes, retrieve or upload a file, run a command or a script, scan for malware, generate a memory dump, or cancel a pending action), inspects action history and status, reads endpoint policy responses, manages the protection-updates note on a Defend package policy, and manages the reusable scripts library.

All Endpoint Management 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).

Note

Response actions require the target hosts to have the Elastic Defend integration installed and enrolled. Against a stack with no enrolled endpoints these routes return an HTTP 400 (The host does not have Elastic Defend integration installed).

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # List enrolled endpoint hosts
>>> hosts = client.endpoint.get_metadata_list(host_statuses=["healthy"])
>>>
>>> # Isolate a host
>>> action = client.endpoint.isolate(
...     endpoint_ids=["endpoint-id-1"],
...     comment="Investigating suspicious activity",
... )

Listing Hosts and Actions

from kibana import Kibana

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

# List enrolled endpoint hosts
hosts = client.endpoint.get_metadata_list(
    host_statuses=["healthy"], page_size=50
)
print(hosts.body["total"])

# Metadata for a single host
host = client.endpoint.get_metadata(id="endpoint-id-1")

# Response-actions state and history
state = client.endpoint.get_actions_state()
actions = client.endpoint.get_actions_list(commands=["isolate"])
status = client.endpoint.get_actions_status(agent_ids=["agent-id-1"])
details = client.endpoint.get_action_details(action_id="action-id-1")

Running Response Actions

# Isolate / release a host
client.endpoint.isolate(
    endpoint_ids=["endpoint-id-1"], comment="Investigating"
)
client.endpoint.unisolate(endpoint_ids=["endpoint-id-1"])

# Terminate or suspend a process
client.endpoint.kill_process(
    endpoint_ids=["endpoint-id-1"], parameters={"pid": 123}
)
client.endpoint.suspend_process(
    endpoint_ids=["endpoint-id-1"], parameters={"entity_id": "abc"}
)

# Collect data
client.endpoint.get_running_processes(endpoint_ids=["endpoint-id-1"])
client.endpoint.get_file(
    endpoint_ids=["endpoint-id-1"], parameters={"path": "/etc/passwd"}
)
client.endpoint.execute(
    endpoint_ids=["endpoint-id-1"],
    parameters={"command": "ls -la", "timeout": 600},
)
client.endpoint.scan(
    endpoint_ids=["endpoint-id-1"], parameters={"path": "/opt"}
)

# Upload a file to the host (multipart)
action = client.endpoint.upload(
    endpoint_ids=["endpoint-id-1"],
    file=b"#!/bin/sh\necho hi\n",
    filename="fix.sh",
    parameters={"overwrite": True},
)

# Retrieve a file produced by a get_file / scan action
info = client.endpoint.get_action_file_info(
    action_id="action-id-1", file_id="file-id-1"
)
blob = client.endpoint.download_action_file(
    action_id="action-id-1", file_id="file-id-1"
)

# Cancel a pending action
client.endpoint.cancel(
    endpoint_ids=["endpoint-id-1"], parameters={"id": "action-id-1"}
)

Policy Response and Protection Updates Note

resp = client.endpoint.get_policy_response(agent_id="agent-id-1")

client.endpoint.create_update_protection_updates_note(
    package_policy_id="package-policy-id-1",
    note="Pinned to 2024-01-01 protection artifacts",
)
note = client.endpoint.get_protection_updates_note(
    package_policy_id="package-policy-id-1"
)

Managing the Scripts Library

created = client.endpoint.create_script(
    name="collect-logs",
    platform=["linux"],
    file_type="script",
    file=b"#!/bin/sh\necho hi\n",
    filename="collect.sh",
    tags=["threatHunting"],
)
script_id = created.body["data"]["id"]

client.endpoint.get_scripts(page_size=50)
client.endpoint.get_script(script_id=script_id)
client.endpoint.update_script(
    script_id=script_id, description="Updated"
)
client.endpoint.download_script(script_id=script_id)
client.endpoint.delete_script(script_id=script_id)

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

Initialize the EndpointClient.

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).

get_metadata_list(*, host_statuses=None, page=None, page_size=None, kuery=None, sort_field=None, sort_direction=None, space_id=None, validate_spaces=None)[source]¶

Get a metadata list of enrolled endpoint hosts.

GET /api/endpoint/metadata

Parameters:

host_statuses (list[str] | None) – Filter by agent health statuses. Any of healthy, offline, updating, inactive, unenrolled. In the 9.4.3 spec this is marked required, but the live server accepts requests without it.
page (int | None) – Page number (default 1).
page_size (int | None) – Number of items per page (1-100, default 10).
kuery (str | None) – A KQL string to filter the hosts.
sort_field (str | None) – Field to sort by (e.g. enrolled_at, metadata.host.hostname, host_status, last_checkin).
sort_direction (str | None) – asc or desc.
space_id (str | None) – Optional space ID to scope the request to.
validate_spaces (bool | None) – Override space validation for this operation.

Returns:

ObjectApiResponse whose body has data (list of host metadata), total, page, pageSize, sortField and sortDirection.

Raises:

AuthenticationException – If authentication fails.
AuthorizationException – If insufficient privileges.

Return type:

EndpointClient¶

AsyncEndpointClient¶