Create rule exception items

POST /api/detection_engine/rules/{id}/exceptions

Api key auth Basic auth

Spaces method and path for this operation:

post /s/{space_id}/api/detection_engine/rules/{id}/exceptions

Refer to Spaces for more information.

Create exception items that apply to a single detection rule.

Path parameters

id string(uuid) Required

Detection rule's identifier

application/json

Body Required

Rule exception items.

items array[object] Required
Hide items attributes Show items attributes object
- comments array[object]
  Hide comments attribute Show comments attribute object
  
  comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- description string Required
  
  Describes the exception list.
- entries array[object] Required
  Any of:
  Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryList object Security_Exceptions_API_ExceptionListItemEntryExists object Security_Exceptions_API_ExceptionListItemEntryNested object Security_Exceptions_API_ExceptionListItemEntryMatchWildcard object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  list object Required
  
  Hide list attributes Show list attributes object
  
  id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
  
  type string Required
  
  Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
  
  keyword: Many ECS fields are Elasticsearch keywords
  
  ip: IP addresses
  
  ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
  
  Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Hide attributes Show attributes
  
  entries array[object] Required
  
  At least 1 element.
  
  One of:
  Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryExists object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is exists.
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required Discriminator
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- expire_time string(date-time)
- item_id string(nonempty)
  
  Human readable string identifier, e.g. trusted-linux-processes
  
  Minimum length is 1.
- meta object
  
  Additional properties are allowed.
- name string(nonempty) Required
  
  Exception list name.
  
  Minimum length is 1.
- namespace_type string
  Determines whether the exception container 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.
  
  For endpoint artifacts, the namespace_type must always be agnostic. Space awareness for endpoint artifacts is enforced based on Elastic Defend policy assignments.
  Values are agnostic or single.
- os_types array[string]
  
  Use this field to specify the operating system.
  
  Values are linux, macos, or windows.
- tags array[string(nonempty)]
  
  String array containing words and phrases to help categorize exception items.
  
  Minimum length of each is 1.
- type string Required
  
  Value is simple.

Responses

200 application/json

Successful response
Hide response attributes Show response attributes object
- _version string
  
  The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.
- comments array[object] Required
  
  Array of comment fields:
  
  comment (string): Comments about the exception item.
  
  Hide comments attributes Show comments attributes object
  
  comment string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  created_at string(date-time) Required
  
  Autogenerated date of object creation.
  
  created_by string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  id string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  updated_at string(date-time)
  
  Autogenerated date of last object update.
  
  updated_by string(nonempty)
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- created_at string(date-time) Required
  
  Autogenerated date of object creation.
- created_by string Required
  
  Autogenerated value - user that created object.
- description string Required
  
  Describes the exception list.
- entries array[object] Required
  
  Any of:
  Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryList object Security_Exceptions_API_ExceptionListItemEntryExists object Security_Exceptions_API_ExceptionListItemEntryNested object Security_Exceptions_API_ExceptionListItemEntryMatchWildcard object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  list object Required
  
  Hide list attributes Show list attributes object
  
  id string(nonempty) Required
  
  Value list's identifier.
  
  Minimum length is 1.
  
  type string Required
  
  Specifies the Elasticsearch data type of excludes the list container holds. Some common examples:
  
  keyword: Many ECS fields are Elasticsearch keywords
  
  ip: IP addresses
  
  ip_range: Range of IP addresses (supports IPv4, IPv6, and CIDR notation)
  
  Values are binary, boolean, byte, date, date_nanos, date_range, double, double_range, float, float_range, geo_point, geo_shape, half_float, integer, integer_range, ip, ip_range, keyword, long, long_range, shape, short, or text.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  Hide attributes Show attributes
  
  entries array[object] Required
  
  At least 1 element.
  
  One of:
  Security_Exceptions_API_ExceptionListItemEntryMatch object Security_Exceptions_API_ExceptionListItemEntryMatchAny object Security_Exceptions_API_ExceptionListItemEntryExists object
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match.
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is match_any.
  
  value array[string(nonempty)] Required
  
  A string that does not contain only whitespace characters
  
  At least 1 element. Minimum length of each is 1.
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required
  
  Value is exists.
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  type string Required Discriminator
  
  Hide attributes Show attributes
  
  field string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
  
  operator string Required
  
  Values are excluded or included.
  
  type string Required Discriminator
  
  value string(nonempty) Required
  
  A string that does not contain only whitespace characters
  
  Minimum length is 1.
- expire_time string(date-time)
  
  The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions.
- id string(nonempty) Required
  
  Exception's identifier.
  
  Minimum length is 1.
- item_id string(nonempty) Required
  
  Human readable string identifier, e.g. trusted-linux-processes
  
  Minimum length is 1.
- list_id string(nonempty) Required
  
  The exception list's human-readable string identifier.
  
  For endpoint artifacts, use one of the following values:
  
  endpoint_list: Elastic Endpoint exception list
  
  endpoint_trusted_apps: Trusted applications list
  
  endpoint_trusted_devices: Trusted devices list
  
  endpoint_event_filters: Event filters list
  
  endpoint_host_isolation_exceptions: Host isolation exceptions list
  
  endpoint_blocklists: Blocklists list
  
  Minimum length is 1.
- meta object
  
  Additional properties are allowed.
- name string(nonempty) Required
  
  Exception list name.
  
  Minimum length is 1.
- namespace_type string Required
  
  Determines whether the exception container 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.
  
  For endpoint artifacts, the namespace_type must always be agnostic. Space awareness for endpoint artifacts is enforced based on Elastic Defend policy assignments.
  
  Values are agnostic or single.
- os_types array[string]
  
  Use this field to specify the operating system.
  
  Values are linux, macos, or windows.
- tags array[string(nonempty)]
  
  String array containing words and phrases to help categorize exception items.
  
  Minimum length of each is 1.
- tie_breaker_id string Required
  
  Field used in search to ensure all containers are sorted and returned correctly.
- type string Required
  
  Value is simple.
- updated_at string(date-time) Required
  
  Autogenerated date of last object update.
- updated_by string Required
  
  Autogenerated value - user that last updated object.
400 application/json

Invalid input data response
One of:
Security_Exceptions_API_PlatformErrorResponse object Security_Exceptions_API_SiemErrorResponse object
Hide attributes Show attributes

error string Required

message string Required

statusCode integer Required
Hide attributes Show attributes

message string Required

status_code integer Required
401 application/json

Unsuccessful authentication response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
403 application/json

Not enough privileges response
Hide response attributes Show response attributes object
- error string Required
- message string Required
- statusCode integer Required
500 application/json

Internal server error response
Hide response attributes Show response attributes object
- message string Required
- status_code integer Required

POST /api/detection_engine/rules/{id}/exceptions

curl \
 --request POST 'https://localhost:5601/api/detection_engine/rules/330bdd28-eedf-40e1-bed0-f10176c7f9e0/exceptions' \
 --header "Authorization: $API_KEY" \
 --header "Content-Type: application/json" \
 --data '"{\n  \"items\": [\n    {\n      \"description\": \"This is a sample detection type exception item.\",\n      \"entries\": [\n        {\n          \"field\": \"actingProcess.file.signer\",\n          \"operator\": \"excluded\",\n          \"type\": \"exists\"\n        },\n        {\n          \"field\": \"host.name\",\n          \"operator\": \"included\",\n          \"type\": \"match_any\",\n          \"value\": [\n            \"saturn\",\n            \"jupiter\"\n          ]\n        }\n      ],\n      \"item_id\": \"simple_list_item\",\n      \"list_id\": \"simple_list\",\n      \"name\": \"Sample Exception List Item\",\n      \"namespace_type\": \"single\",\n      \"os_types\": [\n        \"linux\"\n      ],\n      \"tags\": [\n        \"malware\"\n      ],\n      \"type\": \"simple\"\n    }\n  ]\n}"'

Request example

{
  "items": [
    {
      "description": "This is a sample detection type exception item.",
      "entries": [
        {
          "field": "actingProcess.file.signer",
          "operator": "excluded",
          "type": "exists"
        },
        {
          "field": "host.name",
          "operator": "included",
          "type": "match_any",
          "value": [
            "saturn",
            "jupiter"
          ]
        }
      ],
      "item_id": "simple_list_item",
      "list_id": "simple_list",
      "name": "Sample Exception List Item",
      "namespace_type": "single",
      "os_types": [
        "linux"
      ],
      "tags": [
        "malware"
      ],
      "type": "simple"
    }
  ]
}

Response examples (200)

[
  {
    "_version": "WzQsMV0=",
    "comments": [],
    "created_at": "2025-01-07T20:07:33.119Z",
    "created_by": "elastic",
    "description": "This is a sample detection type exception item.",
    "entries": [
      {
        "field": "actingProcess.file.signer",
        "operator": "excluded",
        "type": "exists"
      },
      {
        "field": "host.name",
        "operator": "included",
        "type": "match_any",
        "value": [
          "saturn",
          "jupiter"
        ]
      }
    ],
    "id": "71a9f4b2-c85c-49b4-866f-c71eb9e67da2",
    "item_id": "simple_list_item",
    "list_id": "simple_list",
    "name": "Sample Exception List Item",
    "namespace_type": "single",
    "os_types": [
      "linux"
    ],
    "tags": [
      "malware"
    ],
    "tie_breaker_id": "09434836-9db9-4942-a234-5a9268e0b34c",
    "type": "simple",
    "updated_at": "2025-01-07T20:07:33.119Z",
    "updated_by": "elastic"
  }
]

Response examples (400)

{
  "error": "Bad Request",
  "message": "Invalid request payload JSON format",
  "statusCode": 400
}

{
  "error": "Bad Request",
  "message": "[request params]: id: Invalid uuid",
  "statusCode": 400
}

Response examples (401)

{
  "error": "Unauthorized",
  "message": "[security_exception\\n\\tRoot causes:\\n\\t\\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]",
  "statusCode": 401
}

Response examples (403)

{
  "message": "Unable to create exception-list",
  "status_code": 403
}

Response examples (500)

{
  "message": "Internal Server Error",
  "status_code": 500
}