A newer version is available. For the latest information, see the current release documentation.
« Managing signal detection rules Create rule »
Elastic Docs ›SIEM Guide [7.6] ›Detections (Beta)

Detections API

edit

Detections API

edit

This functionality is in beta and is subject to change. The design and code is less mature than official GA features and is being provided as-is with no warranties. Beta features are not subject to the support SLA of official GA features.

You can create rules that automatically turn events and alerts sent to the SIEM app into signals. These signals are displayed on the Detections page.

For more information on signals, and the difference between signals, events, and alerts, see detections terminology.

The API has these endpoints:

  • <kibana host>:<port>/api/detection_engine/rules - Signal detection rules CRUD functions
  • <kibana host>:<port>/api/detection_engine/index - Signal index operations
  • <kibana host>:<port>/api/detection_engine/tags - Aggregates and returns rule tags
  • <kibana host>:<port>/api/detection_engine/_import - Imports rules from an ndjson file
  • <kibana host>:<port>/api/detection_engine/_export - Exports rules to an ndjson file
  • <kibana host>:<port>/api/detection_engine/privileges - Returns the user’s Kibana space and signal index permissions, and whether the user is authenticated
  • <kibana host>:<port>/api/detection_engine/signals - Aggregates, queries, and returns signals, and updates their statuses
  • <kibana host>:<port>/api/detection_engine/prepackaged - Loads and retrieves the status of Elastic prebuilt rules

Where <kibana host> is the host name and <port> is the port of your Kibana instance.

In dev mode, the Kibana server runs behind a proxy which adds a random path component to its URL. Considerations for basePath describes how to work with and disable the random path component.

You can view and download a Detections API Postman collection here.

Kibana space API calls

edit

If you are making calls to a Kibana space other than the Default space, the space identifier is part of the endpoint’s URL:

<kibana host>:<port>/s/<space URL>/api/detection_engine/rules

Where <space URL> is the URL identifier for the space.

You can find space URL identifiers on Edit space pages (Management → Spaces → <space name>) or by calling GET /api/spaces/space.

Kibana role requirements

edit

To create and run rules, the user role for the Kibana space must have:

  • the manage_api_key privilege.
  • read, write, create, and view_index_metadata privileges for the signals index (the system index used for storing signals created from rules).
  • all privileges for SIEM features.

Authentication

edit

Token-based authentication, using the same username and password used to log in to the Kibana UI, is required to access the API.

API calls

edit

All calls to the API are stateless. Each call must include all the information SIEM needs to perform the request.

Requests must contain these headers:

  • kbn-xsrf: <value>, where <value> can be any alphanumeric string (for example, kbn-xsrf: kibana)
  • Content-Type: application/json (when the request contains a JSON payload)

For example, the following call retrieves the first 20 signal detection rules from the Kibana siem space:

curl -X GET "<kibana host>:<port>/s/siem/api/detection_engine/rules/_find"
-H 'kbn-xsrf: kibana' -u <username>:<password>
« Managing signal detection rules Create rule »