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

Lists API

edit

Lists API

edit

Lists can be used with detection rule exceptions to define values that prevent a rule from generating alerts. Lists are made up of:

  • List containers: A container for values of the same Elasticsearch data type. The following data types can be used:

    • boolean
    • byte
    • date
    • date_nanos
    • date_range
    • double
    • double_range
    • float
    • float_range
    • half_float
    • integer
    • integer_range
    • ip
    • ip_range
    • keyword
    • long
    • long_range
    • short
    • text
  • List items: The values used to determine whether the exception prevents an alert from being generated.

All list items in the same list container must be of the same data type, and each item defines a single value. For example, an IP list container, named internal-ip-addresses-southport, contains five items, where each item defines one internal IP address:

  1. 192.168.1.1
  2. 192.168.1.3
  3. 192.168.1.18
  4. 192.168.1.12
  5. 192.168.1.7

To use these IP addresses as values for defining rule exceptions, use the Exceptions API to create an exception item that references the internal-ip-addresses-southport list.

Lists cannot be added directly to rules, nor do they define the operators used to determine when exceptions are applied (is in list, is not in list). Use an exception item to define the operator and associate it with an exception container. You can then add the exception container to a rule’s exceptions_list object.

Before you can create lists, 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.

« Lists index endpoint Create list container »