« Create exception container Create shared exception list »

› › ›

Create exception item

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
`expire_time`	String	The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.	No
`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"
}

« Create exception container Create shared exception list »

Create exception item