Detections APIedit

You can create rules that automatically turn events and external alerts sent to Elastic Security into detection alerts. These alerts are displayed on the Detections page.

Console supports only Elasticsearch APIs. Console doesn’t allow interactions with Kibana APIs. You must use curl or another HTTP tool instead. For more information, refer to Run Elasticsearch API requests.

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

The API has these endpoints:

  • <kibana host>:<port>/api/detection_engine/rules - Detection rules CRUD functions
  • <kibana host>:<port>/api/detection_engine/index - Signal index operations (used to store detection alerts)
  • <kibana host>:<port>/api/detection_engine/tags - Aggregates and returns rule tags
  • <kibana host>:<port>/api/detection_engine/rules/_import - Imports rules from an .ndjson file
  • <kibana host>:<port>/api/detection_engine/rules/_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 alerts, and updates their statuses
  • <kibana host>:<port>/api/detection_engine/rules/prepackaged - Loads and retrieves the status of Elastic prebuilt rules

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

Authenticationedit

This API supports both key- and token-based authentication.

To use key-based authentication, create an API key, then specify the key in the header of your API calls.

To use token-based authentication, provide a username and password; this automatically creates an API key that matches the current user’s privileges.

In both cases, the API key is subsequently used for authorization when the rule runs.

If the API key has different privileges than the key that created or most recently updated the rule, the rule behavior might change.

If the key that created the rule gets deleted, or the user that created the rule becomes inactive, the rule will stop running.

Kibana role requirementsedit

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

  • Kibana space All privileges for the Security and Saved Objects Management features (see Feature access based on user privileges).
  • read and write privileges for the .siem-signals-* index (the system index used for storing detection alerts created from rules).

See Detections prerequisites and requirements for a complete list of requirements.