DetectionEngineClient¶

Client for the Kibana Security Detections API.

The detection engine powers Elastic Security: detection rules run over your data and create detection alerts (historically called signals). This client manages detection rules (CRUD, find, bulk actions, preview, NDJSON export/import, Elastic prebuilt rules), detection alerts (search, workflow status, tags, assignees, legacy signals migrations) and the per-space alerts index.

Detection rules and alerts are space-scoped resources: a rule created in one space is not visible from another space. Every method accepts an optional space_id to target a specific space.

Note

The rule-exceptions endpoint (POST /api/detection_engine/rules/{id}/exceptions) is exposed on the exception_lists namespace.

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

Bases: NamespaceClient

Client for the Kibana Security Detections API.

Manages Elastic Security detection rules (create, read, update, delete, find, bulk actions, preview, export/import, prebuilt rule installation), detection alerts – also called signals – (search, status, tags, assignees, legacy signals migrations) and the .alerts-security.alerts index for a Kibana space.

All Security Detections APIs are space-scoped: rules and alerts live in the space they were created in. 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: the rule-exceptions endpoint POST /api/detection_engine/rules/{id}/exceptions is exposed on the exception_lists namespace, not here.

Example

>>> from kibana import Kibana
>>> client = Kibana("http://localhost:5601", api_key="...")
>>>
>>> # Create a custom query rule and find it
>>> rule = client.detection_engine.create_rule(
...     type="query",
...     name="Suspicious login",
...     description="Detects suspicious logins",
...     severity="low",
...     risk_score=21,
...     query='user.name: "suspicious"',
...     index=["logs-*"],
... )
>>> found = client.detection_engine.find_rules(
...     filter='alert.attributes.name: "Suspicious login"'
... )
>>> client.detection_engine.delete_rule(id=rule.body["id"])

Managing Detection Rules

from kibana import Kibana

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

# Create a custom query rule (disabled)
rule = client.detection_engine.create_rule(
    type="query",
    name="Suspicious login",
    description="Detects suspicious logins",
    severity="low",
    risk_score=21,
    query='user.name: "suspicious"',
    index=["logs-*"],
    interval="5m",
    from_="now-6m",
    enabled=False,
)

# Read, patch and find rules
fetched = client.detection_engine.get_rule(rule_id=rule.body["rule_id"])
client.detection_engine.patch_rule(
    rule_id=rule.body["rule_id"], tags=["triage"]
)
found = client.detection_engine.find_rules(
    filter='alert.attributes.tags: "triage"', per_page=50
)

# Full update -- also how you toggle `enabled` on 9.4.3
client.detection_engine.update_rule(
    rule_id=rule.body["rule_id"],
    type="query",
    name="Suspicious login",
    description="Detects suspicious logins",
    severity="medium",
    risk_score=47,
    query='user.name: "suspicious"',
    enabled=True,
)

# Delete it
client.detection_engine.delete_rule(rule_id=rule.body["rule_id"])

Bulk Actions, Export and Import

# Add a tag to many rules at once
client.detection_engine.bulk_action_rules(
    action="edit",
    query='alert.attributes.tags: "triage"',
    edit=[{"type": "add_tags", "value": ["reviewed"]}],
)

# Export rules as NDJSON and import them back
exported = client.detection_engine.export_rules(
    objects=[{"rule_id": "my-rule"}], exclude_export_details=True
)
client.detection_engine.import_rules(file=list(exported), overwrite=True)

# Install the Elastic prebuilt rules and Timeline templates
status = client.detection_engine.get_prepackaged_rules_status()
if status.body["rules_not_installed"]:
    client.detection_engine.install_prepackaged_rules()

Previewing Rules

Preview the alerts a rule would generate without creating it:

preview = client.detection_engine.preview_rule(
    type="query",
    name="Preview",
    description="Preview run",
    severity="low",
    risk_score=21,
    query='user.name: "suspicious"',
    index=["logs-*"],
    invocation_count=1,
    timeframe_end="2026-07-06T12:00:00.000Z",
    from_="now-6h",
    interval="1h",
)
print(preview.body["previewId"], preview.body["logs"])

Working with Detection Alerts

# Search open alerts
alerts = client.detection_engine.search_alerts(
    query={
        "bool": {
            "filter": [
                {"match": {"kibana.alert.workflow_status": "open"}}
            ]
        }
    },
    size=10,
)

# Close alerts, tag them, assign them
alert_ids = [hit["_id"] for hit in alerts.body["hits"]["hits"]]
if alert_ids:
    client.detection_engine.set_alert_status(
        status="closed", signal_ids=alert_ids
    )
    client.detection_engine.set_alert_tags(
        ids=alert_ids, tags_to_add=["triaged"], tags_to_remove=[]
    )
    client.detection_engine.set_alert_assignees(
        ids=alert_ids, add=["u_profile_uid"], remove=[]
    )

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

Initialize the DetectionEngineClient.

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

>>> detection_engine_client = DetectionEngineClient(kibana_client)

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

Get detection-engine privileges for the current user.

GET /api/detection_engine/privileges. Retrieves whether or not the user is authenticated, and the user’s Kibana space and index privileges, which determine if the user can create an index for the Elastic Security alerts generated by detection rules.

Parameters:

space_id (str | None) – Optional space ID to check privileges in.
validate_spaces (bool | None) – Override space validation setting for this operation.

Returns:

ObjectApiResponse with username, has_all_requested, cluster and index privilege maps, is_authenticated and has_encryption_key.

Raises:

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

Return type:

DetectionEngineClient¶

AsyncDetectionEngineClient¶