Create exception item

edit

Creates an exception item and associates it with the specified exception container.

Refer to Lists API for information about creating exception items from lists, such as a list of IP addresses or host names.

Before creating exception items, you must create an exception container.

Endpoint rule exception items cannot use lists (the list in the entries array), and the following fields cannot be used in exception queries (as field values in the entries object):

  • file.Ext.quarantine_path
  • file.Ext.quarantine_result
  • process.entity_id
  • process.parent.entity_id
  • process.ancestry

Request URL

edit

POST <kibana host>:<port>/api/exception_lists/items

Request body

edit

A JSON object with these fields:

Name Type Description Required

comments

comments[]

Array of comment fields:

  • comment (string): Comments about the exception item.

No, defaults to empty array.

description

String

Describes the exception item.

Yes

entries

entries[]

Array containing the exception queries. Boolean AND logic is used to evaluate the relationship between array elements. If you want to use OR logic, create a separate exception item.

Yes

list_id

String

ID of the associated exception container.

Yes

item_id

String

Unique identifier of the exception item.

No, automatically created when it is not provided.

meta

Object

Placeholder for metadata about the exception item.

No

name

String

The exception item’s name.

Yes.

namespace_type

String

Determines whether the exception item is available in all Kibana spaces or just the space in which it is created, where:

  • single: Only available in the Kibana space in which it is created.
  • agnostic: Available in all Kibana spaces.

Must be the same value as its associated exception container.

No, defaults to single.

tags

String[]

String array containing words and phrases to help categorize exception items.

No

type

String

Exception query type, must be simple.

Yes

_tags

String[]

For endpoint rules only, defines the OS on which the exception is implemented. Valid values are:

  • os:windows: Windows OS
  • os:linux: Linux OS
  • os:macos: Mac OS

The array must also include an endpoint element (to implement the exception on Linux hosts, use: ["endpoint", "os:linux"]).

For endpoint exceptions, yes. For detection exceptions, no.

entries schema

edit
Name Type Description Required

field

String

The source event field used to define the exception. Cannot be an empty string.

Yes

list

list

Object containing the list container’s id and type. Only valid for detection exception items.

No, except when using a list to define detection exceptions.

operator

String

The operator used to determine when the exception is used. Can be:

  • included: The field has the specified value or values.
  • excluded: The field does not have specified value or values.

Yes

type

String

The type of query:

  • match: Must be an exact match of the defined value.
  • match_any: Matches any of the defined values.
  • exists: The field exists.
  • list: The field matches values in a list container.
  • wildcard: Matches value using wildcards, such as C:\path\*\app.exe. Use ? to match one character and * to match zero or more characters. The field data type must be keyword, text, or wildcard.
  • nested: Array of entries objects. Nested conditions are required for excluding some Endpoint fields (refer to example below). Exceptions with nested conditions lists all Endpoint fields that require the nested type.

Yes

value

String

String[]

Field value or values:

  • String: When the type is match or wildcard.
  • String[]: When the type is match_any.

Yes, except when type is exists or list.

When you use list containers ("type": "list"), you cannot use other types in the entries array (match, match_any, exists, or nested).

For endpoint exceptions, you cannot create exception items based on excluded values ("operator": "excluded").

Example requests

edit

Example 1

Adds the maintenance-job process to the trusted-linux-processes exception container:

POST api/exception_lists/items
{
  "description": "Excludes the weekly maintenance job",
  "entries": [
    {
      "field": "process.name",
      "operator": "included",
      "type": "match",
      "value": "maintenance-job"
    }
  ],
  "list_id": "trusted-linux-processes",
  "name": "Linux maintenance job",
  "namespace_type": "single",
  "tags": [
    "in-house processes",
    "linux"
  ],
  "type": "simple"
}

Example 2

Adds hosts on which the maintenance process is allowed to run to the allowed-processes exception container:

POST api/exception_lists/items
{
  "comments": [
    {"comment": "Allows maintenance process to run on the specified machines"}
  ],
  "description": "Process allowlist",
  "entries": [
    {
      "field": "process.name",
      "operator": "included",
      "type": "match",
      "value": "maintenance"
    },
    { 
      "field": "host.name",
      "operator": "included",
      "type": "match_any",
      "value": [
        "liv-win-anf",
        "livw-win-mel",
        "linux-anfield"
      ]
    }
  ],
  "list_id": "allowed-processes",
  "item_id": "allow-process-on-machines",
  "name": "Host-process exclusions",
  "namespace_type": "single",
  "tags": [
    "hosts",
    "processes"
  ],
  "type": "simple"
}

Multiple array elements are evaluated using AND operators.

Example 3

Creates an endpoint exception item for files with the specified SHA-1 hash value on Windows OS:

POST api/exception_lists/items
{
  "_tags": [
    "endpoint", 
    "os:windows" 
  ],
  "comments": [
  ]
  "description": "File exception for Windows",
  "entries": [
    {
      "field": "file.hash.sha1",
      "operator": "included",
      "type": "match",
      "value": "27fb21cf5db95ffca43b234affa99becc4023b9d"
    }
  ],
  "item_id": "trusted-windows-file",
  "list_id": "endpoint-exception-container",
  "name": "Trusted Windows file",
  "namespace_type": "agnostic", 
  "tags": [
  ]
  "type": "simple"
}

Indicates this item is for endpoint rules.

Relevant OS.

Item accessible from all Kibana spaces.

Example 4

Associates the external-ip-excludes list container as an exception item to the trusted-IPs exception container:

POST api/exception_lists/items
{
  "description": "Uses the external-ip-container list to exclude trusted external IPs.",
  "entries": [
    {
      "field": "destination.ip",
      "list": {
        "id": "external-ip-excludes", 
        "type": "ip"
      },
      "operator": "included",
      "type": "list"
    }
  ],
  "list_id": "trusted-IPs", 
  "item_id": "external-IPs",
  "name": "Trusted external IPs",
  "namespace_type": "single",
  "tags": [
    "network",
    "trusted IPs"
  ],
  "type": "simple"
}

The list container that holds IP address list items.

The exception container’s ID.

Example 5

Adds an exception for nested Endpoint fields:

POST api/exception_lists/items
{
  "description": "Excludes all processes signed by Trusted Signer, Inc.",
  "entries": [
    {
      "field": "process.Ext.code_signature",
      "type": "nested",
      "entries": [
        {
          "field": "trusted",
          "type": "match",
          "operator": "included",
          "value": "true"
        },
        {
          "field": "subject_name",
          "type": "match",
          "operator": "included",
          "value": "Trusted Signer, Inc."
        }
      ]
    }
  ],
  "list_id": "trusted-self-signed-processes",
  "name": "In-house processes",
  "namespace_type": "single",
  "tags": [
    "in-house processes",
    "linux"
  ],
  "type": "simple"
}

Response code

edit
200
Indicates a successful call.

Response payload

edit
{
  "_tags": [],
  "comments": [
    {
      "comment": "Allows maintenance process to run on the specified machines",
      "created_at": "2020-07-14T08:36:33.172Z",
      "created_by": "elastic",
      "id": "f6c61b4d-31dd-4a5d-8c73-f64787d03b4d"
    }
  ],
  "created_at": "2020-07-14T08:36:33.172Z",
  "created_by": "elastic",
  "description": "Process allowlist",
  "entries": [
    {
      "field": "process.name",
      "operator": "included",
      "type": "match",
      "value": "maintenance"
    },
    {
      "field": "host.name",
      "operator": "included",
      "type": "match_any",
      "value": [
        "liv-win-anf",
        "livw-win-mel",
        "linux-anfield"
      ]
    }
  ],
  "id": "1f4d38b0-c5ad-11ea-a3d8-a5b753aeeb9e",
  "item_id": "allow-process-on-machines",
  "list_id": "allowed-processes",
  "name": "Host-process exclusions",
  "namespace_type": "single",
  "tags": [
    "hosts",
    "processes"
  ],
  "tie_breaker_id": "bb04f1c7-2537-47c1-aaca-40a7c8f771d3",
  "type": "simple",
  "updated_at": "2020-07-14T08:36:33.339Z",
  "updated_by": "elastic"
}