-
- Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/api/detection_engine/signals/assignees:
post:
description: |
@@ -18263,32 +18402,81 @@ paths:
$ref: '#/components/examples/Security_Detections_API_SetAlertAssigneesBodyRemove'
schema:
$ref: '#/components/schemas/Security_Detections_API_SetAlertAssigneesBody'
+ description: User profile IDs to add or remove on each listed alert document ID.
required: true
responses:
'200':
content:
- application/ndjson:
+ application/json:
+ description: Elasticsearch update by query or update by IDs response
examples:
add:
value:
- batches: 1,
- deleted: 0,
+ batches: 1
+ deleted: 0
failures: []
- noops: 0,
- requests_per_second: '-1,'
+ noops: 0
+ requests_per_second: -1
retries:
- - bulk: 0,
- - search: 0
- throttled_millis: 0,
- throttled_until_millis: 0,
- timed_out: false,
- took: 76,
- total: 1,
- updated: 1,
- version_conflicts: 0,
+ bulk: 0
+ search: 0
+ throttled_millis: 0
+ throttled_until_millis: 0
+ timed_out: false
+ took: 76
+ total: 1
+ updated: 1
+ version_conflicts: 0
description: Indicates a successful call.
'400':
- description: Invalid request.
+ content:
+ application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].ids: at least one alert id is required to update assignees'
+ statusCode: 400
+ schema:
+ oneOf:
+ - $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
+ - $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
+ description: Invalid input data response
+ '401':
+ content:
+ application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
+ schema:
+ $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
+ description: Unsuccessful authentication response
+ '403':
+ content:
+ application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: API [POST /api/detection_engine/signals/assignees] is unauthorized for the current user, this action is granted by the Kibana Security Solution privileges for cases and detections
+ statusCode: 403
+ schema:
+ $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
+ description: Not enough privileges response
+ '500':
+ content:
+ application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
+ schema:
+ $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
+ description: Internal server error response
summary: Assign and unassign users from detection alerts
tags:
- Security Detections API
@@ -18380,6 +18568,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: 'Failed to parse search request: unknown query clause in bool filter'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -18388,12 +18582,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -18507,6 +18712,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].signal_ids: at least one alert id is required to update status'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -18515,12 +18726,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -18539,7 +18761,7 @@ paths:
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- And tags to detection alerts, and remove them from alerts.
+ Add tags to detection alerts, and remove them from alerts, by alert IDs or a query, in a single request.
> info
> You cannot add and remove the same alert tag in the same request.
operationId: SetAlertTags
@@ -18585,6 +18807,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].tags: cannot add and remove the same tag in a single request'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -18593,12 +18821,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -22898,7 +23137,10 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: |
+ `single` deletes the list in the current Kibana space; `agnostic` deletes a global list. Must match the
+ list you are removing when using `list_id` or `id`.
+ examples:
agnostic:
value: agnostic
single:
@@ -23026,7 +23268,10 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: |
+ When `single`, the list is resolved in the current Kibana space. When `agnostic`, the list is a global
+ (space-agnostic) container. Required for looking up the correct list when `list_id` is not unique.
+ examples:
agnostic:
value: agnostic
single:
@@ -23146,6 +23391,18 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ createDetection:
+ value:
+ description: This is a sample detection type exception list.
+ list_id: simple_list
+ name: Sample Detection Exception List
+ namespace_type: single
+ os_types:
+ - linux
+ tags:
+ - malware
+ type: detection
schema:
example:
description: This is a sample detection type exception list.
@@ -23352,6 +23609,18 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ fullReplace:
+ value:
+ description: Different description
+ list_id: simple_list
+ name: Updated exception list name
+ os_types:
+ - linux
+ tags:
+ - draft
+ - malware
+ type: detection
schema:
example:
description: Different description
@@ -23500,12 +23769,14 @@ paths:
Duplicate an existing exception list.
operationId: DuplicateExceptionList
parameters:
- - in: query
+ - description: The `list_id` of the existing exception list to copy (source list).
+ in: query
name: list_id
required: true
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: Scope in which the source list is defined (`single` = current space, `agnostic` = all spaces).
+ examples:
agnostic:
value: agnostic
single:
@@ -23597,14 +23868,19 @@ paths:
examples:
notFound:
value:
- message": 'exception list id: "foo" does not exist'
- status_code": 404
+ message: 'exception list id: "foo" does not exist'
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse'
description: Exception list not found
'405':
content:
application/json:
+ examples:
+ notAllowed:
+ value:
+ message: 'Cannot duplicate: list is immutable or the operation is not allowed in this state'
+ status_code: 405
schema:
$ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
description: Exception list to duplicate not found response
@@ -23637,17 +23913,21 @@ paths:
Export an exception list and its associated items to an NDJSON file.
operationId: ExportExceptionList
parameters:
- - in: query
+ - description: Exception list's internal `id` (UUID) returned on create; use with `list_id` and `namespace_type` for an unambiguous target.
+ in: query
name: id
required: true
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListId'
- - in: query
+ - description: Human-readable `list_id` of the exception list to export, as shown in the UI and API responses.
+ in: query
name: list_id
required: true
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: |
+ `single` exports a list in the current Kibana space; `agnostic` exports a global (space-agnostic) list.
+ examples:
agnostic:
value: agnostic
single:
@@ -23964,6 +24244,10 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ ndjsonUpload:
+ value:
+ file: exception_lists.ndjson
schema:
type: object
properties:
@@ -24039,6 +24323,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: Multipart part `file` is required and must contain a valid .ndjson exception list export
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse'
@@ -24109,7 +24399,9 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemHumanId'
- - examples:
+ - description: |
+ `single` deletes the item in the current Kibana space; `agnostic` deletes an item in a space-agnostic list. Must match the list that owns the item.
+ examples:
agnostic:
value: agnostic
single:
@@ -24161,11 +24453,13 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob'''
+ statusCode: 400
schema:
- example:
- error: Bad Request
- message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob'''
- statusCode: 400
oneOf:
- $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse'
- $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
@@ -24245,7 +24539,10 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemHumanId'
- - examples:
+ - description: |
+ `single` fetches the item in the current space; `agnostic` fetches a global (space-agnostic) item. Must
+ match how the list was created.
+ examples:
agnostic:
value: agnostic
single:
@@ -24375,6 +24672,23 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ simpleItem:
+ value:
+ description: This is a sample detection type exception item.
+ entries:
+ - field: actingProcess.file.signer
+ operator: excluded
+ type: exists
+ item_id: simple_list_item
+ list_id: simple_list
+ name: Sample Exception List Item
+ namespace_type: single
+ os_types:
+ - linux
+ tags:
+ - malware
+ type: simple
schema:
oneOf:
- $ref: '#/components/schemas/Security_Exceptions_API_CreateExceptionListItemGeneric'
@@ -24660,6 +24974,14 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ updateItem:
+ value:
+ description: Updated description
+ id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2
+ name: Updated name
+ namespace_type: single
+ type: simple
schema:
oneOf:
- $ref: '#/components/schemas/Security_Exceptions_API_UpdateExceptionListItemGeneric'
@@ -24825,7 +25147,9 @@ paths:
items:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionNamespaceType'
type: array
- - in: query
+ - description: |
+ Free-text search term applied to exception list item fields (for example a hostname or file path fragment).
+ in: query
name: search
required: false
schema:
@@ -25017,7 +25341,10 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: |
+ `single` returns summary for a list in the current space; `agnostic` for a space-agnostic list. Must
+ line up with `id` / `list_id` used to look up the list.
+ examples:
agnostic:
value: agnostic
single:
@@ -57477,7 +57804,8 @@ paths:
> When you delete a list, all of its list items are also deleted.
operationId: DeleteList
parameters:
- - in: query
+ - description: Value list identifier to delete, including all of its list items.
+ in: query
name: id
required: true
schema:
@@ -57598,7 +57926,8 @@ paths:
Get the details of a value list using the list ID.
operationId: ReadList
parameters:
- - in: query
+ - description: Value list identifier (`id`) returned when the list was created.
+ in: query
name: id
required: true
schema:
@@ -57705,6 +58034,11 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ patchName:
+ value:
+ id: ip_list
+ name: Bad ips list - UPDATED
schema:
example:
id: ip_list
@@ -58025,6 +58359,12 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ replaceList:
+ value:
+ description: Latest list of bad ips
+ id: ip_list
+ name: Bad ips - updated
schema:
example:
description: Latest list of bad ips
@@ -58321,6 +58661,10 @@ paths:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -58332,6 +58676,11 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: 'Unable to delete value list data streams: invalid or missing index metadata'
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
@@ -58352,12 +58701,23 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: API [DELETE /api/lists/index] is not authorized; lists-all (or equivalent) is required to delete data streams
+ statusCode: 403
schema:
$ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
description: Not enough privileges response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: The value list data stream was not found in this space
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: List data stream not found response
@@ -58392,6 +58752,11 @@ paths:
'200':
content:
application/json:
+ examples:
+ bothExist:
+ value:
+ list_index: true
+ list_item_index: true
schema:
type: object
properties:
@@ -58406,6 +58771,11 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: Unable to read value list data stream status for this space
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
@@ -58426,12 +58796,23 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: API [GET /api/lists/index] is not authorized; list read permissions are required
+ statusCode: 403
schema:
$ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
description: Not enough privileges response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: Value list backing indices were not found for this space
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: List data stream(s) not found response
@@ -58454,19 +58835,28 @@ paths:
name: product_name
post:
deprecated: true
- description: |-
+ description: |
**Spaces method and path for this operation:**
post/s/{space_id}/api/lists/index
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- Create `.lists` and `.items` data streams in the relevant space.
+ **DEPRECATED.** `deprecated: true` is set on this operation. Value list backing data streams for the space
+ are now created as part of supported workflows; calling this explicitly is rarely required.
+ **WARNING:** Do not use for new integrations. Prefer the UI or the list and list-item APIs after confirming
+ indices exist with `GET /api/lists/index`.
+
+ Creates the `.lists` and `.items` data streams in the current Kibana space.
operationId: CreateListIndex
responses:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -58478,6 +58868,11 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: Indices exist but the request could not be completed for the current space. Check that Elasticsearch and Kibana privileges allow index creation for lists.
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
@@ -58499,6 +58894,12 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: API [POST /api/lists/index] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]
+ statusCode: 403
schema:
$ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
description: Not enough privileges response
@@ -58796,10 +59197,12 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ changeValue:
+ value:
+ id: pd1WRJQBs4HAK3VQeHFI
+ value: 255.255.255.255
schema:
- example:
- id: pd1WRJQBs4HAK3VQeHFI
- value: 255.255.255.255
type: object
properties:
_version:
@@ -59100,10 +59503,15 @@ paths:
requestBody:
content:
application/json:
- example:
- id: ip_item
- value: 255.255.255.255
+ examples:
+ fullReplace:
+ value:
+ id: ip_item
+ value: 255.255.255.255
schema:
+ example:
+ id: ip_item
+ value: 255.255.255.255
type: object
properties:
_version:
@@ -59228,6 +59636,12 @@ paths:
'200':
content:
application/ndjson:
+ examples:
+ ipLines:
+ value: |
+ 127.0.0.1
+ 127.0.0.2
+ 127.0.0.3
schema:
description: A `.txt` file containing list items from the specified list
example: |
@@ -59283,6 +59697,11 @@ paths:
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: 'list id: "unknown_list" not found'
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: List not found response
@@ -59315,7 +59734,8 @@ paths:
Get all value list items in the specified list.
operationId: FindListItems
parameters:
- - in: query
+ - description: Parent value list's `id` to page through items for.
+ in: query
name: list_id
required: true
schema:
@@ -59353,7 +59773,9 @@ paths:
- asc
example: asc
type: string
- - in: query
+ - description: |
+ Opaque cursor returned in a previous response; pass it to continue listing from the next page. Omit on the first request.
+ in: query
name: cursor
required: false
schema:
@@ -59518,6 +59940,10 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ ipLinesFile:
+ value:
+ file: list_values.txt
schema:
type: object
properties:
@@ -59599,6 +60025,11 @@ paths:
'409':
content:
application/json:
+ examples:
+ conflict:
+ value:
+ message: List with the specified list_id does not exist, create the list or fix list_id to import to an existing one
+ status_code: 409
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: List with specified list_id does not exist response
@@ -59621,6 +60052,16 @@ paths:
name: product_name
/api/lists/privileges:
get:
+ description: |
+ **Spaces method and path for this operation:**
+
+
get/s/{space_id}/api/lists/privileges
+
+ Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
+
+ Returns the caller's authentication state and the Elasticsearch `cluster`, `index`, and `application`
+ privileges for `.lists` and `.items` data streams in the current Kibana space. Use this to decide which list
+ APIs (`read` vs `all` operations) are available before you create or import lists.
operationId: ReadListPrivileges
responses:
'200':
@@ -59711,6 +60152,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: 'Unable to resolve list privileges: invalid or missing space context for this request'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
@@ -59757,12 +60204,6 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
- description: |-
- **Spaces method and path for this operation:**
-
-
get/s/{space_id}/api/lists/privileges
-
- Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/api/maintenance_window:
post:
description: |-
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
index c02bf1e4c6adb..8cd8c06a4ca1d 100644
--- a/oas_docs/output/kibana.yaml
+++ b/oas_docs/output/kibana.yaml
@@ -17186,11 +17186,25 @@ paths:
name: product_name
/api/detection_engine/index:
delete:
+ description: |
+ **Spaces method and path for this operation:**
+
+
delete/s/{space_id}/api/detection_engine/index
+
+ Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
+
+ Permanently deletes the Elastic Security alerts backing index in the current space, including the alerts
+ stored in it. Use with caution; prefer lifecycle policies or the UI when available.
+ Call `GET /api/detection_engine/index` first to confirm the index that will be removed.
operationId: DeleteAlertsIndex
responses:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -17202,24 +17216,45 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ message: API [DELETE /api/detection_engine/index] is unauthorized for the current user. The user needs alerts management permissions for the space.
+ status_code: 403
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Not enough permissions response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: The Elastic Security alerts index to delete was not found.
+ status_code: 404
schema:
- type: string
+ $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Index does not exist response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -17229,13 +17264,17 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
- description: |-
+ get:
+ description: |
**Spaces method and path for this operation:**
-
delete/s/{space_id}/api/detection_engine/index
+
get/s/{space_id}/api/detection_engine/index
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- get:
+
+ Returns the backing Elasticsearch index for Elastic Security detection alerts in the current space, and
+ whether its mapping is outdated. Use this to verify that an alert index is provisioned before creating
+ or running rules that write alerts to it.
operationId: ReadAlertsIndex
responses:
'200':
@@ -17261,24 +17300,45 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ message: API [GET /api/detection_engine/index] is unauthorized for the current user. Check Security and Kibana feature privileges (detection engine / alerts) for the space.
+ status_code: 403
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Not enough permissions response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: Elastic Security alert index is not found for the current space.
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Not found
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -17288,12 +17348,6 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
- description: |-
- **Spaces method and path for this operation:**
-
-
get/s/{space_id}/api/detection_engine/index
-
- Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
post:
description: |
**Spaces method and path for this operation:**
@@ -17310,6 +17364,10 @@ paths:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -17321,24 +17379,45 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ message: API [POST /api/detection_engine/index] is unauthorized for the current user. The user must be able to create indices for the Elastic Security solution.
+ status_code: 403
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Not enough permissions response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: A prerequisite resource required to create the alerts index was not found.
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Not found
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -17416,12 +17495,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -17466,6 +17556,36 @@ paths:
'200':
content:
application/json:
+ examples:
+ deletedRule:
+ summary: Response shape after a rule is deleted
+ value:
+ actions: []
+ created_at: '2020-02-03T11:19:04.259Z'
+ created_by: elastic
+ description: Process started by MS Office program in user folder
+ enabled: false
+ false_positives: []
+ from: now-4200s
+ id: c41d170b-8ba6-4de6-b8ec-76440a35ace3
+ immutable: false
+ interval: 1h
+ language: kuery
+ max_signals: 100
+ name: MS Office child process
+ query: event.action:Process*
+ references: []
+ risk_score: 50
+ rule_id: process_started_by_ms_office_user_folder
+ severity: low
+ tags:
+ - tag
+ throttle: null
+ to: now
+ type: query
+ updated_at: '2020-02-03T11:19:04.462Z'
+ updated_by: elastic
+ version: 3
schema:
$ref: '#/components/schemas/Security_Detections_API_RuleResponse'
description: Indicates a successful call.
@@ -19706,6 +19826,13 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ exportByRuleIds:
+ summary: Request body to export a subset of rules
+ value:
+ objects:
+ - rule_id: 343580b5-c811-447c-8d2d-2ccf052c6900
+ - rule_id: 2938c9fa-53eb-4c04-b79c-33cbf041b18d
schema:
nullable: true
type: object
@@ -19727,6 +19854,12 @@ paths:
'200':
content:
application/ndjson:
+ examples:
+ sampleNdjson:
+ value: |
+ {"rule_id":"343580b5-c811-447c-8d2d-2ccf052c6900","name":"Example rule","type":"query","enabled":true}
+ {"exception_list":true}
+ {"export_summary":{"total_rules":1,"exceptions_count":0}}
schema:
description: |
An `.ndjson` file containing the returned rules.
@@ -19767,7 +19900,11 @@ paths:
Retrieve a paginated list of detection rules. By default, the first page is returned, with 20 results per page.
operationId: FindRules
parameters:
- - in: query
+ - description: |
+ List of `alert.attributes` field names to return for each rule (for example `name`, `enabled`).
+ If omitted, the default field set is returned. Repeat the parameter to pass multiple field names, or
+ use comma-separated values when supported by your client.
+ in: query
name: fields
required: false
schema:
@@ -20010,6 +20147,11 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ rulesFile:
+ summary: Multipart part containing a rule export
+ value:
+ file: rules_import.ndjson
schema:
type: object
properties:
@@ -20121,6 +20263,30 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ addItems:
+ value:
+ 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
schema:
example:
items:
@@ -20393,6 +20559,16 @@ paths:
name: product_name
/api/detection_engine/rules/preview:
post:
+ description: |
+ **Spaces method and path for this operation:**
+
+
-
- Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/api/detection_engine/signals/assignees:
post:
description: |
@@ -20507,32 +20725,81 @@ paths:
$ref: '#/components/examples/Security_Detections_API_SetAlertAssigneesBodyRemove'
schema:
$ref: '#/components/schemas/Security_Detections_API_SetAlertAssigneesBody'
+ description: User profile IDs to add or remove on each listed alert document ID.
required: true
responses:
'200':
content:
- application/ndjson:
+ application/json:
+ description: Elasticsearch update by query or update by IDs response
examples:
add:
value:
- batches: 1,
- deleted: 0,
+ batches: 1
+ deleted: 0
failures: []
- noops: 0,
- requests_per_second: '-1,'
+ noops: 0
+ requests_per_second: -1
retries:
- - bulk: 0,
- - search: 0
- throttled_millis: 0,
- throttled_until_millis: 0,
- timed_out: false,
- took: 76,
- total: 1,
- updated: 1,
- version_conflicts: 0,
+ bulk: 0
+ search: 0
+ throttled_millis: 0
+ throttled_until_millis: 0
+ timed_out: false
+ took: 76
+ total: 1
+ updated: 1
+ version_conflicts: 0
description: Indicates a successful call.
'400':
- description: Invalid request.
+ content:
+ application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].ids: at least one alert id is required to update assignees'
+ statusCode: 400
+ schema:
+ oneOf:
+ - $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
+ - $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
+ description: Invalid input data response
+ '401':
+ content:
+ application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
+ schema:
+ $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
+ description: Unsuccessful authentication response
+ '403':
+ content:
+ application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: API [POST /api/detection_engine/signals/assignees] is unauthorized for the current user, this action is granted by the Kibana Security Solution privileges for cases and detections
+ statusCode: 403
+ schema:
+ $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
+ description: Not enough privileges response
+ '500':
+ content:
+ application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
+ schema:
+ $ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
+ description: Internal server error response
summary: Assign and unassign users from detection alerts
tags:
- Security Detections API
@@ -20549,13 +20816,21 @@ paths:
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- Finalize successful migrations of detection alerts. This replaces the original index's alias with the successfully migrated index's alias.
- The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion,
- finalize it.
+ **DEPRECATED.** Completes a legacy alert index migration. Do not automate against this in new code.
+ **WARNING:** Finalizing swaps read aliases; confirm the migration has finished successfully before calling.
+
+ Finalize successful migrations of detection alerts. This replaces the original index's alias with the
+ successfully migrated index's alias. The endpoint is idempotent, so you can poll until a migration
+ finishes and then call this operation once.
operationId: FinalizeAlertsMigration
requestBody:
content:
application/json:
+ examples:
+ oneMigration:
+ value:
+ migration_ids:
+ - 924f7c50-505f-11eb-ae0a-3fa2e626a51d
schema:
example:
migration_ids:
@@ -20595,6 +20870,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].migration_ids: at least one migration id is required to finalize'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -20603,12 +20884,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -20628,17 +20920,22 @@ paths:
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
- the migration process. A successful migration will result in both the old and new indices being present.
- As such, the old, orphaned index can (and likely should) be deleted.
+ **DEPRECATED.** Cleanup API for old migration artifacts. Do not add new call sites.
+ **WARNING:** This schedules deletions; ensure no production reads still point at the source index.
- While you can delete these indices manually,
- the endpoint accomplishes this task by applying a deletion policy to the relevant index, causing it to be deleted
- after 30 days. It also deletes other artifacts specific to the migration implementation.
+ Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
+ the migration process. A successful migration can leave both the old and new indices present, so the old
+ index may be deleted. While you can delete these indices manually, the endpoint applies a deletion policy
+ to the relevant index, causing it to be deleted after 30 days, and removes other migration-specific artifacts.
operationId: AlertsMigrationCleanup
requestBody:
content:
application/json:
+ examples:
+ cleanupMigrations:
+ value:
+ migration_ids:
+ - 924f7c50-505f-11eb-ae0a-3fa2e626a51d
schema:
example:
migration_ids:
@@ -20677,6 +20974,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].migration_ids: at least one migration id is required to run cleanup'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -20685,12 +20988,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -20709,8 +21023,12 @@ paths:
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- Initiate a migration of detection alerts.
- Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly.
+ **DEPRECATED.** Legacy API for on-demand reindexing of old `.siem-signals-*` alert indices. Do not build new
+ integrations; upgrade the Elastic Stack and rely on product-managed data lifecycle instead.
+ **WARNING:** Migrations can be resource intensive and should be planned during a maintenance window.
+
+ Initiate a migration of detection alerts. Migrations are initiated per index. The process is not destructive
+ and should not remove existing data, but it can consume significant cluster resources. Plan capacity accordingly.
operationId: CreateAlertsMigration
requestBody:
content:
@@ -20764,6 +21082,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].index: at least one index name is required to start a migration'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -20772,12 +21096,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -20790,14 +21125,19 @@ paths:
/api/detection_engine/signals/migration_status:
get:
deprecated: true
- description: |-
+ description: |
**Spaces method and path for this operation:**
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- Retrieve indices that contain detection alerts of a particular age, along with migration information for each of those indices.
+ **DEPRECATED.** This endpoint was used for historical `.siem-signals-*` index migration workflows. Do not use
+ for new automations; there is no supported replacement in this public API.
+ **WARNING:** Prefer upgrading through supported Elastic stack upgrades rather than ad-hoc index migrations.
+
+ Retrieves indices that contain detection alerts of a particular age, along with migration information for
+ each of those indices.
operationId: ReadAlertsMigrationStatus
parameters:
- description: Maximum age of qualifying detection alerts
@@ -20852,6 +21192,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request query].from: expected date-math, received null'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -20860,12 +21206,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -20960,6 +21317,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: 'Failed to parse search request: unknown query clause in bool filter'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -20968,12 +21331,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -21087,6 +21461,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].signal_ids: at least one alert id is required to update status'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -21095,12 +21475,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -21119,7 +21510,7 @@ paths:
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- And tags to detection alerts, and remove them from alerts.
+ Add tags to detection alerts, and remove them from alerts, by alert IDs or a query, in a single request.
> info
> You cannot add and remove the same alert tag in the same request.
operationId: SetAlertTags
@@ -21165,6 +21556,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request body].tags: cannot add and remove the same tag in a single request'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
@@ -21173,12 +21570,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/Security_Detections_API_PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/Security_Detections_API_SiemErrorResponse'
description: Internal server error response
@@ -25546,7 +25954,10 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: |
+ `single` deletes the list in the current Kibana space; `agnostic` deletes a global list. Must match the
+ list you are removing when using `list_id` or `id`.
+ examples:
agnostic:
value: agnostic
single:
@@ -25674,7 +26085,10 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: |
+ When `single`, the list is resolved in the current Kibana space. When `agnostic`, the list is a global
+ (space-agnostic) container. Required for looking up the correct list when `list_id` is not unique.
+ examples:
agnostic:
value: agnostic
single:
@@ -25794,6 +26208,18 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ createDetection:
+ value:
+ description: This is a sample detection type exception list.
+ list_id: simple_list
+ name: Sample Detection Exception List
+ namespace_type: single
+ os_types:
+ - linux
+ tags:
+ - malware
+ type: detection
schema:
example:
description: This is a sample detection type exception list.
@@ -26000,6 +26426,18 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ fullReplace:
+ value:
+ description: Different description
+ list_id: simple_list
+ name: Updated exception list name
+ os_types:
+ - linux
+ tags:
+ - draft
+ - malware
+ type: detection
schema:
example:
description: Different description
@@ -26148,12 +26586,14 @@ paths:
Duplicate an existing exception list.
operationId: DuplicateExceptionList
parameters:
- - in: query
+ - description: The `list_id` of the existing exception list to copy (source list).
+ in: query
name: list_id
required: true
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: Scope in which the source list is defined (`single` = current space, `agnostic` = all spaces).
+ examples:
agnostic:
value: agnostic
single:
@@ -26245,14 +26685,19 @@ paths:
examples:
notFound:
value:
- message": 'exception list id: "foo" does not exist'
- status_code": 404
+ message: 'exception list id: "foo" does not exist'
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse'
description: Exception list not found
'405':
content:
application/json:
+ examples:
+ notAllowed:
+ value:
+ message: 'Cannot duplicate: list is immutable or the operation is not allowed in this state'
+ status_code: 405
schema:
$ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
description: Exception list to duplicate not found response
@@ -26285,17 +26730,21 @@ paths:
Export an exception list and its associated items to an NDJSON file.
operationId: ExportExceptionList
parameters:
- - in: query
+ - description: Exception list's internal `id` (UUID) returned on create; use with `list_id` and `namespace_type` for an unambiguous target.
+ in: query
name: id
required: true
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListId'
- - in: query
+ - description: Human-readable `list_id` of the exception list to export, as shown in the UI and API responses.
+ in: query
name: list_id
required: true
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: |
+ `single` exports a list in the current Kibana space; `agnostic` exports a global (space-agnostic) list.
+ examples:
agnostic:
value: agnostic
single:
@@ -26612,6 +27061,10 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ ndjsonUpload:
+ value:
+ file: exception_lists.ndjson
schema:
type: object
properties:
@@ -26687,6 +27140,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: Multipart part `file` is required and must contain a valid .ndjson exception list export
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse'
@@ -26757,7 +27216,9 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemHumanId'
- - examples:
+ - description: |
+ `single` deletes the item in the current Kibana space; `agnostic` deletes an item in a space-agnostic list. Must match the list that owns the item.
+ examples:
agnostic:
value: agnostic
single:
@@ -26809,11 +27270,13 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob'''
+ statusCode: 400
schema:
- example:
- error: Bad Request
- message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob'''
- statusCode: 400
oneOf:
- $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse'
- $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse'
@@ -26893,7 +27356,10 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemHumanId'
- - examples:
+ - description: |
+ `single` fetches the item in the current space; `agnostic` fetches a global (space-agnostic) item. Must
+ match how the list was created.
+ examples:
agnostic:
value: agnostic
single:
@@ -27023,6 +27489,23 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ simpleItem:
+ value:
+ description: This is a sample detection type exception item.
+ entries:
+ - field: actingProcess.file.signer
+ operator: excluded
+ type: exists
+ item_id: simple_list_item
+ list_id: simple_list
+ name: Sample Exception List Item
+ namespace_type: single
+ os_types:
+ - linux
+ tags:
+ - malware
+ type: simple
schema:
oneOf:
- $ref: '#/components/schemas/Security_Exceptions_API_CreateExceptionListItemGeneric'
@@ -27308,6 +27791,14 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ updateItem:
+ value:
+ description: Updated description
+ id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2
+ name: Updated name
+ namespace_type: single
+ type: simple
schema:
oneOf:
- $ref: '#/components/schemas/Security_Exceptions_API_UpdateExceptionListItemGeneric'
@@ -27473,7 +27964,9 @@ paths:
items:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionNamespaceType'
type: array
- - in: query
+ - description: |
+ Free-text search term applied to exception list item fields (for example a hostname or file path fragment).
+ in: query
name: search
required: false
schema:
@@ -27665,7 +28158,10 @@ paths:
required: false
schema:
$ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId'
- - examples:
+ - description: |
+ `single` returns summary for a list in the current space; `agnostic` for a space-agnostic list. Must
+ line up with `id` / `list_id` used to look up the list.
+ examples:
agnostic:
value: agnostic
single:
@@ -60569,7 +61065,8 @@ paths:
> When you delete a list, all of its list items are also deleted.
operationId: DeleteList
parameters:
- - in: query
+ - description: Value list identifier to delete, including all of its list items.
+ in: query
name: id
required: true
schema:
@@ -60690,7 +61187,8 @@ paths:
Get the details of a value list using the list ID.
operationId: ReadList
parameters:
- - in: query
+ - description: Value list identifier (`id`) returned when the list was created.
+ in: query
name: id
required: true
schema:
@@ -60797,6 +61295,11 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ patchName:
+ value:
+ id: ip_list
+ name: Bad ips list - UPDATED
schema:
example:
id: ip_list
@@ -61117,6 +61620,12 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ replaceList:
+ value:
+ description: Latest list of bad ips
+ id: ip_list
+ name: Bad ips - updated
schema:
example:
description: Latest list of bad ips
@@ -61413,6 +61922,10 @@ paths:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -61424,6 +61937,11 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: 'Unable to delete value list data streams: invalid or missing index metadata'
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
@@ -61444,12 +61962,23 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: API [DELETE /api/lists/index] is not authorized; lists-all (or equivalent) is required to delete data streams
+ statusCode: 403
schema:
$ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
description: Not enough privileges response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: The value list data stream was not found in this space
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: List data stream not found response
@@ -61484,6 +62013,11 @@ paths:
'200':
content:
application/json:
+ examples:
+ bothExist:
+ value:
+ list_index: true
+ list_item_index: true
schema:
type: object
properties:
@@ -61498,6 +62032,11 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: Unable to read value list data stream status for this space
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
@@ -61518,12 +62057,23 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: API [GET /api/lists/index] is not authorized; list read permissions are required
+ statusCode: 403
schema:
$ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
description: Not enough privileges response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: Value list backing indices were not found for this space
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: List data stream(s) not found response
@@ -61546,19 +62096,28 @@ paths:
name: product_name
post:
deprecated: true
- description: |-
+ description: |
**Spaces method and path for this operation:**
post/s/{space_id}/api/lists/index
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- Create `.lists` and `.items` data streams in the relevant space.
+ **DEPRECATED.** `deprecated: true` is set on this operation. Value list backing data streams for the space
+ are now created as part of supported workflows; calling this explicitly is rarely required.
+ **WARNING:** Do not use for new integrations. Prefer the UI or the list and list-item APIs after confirming
+ indices exist with `GET /api/lists/index`.
+
+ Creates the `.lists` and `.items` data streams in the current Kibana space.
operationId: CreateListIndex
responses:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -61570,6 +62129,11 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: Indices exist but the request could not be completed for the current space. Check that Elasticsearch and Kibana privileges allow index creation for lists.
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
@@ -61591,6 +62155,12 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: API [POST /api/lists/index] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]
+ statusCode: 403
schema:
$ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
description: Not enough privileges response
@@ -61888,10 +62458,12 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ changeValue:
+ value:
+ id: pd1WRJQBs4HAK3VQeHFI
+ value: 255.255.255.255
schema:
- example:
- id: pd1WRJQBs4HAK3VQeHFI
- value: 255.255.255.255
type: object
properties:
_version:
@@ -62192,10 +62764,15 @@ paths:
requestBody:
content:
application/json:
- example:
- id: ip_item
- value: 255.255.255.255
+ examples:
+ fullReplace:
+ value:
+ id: ip_item
+ value: 255.255.255.255
schema:
+ example:
+ id: ip_item
+ value: 255.255.255.255
type: object
properties:
_version:
@@ -62320,6 +62897,12 @@ paths:
'200':
content:
application/ndjson:
+ examples:
+ ipLines:
+ value: |
+ 127.0.0.1
+ 127.0.0.2
+ 127.0.0.3
schema:
description: A `.txt` file containing list items from the specified list
example: |
@@ -62375,6 +62958,11 @@ paths:
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: 'list id: "unknown_list" not found'
+ status_code: 404
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: List not found response
@@ -62407,7 +62995,8 @@ paths:
Get all value list items in the specified list.
operationId: FindListItems
parameters:
- - in: query
+ - description: Parent value list's `id` to page through items for.
+ in: query
name: list_id
required: true
schema:
@@ -62445,7 +63034,9 @@ paths:
- asc
example: asc
type: string
- - in: query
+ - description: |
+ Opaque cursor returned in a previous response; pass it to continue listing from the next page. Omit on the first request.
+ in: query
name: cursor
required: false
schema:
@@ -62610,6 +63201,10 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ ipLinesFile:
+ value:
+ file: list_values.txt
schema:
type: object
properties:
@@ -62691,6 +63286,11 @@ paths:
'409':
content:
application/json:
+ examples:
+ conflict:
+ value:
+ message: List with the specified list_id does not exist, create the list or fix list_id to import to an existing one
+ status_code: 409
schema:
$ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse'
description: List with specified list_id does not exist response
@@ -62713,6 +63313,16 @@ paths:
name: product_name
/api/lists/privileges:
get:
+ description: |
+ **Spaces method and path for this operation:**
+
+
get/s/{space_id}/api/lists/privileges
+
+ Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
+
+ Returns the caller's authentication state and the Elasticsearch `cluster`, `index`, and `application`
+ privileges for `.lists` and `.items` data streams in the current Kibana space. Use this to decide which list
+ APIs (`read` vs `all` operations) are available before you create or import lists.
operationId: ReadListPrivileges
responses:
'200':
@@ -62803,6 +63413,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: 'Unable to resolve list privileges: invalid or missing space context for this request'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse'
@@ -62849,12 +63465,6 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
- description: |-
- **Spaces method and path for this operation:**
-
-
get/s/{space_id}/api/lists/privileges
-
- Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/api/logstash/pipeline/{id}:
delete:
description: |
diff --git a/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json b/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json
index 1972ba8064e5a..866f5614217f0 100644
--- a/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json
+++ b/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json
@@ -1,4 +1,4 @@
{
- "./oas_docs/output/kibana.yaml": 554,
- "./oas_docs/output/kibana.serverless.yaml": 519
+ "./oas_docs/output/kibana.yaml": 462,
+ "./oas_docs/output/kibana.serverless.yaml": 455
}
\ No newline at end of file
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml
index 1826d94495dcb..57b0f412dd1ac 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml
@@ -54,6 +54,16 @@ paths:
- name
- description
- type
+ examples:
+ createDetection:
+ value:
+ list_id: simple_list
+ type: detection
+ name: Sample Detection Exception List
+ description: This is a sample detection type exception list.
+ namespace_type: single
+ tags: [malware]
+ os_types: [linux]
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml
index aed28c154748f..3a2662c5c3faf 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml
@@ -33,6 +33,21 @@ paths:
- $ref: '#/components/schemas/CreateExceptionListItemBlocklistWindows'
- $ref: '#/components/schemas/CreateExceptionListItemBlocklistLinux'
- $ref: '#/components/schemas/CreateExceptionListItemBlocklistMac'
+ examples:
+ simpleItem:
+ value:
+ list_id: simple_list
+ item_id: simple_list_item
+ name: Sample Exception List Item
+ type: simple
+ description: This is a sample detection type exception item.
+ namespace_type: single
+ entries:
+ - type: exists
+ field: actingProcess.file.signer
+ operator: excluded
+ os_types: [linux]
+ tags: [malware]
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml
index f466f50839ead..fd9f82c15e3a1 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml
@@ -51,6 +51,26 @@ paths:
namespace_type: single
os_types: [linux]
tags: [malware]
+ examples:
+ addItems:
+ value:
+ items:
+ - item_id: simple_list_item
+ list_id: simple_list
+ type: simple
+ name: Sample Exception List Item
+ description: This is a sample detection type exception item.
+ entries:
+ - type: exists
+ field: actingProcess.file.signer
+ operator: excluded
+ - type: match_any
+ field: host.name
+ value: [saturn, jupiter]
+ operator: included
+ namespace_type: single
+ os_types: [linux]
+ tags: [malware]
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.gen.ts
index e48a3e1d93838..1d7c4ffd2910b 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.gen.ts
@@ -33,6 +33,11 @@ export const DeleteExceptionListRequestQuery = lazySchema(() =>
* Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified.
*/
list_id: ExceptionListHumanId.optional(),
+ /**
+ * `single` deletes the list in the current Kibana space; `agnostic` deletes a global list. Must match the
+list you are removing when using `list_id` or `id`.
+
+ */
namespace_type: ExceptionNamespaceType.optional().default('single'),
})
);
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml
index 0135f0fa86557..36741eb2432ea 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml
@@ -31,6 +31,9 @@ paths:
- name: namespace_type
in: query
required: false
+ description: |
+ `single` deletes the list in the current Kibana space; `agnostic` deletes a global list. Must match the
+ list you are removing when using `list_id` or `id`.
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
default: single
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.gen.ts
index f3962ad4f689c..227a141523afa 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.gen.ts
@@ -33,6 +33,10 @@ export const DeleteExceptionListItemRequestQuery = lazySchema(() =>
* Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified
*/
item_id: ExceptionListItemHumanId.optional(),
+ /**
+ * `single` deletes the item in the current Kibana space; `agnostic` deletes an item in a space-agnostic list. Must match the list that owns the item.
+
+ */
namespace_type: ExceptionNamespaceType.optional().default('single'),
})
);
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml
index 47853cade34f8..2c7d70cdcb9c2 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml
@@ -26,6 +26,8 @@ paths:
- name: namespace_type
in: query
required: false
+ description: |
+ `single` deletes the item in the current Kibana space; `agnostic` deletes an item in a space-agnostic list. Must match the list that owns the item.
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
default: single
@@ -76,10 +78,12 @@ paths:
oneOf:
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
- example:
- statusCode: 400
- error: Bad Request
- message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'"
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'"
401:
description: Unsuccessful authentication response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.gen.ts
index eaa504627bb73..3b497483d74b9 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.gen.ts
@@ -24,7 +24,13 @@ import {
export const DuplicateExceptionListRequestQuery = lazySchema(() =>
z.object({
+ /**
+ * The `list_id` of the existing exception list to copy (source list).
+ */
list_id: ExceptionListHumanId,
+ /**
+ * Scope in which the source list is defined (`single` = current space, `agnostic` = all spaces).
+ */
namespace_type: ExceptionNamespaceType,
/**
* Determines whether to include expired exceptions in the duplicated list. Expiration date defined by `expire_time`.
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml
index 6d3ab96bb122f..a449557fb17f8 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml
@@ -14,11 +14,13 @@ paths:
- name: list_id
in: query
required: true
+ description: The `list_id` of the existing exception list to copy (source list).
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId'
- name: namespace_type
in: query
required: true
+ description: Scope in which the source list is defined (`single` = current space, `agnostic` = all spaces).
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
examples:
@@ -108,14 +110,19 @@ paths:
examples:
notFound:
value:
- message": 'exception list id: "foo" does not exist'
- status_code": 404
+ message: 'exception list id: "foo" does not exist'
+ status_code: 404
405:
description: Exception list to duplicate not found response
content:
application/json:
schema:
$ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ notAllowed:
+ value:
+ message: 'Cannot duplicate: list is immutable or the operation is not allowed in this state'
+ status_code: 405
500:
description: Internal server error response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.gen.ts
index c0bf4523a8671..84d81dea3d7d0 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.gen.ts
@@ -24,8 +24,18 @@ import {
export const ExportExceptionListRequestQuery = lazySchema(() =>
z.object({
+ /**
+ * Exception list's internal `id` (UUID) returned on create; use with `list_id` and `namespace_type` for an unambiguous target.
+ */
id: ExceptionListId,
+ /**
+ * Human-readable `list_id` of the exception list to export, as shown in the UI and API responses.
+ */
list_id: ExceptionListHumanId,
+ /**
+ * `single` exports a list in the current Kibana space; `agnostic` exports a global (space-agnostic) list.
+
+ */
namespace_type: ExceptionNamespaceType,
/**
* Determines whether to include expired exceptions in the exported list. Expiration date defined by `expire_time`.
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml
index fe15640bf2cc3..68306353eae7d 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml
@@ -14,16 +14,20 @@ paths:
- name: id
in: query
required: true
+ description: Exception list's internal `id` (UUID) returned on create; use with `list_id` and `namespace_type` for an unambiguous target.
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListId'
- name: list_id
in: query
required: true
+ description: Human-readable `list_id` of the exception list to export, as shown in the UI and API responses.
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId'
- name: namespace_type
in: query
required: true
+ description: |
+ `single` exports a list in the current Kibana space; `agnostic` exports a global (space-agnostic) list.
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
examples:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.gen.ts
index 8e3532c60f8de..a79ec42caaee5 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.gen.ts
@@ -45,6 +45,10 @@ or available in all spaces (`agnostic` or `single`)
*/
namespace_type: ArrayFromString(ExceptionNamespaceType).optional().default(['single']),
+ /**
+ * Free-text search term applied to exception list item fields (for example a hostname or file path fragment).
+
+ */
search: z.string().optional(),
/**
* The page number to return
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml
index 640ec9b69efad..943fa1729030c 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml
@@ -50,6 +50,8 @@ paths:
- name: search
in: query
required: false
+ description: |
+ Free-text search term applied to exception list item fields (for example a hostname or file path fragment).
schema:
type: string
example: host.name
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml
index c3bd0eb853e0c..a0bfb0544e1a7 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml
@@ -24,6 +24,10 @@ paths:
example: |
{"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This is a sample detection type exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample Detection Exception List","namespace_type":"single","os_types":[],"tags":["user added string for a tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1}
{"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This is a sample endpoint type exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some host","another host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample Endpoint Exception List","namespace_type":"single","os_types":["linux"],"tags":["user added string for a tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"}
+ examples:
+ ndjsonUpload:
+ value:
+ file: exception_lists.ndjson
parameters:
- name: overwrite
in: query
@@ -115,6 +119,12 @@ paths:
oneOf:
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: "Multipart part `file` is required and must contain a valid .ndjson exception list export"
401:
description: Unsuccessful authentication response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.gen.ts
index 8b2ae497bc4c9..02b237814096a 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.gen.ts
@@ -33,6 +33,11 @@ export const ReadExceptionListRequestQuery = lazySchema(() =>
* Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified.
*/
list_id: ExceptionListHumanId.optional(),
+ /**
+ * When `single`, the list is resolved in the current Kibana space. When `agnostic`, the list is a global
+(space-agnostic) container. Required for looking up the correct list when `list_id` is not unique.
+
+ */
namespace_type: ExceptionNamespaceType.optional().default('single'),
})
);
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml
index 5d5e414dfad0e..149d8dcbd6d79 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml
@@ -26,6 +26,9 @@ paths:
- name: namespace_type
in: query
required: false
+ description: |
+ When `single`, the list is resolved in the current Kibana space. When `agnostic`, the list is a global
+ (space-agnostic) container. Required for looking up the correct list when `list_id` is not unique.
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
default: single
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.gen.ts
index 092febe31abf0..5f23a3cd0aeb2 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.gen.ts
@@ -33,6 +33,11 @@ export const ReadExceptionListItemRequestQuery = lazySchema(() =>
* Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified.
*/
item_id: ExceptionListItemHumanId.optional(),
+ /**
+ * `single` fetches the item in the current space; `agnostic` fetches a global (space-agnostic) item. Must
+match how the list was created.
+
+ */
namespace_type: ExceptionNamespaceType.optional().default('single'),
})
);
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml
index 3b451d5de9e33..e22feb735aee4 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml
@@ -26,6 +26,9 @@ paths:
- name: namespace_type
in: query
required: false
+ description: |
+ `single` fetches the item in the current space; `agnostic` fetches a global (space-agnostic) item. Must
+ match how the list was created.
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
default: single
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.gen.ts
index e801ed6d3b0d0..cda57dc88c0ce 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.gen.ts
@@ -32,6 +32,11 @@ export const ReadExceptionListSummaryRequestQuery = lazySchema(() =>
* Exception list's human readable identifier.
*/
list_id: ExceptionListHumanId.optional(),
+ /**
+ * `single` returns summary for a list in the current space; `agnostic` for a space-agnostic list. Must
+line up with `id` / `list_id` used to look up the list.
+
+ */
namespace_type: ExceptionNamespaceType.optional().default('single'),
/**
* Search filter clause
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml
index 8037c18a14026..40bc5679398d0 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml
@@ -26,6 +26,9 @@ paths:
- name: namespace_type
in: query
required: false
+ description: |
+ `single` returns summary for a list in the current space; `agnostic` for a space-agnostic list. Must
+ line up with `id` / `list_id` used to look up the list.
schema:
$ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType'
default: single
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml
index d62845f48f17d..626fa85863433 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml
@@ -54,6 +54,15 @@ paths:
os_types: [linux]
description: Different description
name: Updated exception list name
+ examples:
+ fullReplace:
+ value:
+ list_id: simple_list
+ tags: [draft, malware]
+ type: detection
+ os_types: [linux]
+ description: Different description
+ name: Updated exception list name
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml
index a74eac06c0932..07863c04ee7e6 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml
@@ -30,6 +30,14 @@ paths:
- $ref: '#/components/schemas/UpdateExceptionListItemBlocklistWindows'
- $ref: '#/components/schemas/UpdateExceptionListItemBlocklistLinux'
- $ref: '#/components/schemas/UpdateExceptionListItemBlocklistMac'
+ examples:
+ updateItem:
+ value:
+ id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2
+ name: Updated name
+ type: simple
+ description: Updated description
+ namespace_type: single
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml
index 2ba1fd372abdd..469674d758aa1 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml
@@ -31,6 +31,30 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ addItems:
+ value:
+ 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
schema:
example:
items:
@@ -192,7 +216,12 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >
+ `single` deletes the list in the current Kibana space; `agnostic`
+ deletes a global list. Must match the
+
+ list you are removing when using `list_id` or `id`.
+ examples:
agnostic:
value: agnostic
single:
@@ -326,7 +355,13 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >
+ When `single`, the list is resolved in the current Kibana space.
+ When `agnostic`, the list is a global
+
+ (space-agnostic) container. Required for looking up the correct list
+ when `list_id` is not unique.
+ examples:
agnostic:
value: agnostic
single:
@@ -457,6 +492,18 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ createDetection:
+ value:
+ description: This is a sample detection type exception list.
+ list_id: simple_list
+ name: Sample Detection Exception List
+ namespace_type: single
+ os_types:
+ - linux
+ tags:
+ - malware
+ type: detection
schema:
example:
description: This is a sample detection type exception list.
@@ -658,6 +705,18 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ fullReplace:
+ value:
+ description: Different description
+ list_id: simple_list
+ name: Updated exception list name
+ os_types:
+ - linux
+ tags:
+ - draft
+ - malware
+ type: detection
schema:
example:
description: Different description
@@ -807,12 +866,16 @@ paths:
description: Duplicate an existing exception list.
operationId: DuplicateExceptionList
parameters:
- - in: query
+ - description: The `list_id` of the existing exception list to copy (source list).
+ in: query
name: list_id
required: true
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >-
+ Scope in which the source list is defined (`single` = current space,
+ `agnostic` = all spaces).
+ examples:
agnostic:
value: agnostic
single:
@@ -916,14 +979,21 @@ paths:
examples:
notFound:
value:
- message": 'exception list id: "foo" does not exist'
- status_code": 404
+ message: 'exception list id: "foo" does not exist'
+ status_code: 404
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Exception list not found
'405':
content:
application/json:
+ examples:
+ notAllowed:
+ value:
+ message: >-
+ Cannot duplicate: list is immutable or the operation is
+ not allowed in this state
+ status_code: 405
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Exception list to duplicate not found response
@@ -946,17 +1016,26 @@ paths:
description: Export an exception list and its associated items to an NDJSON file.
operationId: ExportExceptionList
parameters:
- - in: query
+ - description: >-
+ Exception list's internal `id` (UUID) returned on create; use with
+ `list_id` and `namespace_type` for an unambiguous target.
+ in: query
name: id
required: true
schema:
$ref: '#/components/schemas/ExceptionListId'
- - in: query
+ - description: >-
+ Human-readable `list_id` of the exception list to export, as shown
+ in the UI and API responses.
+ in: query
name: list_id
required: true
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >
+ `single` exports a list in the current Kibana space; `agnostic`
+ exports a global (space-agnostic) list.
+ examples:
agnostic:
value: agnostic
single:
@@ -1308,6 +1387,10 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ ndjsonUpload:
+ value:
+ file: exception_lists.ndjson
schema:
type: object
properties:
@@ -1404,6 +1487,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ Multipart part `file` is required and must contain a valid
+ .ndjson exception list export
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -1477,7 +1568,11 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListItemHumanId'
- - examples:
+ - description: >
+ `single` deletes the item in the current Kibana space; `agnostic`
+ deletes an item in a space-agnostic list. Must match the list that
+ owns the item.
+ examples:
agnostic:
value: agnostic
single:
@@ -1529,13 +1624,15 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request query]: namespace_type.0: Invalid enum value.
+ Expected 'agnostic' | 'single', received 'blob'
+ statusCode: 400
schema:
- example:
- error: Bad Request
- message: >-
- [request query]: namespace_type.0: Invalid enum value.
- Expected 'agnostic' | 'single', received 'blob'
- statusCode: 400
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
- $ref: '#/components/schemas/SiemErrorResponse'
@@ -1621,7 +1718,12 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListItemHumanId'
- - examples:
+ - description: >
+ `single` fetches the item in the current space; `agnostic` fetches a
+ global (space-agnostic) item. Must
+
+ match how the list was created.
+ examples:
agnostic:
value: agnostic
single:
@@ -1756,6 +1858,23 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ simpleItem:
+ value:
+ description: This is a sample detection type exception item.
+ entries:
+ - field: actingProcess.file.signer
+ operator: excluded
+ type: exists
+ item_id: simple_list_item
+ list_id: simple_list
+ name: Sample Exception List Item
+ namespace_type: single
+ os_types:
+ - linux
+ tags:
+ - malware
+ type: simple
schema:
oneOf:
- $ref: '#/components/schemas/CreateExceptionListItemGeneric'
@@ -2049,6 +2168,14 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ updateItem:
+ value:
+ description: Updated description
+ id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2
+ name: Updated name
+ namespace_type: single
+ type: simple
schema:
oneOf:
- $ref: '#/components/schemas/UpdateExceptionListItemGeneric'
@@ -2220,7 +2347,10 @@ paths:
items:
$ref: '#/components/schemas/ExceptionNamespaceType'
type: array
- - in: query
+ - description: >
+ Free-text search term applied to exception list item fields (for
+ example a hostname or file path fragment).
+ in: query
name: search
required: false
schema:
@@ -2413,7 +2543,12 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >
+ `single` returns summary for a list in the current space; `agnostic`
+ for a space-agnostic list. Must
+
+ line up with `id` / `list_id` used to look up the list.
+ examples:
agnostic:
value: agnostic
single:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml
index 0395595065c88..d940d53121223 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml
@@ -31,6 +31,30 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ addItems:
+ value:
+ 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
schema:
example:
items:
@@ -192,7 +216,12 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >
+ `single` deletes the list in the current Kibana space; `agnostic`
+ deletes a global list. Must match the
+
+ list you are removing when using `list_id` or `id`.
+ examples:
agnostic:
value: agnostic
single:
@@ -326,7 +355,13 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >
+ When `single`, the list is resolved in the current Kibana space.
+ When `agnostic`, the list is a global
+
+ (space-agnostic) container. Required for looking up the correct list
+ when `list_id` is not unique.
+ examples:
agnostic:
value: agnostic
single:
@@ -457,6 +492,18 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ createDetection:
+ value:
+ description: This is a sample detection type exception list.
+ list_id: simple_list
+ name: Sample Detection Exception List
+ namespace_type: single
+ os_types:
+ - linux
+ tags:
+ - malware
+ type: detection
schema:
example:
description: This is a sample detection type exception list.
@@ -658,6 +705,18 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ fullReplace:
+ value:
+ description: Different description
+ list_id: simple_list
+ name: Updated exception list name
+ os_types:
+ - linux
+ tags:
+ - draft
+ - malware
+ type: detection
schema:
example:
description: Different description
@@ -807,12 +866,16 @@ paths:
description: Duplicate an existing exception list.
operationId: DuplicateExceptionList
parameters:
- - in: query
+ - description: The `list_id` of the existing exception list to copy (source list).
+ in: query
name: list_id
required: true
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >-
+ Scope in which the source list is defined (`single` = current space,
+ `agnostic` = all spaces).
+ examples:
agnostic:
value: agnostic
single:
@@ -916,14 +979,21 @@ paths:
examples:
notFound:
value:
- message": 'exception list id: "foo" does not exist'
- status_code": 404
+ message: 'exception list id: "foo" does not exist'
+ status_code: 404
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Exception list not found
'405':
content:
application/json:
+ examples:
+ notAllowed:
+ value:
+ message: >-
+ Cannot duplicate: list is immutable or the operation is
+ not allowed in this state
+ status_code: 405
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Exception list to duplicate not found response
@@ -946,17 +1016,26 @@ paths:
description: Export an exception list and its associated items to an NDJSON file.
operationId: ExportExceptionList
parameters:
- - in: query
+ - description: >-
+ Exception list's internal `id` (UUID) returned on create; use with
+ `list_id` and `namespace_type` for an unambiguous target.
+ in: query
name: id
required: true
schema:
$ref: '#/components/schemas/ExceptionListId'
- - in: query
+ - description: >-
+ Human-readable `list_id` of the exception list to export, as shown
+ in the UI and API responses.
+ in: query
name: list_id
required: true
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >
+ `single` exports a list in the current Kibana space; `agnostic`
+ exports a global (space-agnostic) list.
+ examples:
agnostic:
value: agnostic
single:
@@ -1308,6 +1387,10 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ ndjsonUpload:
+ value:
+ file: exception_lists.ndjson
schema:
type: object
properties:
@@ -1404,6 +1487,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ Multipart part `file` is required and must contain a valid
+ .ndjson exception list export
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -1477,7 +1568,11 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListItemHumanId'
- - examples:
+ - description: >
+ `single` deletes the item in the current Kibana space; `agnostic`
+ deletes an item in a space-agnostic list. Must match the list that
+ owns the item.
+ examples:
agnostic:
value: agnostic
single:
@@ -1529,13 +1624,15 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request query]: namespace_type.0: Invalid enum value.
+ Expected 'agnostic' | 'single', received 'blob'
+ statusCode: 400
schema:
- example:
- error: Bad Request
- message: >-
- [request query]: namespace_type.0: Invalid enum value.
- Expected 'agnostic' | 'single', received 'blob'
- statusCode: 400
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
- $ref: '#/components/schemas/SiemErrorResponse'
@@ -1621,7 +1718,12 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListItemHumanId'
- - examples:
+ - description: >
+ `single` fetches the item in the current space; `agnostic` fetches a
+ global (space-agnostic) item. Must
+
+ match how the list was created.
+ examples:
agnostic:
value: agnostic
single:
@@ -1756,6 +1858,23 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ simpleItem:
+ value:
+ description: This is a sample detection type exception item.
+ entries:
+ - field: actingProcess.file.signer
+ operator: excluded
+ type: exists
+ item_id: simple_list_item
+ list_id: simple_list
+ name: Sample Exception List Item
+ namespace_type: single
+ os_types:
+ - linux
+ tags:
+ - malware
+ type: simple
schema:
oneOf:
- $ref: '#/components/schemas/CreateExceptionListItemGeneric'
@@ -2049,6 +2168,14 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ updateItem:
+ value:
+ description: Updated description
+ id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2
+ name: Updated name
+ namespace_type: single
+ type: simple
schema:
oneOf:
- $ref: '#/components/schemas/UpdateExceptionListItemGeneric'
@@ -2220,7 +2347,10 @@ paths:
items:
$ref: '#/components/schemas/ExceptionNamespaceType'
type: array
- - in: query
+ - description: >
+ Free-text search term applied to exception list item fields (for
+ example a hostname or file path fragment).
+ in: query
name: search
required: false
schema:
@@ -2413,7 +2543,12 @@ paths:
required: false
schema:
$ref: '#/components/schemas/ExceptionListHumanId'
- - examples:
+ - description: >
+ `single` returns summary for a list in the current space; `agnostic`
+ for a space-agnostic list. Must
+
+ line up with `id` / `list_id` used to look up the list.
+ examples:
agnostic:
value: agnostic
single:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml
index bb1713f79b619..7cb3bc42ca53d 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml
@@ -10,7 +10,13 @@ paths:
operationId: CreateListIndex
x-codegen-enabled: true
summary: Create list data streams
- description: Create `.lists` and `.items` data streams in the relevant space.
+ description: |
+ **DEPRECATED.** `deprecated: true` is set on this operation. Value list backing data streams for the space
+ are now created as part of supported workflows; calling this explicitly is rarely required.
+ **WARNING:** Do not use for new integrations. Prefer the UI or the list and list-item APIs after confirming
+ indices exist with `GET /api/lists/index`.
+
+ Creates the `.lists` and `.items` data streams in the current Kibana space.
responses:
200:
description: Successful response
@@ -22,6 +28,10 @@ paths:
acknowledged:
type: boolean
required: [acknowledged]
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
400:
description: Invalid input data response
content:
@@ -30,6 +40,11 @@ paths:
oneOf:
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ message: "Indices exist but the request could not be completed for the current space. Check that Elasticsearch and Kibana privileges allow index creation for lists."
+ status_code: 400
401:
description: Unsuccessful authentication response
content:
@@ -49,6 +64,12 @@ paths:
application/json:
schema:
$ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ forbidden:
+ value:
+ statusCode: 403
+ error: Forbidden
+ message: 'API [POST /api/lists/index] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]'
409:
description: List data stream exists response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts
index fe4900d4cb926..41d6e1bcac2f2 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts
@@ -22,6 +22,9 @@ import { List } from '../model/list_schemas.gen';
export const DeleteListRequestQuery = lazySchema(() =>
z.object({
+ /**
+ * Value list identifier to delete, including all of its list items.
+ */
id: ListId,
/**
* Determines whether exception items referencing this value list should be deleted.
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml
index 7328710896ab7..9c0c20d9b66c5 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml
@@ -17,6 +17,7 @@ paths:
- name: id
in: query
required: true
+ description: Value list identifier to delete, including all of its list items.
schema:
$ref: '../model/list_common.schema.yaml#/components/schemas/ListId'
- name: deleteReferences
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml
index c695245938927..3c61dbf843913 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml
@@ -21,6 +21,10 @@ paths:
acknowledged:
type: boolean
required: [acknowledged]
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
400:
description: Invalid input data response
content:
@@ -29,6 +33,11 @@ paths:
oneOf:
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ message: "Unable to delete value list data streams: invalid or missing index metadata"
+ status_code: 400
401:
description: Unsuccessful authentication response
content:
@@ -47,12 +56,23 @@ paths:
application/json:
schema:
$ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ forbidden:
+ value:
+ statusCode: 403
+ error: Forbidden
+ message: "API [DELETE /api/lists/index] is not authorized; lists-all (or equivalent) is required to delete data streams"
404:
description: List data stream not found response
content:
application/json:
schema:
$ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ notFound:
+ value:
+ message: "The value list data stream was not found in this space"
+ status_code: 404
500:
description: Internal server error response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml
index f5e13d627fe76..da8e9e3b5181b 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml
@@ -36,6 +36,12 @@ paths:
127.0.0.7
127.0.0.8
127.0.0.9
+ examples:
+ ipLines:
+ value: |
+ 127.0.0.1
+ 127.0.0.2
+ 127.0.0.3
400:
description: Invalid input data response
content:
@@ -79,6 +85,11 @@ paths:
application/json:
schema:
$ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ notFound:
+ value:
+ message: 'list id: "unknown_list" not found'
+ status_code: 404
500:
description: Internal server error response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts
index 3a0e95f7ec132..cf8e25a3c619c 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts
@@ -33,6 +33,9 @@ export type FindListItemsFilter = z.infer;
export const FindListItemsRequestQuery = lazySchema(() =>
z.object({
+ /**
+ * Parent value list's `id` to page through items for.
+ */
list_id: ListId,
/**
* The page number to return.
@@ -50,6 +53,10 @@ export const FindListItemsRequestQuery = lazySchema(() =>
* Determines the sort order, which can be `desc` or `asc`
*/
sort_order: z.enum(['desc', 'asc']).optional(),
+ /**
+ * Opaque cursor returned in a previous response; pass it to continue listing from the next page. Omit on the first request.
+
+ */
cursor: FindListItemsCursor.optional(),
/**
* Filters the returned results according to the value of the specified field,
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml
index 25ec88a78cd46..cb83fb9df7c5c 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml
@@ -14,6 +14,7 @@ paths:
- name: list_id
in: query
required: true
+ description: Parent value list's `id` to page through items for.
schema:
$ref: '../model/list_common.schema.yaml#/components/schemas/ListId'
- name: page
@@ -50,6 +51,8 @@ paths:
- name: cursor
in: query
required: false
+ description: |
+ Opaque cursor returned in a previous response; pass it to continue listing from the next page. Omit on the first request.
schema:
$ref: '#/components/schemas/FindListItemsCursor'
- name: filter
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml
index ea58da22bfafd..b73849de31bdc 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml
@@ -34,6 +34,10 @@ paths:
127.0.0.7
127.0.0.8
127.0.0.9
+ examples:
+ ipLinesFile:
+ value:
+ file: list_values.txt
parameters:
- name: list_id
in: query
@@ -130,6 +134,11 @@ paths:
application/json:
schema:
$ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ conflict:
+ value:
+ message: 'List with the specified list_id does not exist, create the list or fix list_id to import to an existing one'
+ status_code: 409
500:
description: Internal server error response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml
index c0b39a662262d..81df596c29a12 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml
@@ -35,6 +35,11 @@ paths:
example:
id: ip_list
name: Bad ips list - UPDATED
+ examples:
+ patchName:
+ value:
+ id: ip_list
+ name: Bad ips list - UPDATED
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml
index ada1d17e6ef6a..f237c30d008f6 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml
@@ -35,9 +35,11 @@ paths:
description: Determines when changes made by the request are made visible to search.
required:
- id
- example:
- id: pd1WRJQBs4HAK3VQeHFI
- value: 255.255.255.255
+ examples:
+ changeValue:
+ value:
+ id: pd1WRJQBs4HAK3VQeHFI
+ value: 255.255.255.255
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts
index 26fc8953b07f7..a139c71ed8477 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts
@@ -92,8 +92,14 @@ export class Client {
.catch(catchAxiosErrorFormatAndThrow);
}
/**
- * Create `.lists` and `.items` data streams in the relevant space.
- */
+ * **DEPRECATED.** `deprecated: true` is set on this operation. Value list backing data streams for the space
+are now created as part of supported workflows; calling this explicitly is rarely required.
+**WARNING:** Do not use for new integrations. Prefer the UI or the list and list-item APIs after confirming
+indices exist with `GET /api/lists/index`.
+
+Creates the `.lists` and `.items` data streams in the current Kibana space.
+
+ */
async createListIndex() {
this.log.info(`${new Date().toISOString()} Calling API CreateListIndex`);
return this.kbnClient
@@ -331,6 +337,12 @@ You can import items to a new or existing list.
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Returns the caller's authentication state and the Elasticsearch `cluster`, `index`, and `application`
+privileges for `.lists` and `.items` data streams in the current Kibana space. Use this to decide which list
+APIs (`read` vs `all` operations) are available before you create or import lists.
+
+ */
async readListPrivileges() {
this.log.info(`${new Date().toISOString()} Calling API ReadListPrivileges`);
return this.kbnClient
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts
index 6abb4243af8e0..5d4605c988833 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts
@@ -21,6 +21,9 @@ import { List } from '../model/list_schemas.gen';
export const ReadListRequestQuery = lazySchema(() =>
z.object({
+ /**
+ * Value list identifier (`id`) returned when the list was created.
+ */
id: ListId,
})
);
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml
index 4cf25bd80be38..60453912182b9 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml
@@ -14,6 +14,7 @@ paths:
- name: id
in: query
required: true
+ description: Value list identifier (`id`) returned when the list was created.
schema:
$ref: '../model/list_common.schema.yaml#/components/schemas/ListId'
responses:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml
index ddd5d347d4750..e7d637b2bcad9 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml
@@ -23,6 +23,11 @@ paths:
list_item_index:
type: boolean
required: [list_index, list_item_index]
+ examples:
+ bothExist:
+ value:
+ list_index: true
+ list_item_index: true
400:
description: Invalid input data response
content:
@@ -31,6 +36,11 @@ paths:
oneOf:
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ message: "Unable to read value list data stream status for this space"
+ status_code: 400
401:
description: Unsuccessful authentication response
content:
@@ -49,12 +59,23 @@ paths:
application/json:
schema:
$ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ forbidden:
+ value:
+ statusCode: 403
+ error: Forbidden
+ message: "API [GET /api/lists/index] is not authorized; list read permissions are required"
404:
description: List data stream(s) not found response
content:
application/json:
schema:
$ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ notFound:
+ value:
+ message: "Value list backing indices were not found for this space"
+ status_code: 404
500:
description: Internal server error response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml
index d83d5d837647b..e2f486a6792f0 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml
@@ -9,6 +9,10 @@ paths:
operationId: ReadListPrivileges
x-codegen-enabled: true
summary: Get value list privileges
+ description: |
+ Returns the caller's authentication state and the Elasticsearch `cluster`, `index`, and `application`
+ privileges for `.lists` and `.items` data streams in the current Kibana space. Use this to decide which list
+ APIs (`read` vs `all` operations) are available before you create or import lists.
responses:
200:
description: Successful response
@@ -103,6 +107,12 @@ paths:
oneOf:
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: 'Unable to resolve list privileges: invalid or missing space context for this request'
401:
description: Unsuccessful authentication response
content:
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml
index e20081f5f4b59..47d1d99d2735d 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml
@@ -41,6 +41,12 @@ paths:
id: ip_list
name: Bad ips - updated
description: Latest list of bad ips
+ examples:
+ replaceList:
+ value:
+ id: ip_list
+ name: Bad ips - updated
+ description: Latest list of bad ips
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml
index ef17a470f6595..cdb0e8eff376b 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml
@@ -32,9 +32,14 @@ paths:
required:
- id
- value
- example:
- id: ip_item
- value: 255.255.255.255
+ example:
+ id: ip_item
+ value: 255.255.255.255
+ examples:
+ fullReplace:
+ value:
+ id: ip_item
+ value: 255.255.255.255
responses:
200:
description: Successful response
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml
index 3d50bc00fda93..4093193d90681 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml
@@ -19,7 +19,8 @@ paths:
> When you delete a list, all of its list items are also deleted.
operationId: DeleteList
parameters:
- - in: query
+ - description: Value list identifier to delete, including all of its list items.
+ in: query
name: id
required: true
schema:
@@ -142,7 +143,8 @@ paths:
description: Get the details of a value list using the list ID.
operationId: ReadList
parameters:
- - in: query
+ - description: Value list identifier (`id`) returned when the list was created.
+ in: query
name: id
required: true
schema:
@@ -242,6 +244,11 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ patchName:
+ value:
+ id: ip_list
+ name: Bad ips list - UPDATED
schema:
example:
id: ip_list
@@ -562,6 +569,12 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ replaceList:
+ value:
+ description: Latest list of bad ips
+ id: ip_list
+ name: Bad ips - updated
schema:
example:
description: Latest list of bad ips
@@ -862,6 +875,10 @@ paths:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -873,6 +890,13 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: >-
+ Unable to delete value list data streams: invalid or
+ missing index metadata
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -898,12 +922,25 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: >-
+ API [DELETE /api/lists/index] is not authorized; lists-all
+ (or equivalent) is required to delete data streams
+ statusCode: 403
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Not enough privileges response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: The value list data stream was not found in this space
+ status_code: 404
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: List data stream not found response
@@ -928,6 +965,11 @@ paths:
'200':
content:
application/json:
+ examples:
+ bothExist:
+ value:
+ list_index: true
+ list_item_index: true
schema:
type: object
properties:
@@ -942,6 +984,13 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: >-
+ Unable to read value list data stream status for this
+ space
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -967,12 +1016,25 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: >-
+ API [GET /api/lists/index] is not authorized; list read
+ permissions are required
+ statusCode: 403
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Not enough privileges response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: Value list backing indices were not found for this space
+ status_code: 404
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: List data stream(s) not found response
@@ -992,12 +1054,30 @@ paths:
- Security Lists API
post:
deprecated: true
- description: Create `.lists` and `.items` data streams in the relevant space.
+ description: >
+ **DEPRECATED.** `deprecated: true` is set on this operation. Value list
+ backing data streams for the space
+
+ are now created as part of supported workflows; calling this explicitly
+ is rarely required.
+
+ **WARNING:** Do not use for new integrations. Prefer the UI or the list
+ and list-item APIs after confirming
+
+ indices exist with `GET /api/lists/index`.
+
+
+ Creates the `.lists` and `.items` data streams in the current Kibana
+ space.
operationId: CreateListIndex
responses:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -1009,6 +1089,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: >-
+ Indices exist but the request could not be completed for
+ the current space. Check that Elasticsearch and Kibana
+ privileges allow index creation for lists.
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -1034,6 +1122,14 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: >-
+ API [POST /api/lists/index] is unauthorized for user, this
+ action is granted by the Kibana privileges [lists-all]
+ statusCode: 403
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Not enough privileges response
@@ -1339,10 +1435,12 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ changeValue:
+ value:
+ id: pd1WRJQBs4HAK3VQeHFI
+ value: 255.255.255.255
schema:
- example:
- id: pd1WRJQBs4HAK3VQeHFI
- value: 255.255.255.255
type: object
properties:
_version:
@@ -1659,10 +1757,15 @@ paths:
requestBody:
content:
application/json:
- example:
- id: ip_item
- value: 255.255.255.255
+ examples:
+ fullReplace:
+ value:
+ id: ip_item
+ value: 255.255.255.255
schema:
+ example:
+ id: ip_item
+ value: 255.255.255.255
type: object
properties:
_version:
@@ -1785,6 +1888,12 @@ paths:
'200':
content:
application/ndjson:
+ examples:
+ ipLines:
+ value: |
+ 127.0.0.1
+ 127.0.0.2
+ 127.0.0.3
schema:
description: A `.txt` file containing list items from the specified list
example: |
@@ -1848,6 +1957,11 @@ paths:
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: 'list id: "unknown_list" not found'
+ status_code: 404
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: List not found response
@@ -1870,7 +1984,8 @@ paths:
description: Get all value list items in the specified list.
operationId: FindListItems
parameters:
- - in: query
+ - description: Parent value list's `id` to page through items for.
+ in: query
name: list_id
required: true
schema:
@@ -1908,7 +2023,10 @@ paths:
- asc
example: asc
type: string
- - in: query
+ - description: >
+ Opaque cursor returned in a previous response; pass it to continue
+ listing from the next page. Omit on the first request.
+ in: query
name: cursor
required: false
schema:
@@ -2080,6 +2198,10 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ ipLinesFile:
+ value:
+ file: list_values.txt
schema:
type: object
properties:
@@ -2171,6 +2293,13 @@ paths:
'409':
content:
application/json:
+ examples:
+ conflict:
+ value:
+ message: >-
+ List with the specified list_id does not exist, create the
+ list or fix list_id to import to an existing one
+ status_code: 409
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: List with specified list_id does not exist response
@@ -2190,6 +2319,15 @@ paths:
- Security Lists API
/api/lists/privileges:
get:
+ description: >
+ Returns the caller's authentication state and the Elasticsearch
+ `cluster`, `index`, and `application`
+
+ privileges for `.lists` and `.items` data streams in the current Kibana
+ space. Use this to decide which list
+
+ APIs (`read` vs `all` operations) are available before you create or
+ import lists.
operationId: ReadListPrivileges
responses:
'200':
@@ -2280,6 +2418,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ Unable to resolve list privileges: invalid or missing
+ space context for this request
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml
index 4d5f832d860b7..9ab4f63273b19 100644
--- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml
+++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml
@@ -19,7 +19,8 @@ paths:
> When you delete a list, all of its list items are also deleted.
operationId: DeleteList
parameters:
- - in: query
+ - description: Value list identifier to delete, including all of its list items.
+ in: query
name: id
required: true
schema:
@@ -142,7 +143,8 @@ paths:
description: Get the details of a value list using the list ID.
operationId: ReadList
parameters:
- - in: query
+ - description: Value list identifier (`id`) returned when the list was created.
+ in: query
name: id
required: true
schema:
@@ -242,6 +244,11 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ patchName:
+ value:
+ id: ip_list
+ name: Bad ips list - UPDATED
schema:
example:
id: ip_list
@@ -562,6 +569,12 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ replaceList:
+ value:
+ description: Latest list of bad ips
+ id: ip_list
+ name: Bad ips - updated
schema:
example:
description: Latest list of bad ips
@@ -862,6 +875,10 @@ paths:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -873,6 +890,13 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: >-
+ Unable to delete value list data streams: invalid or
+ missing index metadata
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -898,12 +922,25 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: >-
+ API [DELETE /api/lists/index] is not authorized; lists-all
+ (or equivalent) is required to delete data streams
+ statusCode: 403
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Not enough privileges response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: The value list data stream was not found in this space
+ status_code: 404
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: List data stream not found response
@@ -928,6 +965,11 @@ paths:
'200':
content:
application/json:
+ examples:
+ bothExist:
+ value:
+ list_index: true
+ list_item_index: true
schema:
type: object
properties:
@@ -942,6 +984,13 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: >-
+ Unable to read value list data stream status for this
+ space
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -967,12 +1016,25 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: >-
+ API [GET /api/lists/index] is not authorized; list read
+ permissions are required
+ statusCode: 403
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Not enough privileges response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: Value list backing indices were not found for this space
+ status_code: 404
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: List data stream(s) not found response
@@ -992,12 +1054,30 @@ paths:
- Security Lists API
post:
deprecated: true
- description: Create `.lists` and `.items` data streams in the relevant space.
+ description: >
+ **DEPRECATED.** `deprecated: true` is set on this operation. Value list
+ backing data streams for the space
+
+ are now created as part of supported workflows; calling this explicitly
+ is rarely required.
+
+ **WARNING:** Do not use for new integrations. Prefer the UI or the list
+ and list-item APIs after confirming
+
+ indices exist with `GET /api/lists/index`.
+
+
+ Creates the `.lists` and `.items` data streams in the current Kibana
+ space.
operationId: CreateListIndex
responses:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -1009,6 +1089,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ message: >-
+ Indices exist but the request could not be completed for
+ the current space. Check that Elasticsearch and Kibana
+ privileges allow index creation for lists.
+ status_code: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -1034,6 +1122,14 @@ paths:
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: >-
+ API [POST /api/lists/index] is unauthorized for user, this
+ action is granted by the Kibana privileges [lists-all]
+ statusCode: 403
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Not enough privileges response
@@ -1339,10 +1435,12 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ changeValue:
+ value:
+ id: pd1WRJQBs4HAK3VQeHFI
+ value: 255.255.255.255
schema:
- example:
- id: pd1WRJQBs4HAK3VQeHFI
- value: 255.255.255.255
type: object
properties:
_version:
@@ -1659,10 +1757,15 @@ paths:
requestBody:
content:
application/json:
- example:
- id: ip_item
- value: 255.255.255.255
+ examples:
+ fullReplace:
+ value:
+ id: ip_item
+ value: 255.255.255.255
schema:
+ example:
+ id: ip_item
+ value: 255.255.255.255
type: object
properties:
_version:
@@ -1785,6 +1888,12 @@ paths:
'200':
content:
application/ndjson:
+ examples:
+ ipLines:
+ value: |
+ 127.0.0.1
+ 127.0.0.2
+ 127.0.0.3
schema:
description: A `.txt` file containing list items from the specified list
example: |
@@ -1848,6 +1957,11 @@ paths:
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: 'list id: "unknown_list" not found'
+ status_code: 404
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: List not found response
@@ -1870,7 +1984,8 @@ paths:
description: Get all value list items in the specified list.
operationId: FindListItems
parameters:
- - in: query
+ - description: Parent value list's `id` to page through items for.
+ in: query
name: list_id
required: true
schema:
@@ -1908,7 +2023,10 @@ paths:
- asc
example: asc
type: string
- - in: query
+ - description: >
+ Opaque cursor returned in a previous response; pass it to continue
+ listing from the next page. Omit on the first request.
+ in: query
name: cursor
required: false
schema:
@@ -2080,6 +2198,10 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ ipLinesFile:
+ value:
+ file: list_values.txt
schema:
type: object
properties:
@@ -2171,6 +2293,13 @@ paths:
'409':
content:
application/json:
+ examples:
+ conflict:
+ value:
+ message: >-
+ List with the specified list_id does not exist, create the
+ list or fix list_id to import to an existing one
+ status_code: 409
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: List with specified list_id does not exist response
@@ -2190,6 +2319,15 @@ paths:
- Security Lists API
/api/lists/privileges:
get:
+ description: >
+ Returns the caller's authentication state and the Elasticsearch
+ `cluster`, `index`, and `application`
+
+ privileges for `.lists` and `.items` data streams in the current Kibana
+ space. Use this to decide which list
+
+ APIs (`read` vs `all` operations) are available before you create or
+ import lists.
operationId: ReadListPrivileges
responses:
'200':
@@ -2280,6 +2418,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ Unable to resolve list privileges: invalid or missing
+ space context for this request
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
diff --git a/x-pack/solutions/security/packages/test-api-clients/supertest/detections.gen.ts b/x-pack/solutions/security/packages/test-api-clients/supertest/detections.gen.ts
index 2af13f0308e05..25c7b5137ddc8 100644
--- a/x-pack/solutions/security/packages/test-api-clients/supertest/detections.gen.ts
+++ b/x-pack/solutions/security/packages/test-api-clients/supertest/detections.gen.ts
@@ -65,13 +65,13 @@ import { getRouteUrlForSpace } from '@kbn/spaces-plugin/common';
const securitySolutionApiServiceFactory = (supertest: SuperTest.Agent) => ({
/**
- * Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
-the migration process. A successful migration will result in both the old and new indices being present.
-As such, the old, orphaned index can (and likely should) be deleted.
+ * **DEPRECATED.** Cleanup API for old migration artifacts. Do not add new call sites.
+**WARNING:** This schedules deletions; ensure no production reads still point at the source index.
-While you can delete these indices manually,
-the endpoint accomplishes this task by applying a deletion policy to the relevant index, causing it to be deleted
-after 30 days. It also deletes other artifacts specific to the migration implementation.
+Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
+the migration process. A successful migration can leave both the old and new indices present, so the old
+index may be deleted. While you can delete these indices manually, the endpoint applies a deletion policy
+to the relevant index, causing it to be deleted after 30 days, and removes other migration-specific artifacts.
*/
alertsMigrationCleanup(props: AlertsMigrationCleanupProps, kibanaSpace: string = 'default') {
@@ -108,8 +108,12 @@ rules and alerts without calling this API.
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
/**
- * Initiate a migration of detection alerts.
-Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly.
+ * **DEPRECATED.** Legacy API for on-demand reindexing of old `.siem-signals-*` alert indices. Do not build new
+integrations; upgrade the Elastic Stack and rely on product-managed data lifecycle instead.
+**WARNING:** Migrations can be resource intensive and should be planned during a maintenance window.
+
+Initiate a migration of detection alerts. Migrations are initiated per index. The process is not destructive
+and should not remove existing data, but it can consume significant cluster resources. Plan capacity accordingly.
*/
createAlertsMigration(props: CreateAlertsMigrationProps, kibanaSpace: string = 'default') {
@@ -185,6 +189,12 @@ For detailed information on Kibana actions and alerting, and additional API call
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.send(props.body as object);
},
+ /**
+ * Permanently deletes the Elastic Security alerts backing index in the current space, including the alerts
+stored in it. Use with caution; prefer lifecycle policies or the UI when available.
+Call `GET /api/detection_engine/index` first to confirm the index that will be removed.
+
+ */
deleteAlertsIndex(kibanaSpace: string = 'default') {
return supertest
.delete(getRouteUrlForSpace('/api/detection_engine/index', kibanaSpace))
@@ -233,9 +243,12 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
.query(props.query);
},
/**
- * Finalize successful migrations of detection alerts. This replaces the original index's alias with the successfully migrated index's alias.
-The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion,
-finalize it.
+ * **DEPRECATED.** Completes a legacy alert index migration. Do not automate against this in new code.
+**WARNING:** Finalizing swaps read aliases; confirm the migration has finished successfully before calling.
+
+Finalize successful migrations of detection alerts. This replaces the original index's alias with the
+successfully migrated index's alias. The endpoint is idempotent, so you can poll until a migration
+finishes and then call this operation once.
*/
finalizeAlertsMigration(props: FinalizeAlertsMigrationProps, kibanaSpace: string = 'default') {
@@ -343,6 +356,12 @@ The edit action is idempotent, meaning that if you add a tag to a rule that alre
.send(props.body as object)
.query(props.query);
},
+ /**
+ * Returns the backing Elasticsearch index for Elastic Security detection alerts in the current space, and
+whether its mapping is outdated. Use this to verify that an alert index is provisioned before creating
+or running rules that write alerts to it.
+
+ */
readAlertsIndex(kibanaSpace: string = 'default') {
return supertest
.get(getRouteUrlForSpace('/api/detection_engine/index', kibanaSpace))
@@ -351,8 +370,14 @@ The edit action is idempotent, meaning that if you add a tag to a rule that alre
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
/**
- * Retrieve indices that contain detection alerts of a particular age, along with migration information for each of those indices.
- */
+ * **DEPRECATED.** This endpoint was used for historical `.siem-signals-*` index migration workflows. Do not use
+for new automations; there is no supported replacement in this public API.
+**WARNING:** Prefer upgrading through supported Elastic stack upgrades rather than ad-hoc index migrations.
+
+Retrieves indices that contain detection alerts of a particular age, along with migration information for
+each of those indices.
+
+ */
readAlertsMigrationStatus(
props: ReadAlertsMigrationStatusProps,
kibanaSpace: string = 'default'
@@ -436,6 +461,12 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
.set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
+ /**
+ * Simulates a detection rule using the same rule type and query logic as a persisted rule, over a short
+time window, without persisting a rule or writing alerts. Use the response to validate queries, see sample
+matching documents, and inspect execution logs. Pair `invocationCount` and `timeframeEnd` to cap run time.
+
+ */
rulePreview(props: RulePreviewProps, kibanaSpace: string = 'default') {
return supertest
.post(getRouteUrlForSpace('/api/detection_engine/rules/preview', kibanaSpace))
@@ -493,7 +524,7 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
.send(props.body as object);
},
/**
- * And tags to detection alerts, and remove them from alerts.
+ * Add tags to detection alerts, and remove them from alerts, by alert IDs or a query, in a single request.
> info
> You cannot add and remove the same alert tag in the same request.
diff --git a/x-pack/solutions/security/packages/test-api-clients/supertest/lists.gen.ts b/x-pack/solutions/security/packages/test-api-clients/supertest/lists.gen.ts
index 4be0818f8a5fc..0e2302127a8c7 100644
--- a/x-pack/solutions/security/packages/test-api-clients/supertest/lists.gen.ts
+++ b/x-pack/solutions/security/packages/test-api-clients/supertest/lists.gen.ts
@@ -53,8 +53,14 @@ const securitySolutionApiServiceFactory = (supertest: SuperTest.Agent) => ({
.send(props.body as object);
},
/**
- * Create `.lists` and `.items` data streams in the relevant space.
- */
+ * **DEPRECATED.** `deprecated: true` is set on this operation. Value list backing data streams for the space
+are now created as part of supported workflows; calling this explicitly is rarely required.
+**WARNING:** Do not use for new integrations. Prefer the UI or the list and list-item APIs after confirming
+indices exist with `GET /api/lists/index`.
+
+Creates the `.lists` and `.items` data streams in the current Kibana space.
+
+ */
createListIndex(kibanaSpace: string = 'default') {
return supertest
.post(getRouteUrlForSpace('/api/lists/index', kibanaSpace))
@@ -214,6 +220,12 @@ You can import items to a new or existing list.
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
+ /**
+ * Returns the caller's authentication state and the Elasticsearch `cluster`, `index`, and `application`
+privileges for `.lists` and `.items` data streams in the current Kibana space. Use this to decide which list
+APIs (`read` vs `all` operations) are available before you create or import lists.
+
+ */
readListPrivileges(kibanaSpace: string = 'default') {
return supertest
.get(getRouteUrlForSpace('/api/lists/privileges', kibanaSpace))
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml
index 78a2098155c48..2b2eeb63c8db3 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml
@@ -13,7 +13,10 @@ paths:
Assign users to detection alerts, and unassign them from alerts.
> info
> You cannot add and remove the same assignee in the same request.
+ tags:
+ - Alerts API
requestBody:
+ description: User profile IDs to add or remove on each listed alert document ID.
required: true
content:
application/json:
@@ -28,24 +31,72 @@ paths:
200:
description: Indicates a successful call.
content:
- application/ndjson:
+ application/json:
+ description: Elasticsearch update by query or update by IDs response
examples:
add:
value:
- took: 76,
- timed_out: false,
- total: 1,
- updated: 1,
- deleted: 0,
- batches: 1,
- version_conflicts: 0,
- noops: 0,
+ took: 76
+ timed_out: false
+ total: 1
+ updated: 1
+ deleted: 0
+ batches: 1
+ version_conflicts: 0
+ noops: 0
retries:
- - bulk: 0,
- - search: 0
- throttled_millis: 0,
- requests_per_second: -1,
- throttled_until_millis: 0,
+ bulk: 0
+ search: 0
+ throttled_millis: 0
+ requests_per_second: -1
+ throttled_until_millis: 0
failures: []
400:
- description: Invalid request.
+ description: Invalid input data response
+ content:
+ application/json:
+ schema:
+ oneOf:
+ - $ref: '../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ - $ref: '../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: '[request body].ids: at least one alert id is required to update assignees'
+ 401:
+ description: Unsuccessful authentication response
+ content:
+ application/json:
+ schema:
+ $ref: '../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
+ 403:
+ description: Not enough privileges response
+ content:
+ application/json:
+ schema:
+ $ref: '../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ forbidden:
+ value:
+ statusCode: 403
+ error: Forbidden
+ message: 'API [POST /api/detection_engine/signals/assignees] is unauthorized for the current user, this action is granted by the Kibana Security Solution privileges for cases and detections'
+ 500:
+ description: Internal server error response
+ content:
+ application/json:
+ schema:
+ $ref: '../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml
index df7324451ee21..329134f15ab9d 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml
@@ -10,7 +10,7 @@ paths:
x-codegen-enabled: true
summary: Add and remove detection alert tags
description: |
- And tags to detection alerts, and remove them from alerts.
+ Add tags to detection alerts, and remove them from alerts, by alert IDs or a query, in a single request.
> info
> You cannot add and remove the same alert tag in the same request.
tags:
@@ -62,15 +62,32 @@ paths:
oneOf:
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: '[request body].tags: cannot add and remove the same tag in a single request'
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/create_index/create_index.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/create_index/create_index.schema.yaml
index c66e44baf8256..f8e9fcba3dcd7 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/create_index/create_index.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/create_index/create_index.schema.yaml
@@ -26,27 +26,52 @@ paths:
acknowledged:
type: boolean
required: [acknowledged]
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
403:
description: Not enough permissions response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ forbidden:
+ value:
+ message: "API [POST /api/detection_engine/index] is unauthorized for the current user. The user must be able to create indices for the Elastic Security solution."
+ status_code: 403
404:
description: Not found
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ notFound:
+ value:
+ message: A prerequisite resource required to create the alerts index was not found.
+ status_code: 404
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/delete_index/delete_index.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/delete_index/delete_index.schema.yaml
index 7cdb02632535e..b832e5f5ae188 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/delete_index/delete_index.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/delete_index/delete_index.schema.yaml
@@ -9,6 +9,10 @@ paths:
operationId: DeleteAlertsIndex
x-codegen-enabled: true
summary: Delete an alerts index
+ description: |
+ Permanently deletes the Elastic Security alerts backing index in the current space, including the alerts
+ stored in it. Use with caution; prefer lifecycle policies or the UI when available.
+ Call `GET /api/detection_engine/index` first to confirm the index that will be removed.
tags:
- Alert index API
responses:
@@ -22,27 +26,52 @@ paths:
acknowledged:
type: boolean
required: [acknowledged]
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
403:
description: Not enough permissions response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ forbidden:
+ value:
+ message: "API [DELETE /api/detection_engine/index] is unauthorized for the current user. The user needs alerts management permissions for the space."
+ status_code: 403
404:
description: Index does not exist response
content:
application/json:
schema:
- type: string
+ $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ notFound:
+ value:
+ message: "The Elastic Security alerts index to delete was not found."
+ status_code: 404
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_index/read_index.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_index/read_index.schema.yaml
index f9a854689c490..b8374b2e37e3f 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_index/read_index.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_index/read_index.schema.yaml
@@ -9,6 +9,10 @@ paths:
operationId: ReadAlertsIndex
x-codegen-enabled: true
summary: Reads the alert index name if it exists
+ description: |
+ Returns the backing Elasticsearch index for Elastic Security detection alerts in the current space, and
+ whether its mapping is outdated. Use this to verify that an alert index is provisioned before creating
+ or running rules that write alerts to it.
tags:
- Alert index API
responses:
@@ -36,21 +40,42 @@ paths:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
403:
description: Not enough permissions response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ forbidden:
+ value:
+ message: "API [GET /api/detection_engine/index] is unauthorized for the current user. Check Security and Kibana feature privileges (detection engine / alerts) for the space."
+ status_code: 403
404:
description: Not found
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ notFound:
+ value:
+ message: "Elastic Security alert index is not found for the current space."
+ status_code: 404
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_privileges/read_privileges.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_privileges/read_privileges.schema.yaml
index 02239060325dc..4a4b3c7f9a546 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_privileges/read_privileges.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/index_management/read_privileges/read_privileges.schema.yaml
@@ -71,9 +71,20 @@ paths:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml
index 0aecb59d1772d..82d5186ddf1c3 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml
@@ -46,3 +46,32 @@ paths:
application/json:
schema:
$ref: '../../../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/RuleResponse'
+ examples:
+ deletedRule:
+ summary: Response shape after a rule is deleted
+ value:
+ id: c41d170b-8ba6-4de6-b8ec-76440a35ace3
+ updated_at: '2020-02-03T11:19:04.462Z'
+ updated_by: elastic
+ name: 'MS Office child process'
+ rule_id: process_started_by_ms_office_user_folder
+ description: 'Process started by MS Office program in user folder'
+ enabled: false
+ immutable: false
+ version: 3
+ tags: [tag]
+ type: query
+ language: kuery
+ query: 'event.action:Process*'
+ risk_score: 50
+ severity: low
+ from: 'now-4200s'
+ to: 'now'
+ max_signals: 100
+ references: []
+ false_positives: []
+ interval: 1h
+ actions: []
+ throttle: null
+ created_at: '2020-02-03T11:19:04.259Z'
+ created_by: elastic
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml
index b8b8c869f520c..2305513f30d4e 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml
@@ -73,6 +73,13 @@ paths:
rule_id:
$ref: '../../model/rule_schema/common_attributes.schema.yaml#/components/schemas/RuleSignatureId'
description: Array of objects with a rule's `rule_id` field. Do not use rule's `id` here. Exports all rules when unspecified.
+ examples:
+ exportByRuleIds:
+ summary: Request body to export a subset of rules
+ value:
+ objects:
+ - rule_id: 343580b5-c811-447c-8d2d-2ccf052c6900
+ - rule_id: 2938c9fa-53eb-4c04-b79c-33cbf041b18d
responses:
200:
description: Indicates a successful call.
@@ -85,3 +92,9 @@ paths:
An `.ndjson` file containing the returned rules.
Each line in the file represents an object (a rule, exception list parent container, or exception list item), and the last line includes a summary of what was exported.
+ examples:
+ sampleNdjson:
+ value: |
+ {"rule_id":"343580b5-c811-447c-8d2d-2ccf052c6900","name":"Example rule","type":"query","enabled":true}
+ {"exception_list":true}
+ {"export_summary":{"total_rules":1,"exceptions_count":0}}
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.gen.ts
index c5343dd68deb0..6b84e426a2488 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.gen.ts
@@ -46,6 +46,12 @@ export const FindRulesSortFieldEnum = FindRulesSortField.enum;
export const FindRulesRequestQuery = lazySchema(() =>
z.object({
+ /**
+ * List of `alert.attributes` field names to return for each rule (for example `name`, `enabled`).
+If omitted, the default field set is returned. Repeat the parameter to pass multiple field names, or
+use comma-separated values when supported by your client.
+
+ */
fields: ArrayFromString(z.string()).optional(),
/**
* Search query
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml
index 171d2cd64e08e..e4c979a699121 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml
@@ -16,6 +16,10 @@ paths:
- name: 'fields'
in: query
required: false
+ description: |
+ List of `alert.attributes` field names to return for each rule (for example `name`, `enabled`).
+ If omitted, the default field set is returned. Repeat the parameter to pass multiple field names, or
+ use comma-separated values when supported by your client.
schema:
type: array
items:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml
index cb93acf2359ff..e7b0391234f20 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml
@@ -46,6 +46,11 @@ paths:
type: string
format: binary
description: The `.ndjson` file containing the rules.
+ examples:
+ rulesFile:
+ summary: Multipart part containing a rule export
+ value:
+ file: rules_import.ndjson
parameters:
- name: overwrite
in: query
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_preview/rule_preview.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_preview/rule_preview.schema.yaml
index c680fc6b89459..56ea6d2074c24 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_preview/rule_preview.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_preview/rule_preview.schema.yaml
@@ -9,6 +9,10 @@ paths:
operationId: RulePreview
x-codegen-enabled: true
summary: Preview rule alerts generated on specified time range
+ description: |
+ Simulates a detection rule using the same rule type and query logic as a persisted rule, over a short
+ time window, without persisting a rule or writing alerts. Use the response to validate queries, see sample
+ matching documents, and inspect execution logs. Pair `invocationCount` and `timeframeEnd` to cap run time.
tags:
- Rule preview API
parameters:
@@ -19,7 +23,10 @@ paths:
schema:
type: boolean
requestBody:
- description: An object containing tags to add or remove and alert ids the changes will be applied
+ description: |
+ Rule create payload (same shape as `POST /api/detection_engine/rules` for a given `type`) plus
+ `invocationCount` and `timeframeEnd` to control how the preview is executed. Optional
+ `enable_logged_requests` surfaces Elasticsearch request logging for debugging.
required: true
content:
application/json:
@@ -51,6 +58,22 @@ paths:
- allOf:
- $ref: '../model/rule_schema/rule_schemas.schema.yaml#/components/schemas/EsqlRuleCreateProps'
- $ref: '#/components/schemas/RulePreviewParams'
+ examples:
+ queryRule:
+ value:
+ type: query
+ name: Rule preview
+ description: Find matching events
+ index: ['logs-*']
+ query: "process.name : *"
+ language: kuery
+ risk_score: 25
+ severity: low
+ from: 'now-24h'
+ to: now
+ max_signals: 20
+ invocationCount: 1
+ timeframeEnd: '2025-01-20T12:00:00.000Z'
responses:
200:
description: Successful response
@@ -68,6 +91,17 @@ paths:
isAborted:
type: boolean
required: [logs]
+ examples:
+ success:
+ value:
+ isAborted: false
+ previewId: 7f1c9d1e-4c8a-4a3e-9a5d-0d4f6e1b2a90
+ logs:
+ - errors: []
+ warnings: []
+ duration: 45
+ startedAt: 2025-01-20T10:00:00.000Z
+ requests: []
400:
description: Invalid input data response
content:
@@ -76,18 +110,35 @@ paths:
oneOf:
- $ref: '../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: '[request body].timeframeEnd: expected string, received null'
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
components:
schemas:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml
index 7b403ba89153b..86002668be076 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml
@@ -91,18 +91,35 @@ paths:
oneOf:
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: 'Failed to parse search request: unknown query clause in bool filter'
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
components:
schemas:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml
index 9157175d2dafe..0e1086fb166db 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml
@@ -109,18 +109,35 @@ paths:
oneOf:
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: '[request body].signal_ids: at least one alert id is required to update status'
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
components:
schemas:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml
index 0196e031f8724..e467da961cc75 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml
@@ -11,8 +11,12 @@ paths:
summary: Initiate a detection alert migration
deprecated: true
description: |
- Initiate a migration of detection alerts.
- Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly.
+ **DEPRECATED.** Legacy API for on-demand reindexing of old `.siem-signals-*` alert indices. Do not build new
+ integrations; upgrade the Elastic Stack and rely on product-managed data lifecycle instead.
+ **WARNING:** Migrations can be resource intensive and should be planned during a maintenance window.
+
+ Initiate a migration of detection alerts. Migrations are initiated per index. The process is not destructive
+ and should not remove existing data, but it can consume significant cluster resources. Plan capacity accordingly.
tags:
- Alerts migration API
requestBody:
@@ -69,18 +73,35 @@ paths:
oneOf:
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: '[request body].index: at least one index name is required to start a migration'
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
components:
schemas:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml
index 458f594091ddd..8b79c349368d4 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml
@@ -11,13 +11,13 @@ paths:
summary: Clean up detection alert migrations
deprecated: true
description: |
- Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
- the migration process. A successful migration will result in both the old and new indices being present.
- As such, the old, orphaned index can (and likely should) be deleted.
+ **DEPRECATED.** Cleanup API for old migration artifacts. Do not add new call sites.
+ **WARNING:** This schedules deletions; ensure no production reads still point at the source index.
- While you can delete these indices manually,
- the endpoint accomplishes this task by applying a deletion policy to the relevant index, causing it to be deleted
- after 30 days. It also deletes other artifacts specific to the migration implementation.
+ Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
+ the migration process. A successful migration can leave both the old and new indices present, so the old
+ index may be deleted. While you can delete these indices manually, the endpoint applies a deletion policy
+ to the relevant index, causing it to be deleted after 30 days, and removes other migration-specific artifacts.
tags:
- Alerts migration API
requestBody:
@@ -37,6 +37,10 @@ paths:
required: [migration_ids]
example:
migration_ids: [924f7c50-505f-11eb-ae0a-3fa2e626a51d]
+ examples:
+ cleanupMigrations:
+ value:
+ migration_ids: [924f7c50-505f-11eb-ae0a-3fa2e626a51d]
responses:
200:
description: Successful response
@@ -64,18 +68,35 @@ paths:
oneOf:
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: '[request body].migration_ids: at least one migration id is required to run cleanup'
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
components:
schemas:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml
index 03ec7e4813227..b45f0f847304b 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml
@@ -11,9 +11,12 @@ paths:
summary: Finalize detection alert migrations
deprecated: true
description: |
- Finalize successful migrations of detection alerts. This replaces the original index's alias with the successfully migrated index's alias.
- The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion,
- finalize it.
+ **DEPRECATED.** Completes a legacy alert index migration. Do not automate against this in new code.
+ **WARNING:** Finalizing swaps read aliases; confirm the migration has finished successfully before calling.
+
+ Finalize successful migrations of detection alerts. This replaces the original index's alias with the
+ successfully migrated index's alias. The endpoint is idempotent, so you can poll until a migration
+ finishes and then call this operation once.
tags:
- Alerts migration API
requestBody:
@@ -33,6 +36,10 @@ paths:
required: [migration_ids]
example:
migration_ids: ['924f7c50-505f-11eb-ae0a-3fa2e626a51d']
+ examples:
+ oneMigration:
+ value:
+ migration_ids: ['924f7c50-505f-11eb-ae0a-3fa2e626a51d']
responses:
200:
description: Successful response
@@ -61,18 +68,35 @@ paths:
oneOf:
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: '[request body].migration_ids: at least one migration id is required to finalize'
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
components:
schemas:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/read_signals_migration_status/read_signals_migration_status.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/read_signals_migration_status/read_signals_migration_status.schema.yaml
index 27688f9867f4b..8ad56a55f5969 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/read_signals_migration_status/read_signals_migration_status.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/signals_migration/read_signals_migration_status/read_signals_migration_status.schema.yaml
@@ -10,7 +10,13 @@ paths:
x-codegen-enabled: true
summary: Retrieve the status of detection alert migrations
deprecated: true
- description: Retrieve indices that contain detection alerts of a particular age, along with migration information for each of those indices.
+ description: |
+ **DEPRECATED.** This endpoint was used for historical `.siem-signals-*` index migration workflows. Do not use
+ for new automations; there is no supported replacement in this public API.
+ **WARNING:** Prefer upgrading through supported Elastic stack upgrades rather than ad-hoc index migrations.
+
+ Retrieves indices that contain detection alerts of a particular age, along with migration information for
+ each of those indices.
tags:
- Alerts migration API
parameters:
@@ -70,18 +76,35 @@ paths:
oneOf:
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
- $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ badRequest:
+ value:
+ statusCode: 400
+ error: Bad Request
+ message: '[request query].from: expected date-math, received null'
401:
description: Unsuccessful authentication response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse'
+ examples:
+ unauthorized:
+ value:
+ statusCode: 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]"
500:
description: Internal server error response
content:
application/json:
schema:
$ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse'
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
components:
schemas:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts
index be17a724e287f..2fa2d404e632c 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts
@@ -575,13 +575,13 @@ export class Client {
this.log = options.log;
}
/**
- * Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
-the migration process. A successful migration will result in both the old and new indices being present.
-As such, the old, orphaned index can (and likely should) be deleted.
+ * **DEPRECATED.** Cleanup API for old migration artifacts. Do not add new call sites.
+**WARNING:** This schedules deletions; ensure no production reads still point at the source index.
-While you can delete these indices manually,
-the endpoint accomplishes this task by applying a deletion policy to the relevant index, causing it to be deleted
-after 30 days. It also deletes other artifacts specific to the migration implementation.
+Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of
+the migration process. A successful migration can leave both the old and new indices present, so the old
+index may be deleted. While you can delete these indices manually, the endpoint applies a deletion policy
+to the relevant index, causing it to be deleted after 30 days, and removes other migration-specific artifacts.
*/
async alertsMigrationCleanup(props: AlertsMigrationCleanupProps) {
@@ -784,8 +784,12 @@ rules and alerts without calling this API.
.catch(catchAxiosErrorFormatAndThrow);
}
/**
- * Initiate a migration of detection alerts.
-Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly.
+ * **DEPRECATED.** Legacy API for on-demand reindexing of old `.siem-signals-*` alert indices. Do not build new
+integrations; upgrade the Elastic Stack and rely on product-managed data lifecycle instead.
+**WARNING:** Migrations can be resource intensive and should be planned during a maintenance window.
+
+Initiate a migration of detection alerts. Migrations are initiated per index. The process is not destructive
+and should not remove existing data, but it can consume significant cluster resources. Plan capacity accordingly.
*/
async createAlertsMigration(props: CreateAlertsMigrationProps) {
@@ -1085,6 +1089,12 @@ For detailed information on Kibana actions and alerting, and additional API call
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Permanently deletes the Elastic Security alerts backing index in the current space, including the alerts
+stored in it. Use with caution; prefer lifecycle policies or the UI when available.
+Call `GET /api/detection_engine/index` first to confirm the index that will be removed.
+
+ */
async deleteAlertsIndex() {
this.log.info(`${new Date().toISOString()} Calling API DeleteAlertsIndex`);
return this.kbnClient
@@ -1668,9 +1678,12 @@ The entity will be immediately deleted from the latest index. It will remain av
.catch(catchAxiosErrorFormatAndThrow);
}
/**
- * Finalize successful migrations of detection alerts. This replaces the original index's alias with the successfully migrated index's alias.
-The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion,
-finalize it.
+ * **DEPRECATED.** Completes a legacy alert index migration. Do not automate against this in new code.
+**WARNING:** Finalizing swaps read aliases; confirm the migration has finished successfully before calling.
+
+Finalize successful migrations of detection alerts. This replaces the original index's alias with the
+successfully migrated index's alias. The endpoint is idempotent, so you can poll until a migration
+finishes and then call this operation once.
*/
async finalizeAlertsMigration(props: FinalizeAlertsMigrationProps) {
@@ -2849,6 +2862,12 @@ Requires the **Timeline and Notes** write privilege (`notes_write`).
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Returns the backing Elasticsearch index for Elastic Security detection alerts in the current space, and
+whether its mapping is outdated. Use this to verify that an alert index is provisioned before creating
+or running rules that write alerts to it.
+
+ */
async readAlertsIndex() {
this.log.info(`${new Date().toISOString()} Calling API ReadAlertsIndex`);
return this.kbnClient
@@ -2862,8 +2881,14 @@ Requires the **Timeline and Notes** write privilege (`notes_write`).
.catch(catchAxiosErrorFormatAndThrow);
}
/**
- * Retrieve indices that contain detection alerts of a particular age, along with migration information for each of those indices.
- */
+ * **DEPRECATED.** This endpoint was used for historical `.siem-signals-*` index migration workflows. Do not use
+for new automations; there is no supported replacement in this public API.
+**WARNING:** Prefer upgrading through supported Elastic stack upgrades rather than ad-hoc index migrations.
+
+Retrieves indices that contain detection alerts of a particular age, along with migration information for
+each of those indices.
+
+ */
async readAlertsMigrationStatus(props: ReadAlertsMigrationStatusProps) {
this.log.info(`${new Date().toISOString()} Calling API ReadAlertsMigrationStatus`);
return this.kbnClient
@@ -3031,6 +3056,12 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Simulates a detection rule using the same rule type and query logic as a persisted rule, over a short
+time window, without persisting a rule or writing alerts. Use the response to validate queries, see sample
+matching documents, and inspect execution logs. Pair `invocationCount` and `timeframeEnd` to cap run time.
+
+ */
async rulePreview(props: RulePreviewProps) {
this.log.info(`${new Date().toISOString()} Calling API RulePreview`);
return this.kbnClient
@@ -3185,7 +3216,7 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
.catch(catchAxiosErrorFormatAndThrow);
}
/**
- * And tags to detection alerts, and remove them from alerts.
+ * Add tags to detection alerts, and remove them from alerts, by alert IDs or a query, in a single request.
> info
> You cannot add and remove the same alert tag in the same request.
diff --git a/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml
index a53f0d9f25a0b..b2630bfbfeb9a 100644
--- a/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml
@@ -18,11 +18,24 @@ servers:
paths:
/api/detection_engine/index:
delete:
+ description: >
+ Permanently deletes the Elastic Security alerts backing index in the
+ current space, including the alerts
+
+ stored in it. Use with caution; prefer lifecycle policies or the UI when
+ available.
+
+ Call `GET /api/detection_engine/index` first to confirm the index that
+ will be removed.
operationId: DeleteAlertsIndex
responses:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -34,24 +47,48 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ message: >-
+ API [DELETE /api/detection_engine/index] is unauthorized
+ for the current user. The user needs alerts management
+ permissions for the space.
+ status_code: 403
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Not enough permissions response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: The Elastic Security alerts index to delete was not found.
+ status_code: 404
schema:
- type: string
+ $ref: '#/components/schemas/SiemErrorResponse'
description: Index does not exist response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -60,6 +97,14 @@ paths:
- Security Detections API
- Alert index API
get:
+ description: >
+ Returns the backing Elasticsearch index for Elastic Security detection
+ alerts in the current space, and
+
+ whether its mapping is outdated. Use this to verify that an alert index
+ is provisioned before creating
+
+ or running rules that write alerts to it.
operationId: ReadAlertsIndex
responses:
'200':
@@ -85,24 +130,50 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ message: >-
+ API [GET /api/detection_engine/index] is unauthorized for
+ the current user. Check Security and Kibana feature
+ privileges (detection engine / alerts) for the space.
+ status_code: 403
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Not enough permissions response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: >-
+ Elastic Security alert index is not found for the current
+ space.
+ status_code: 404
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Not found
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -120,6 +191,10 @@ paths:
'200':
content:
application/json:
+ examples:
+ acknowledged:
+ value:
+ acknowledged: true
schema:
type: object
properties:
@@ -131,24 +206,50 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'403':
content:
application/json:
+ examples:
+ forbidden:
+ value:
+ message: >-
+ API [POST /api/detection_engine/index] is unauthorized for
+ the current user. The user must be able to create indices
+ for the Elastic Security solution.
+ status_code: 403
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Not enough permissions response
'404':
content:
application/json:
+ examples:
+ notFound:
+ value:
+ message: >-
+ A prerequisite resource required to create the alerts
+ index was not found.
+ status_code: 404
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Not found
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -222,12 +323,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -271,6 +383,36 @@ paths:
'200':
content:
application/json:
+ examples:
+ deletedRule:
+ summary: Response shape after a rule is deleted
+ value:
+ actions: []
+ created_at: '2020-02-03T11:19:04.259Z'
+ created_by: elastic
+ description: Process started by MS Office program in user folder
+ enabled: false
+ false_positives: []
+ from: now-4200s
+ id: c41d170b-8ba6-4de6-b8ec-76440a35ace3
+ immutable: false
+ interval: 1h
+ language: kuery
+ max_signals: 100
+ name: MS Office child process
+ query: event.action:Process*
+ references: []
+ risk_score: 50
+ rule_id: process_started_by_ms_office_user_folder
+ severity: low
+ tags:
+ - tag
+ throttle: null
+ to: now
+ type: query
+ updated_at: '2020-02-03T11:19:04.462Z'
+ updated_by: elastic
+ version: 3
schema:
$ref: '#/components/schemas/RuleResponse'
description: Indicates a successful call.
@@ -2899,6 +3041,13 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ exportByRuleIds:
+ summary: Request body to export a subset of rules
+ value:
+ objects:
+ - rule_id: 343580b5-c811-447c-8d2d-2ccf052c6900
+ - rule_id: 2938c9fa-53eb-4c04-b79c-33cbf041b18d
schema:
nullable: true
type: object
@@ -2922,6 +3071,15 @@ paths:
'200':
content:
application/ndjson:
+ examples:
+ sampleNdjson:
+ value: >
+ {"rule_id":"343580b5-c811-447c-8d2d-2ccf052c6900","name":"Example
+ rule","type":"query","enabled":true}
+
+ {"exception_list":true}
+
+ {"export_summary":{"total_rules":1,"exceptions_count":0}}
schema:
description: >
An `.ndjson` file containing the returned rules.
@@ -2961,7 +3119,15 @@ paths:
is returned, with 20 results per page.
operationId: FindRules
parameters:
- - in: query
+ - description: >
+ List of `alert.attributes` field names to return for each rule (for
+ example `name`, `enabled`).
+
+ If omitted, the default field set is returned. Repeat the parameter
+ to pass multiple field names, or
+
+ use comma-separated values when supported by your client.
+ in: query
name: fields
required: false
schema:
@@ -3270,6 +3436,11 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ rulesFile:
+ summary: Multipart part containing a rule export
+ value:
+ file: rules_import.ndjson
schema:
type: object
properties:
@@ -3504,6 +3675,15 @@ paths:
- Prebuilt Rules API
/api/detection_engine/rules/preview:
post:
+ description: >
+ Simulates a detection rule using the same rule type and query logic as a
+ persisted rule, over a short
+
+ time window, without persisting a rule or writing alerts. Use the
+ response to validate queries, see sample
+
+ matching documents, and inspect execution logs. Pair `invocationCount`
+ and `timeframeEnd` to cap run time.
operationId: RulePreview
parameters:
- description: >-
@@ -3517,6 +3697,23 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ queryRule:
+ value:
+ description: Find matching events
+ from: now-24h
+ index:
+ - logs-*
+ invocationCount: 1
+ language: kuery
+ max_signals: 20
+ name: Rule preview
+ query: 'process.name : *'
+ risk_score: 25
+ severity: low
+ timeframeEnd: '2025-01-20T12:00:00.000Z'
+ to: now
+ type: query
schema:
anyOf:
- allOf:
@@ -3545,14 +3742,31 @@ paths:
- $ref: '#/components/schemas/RulePreviewParams'
discriminator:
propertyName: type
- description: >-
- An object containing tags to add or remove and alert ids the changes
- will be applied
+ description: >
+ Rule create payload (same shape as `POST /api/detection_engine/rules`
+ for a given `type`) plus
+
+ `invocationCount` and `timeframeEnd` to control how the preview is
+ executed. Optional
+
+ `enable_logged_requests` surfaces Elasticsearch request logging for
+ debugging.
required: true
responses:
'200':
content:
application/json:
+ examples:
+ success:
+ value:
+ isAborted: false
+ logs:
+ - duration: 45
+ errors: []
+ requests: []
+ startedAt: 2025-01-20T10:00:00.000Z
+ warnings: []
+ previewId: 7f1c9d1e-4c8a-4a3e-9a5d-0d4f6e1b2a90
schema:
type: object
properties:
@@ -3570,6 +3784,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].timeframeEnd: expected string, received
+ null
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3578,12 +3800,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -3608,50 +3841,118 @@ paths:
$ref: '#/components/examples/SetAlertAssigneesBodyRemove'
schema:
$ref: '#/components/schemas/SetAlertAssigneesBody'
+ description: User profile IDs to add or remove on each listed alert document ID.
required: true
responses:
'200':
content:
- application/ndjson:
+ application/json:
+ description: Elasticsearch update by query or update by IDs response
examples:
add:
value:
- batches: 1,
- deleted: 0,
+ batches: 1
+ deleted: 0
failures: []
- noops: 0,
- requests_per_second: '-1,'
+ noops: 0
+ requests_per_second: -1
retries:
- - bulk: 0,
- - search: 0
- throttled_millis: 0,
- throttled_until_millis: 0,
- timed_out: false,
- took: 76,
- total: 1,
- updated: 1,
- version_conflicts: 0,
+ bulk: 0
+ search: 0
+ throttled_millis: 0
+ throttled_until_millis: 0
+ timed_out: false
+ took: 76
+ total: 1
+ updated: 1
+ version_conflicts: 0
description: Indicates a successful call.
'400':
- description: Invalid request.
+ content:
+ application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].ids: at least one alert id is required to
+ update assignees
+ statusCode: 400
+ schema:
+ oneOf:
+ - $ref: '#/components/schemas/PlatformErrorResponse'
+ - $ref: '#/components/schemas/SiemErrorResponse'
+ description: Invalid input data response
+ '401':
+ content:
+ application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
+ schema:
+ $ref: '#/components/schemas/PlatformErrorResponse'
+ description: Unsuccessful authentication response
+ '403':
+ content:
+ application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: >-
+ API [POST /api/detection_engine/signals/assignees] is
+ unauthorized for the current user, this action is granted
+ by the Kibana Security Solution privileges for cases and
+ detections
+ statusCode: 403
+ schema:
+ $ref: '#/components/schemas/PlatformErrorResponse'
+ description: Not enough privileges response
+ '500':
+ content:
+ application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
+ schema:
+ $ref: '#/components/schemas/SiemErrorResponse'
+ description: Internal server error response
summary: Assign and unassign users from detection alerts
tags:
- Security Detections API
+ - Alerts API
/api/detection_engine/signals/finalize_migration:
post:
deprecated: true
description: >
+ **DEPRECATED.** Completes a legacy alert index migration. Do not
+ automate against this in new code.
+
+ **WARNING:** Finalizing swaps read aliases; confirm the migration has
+ finished successfully before calling.
+
+
Finalize successful migrations of detection alerts. This replaces the
- original index's alias with the successfully migrated index's alias.
+ original index's alias with the
- The endpoint is idempotent; therefore, it can safely be used to poll a
- given migration and, upon completion,
+ successfully migrated index's alias. The endpoint is idempotent, so you
+ can poll until a migration
- finalize it.
+ finishes and then call this operation once.
operationId: FinalizeAlertsMigration
requestBody:
content:
application/json:
+ examples:
+ oneMigration:
+ value:
+ migration_ids:
+ - 924f7c50-505f-11eb-ae0a-3fa2e626a51d
schema:
example:
migration_ids:
@@ -3691,6 +3992,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].migration_ids: at least one migration id is
+ required to finalize
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3699,12 +4008,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -3716,26 +4036,33 @@ paths:
delete:
deprecated: true
description: >
- Migrations favor data integrity over shard size. Consequently, unused or
- orphaned indices are artifacts of
+ **DEPRECATED.** Cleanup API for old migration artifacts. Do not add new
+ call sites.
- the migration process. A successful migration will result in both the
- old and new indices being present.
+ **WARNING:** This schedules deletions; ensure no production reads still
+ point at the source index.
- As such, the old, orphaned index can (and likely should) be deleted.
+ Migrations favor data integrity over shard size. Consequently, unused or
+ orphaned indices are artifacts of
- While you can delete these indices manually,
+ the migration process. A successful migration can leave both the old and
+ new indices present, so the old
- the endpoint accomplishes this task by applying a deletion policy to the
- relevant index, causing it to be deleted
+ index may be deleted. While you can delete these indices manually, the
+ endpoint applies a deletion policy
- after 30 days. It also deletes other artifacts specific to the migration
- implementation.
+ to the relevant index, causing it to be deleted after 30 days, and
+ removes other migration-specific artifacts.
operationId: AlertsMigrationCleanup
requestBody:
content:
application/json:
+ examples:
+ cleanupMigrations:
+ value:
+ migration_ids:
+ - 924f7c50-505f-11eb-ae0a-3fa2e626a51d
schema:
example:
migration_ids:
@@ -3774,6 +4101,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].migration_ids: at least one migration id is
+ required to run cleanup
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3782,12 +4117,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -3798,12 +4144,21 @@ paths:
post:
deprecated: true
description: >
- Initiate a migration of detection alerts.
+ **DEPRECATED.** Legacy API for on-demand reindexing of old
+ `.siem-signals-*` alert indices. Do not build new
+
+ integrations; upgrade the Elastic Stack and rely on product-managed data
+ lifecycle instead.
+
+ **WARNING:** Migrations can be resource intensive and should be planned
+ during a maintenance window.
+
- Migrations are initiated per index. While the process is neither
- destructive nor interferes with existing data, it may be
- resource-intensive. As such, it is recommended that you plan your
- migrations accordingly.
+ Initiate a migration of detection alerts. Migrations are initiated per
+ index. The process is not destructive
+
+ and should not remove existing data, but it can consume significant
+ cluster resources. Plan capacity accordingly.
operationId: CreateAlertsMigration
requestBody:
content:
@@ -3857,6 +4212,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].index: at least one index name is required
+ to start a migration
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3865,12 +4228,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -3881,9 +4255,21 @@ paths:
/api/detection_engine/signals/migration_status:
get:
deprecated: true
- description: >-
- Retrieve indices that contain detection alerts of a particular age,
- along with migration information for each of those indices.
+ description: >
+ **DEPRECATED.** This endpoint was used for historical `.siem-signals-*`
+ index migration workflows. Do not use
+
+ for new automations; there is no supported replacement in this public
+ API.
+
+ **WARNING:** Prefer upgrading through supported Elastic stack upgrades
+ rather than ad-hoc index migrations.
+
+
+ Retrieves indices that contain detection alerts of a particular age,
+ along with migration information for
+
+ each of those indices.
operationId: ReadAlertsMigrationStatus
parameters:
- description: Maximum age of qualifying detection alerts
@@ -3941,6 +4327,12 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: '[request query].from: expected date-math, received null'
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3949,12 +4341,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -4040,6 +4443,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ Failed to parse search request: unknown query clause in
+ bool filter
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -4048,12 +4459,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -4161,6 +4583,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].signal_ids: at least one alert id is
+ required to update status
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -4169,12 +4599,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -4184,9 +4625,12 @@ paths:
- Alerts API
/api/detection_engine/signals/tags:
post:
- description: |
- And tags to detection alerts, and remove them from alerts.
+ description: >
+ Add tags to detection alerts, and remove them from alerts, by alert IDs
+ or a query, in a single request.
+
> info
+
> You cannot add and remove the same alert tag in the same request.
operationId: SetAlertTags
requestBody:
@@ -4233,6 +4677,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].tags: cannot add and remove the same tag in
+ a single request
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -4241,12 +4693,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
diff --git a/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml
index 181feb555dff9..744ddd6caba33 100644
--- a/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml
@@ -82,12 +82,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -131,6 +142,36 @@ paths:
'200':
content:
application/json:
+ examples:
+ deletedRule:
+ summary: Response shape after a rule is deleted
+ value:
+ actions: []
+ created_at: '2020-02-03T11:19:04.259Z'
+ created_by: elastic
+ description: Process started by MS Office program in user folder
+ enabled: false
+ false_positives: []
+ from: now-4200s
+ id: c41d170b-8ba6-4de6-b8ec-76440a35ace3
+ immutable: false
+ interval: 1h
+ language: kuery
+ max_signals: 100
+ name: MS Office child process
+ query: event.action:Process*
+ references: []
+ risk_score: 50
+ rule_id: process_started_by_ms_office_user_folder
+ severity: low
+ tags:
+ - tag
+ throttle: null
+ to: now
+ type: query
+ updated_at: '2020-02-03T11:19:04.462Z'
+ updated_by: elastic
+ version: 3
schema:
$ref: '#/components/schemas/RuleResponse'
description: Indicates a successful call.
@@ -2759,6 +2800,13 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ exportByRuleIds:
+ summary: Request body to export a subset of rules
+ value:
+ objects:
+ - rule_id: 343580b5-c811-447c-8d2d-2ccf052c6900
+ - rule_id: 2938c9fa-53eb-4c04-b79c-33cbf041b18d
schema:
nullable: true
type: object
@@ -2782,6 +2830,15 @@ paths:
'200':
content:
application/ndjson:
+ examples:
+ sampleNdjson:
+ value: >
+ {"rule_id":"343580b5-c811-447c-8d2d-2ccf052c6900","name":"Example
+ rule","type":"query","enabled":true}
+
+ {"exception_list":true}
+
+ {"export_summary":{"total_rules":1,"exceptions_count":0}}
schema:
description: >
An `.ndjson` file containing the returned rules.
@@ -2821,7 +2878,15 @@ paths:
is returned, with 20 results per page.
operationId: FindRules
parameters:
- - in: query
+ - description: >
+ List of `alert.attributes` field names to return for each rule (for
+ example `name`, `enabled`).
+
+ If omitted, the default field set is returned. Repeat the parameter
+ to pass multiple field names, or
+
+ use comma-separated values when supported by your client.
+ in: query
name: fields
required: false
schema:
@@ -3130,6 +3195,11 @@ paths:
requestBody:
content:
multipart/form-data:
+ examples:
+ rulesFile:
+ summary: Multipart part containing a rule export
+ value:
+ file: rules_import.ndjson
schema:
type: object
properties:
@@ -3217,6 +3287,15 @@ paths:
--form "file=@"
/api/detection_engine/rules/preview:
post:
+ description: >
+ Simulates a detection rule using the same rule type and query logic as a
+ persisted rule, over a short
+
+ time window, without persisting a rule or writing alerts. Use the
+ response to validate queries, see sample
+
+ matching documents, and inspect execution logs. Pair `invocationCount`
+ and `timeframeEnd` to cap run time.
operationId: RulePreview
parameters:
- description: >-
@@ -3230,6 +3309,23 @@ paths:
requestBody:
content:
application/json:
+ examples:
+ queryRule:
+ value:
+ description: Find matching events
+ from: now-24h
+ index:
+ - logs-*
+ invocationCount: 1
+ language: kuery
+ max_signals: 20
+ name: Rule preview
+ query: 'process.name : *'
+ risk_score: 25
+ severity: low
+ timeframeEnd: '2025-01-20T12:00:00.000Z'
+ to: now
+ type: query
schema:
anyOf:
- allOf:
@@ -3258,14 +3354,31 @@ paths:
- $ref: '#/components/schemas/RulePreviewParams'
discriminator:
propertyName: type
- description: >-
- An object containing tags to add or remove and alert ids the changes
- will be applied
+ description: >
+ Rule create payload (same shape as `POST /api/detection_engine/rules`
+ for a given `type`) plus
+
+ `invocationCount` and `timeframeEnd` to control how the preview is
+ executed. Optional
+
+ `enable_logged_requests` surfaces Elasticsearch request logging for
+ debugging.
required: true
responses:
'200':
content:
application/json:
+ examples:
+ success:
+ value:
+ isAborted: false
+ logs:
+ - duration: 45
+ errors: []
+ requests: []
+ startedAt: 2025-01-20T10:00:00.000Z
+ warnings: []
+ previewId: 7f1c9d1e-4c8a-4a3e-9a5d-0d4f6e1b2a90
schema:
type: object
properties:
@@ -3283,6 +3396,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].timeframeEnd: expected string, received
+ null
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3291,12 +3412,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -3321,35 +3453,91 @@ paths:
$ref: '#/components/examples/SetAlertAssigneesBodyRemove'
schema:
$ref: '#/components/schemas/SetAlertAssigneesBody'
+ description: User profile IDs to add or remove on each listed alert document ID.
required: true
responses:
'200':
content:
- application/ndjson:
+ application/json:
+ description: Elasticsearch update by query or update by IDs response
examples:
add:
value:
- batches: 1,
- deleted: 0,
+ batches: 1
+ deleted: 0
failures: []
- noops: 0,
- requests_per_second: '-1,'
+ noops: 0
+ requests_per_second: -1
retries:
- - bulk: 0,
- - search: 0
- throttled_millis: 0,
- throttled_until_millis: 0,
- timed_out: false,
- took: 76,
- total: 1,
- updated: 1,
- version_conflicts: 0,
+ bulk: 0
+ search: 0
+ throttled_millis: 0
+ throttled_until_millis: 0
+ timed_out: false
+ took: 76
+ total: 1
+ updated: 1
+ version_conflicts: 0
description: Indicates a successful call.
'400':
- description: Invalid request.
+ content:
+ application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].ids: at least one alert id is required to
+ update assignees
+ statusCode: 400
+ schema:
+ oneOf:
+ - $ref: '#/components/schemas/PlatformErrorResponse'
+ - $ref: '#/components/schemas/SiemErrorResponse'
+ description: Invalid input data response
+ '401':
+ content:
+ application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
+ schema:
+ $ref: '#/components/schemas/PlatformErrorResponse'
+ description: Unsuccessful authentication response
+ '403':
+ content:
+ application/json:
+ examples:
+ forbidden:
+ value:
+ error: Forbidden
+ message: >-
+ API [POST /api/detection_engine/signals/assignees] is
+ unauthorized for the current user, this action is granted
+ by the Kibana Security Solution privileges for cases and
+ detections
+ statusCode: 403
+ schema:
+ $ref: '#/components/schemas/PlatformErrorResponse'
+ description: Not enough privileges response
+ '500':
+ content:
+ application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
+ schema:
+ $ref: '#/components/schemas/SiemErrorResponse'
+ description: Internal server error response
summary: Assign and unassign users from detection alerts
tags:
- Security Detections API
+ - Alerts API
/api/detection_engine/signals/search:
post:
description: Find and/or aggregate detection alerts that match the given query.
@@ -3428,6 +3616,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ Failed to parse search request: unknown query clause in
+ bool filter
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3436,12 +3632,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -3549,6 +3756,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].signal_ids: at least one alert id is
+ required to update status
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3557,12 +3772,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response
@@ -3572,9 +3798,12 @@ paths:
- Alerts API
/api/detection_engine/signals/tags:
post:
- description: |
- And tags to detection alerts, and remove them from alerts.
+ description: >
+ Add tags to detection alerts, and remove them from alerts, by alert IDs
+ or a query, in a single request.
+
> info
+
> You cannot add and remove the same alert tag in the same request.
operationId: SetAlertTags
requestBody:
@@ -3621,6 +3850,14 @@ paths:
'400':
content:
application/json:
+ examples:
+ badRequest:
+ value:
+ error: Bad Request
+ message: >-
+ [request body].tags: cannot add and remove the same tag in
+ a single request
+ statusCode: 400
schema:
oneOf:
- $ref: '#/components/schemas/PlatformErrorResponse'
@@ -3629,12 +3866,23 @@ paths:
'401':
content:
application/json:
+ examples:
+ unauthorized:
+ value:
+ 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
schema:
$ref: '#/components/schemas/PlatformErrorResponse'
description: Unsuccessful authentication response
'500':
content:
application/json:
+ examples:
+ serverError:
+ value:
+ message: Internal Server Error
+ status_code: 500
schema:
$ref: '#/components/schemas/SiemErrorResponse'
description: Internal server error response