Security Exceptions API

Update an exception list

Changed on

Spaces method and path for this operation:

<div><span class="operation-verb put">put</span>&nbsp;<span class="operation-path">/s/{space_id}/api/exception_lists</span></div>

Refer to Spaces for more information.

Update an exception list using the id or list_id field.

put/api/exception_lists

Request

  • Base URL
    https://localhost:5601
  • URL
    https://localhost:5601/api/exception_lists
  • Auth
    • API key in header Authorization
    • or HTTP basic

Request body

_versionstring

The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.

descriptionstring required

Describes the exception list.

idstring nonempty

Exception list's identifier.

list_idstring nonempty

The exception list's human-readable string identifier.

For endpoint artifacts, use one of the following values:

  • endpoint_list: Elastic Endpoint exceptions 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: Blocklist
metaSecurityExceptionsAPIExceptionListMeta

Placeholder for metadata about the list container.

namestring required

The name of the exception list.

namespace_type'agnostic' | 'single'

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.

os_typesSecurityExceptionsAPIExceptionListOsType[]

Use this field to specify the operating system. Only enter one value.

tagsstring[]

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

type'detection' | 'rule_default' | 'endpoint' | 'endpoint_trusted_apps' | 'endpoint_trusted_devices' | 'endpoint_events' | 'endpoint_host_isolation_exceptions' | 'endpoint_blocklists' | 'endpoint_custom_yara_signatures' required

The type of exception list to be created. Different list types may denote where they can be utilized.

versioninteger

The document version, automatically increasd on updates.

Example request

{
  "description": "Different description",
  "list_id": "simple_list",
  "name": "Updated exception list name",
  "os_types": [
    "linux"
  ],
  "tags": [
    "draft malware"
  ],
  "type": "detection"
}

Response

Successful response

_versionstring

The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version.

created_atstring date-time required

Autogenerated date of object creation.

created_bystring required

Autogenerated value - user that created object.

descriptionstring required

Describes the exception list.

idstring nonempty required

Exception list's identifier.

immutableboolean required
list_idstring nonempty required

The exception list's human-readable string identifier.

For endpoint artifacts, use one of the following values:

  • endpoint_list: Elastic Endpoint exceptions 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: Blocklist
metaSecurityExceptionsAPIExceptionListMeta

Placeholder for metadata about the list container.

namestring required

The name of the exception list.

namespace_type'agnostic' | 'single' 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.

os_typesSecurityExceptionsAPIExceptionListOsType[]

Use this field to specify the operating system. Only enter one value.

tagsstring[]

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

tie_breaker_idstring required

Field used in search to ensure all containers are sorted and returned correctly.

type'detection' | 'rule_default' | 'endpoint' | 'endpoint_trusted_apps' | 'endpoint_trusted_devices' | 'endpoint_events' | 'endpoint_host_isolation_exceptions' | 'endpoint_blocklists' | 'endpoint_custom_yara_signatures' required

The type of exception list to be created. Different list types may denote where they can be utilized.

updated_atstring date-time required

Autogenerated date of last object update.

updated_bystring required

Autogenerated value - user that last updated object.

versioninteger required

The document version, automatically increasd on updates.

Example response

{
  "description": "This list tracks allowlisted values.",
  "id": "9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85",
  "list_id": "simple_list",
  "name": "My exception list"
}

Changes

  • 707a2918b22bRevision changes
    • warning

      added the new endpoint_custom_yara_signatures enum value to the response property for the response status

    • info

      added the new endpoint_custom_yara_signatures enum value to the request property