EntityAnalyticsClient¶

Client for the Kibana Security Entity Analytics API.

Entity Analytics surfaces risk and privilege insights for entities (hosts, users, services and generic entities) observed by the Elastic Security solution. The client covers asset criticality, the risk scoring engine, privileged user monitoring (including the privileged access detection ML package), watchlists (Technical Preview in 9.4) and the Entity Store.

All Entity Analytics resources are space-scoped: every method accepts an optional space_id to target a specific space.

Note

The asset criticality endpoints are deprecated in Kibana 9.4 in favor of the Entity Store entity APIs, but remain fully functional. On deployments where Entity Store V2 is enabled, the legacy public risk engine routes (schedule_risk_engine_now, configure_risk_engine_saved_object, cleanup_risk_engine) are not registered and answer 404.

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

Bases: NamespaceClient

Client for the Kibana Security Entity Analytics API.

Entity Analytics surfaces risk and privilege insights for entities (hosts, users, services and generic entities) observed by the Elastic Security solution. This client covers the Kibana 9.4.3 Entity Analytics REST APIs:

Asset criticality (/api/asset_criticality): classify how critical an entity is (deprecated in 9.4 in favor of the Entity Store).
Risk engine (/api/risk_score/engine): schedule, configure and clean up the risk scoring engine.
Privilege monitoring (/api/entity_analytics/monitoring): manage the Privilege Monitoring Engine and monitored privileged users, including CSV bulk upload.
Privileged access detection (.../privileged_user_monitoring/pad): install and inspect the PAD ML package.
Watchlists (/api/entity_analytics/watchlists): group entities and apply risk modifiers (Technical Preview in 9.4).
Entity Store (/api/security/entity_store): install, manage and query the entity store, including direct entity CRUD and entity resolution (linking).

All Entity Analytics resources 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="...")
>>>
>>> # Classify an asset and read it back
>>> client.entity_analytics.create_asset_criticality(
...     id_field="host.name",
...     id_value="my-host",
...     criticality_level="high_impact",
... )
>>> record = client.entity_analytics.get_asset_criticality(
...     id_field="host.name", id_value="my-host"
... )
>>>
>>> # Install the Entity Store and check its status
>>> client.entity_analytics.install_entity_store(entity_types=["host"])
>>> status = client.entity_analytics.get_entity_store_status()
>>> print(status.body["status"])

Classifying Asset Criticality

from kibana import Kibana

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

# Upsert a single record
client.entity_analytics.create_asset_criticality(
    id_field="host.name",
    id_value="web-01",
    criticality_level="high_impact",
    refresh="wait_for",
)

# Bulk upsert ("unassigned" removes an assignment)
client.entity_analytics.bulk_upsert_asset_criticality(
    records=[
        {
            "id_field": "user.name",
            "id_value": "alice",
            "criticality_level": "medium_impact",
        },
    ]
)

# Read and search records
record = client.entity_analytics.get_asset_criticality(
    id_field="host.name", id_value="web-01"
)
found = client.entity_analytics.find_asset_criticality(
    kuery="criticality_level: high_impact", per_page=100
)

# Delete a record
client.entity_analytics.delete_asset_criticality(
    id_field="host.name", id_value="web-01"
)

Privileged User Monitoring

# Initialize the Privilege Monitoring Engine for the space
client.entity_analytics.init_monitoring_engine()

# Add monitored users one by one or in bulk via CSV
user = client.entity_analytics.create_monitored_user(name="admin-user")
client.entity_analytics.upload_monitored_users_csv(
    file="admin-1\nadmin-2\n"
)

# Inspect and manage
users = client.entity_analytics.list_monitored_users(
    kql="user.name: admin*"
)
client.entity_analytics.schedule_monitoring_engine_now()
health = client.entity_analytics.get_monitoring_health()

# Disable or remove the engine (data=True also deletes the users)
client.entity_analytics.disable_monitoring_engine()
client.entity_analytics.delete_monitoring_engine(data=True)

# Privileged access detection (PAD) ML package
client.entity_analytics.install_pad_package()
pad = client.entity_analytics.get_pad_status()

Watchlists (Technical Preview)

watchlist = client.entity_analytics.create_watchlist(
    name="High Risk Vendors",
    risk_modifier=1.5,
    description="High risk vendor watchlist",
)
watchlist_id = watchlist.body["id"]

# Add entities from a CSV (matched against the Entity Store)
client.entity_analytics.upload_watchlist_csv(
    watchlist_id=watchlist_id,
    file="type,name\nhost,web-01\n",
)

# Manual entity assignment by EUID
client.entity_analytics.assign_watchlist_entities(
    watchlist_id=watchlist_id, euids=["host:web-01"]
)
client.entity_analytics.unassign_watchlist_entities(
    watchlist_id=watchlist_id, euids=["host:web-01"]
)

client.entity_analytics.delete_watchlist(id=watchlist_id)

Managing the Entity Store

# Install engines and wait until the store is running
client.entity_analytics.install_entity_store(
    entity_types=["host", "user"],
    log_extraction={"frequency": "5m", "lookbackPeriod": "12h"},
)
status = client.entity_analytics.get_entity_store_status(
    include_components=True
)

# Query and manage entities
entities = client.entity_analytics.list_entities(
    entity_types=["host"], sort_field="entity.name", per_page=100
)
client.entity_analytics.create_entity(
    entity_type="host", document={"host": {"name": "web-01"}}
)

# Entity resolution: link duplicates to a canonical entity
client.entity_analytics.link_entities(
    entity_ids=["host:web-01.internal"], target_id="host:web-01"
)
group = client.entity_analytics.get_entity_resolution_group(
    entity_id="host:web-01"
)

# Pause, resume or remove the store
client.entity_analytics.stop_entity_store()
client.entity_analytics.start_entity_store()
client.entity_analytics.uninstall_entity_store()

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

Initialize the EntityAnalyticsClient.

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

>>> entity_analytics_client = EntityAnalyticsClient(kibana_client)

create_asset_criticality(*, id_field, id_value, criticality_level, refresh=None, space_id=None, validate_spaces=None)[source]¶

Upsert an asset criticality record.

Deprecated since version 9.4: The asset criticality APIs are deprecated; manage asset criticality through the Entity Store entity APIs instead (e.g. update_entity()).

POST /api/asset_criticality. Creates or updates (upserts) the asset criticality record for the given entity. If a record already exists for the specified entity, that record is overwritten. If no record exists, a new record is created.

Parameters:

id_field (str) – The field representing the entity identifier. One of "host.name", "user.name", "service.name", "entity.id".
id_value (str) – The identifier of the entity (e.g. the host name).
criticality_level (str) – The criticality level. One of "low_impact", "medium_impact", "high_impact", "extreme_impact".
refresh (str | None) – If "wait_for", wait for a refresh so the created record is visible to subsequent searches.
space_id (str | None) – Optional space ID for space-scoped operations.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse containing the created/updated record (id_field, id_value, criticality_level, @timestamp, asset and the entity field object).

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:

EntityAnalyticsClient¶

AsyncEntityAnalyticsClient¶