IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Create default exception list for a rule Index endpoint »

› › ›

Create exceptions for a rule

edit

Create exceptions for a rule

edit

Adds specified exception items to a rule’s default exception list. A default exception list contains exceptions that are associated with a single rule, as opposed to a shared exception list, which contains exceptions that are associated with multiple rules.

If a default exception list doesn’t exist for a rule, one is automatically created when you try to add an exception to it.

For more information about creating exceptions that are used by multiple rules, refer to Create exceptions used by multiple rules. For more information about creating exception items from a list, such as a list of IP addresses or hosts names, refer to Lists API.

Request URL

edit

POST <kibana host>:<port>/api/detection_engine/rules/<id>/exceptions

Allows you to create exception items that are associated with a specified rule id.

URL query parameters

edit

Name	Type	Description	Required
`id`	String	Specify the rule ID.	Yes.

Request body

edit

A JSON object with an array of exception items, where each exception item has the required fields.

Name	Type	Description	Required
`items`	String[]	Specify an array of exception list items to create.	Yes
`comments`	Object[]	Array of `comment` fields. Default value is [] (empty): `comment` (string): Comments about the exception item.	No
`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. Default value is `single`.	No
`os_types`	String[]	Defines the OS on which the exception is implemented. Valid values are: `os:windows`: Windows OS `os:linux`: Linux OS `os:macos`: Mac OS Default value is `[]` (empty).	No
`tags`	String[]	String array containing words and phrases to help categorize exception items.	No
`type`	String	Exception query type, must be `simple`.	Yes

`entries` schema

edit

Name	Type	Description	Required
`field`	String	The source event field used to define the exception. Cannot be an empty string.	Yes
`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

POST api/detection_engine/rules/<id>/exceptions
{
  "items": [
    {
      "description": "Excludes the weekly maintenance job",
      "entries": [
        {
          "field": "process.name",
          "operator": "included",
          "type": "match",
          "value": "maintenance-job"
        }
        ],
      "name": "Linux maintenance job",
      "tags": [
          "in-house processes",
          "linux"
        ],
      "type": "simple"
    }
        ]
}

Response code

edit

200: Indicates a successful call.

Response payload

edit

The returned exception item.

Example response:

{
  "body": [
    {
          "comments": [],
          "created_by": "elastic",
          "description": "Exception item for rule default exception list",
          "entries": [
            {
              "field": "host.name",
              "operator": "included",
              "type": "match",
              "value": "foo",
            },
          ],
          "name": "Sample exception item",
          "list_id": "e6c44050-c661-11ea-bab5-9d6ae015701b",
          "namespace_type": "single",
          "os_types": [],
          "tags": [],
          "type": "simple",
          "updated_by": "elastic"
        }
  ]
}

« Create default exception list for a rule Index endpoint »

Create exceptions for a rule

Create exceptions for a rule

Request URL

URL query parameters

Request body

entries schema

Example requests

Response code

Response payload

`entries` schema