IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.
« Prebuilt rules Create exception container »
Elastic Docs ›Elastic Security Solution [7.16] ›Elastic Security APIs

Exceptions API

edit

Exceptions API

edit

Exceptions are associated with detection and endpoint rules, and are used to prevent a rule from generating an alert from incoming events even when the rule’s other criteria are met. They can be used to reduce the number of false positives, and to prevent trusted processes and network activity from generating unnecessary alerts.

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.

Exceptions are made up of:

  • Exception containers: A container for related exceptions. In general, a single exception container contains all the exception items relevant for a subset of rules. For example, a container can be used to group together network-related exceptions that are relevant for a large number of network rules. The container can then be associated with all the relevant rules.
  • Exception items: The query (fields, values, and logic) used to prevent rules from generating alerts. When an exception item’s query evaluates to true, the rule does not generate an alert.

For detection rules, you can also use lists to define rule exceptions. A list holds multiple values of the same Elasticsearch data type, such as IP addresses, which are used to determine when an exception prevents an alert from being generated.

You cannot use lists with endpoint rule exceptions.

Only exception containers can be associated with rules. You cannot directly associate an exception item or a list container with a rule. To use list exceptions, create an exception item that references the relevant list container (see this example request).

The following diagram represents the logical relationship between rules, detections, and lists, and shows the boolean operator used between sibling entities:

exceptions logic

Before you can create exceptions, you must create .lists and .items indices for the Kibana space (see Lists index endpoint).

Kibana role requirements

edit

To create list containers and items, the user role for the Kibana space must have:

  • read and write index privileges for the .lists and .items indices (the system index used for storing exception lists).
  • Kibana space All privileges for the Security and Saved Objects Management features (see Feature access based on user privileges).

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

« Prebuilt rules Create exception container »