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

Create list container

edit

Create list container

edit

Creates a list container.

A list container groups common list items that define exceptions for when detection rule alerts are not generated even when a rule’s other criteria are met.

All list items in the same list container refer to the same type of exception. For example, each list item in an ip list container excludes an IP address.

You can retrieve ip items in a list container using CIDR notation, and ip_range items using a single IP value. For examples, see Get list item.

Request URL

edit

POST <kibana host>:<port>/api/lists

Request body

edit

A JSON object that defines the list container’s properties.

Required fields

edit
Name Type Description

description

String

Describes the list container.

name

String

The list container’s name.

type

String

Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:

Optional fields

edit
Name Type Description

deserializer

String

Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions:

  • {{{value}}} - Single value item types, such as ip, long, date, keyword, and text.
  • {{{gte}}}-{{{lte}}} - Range value item types, such as ip_range, double_range, float_range, integer_range, and long_range.
  • {{{gte}}},{{{lte}}} - Date range values.

For information on parsing item values when they are uploaded, see serializer.

id

String

Unique identifier. Automatically created when it is not provided.

meta

Object

Placeholder for metadata about the list container.

serializer

String

Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups:

  • (?<value>.+) - Single value item types, such as ip, long, date, keyword, and text.
  • (?<gte>.+)-(?<lte>.+)|(?<value>.+) - Range value item types, such as date_range, ip_range, double_range, float_range, integer_range, and long_range.

version

Integer

The list container’s version number. Defaults to 1.

Example requests

edit

Creates a list container for IP addresses:

POST api/lists
{
  "id": "internal-ip-excludes",
  "name": "Exclude internal IP addresses",
  "description": "Contains list items that exclude internal IP addresses from detection rules.",
  "type": "ip"
}

Creates a list container for a keyword:

POST api/lists
{
  "id": "host.name-container",
  "name": "Exclude hosts",
  "description": "Contains list items that exclude host names from detection rules.",
  "type": "keyword"
}

Creates a list container for ip_range items with custom parsing:

POST api/lists
{
  "id": "internal-ip-range-excludes",
  "name": "Exclude IP ranges",
  "description": "Contains excluded IP ranges.",
  "serializer": "(?<gte>.+)/(?<lte>.+)", 
  "deserializer": "{{{gte}}}--{{{lte}}}", 
  "type": "ip_range"
}

Uploads IP ranges using / characters instead of - characters. The list item or source file from which the IP ranges are uploaded must use the / character to define the range. For example, 192.168.0.1/192.168.0.27.

Presents the container’s retrieved IP range list items using -- characters. For example, 192.168.0.1--192.168.0.27.

Response code

edit
200
Indicates a successful call.

Response payload

edit
{
  "_version": "WzAsMV0=", 
  "id": "internal-ip-excludes",
  "created_at": "2020-08-11T10:08:05.289Z",
  "created_by": "elastic",
  "description": "Contains list items that exclude internal IP addresses from detection rule matches.",
  "immutable": false,
  "name": "Exclude internal IP addresses",
  "tie_breaker_id": "f7951678-ad13-4d65-8d15-a4c706d4893e",
  "type": "ip",
  "updated_at": "2020-08-11T10:08:05.289Z",
  "updated_by": "elastic",
  "version": 1
}

Base-64 encoded value of if_seq_no and if_primary_term parameters, used for Optimistic concurrency control. To ensure there are no conflicts, use this value when updating a list container.
« Lists API Create list item »