diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml index bc71cc8f16492..b3684105ed42d 100644 --- a/oas_docs/output/kibana.serverless.yaml +++ b/oas_docs/output/kibana.serverless.yaml @@ -33134,39 +33134,64 @@ paths: /api/lists: delete: description: | - Delete a list using the list ID. + Delete a value list using the list ID. > info > When you delete a list, all of its list items are also deleted. operationId: DeleteList parameters: - - description: List's `id` value - in: query + - in: query name: id required: true schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - in: query + - description: Determines whether exception items referencing this value list should be deleted. + in: query name: deleteReferences required: false schema: default: false + example: false type: boolean - - in: query + - description: Determines whether to delete value list without performing any additional checks of where this list may be utilized. + in: query name: ignoreReferences required: false schema: default: false + example: false type: boolean responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ipList: + value: + _version: WzIsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: List of bad internet ips. + id: 21b01cfb-058d-44b9-838c-282be16c91cd + immutable: false + name: Bad ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T05:39:39.292Z' + updated_by: elastic + version: 3 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33175,37 +33200,58 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [DELETE /api/lists?id=ip_list] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list id: \"ip_list\" was not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Delete a list + summary: Delete a value list tags: - Security Lists API x-beta: true get: - description: Get the details of a list using the list ID. + description: Get the details of a value list using the list ID. operationId: ReadList parameters: - - description: List's `id` value - in: query + - in: query name: id required: true schema: @@ -33214,12 +33260,34 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzEsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: My bad ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T05:21:53.843Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33228,42 +33296,67 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get list details + summary: Get value list details tags: - Security Lists API x-beta: true patch: - description: Update specific fields of an existing list using the list ID. + description: Update specific fields of an existing list using the list `id`. operationId: PatchList requestBody: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + id: ip_list + name: Bad ips list - UPDATED type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' description: $ref: '#/components/schemas/Security_Lists_API_ListDescription' id: @@ -33273,22 +33366,43 @@ paths: name: $ref: '#/components/schemas/Security_Lists_API_ListName' version: - minimum: 1 - type: integer + $ref: '#/components/schemas/Security_Lists_API_ListVersion' required: - id - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzEsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: This list describes bad internet ips + id: ip_list + immutable: false + name: Bad ips list - UPDATED + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T05:21:53.843Z' + updated_by: elastic + version: 2 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: name: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33297,44 +33411,93 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [PATCH /api/lists] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Patch a list + summary: Patch a value list tags: - Security Lists API x-beta: true post: - description: Create a new list. + description: Create a new value list. operationId: CreateList requestBody: content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + description: This list describes bad internet ips + id: ip_list + name: Simple list with ips + type: ip + ip_range: + value: + description: This list has ip ranges + id: ip_range_list + name: Simple list with ip ranges + type: ip_range + keyword: + value: + description: This list describes bad host names + id: keyword_list + name: Simple list with a keyword + type: keyword + keyword_custom_format: + value: + description: This parses the first found ipv4 only + deserializer: '{{value}}' + id: keyword_custom_format_list + name: Simple list with a keyword using a custom format + serializer: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + type: keyword schema: type: object properties: description: $ref: '#/components/schemas/Security_Lists_API_ListDescription' deserializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListDeserializer' id: $ref: '#/components/schemas/Security_Lists_API_ListId' meta: @@ -33342,7 +33505,7 @@ paths: name: $ref: '#/components/schemas/Security_Lists_API_ListName' serializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListSerializer' type: $ref: '#/components/schemas/Security_Lists_API_ListType' version: @@ -33353,18 +33516,86 @@ paths: - name - description - type - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: This list describes bad internet ips + id: ip_list + immutable: false + name: Simple list with ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T04:47:34.273Z' + updated_by: elastic + version: 1 + ip_range: + value: + _version: WzAsMV0= + '@timestamp': '2025-01-09T18:23:52.241Z' + created_at: '2025-01-09T18:23:52.241Z' + created_by: elastic + description: This list has ip ranges + id: ip_range_list + immutable: false + name: Simple list with ip ranges + tie_breaker_id: 74aebdaf-601f-4940-b351-155728ff7003 + type: ip_range + updated_at: '2025-01-09T18:23:52.241Z' + updated_by: elastic + version: 1 + keyword: + value: + _version: WzEsMV0= + '@timestamp': '2025-01-09T18:24:55.786Z' + created_at: '2025-01-09T18:24:55.786Z' + created_by: elastic + description: This list describes bad host names + id: keyword_list + immutable: false + name: Simple list with a keyword + tie_breaker_id: f7e7dbaa-daf7-4c9a-a3dc-56643923ef68 + type: keyword + updated_at: '2025-01-09T18:24:55.786Z' + updated_by: elastic + version: 1 + keyword_custom_format: + value: + _version: WzIsMV0= + '@timestamp': '2025-01-09T18:25:39.604Z' + created_at: '2025-01-09T18:25:39.604Z' + created_by: elastic + description: This parses the first found ipv4 only + deserializer: '{{value}}' + id: keyword_custom_format_list + immutable: false + name: Simple list with a keyword using a custom format + serializer: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + tie_breaker_id: 8247ae63-b780-47b8-9a89-948b643e9ec2 + type: keyword + updated_at: '2025-01-09T18:25:39.604Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: To create a list, the data stream must exist first. Data stream \".lists-default\" does not exist + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33373,34 +33604,56 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [POST /api/lists] 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 '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'list id: "keyword_custom_format_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List already exists response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Create a list + summary: Create a value list tags: - Security Lists API x-beta: true put: description: | - Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted. + Update a value list using the list `id`. The original list is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. operationId: UpdateList @@ -33408,10 +33661,14 @@ paths: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + description: Latest list of bad ips + id: ip_list + name: Bad ips - updated type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' description: $ref: '#/components/schemas/Security_Lists_API_ListDescription' id: @@ -33421,24 +33678,45 @@ paths: name: $ref: '#/components/schemas/Security_Lists_API_ListName' version: - minimum: 1 - type: integer + $ref: '#/components/schemas/Security_Lists_API_ListVersion' required: - id - name - description - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzIsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: Latest list of bad ips + id: ip_list + immutable: false + name: Bad ips - updated + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T05:39:39.292Z' + updated_by: elastic + version: 3 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33447,54 +33725,81 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [PUT /api/lists] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Update a list + summary: Update a value list tags: - Security Lists API x-beta: true /api/lists/_find: get: - description: Get a paginated subset of lists. By default, the first page is returned, with 20 results per page. + description: Get a paginated subset of value lists. By default, the first page is returned, with 20 results per page. operationId: FindLists parameters: - - description: The page number to return + - description: The page number to return. in: query name: page required: false schema: + example: 1 type: integer - - description: The number of lists to return per page + - description: The number of value lists to return per page. in: query name: per_page required: false schema: + example: 20 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. in: query name: sort_field required: false schema: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + example: name + format: nonempty + minLength: 1 + type: string - description: Determines the sort order, which can be `desc` or `asc` in: query name: sort_order @@ -33503,11 +33808,9 @@ paths: enum: - desc - asc + example: asc type: string - - description: | - Returns the list that come after the last list returned in the previous call - (use the cursor value returned in the previous call). This parameter uses - the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. + - description: Returns the lists that come after the last lists returned in the previous call (use the `cursor` value returned in the previous call). This parameter uses the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. in: query name: cursor required: false @@ -33525,6 +33828,30 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ipList: + value: + cursor: WzIwLFsiZjU1MDgxODgtYjFlOS00ZTZlLTk2NjItZDAzOWE3ZDg5ODk5Il1d + data: + - _version: WzAsMV0= + '@timestamp': | + 2025-01-08T04:47:34.273Z + created_at: | + 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: Simple list with an ip + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: | + 2025-01-08T04:47:34.273Z + updated_by: elastic + version: 1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -33553,6 +33880,12 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: page: Expected number, received nan' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33561,22 +33894,39 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists/_find?page=1&per_page=20] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get lists + summary: Get value lists tags: - Security Lists API x-beta: true @@ -33607,6 +33957,12 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response @@ -33625,10 +33981,15 @@ paths: '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Delete list data streams + summary: Delete value list data streams tags: - Security Lists API x-beta: true @@ -33661,6 +34022,12 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response @@ -33679,10 +34046,15 @@ paths: '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get status of list data streams + summary: Get status of value list data streams tags: - Security Lists API x-beta: true @@ -33712,6 +34084,13 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response @@ -33724,12 +34103,22 @@ paths: '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'data stream: \".lists-default\" and \".items-default\" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List data stream exists response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response @@ -33739,28 +34128,29 @@ paths: x-beta: true /api/lists/items: delete: - description: Delete a list item using its `id`, or its `list_id` and `value` fields. + description: Delete a value list item using its `id`, or its `list_id` and `value` fields. operationId: DeleteListItem parameters: - - description: Required if `list_id` and `value` are not specified + - description: Value list item's identifier. Required if `list_id` and `value` are not specified. in: query name: id required: false schema: - $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: Required if `id` is not specified + $ref: '#/components/schemas/Security_Lists_API_ListItemId' + - description: Value list's identifier. Required if `id` is not specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: Required if `id` is not specified + - description: The value used to evaluate exceptions. Required if `id` is not specified. in: query name: value required: false schema: + example: 255.255.255.255 type: string - - description: Determines when changes made by the request are made visible to search + - description: Determines when changes made by the request are made visible to search. in: query name: refresh required: false @@ -33770,11 +34160,26 @@ paths: - 'true' - 'false' - wait_for + example: false type: string responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzIwLDFd + '@timestamp': '2025-01-08T05:15:05.159Z' + created_at: '2025-01-08T05:15:05.159Z' + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: '2025-01-08T05:44:14.009Z' + updated_by: elastic + value: 255.255.255.255 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_ListItem' @@ -33785,6 +34190,11 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + message: Either \"list_id\" or \"id\" needs to be defined in the request + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33793,57 +34203,94 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [DELETE /api/lists/items?id=pd1WRJQBs4HAK3VQeHFI] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list item with id: \"pd1WRJQBs4HAK3VQeHFI\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Delete a list item + summary: Delete a value list item tags: - Security Lists API x-beta: true get: - description: Get the details of a list item. + description: Get the details of a value list item. operationId: ReadListItem parameters: - - description: Required if `list_id` and `value` are not specified + - description: Value list item identifier. Required if `list_id` and `value` are not specified. in: query name: id required: false schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: Required if `id` is not specified + - description: Value list item list's `id` identfier. Required if `id` is not specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: Required if `id` is not specified + - description: The value used to evaluate exceptions. Required if `id` is not specified. in: query name: value required: false schema: + example: 127.0.0.2 type: string responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzExLDFd + '@timestamp': '2025-01-08T05:16:25.882Z' + created_at: '2025-01-08T05:16:25.882Z' + created_by: elastic + id: qN1XRJQBs4HAK3VQs3Gc + list_id: ip_list + tie_breaker_id: a9a34c02-a385-436e-86a0-02a3942f3537 + type: ip + updated_at: '2025-01-08T05:16:25.882Z' + updated_by: elastic + value: 127.0.0.2 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_ListItem' @@ -33854,6 +34301,11 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + message: Either \"list_id\" or \"id\" needs to be defined in the request + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33862,48 +34314,73 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists/items?id=qN1XRJQBs4HAK3VQs3Gc] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get a list item + summary: Get a value list item tags: - Security Lists API x-beta: true patch: - description: Update specific fields of an existing list item using the list item ID. + description: Update specific fields of an existing value list item using the item `id`. operationId: PatchListItem requestBody: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + id: pd1WRJQBs4HAK3VQeHFI + value: 255.255.255.255 type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' id: $ref: '#/components/schemas/Security_Lists_API_ListItemId' meta: $ref: '#/components/schemas/Security_Lists_API_ListItemMetadata' refresh: - description: Determines when changes made by the request are made visible to search + description: Determines when changes made by the request are made visible to search. enum: - 'true' - 'false' @@ -33913,18 +34390,37 @@ paths: $ref: '#/components/schemas/Security_Lists_API_ListItemValue' required: - id - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ipItem: + value: + _version: WzE5LDFd + '@timestamp': '2025-01-08T05:15:05.159Z' + created_at: '2025-01-08T05:15:05.159Z' + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: '2025-01-08T05:23:37.602Z' + updated_by: elastic + value: 255.255.255.255 schema: $ref: '#/components/schemas/Security_Lists_API_ListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + message: '{"took":15,"timed_out":false,"total":1,"updated":0,"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,"failures":[{"index":".ds-.items-default-2025.01.09-000001","id":"ip_item","cause":{"type":"document_parsing_exception","reason":"[1:107] failed to parse field [ip] of type [ip] in document with id ip_item. Preview of fields value: 2","caused_by":{"type":"illegal_argument_exception","reason":"2 is not an IP string literal."}},"status":400}]}' + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -33933,42 +34429,77 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [PATCH /api/lists/items] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Patch a list item + summary: Patch a value list item tags: - Security Lists API x-beta: true post: description: | - Create a list item and associate it with the specified list. + Create a value list item and associate it with the specified value list. - All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. + All value list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. > info > Before creating a list item, you must create a list. operationId: CreateListItem requestBody: content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + list_id: ip_list + value: 127.0.0.1 + ip_range: + value: + list_id: ip_range_list + value: 192.168.0.0/16 + keyword: + value: + list_id: keyword_list + value: zeek schema: type: object properties: @@ -33979,29 +34510,76 @@ paths: meta: $ref: '#/components/schemas/Security_Lists_API_ListItemMetadata' refresh: - description: Determines when changes made by the request are made visible to search + description: Determines when changes made by the request are made visible to search. enum: - 'true' - 'false' - wait_for + example: wait_for type: string value: $ref: '#/components/schemas/Security_Lists_API_ListItemValue' required: - list_id - value - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': '2025-01-08T04:59:06.154Z' + created_at: '2025-01-08T04:59:06.154Z' + created_by: elastic + id: 21b01cfb-058d-44b9-838c-282be16c91cc + list_id: ip_list + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + type: ip + updated_at: '2025-01-08T04:59:06.154Z' + updated_by: elastic + value: 127.0.0.1 + ip_range: + value: + _version: WzEsMV0= + '@timestamp': '2025-01-09T18:33:08.202Z' + created_at: '2025-01-09T18:33:08.202Z' + created_by: elastic + id: ip_range_item + list_id: ip_range_list + tie_breaker_id: ea1b4189-efda-4637-b8f9-74655a5ebb61 + type: ip_range + updated_at: '2025-01-09T18:33:08.202Z' + updated_by: elastic + value: 192.168.0.0/16 + keyword: + value: + _version: WzIsMV0= + '@timestamp': '2025-01-09T18:34:29.422Z' + created_at: '2025-01-09T18:34:29.422Z' + created_by: elastic + id: 7f24737d-1da8-4626-a568-33070591bb4e + list_id: keyword_list + tie_breaker_id: 2108ced2-5e5d-401e-a88e-4dd69fc5fa27 + type: keyword + updated_at: '2025-01-09T18:34:29.422Z' + updated_by: elastic + value: zeek schema: $ref: '#/components/schemas/Security_Lists_API_ListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: uri [/api/lists/items] with method [post] exists but is not available with the current configuration + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -34010,45 +34588,81 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [POST /api/lists/items] 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 + '404': + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + listNotFound: + value: + message: 'list id: \"ip_list\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'list item id: \"ip_item\" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item already exists response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Create a list item + summary: Create a value list item tags: - Security Lists API x-beta: true put: description: | - Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. + Update a value list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. operationId: UpdateListItem requestBody: content: application/json; Elastic-Api-Version=2023-10-31: + example: + id: ip_item + value: 255.255.255.255 schema: type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' id: $ref: '#/components/schemas/Security_Lists_API_ListItemId' meta: @@ -34058,18 +34672,38 @@ paths: required: - id - value - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzIwLDFd + '@timestamp': '2025-01-08T05:15:05.159Z' + created_at: '2025-01-08T05:15:05.159Z' + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: '2025-01-08T05:44:14.009Z' + updated_by: elastic + value: 255.255.255.255 schema: $ref: '#/components/schemas/Security_Lists_API_ListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -34078,37 +34712,59 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [PATCH /api/lists/items] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Update a list item + summary: Update a value list item tags: - Security Lists API x-beta: true /api/lists/items/_export: post: - description: Export list item values from the specified list. + description: Export list item values from the specified value list. operationId: ExportListItems parameters: - - description: List's id to export + - description: Value list's `id` to export. in: query name: list_id required: true @@ -34120,12 +34776,27 @@ paths: application/ndjson; Elastic-Api-Version=2023-10-31: schema: description: A `.txt` file containing list items from the specified list + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 format: binary type: string description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: 'Bad Request","message":"[request query]: list_id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -34134,12 +34805,24 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [POST /api/lists/items/_export?list_id=ips.txt] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response @@ -34152,42 +34835,51 @@ paths: '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Export list items + summary: Export value list items tags: - Security Lists API x-beta: true /api/lists/items/_find: get: - description: Get all list items in the specified list. + description: Get all value list items in the specified list. operationId: FindListItems parameters: - - description: List's id - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: The page number to return + - description: The page number to return. in: query name: page required: false schema: + example: 1 type: integer - - description: The number of list items to return per page + - description: The number of list items to return per page. in: query name: per_page required: false schema: + example: 20 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. in: query name: sort_field required: false schema: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + example: value + format: nonempty + minLength: 1 + type: string - description: Determines the sort order, which can be `desc` or `asc` in: query name: sort_order @@ -34196,12 +34888,9 @@ paths: enum: - desc - asc + example: asc type: string - - description: | - Returns the list that come after the last list returned in the previous call - (use the cursor value returned in the previous call). This parameter uses - the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. - in: query + - in: query name: cursor required: false schema: @@ -34218,6 +34907,25 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + cursor: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + data: + - _version: WzAsMV0= + '@timestamp': '2025-01-08T04:59:06.154Z' + created_at: '2025-01-08T04:59:06.154Z' + created_by: elastic + id: 21b01cfb-058d-44b9-838c-282be16c91cc + list_id: ip_list + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + type: ip + updated_at: '2025-01-08T04:59:06.154Z' + updated_by: elastic + value: 127.0.0.1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -34246,6 +34954,12 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request, + message: '[request query]: list_id: Required' + statusCode: 400, schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -34254,29 +34968,46 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists/items/_find?list_id=ip_list&page=1&per_page=20] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get list items + summary: Get value list items tags: - Security Lists API x-beta: true /api/lists/items/_import: post: description: | - Import list items from a TXT or CSV file. The maximum file size is 9 million bytes. + Import value list items from a TXT or CSV file. The maximum file size is 9 million bytes. You can import items to a new or existing list. operationId: ImportListItems @@ -34293,23 +35024,39 @@ paths: - description: | Type of the importing list. - Required when importing a new list that is `list_id` is not specified. + Required when importing a new list whose list `id` is not specified. + examples: + ip: + value: ip in: query name: type required: false schema: $ref: '#/components/schemas/Security_Lists_API_ListType' - - in: query + - description: | + Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups: + + - `(?.+)` - Single value item types, such as ip, long, date, keyword, and text. + - `(?.+)-(?.+)|(?.+)` - Range value item types, such as `date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + in: query name: serializer required: false schema: + example: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) type: string - - in: query + - description: | + Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions: + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, and `text`. + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + - `{{{gte}}},{{{lte}}}` - Date range values. + in: query name: deserializer required: false schema: + example: '{{value}}' type: string - - description: Determines when changes made by the request are made visible to search + - description: Determines when changes made by the request are made visible to search. in: query name: refresh required: false @@ -34318,6 +35065,7 @@ paths: - 'true' - 'false' - wait_for + example: true type: string requestBody: content: @@ -34326,7 +35074,17 @@ paths: type: object properties: file: - description: A `.txt` or `.csv` file containing newline separated list items + description: A `.txt` or `.csv` file containing newline separated list items. + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 format: binary type: string required: true @@ -34334,12 +35092,33 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: Simple list with an ip + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T04:47:34.273Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + message: Either type or list_id need to be defined in the query + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -34348,12 +35127,24 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [POST /api/lists/items/_import?list_id=ip_list] 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 @@ -34366,10 +35157,15 @@ paths: '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Import list items + summary: Import value list items tags: - Security Lists API x-beta: true @@ -34380,6 +35176,74 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + privileges: + value: + is_authenticated: true + listItems: + application: {} + cluster: + all: true + manage: true + manage_api_key: true + manage_index_templates: true + manage_ml: true + manage_own_api_key: true + manage_pipeline: true + manage_security: true + manage_transform: true + monitor: true + monitor_ml: true + monitor_transform: true + has_all_requested: true + index: + .items-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + username: elastic + lists: + application: {} + cluster: + all: true + manage: true + manage_api_key: true + manage_index_templates: true + manage_ml: true + manage_own_api_key: true + manage_pipeline: true + manage_security: true + manage_transform: true + monitor: true + monitor_ml: true + monitor_transform: true + has_all_requested: true + index: + .lists-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + username: elastic schema: type: object properties: @@ -34405,22 +35269,39 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists/privileges] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get list privileges + summary: Get value list privileges tags: - Security Lists API x-beta: true @@ -47870,8 +48751,18 @@ components: Security_Endpoint_Exceptions_API_FindEndpointListItemsFilter: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' Security_Endpoint_Exceptions_API_ListId: - $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string Security_Endpoint_Exceptions_API_ListType: + description: | + Specifies the Elasticsearch data type of excludes the list container holds. Some common examples: + + - `keyword`: Many ECS fields are Elasticsearch keywords + - `ip`: IP addresses + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR notation) enum: - binary - boolean @@ -49561,8 +50452,18 @@ components: example: exception-list.attributes.name:%Detection%20List type: string Security_Exceptions_API_ListId: - $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string Security_Exceptions_API_ListType: + description: | + Specifies the Elasticsearch data type of excludes the list container holds. Some common examples: + + - `keyword`: Many ECS fields are Elasticsearch keywords + - `ip`: IP addresses + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR notation) enum: - binary - boolean @@ -49636,30 +50537,44 @@ components: format: uuid type: string Security_Lists_API_FindListItemsCursor: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Returns the items that come after the last item returned in the previous call (use the `cursor` value returned in the previous call). This parameter uses the `tie_breaker_id` field to ensure all items are sorted and returned correctly. + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + format: nonempty + minLength: 1 + type: string Security_Lists_API_FindListItemsFilter: + example: value:127.0.0.1 type: string Security_Lists_API_FindListsCursor: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + format: nonempty + minLength: 1 + type: string Security_Lists_API_FindListsFilter: + example: value:127.0.0.1 type: string Security_Lists_API_List: type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' '@timestamp': + example: '2025-01-08T04:47:34.273Z' format: date-time type: string created_at: + description: Autogenerated date of object creation. + example: '2025-01-08T04:47:34.273Z' format: date-time type: string created_by: + description: Autogenerated value - user that created object. + example: elastic type: string description: $ref: '#/components/schemas/Security_Lists_API_ListDescription' deserializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListDeserializer' id: $ref: '#/components/schemas/Security_Lists_API_ListId' immutable: @@ -49669,19 +50584,24 @@ components: name: $ref: '#/components/schemas/Security_Lists_API_ListName' serializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListSerializer' tie_breaker_id: + description: Field used in search to ensure all containers are sorted and returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 type: string type: $ref: '#/components/schemas/Security_Lists_API_ListType' updated_at: + description: Autogenerated date of last object update. + example: '2025-01-08T04:47:34.273Z' format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. + example: elastic type: string version: - minimum: 1 - type: integer + $ref: '#/components/schemas/Security_Lists_API_ListVersion' required: - id - type @@ -49695,24 +50615,45 @@ components: - updated_at - updated_by Security_Lists_API_ListDescription: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Describes the value list. + format: nonempty + minLength: 1 + type: string + Security_Lists_API_ListDeserializer: + description: | + Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions: + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, and `text`. + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + - `{{{gte}}},{{{lte}}}` - Date range values. + example: '{{value}}' + type: string Security_Lists_API_ListId: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string Security_Lists_API_ListItem: type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' '@timestamp': + example: '2025-01-08T04:47:34.273Z' format: date-time type: string created_at: + description: Autogenerated date of object creation. + example: '2025-01-08T04:47:34.273Z' format: date-time type: string created_by: + description: Autogenerated value - user that created object. + example: elastic type: string deserializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListDeserializer' id: $ref: '#/components/schemas/Security_Lists_API_ListItemId' list_id: @@ -49720,15 +50661,21 @@ components: meta: $ref: '#/components/schemas/Security_Lists_API_ListItemMetadata' serializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListSerializer' tie_breaker_id: + description: Field used in search to ensure all containers are sorted and returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 type: string type: $ref: '#/components/schemas/Security_Lists_API_ListType' updated_at: + description: Autogenerated date of last object update. + example: '2025-01-08T04:47:34.273Z' format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. + example: elastic type: string value: $ref: '#/components/schemas/Security_Lists_API_ListItemValue' @@ -49743,9 +50690,14 @@ components: - updated_at - updated_by Security_Lists_API_ListItemId: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Value list item's identifier. + example: 54b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string Security_Lists_API_ListItemMetadata: additionalProperties: true + description: Placeholder for metadata about the value list item. type: object Security_Lists_API_ListItemPrivileges: type: object @@ -49775,12 +50727,20 @@ components: - index - application Security_Lists_API_ListItemValue: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: The value used to evaluate exceptions. + format: nonempty + minLength: 1 + type: string Security_Lists_API_ListMetadata: additionalProperties: true + description: Placeholder for metadata about the value list. type: object Security_Lists_API_ListName: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Value list's name. + example: List of bad IPs + format: nonempty + minLength: 1 + type: string Security_Lists_API_ListPrivileges: type: object properties: @@ -49808,7 +50768,21 @@ components: - cluster - index - application + Security_Lists_API_ListSerializer: + description: | + Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups: + + - `(?.+)` - Single value item types, such as ip, long, date, keyword, and text. + - `(?.+)-(?.+)|(?.+)` - Range value item types, such as `date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + example: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + type: string Security_Lists_API_ListType: + description: | + Specifies the Elasticsearch data type of excludes the list container holds. Some common examples: + + - `keyword`: Many ECS fields are Elasticsearch keywords + - `ip`: IP addresses + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR notation) enum: - binary - boolean @@ -49834,10 +50808,15 @@ components: - short - text type: string - Security_Lists_API_NonEmptyString: - description: A string that does not contain only whitespace characters - format: nonempty - minLength: 1 + Security_Lists_API_ListVersion: + description: The document version number. + example: 1 + minimum: 1 + type: integer + Security_Lists_API_ListVersionId: + description: | + The version id, normally returned by the API when the document is retrieved. Use it ensure updates are done against the latest version. + example: WzIsMV0= type: string Security_Lists_API_PlatformErrorResponse: type: object diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index f4e4b6a28861e..5ffa4e5f97af1 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -17314,39 +17314,64 @@ paths: /api/lists: delete: description: | - Delete a list using the list ID. + Delete a value list using the list ID. > info > When you delete a list, all of its list items are also deleted. operationId: DeleteList parameters: - - description: List's `id` value - in: query + - in: query name: id required: true schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - in: query + - description: Determines whether exception items referencing this value list should be deleted. + in: query name: deleteReferences required: false schema: default: false + example: false type: boolean - - in: query + - description: Determines whether to delete value list without performing any additional checks of where this list may be utilized. + in: query name: ignoreReferences required: false schema: default: false + example: false type: boolean responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ipList: + value: + _version: WzIsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: List of bad internet ips. + id: 21b01cfb-058d-44b9-838c-282be16c91cd + immutable: false + name: Bad ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T05:39:39.292Z' + updated_by: elastic + version: 3 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -17355,36 +17380,57 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [DELETE /api/lists?id=ip_list] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list id: \"ip_list\" was not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Delete a list + summary: Delete a value list tags: - Security Lists API get: - description: Get the details of a list using the list ID. + description: Get the details of a value list using the list ID. operationId: ReadList parameters: - - description: List's `id` value - in: query + - in: query name: id required: true schema: @@ -17393,12 +17439,34 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzEsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: My bad ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T05:21:53.843Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -17407,41 +17475,66 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get list details + summary: Get value list details tags: - Security Lists API patch: - description: Update specific fields of an existing list using the list ID. + description: Update specific fields of an existing list using the list `id`. operationId: PatchList requestBody: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + id: ip_list + name: Bad ips list - UPDATED type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' description: $ref: '#/components/schemas/Security_Lists_API_ListDescription' id: @@ -17451,22 +17544,43 @@ paths: name: $ref: '#/components/schemas/Security_Lists_API_ListName' version: - minimum: 1 - type: integer + $ref: '#/components/schemas/Security_Lists_API_ListVersion' required: - id - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzEsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: This list describes bad internet ips + id: ip_list + immutable: false + name: Bad ips list - UPDATED + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T05:21:53.843Z' + updated_by: elastic + version: 2 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: name: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -17475,43 +17589,92 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [PATCH /api/lists] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Patch a list + summary: Patch a value list tags: - Security Lists API post: - description: Create a new list. + description: Create a new value list. operationId: CreateList requestBody: content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + description: This list describes bad internet ips + id: ip_list + name: Simple list with ips + type: ip + ip_range: + value: + description: This list has ip ranges + id: ip_range_list + name: Simple list with ip ranges + type: ip_range + keyword: + value: + description: This list describes bad host names + id: keyword_list + name: Simple list with a keyword + type: keyword + keyword_custom_format: + value: + description: This parses the first found ipv4 only + deserializer: '{{value}}' + id: keyword_custom_format_list + name: Simple list with a keyword using a custom format + serializer: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + type: keyword schema: type: object properties: description: $ref: '#/components/schemas/Security_Lists_API_ListDescription' deserializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListDeserializer' id: $ref: '#/components/schemas/Security_Lists_API_ListId' meta: @@ -17519,7 +17682,7 @@ paths: name: $ref: '#/components/schemas/Security_Lists_API_ListName' serializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListSerializer' type: $ref: '#/components/schemas/Security_Lists_API_ListType' version: @@ -17530,18 +17693,86 @@ paths: - name - description - type - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: This list describes bad internet ips + id: ip_list + immutable: false + name: Simple list with ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T04:47:34.273Z' + updated_by: elastic + version: 1 + ip_range: + value: + _version: WzAsMV0= + '@timestamp': '2025-01-09T18:23:52.241Z' + created_at: '2025-01-09T18:23:52.241Z' + created_by: elastic + description: This list has ip ranges + id: ip_range_list + immutable: false + name: Simple list with ip ranges + tie_breaker_id: 74aebdaf-601f-4940-b351-155728ff7003 + type: ip_range + updated_at: '2025-01-09T18:23:52.241Z' + updated_by: elastic + version: 1 + keyword: + value: + _version: WzEsMV0= + '@timestamp': '2025-01-09T18:24:55.786Z' + created_at: '2025-01-09T18:24:55.786Z' + created_by: elastic + description: This list describes bad host names + id: keyword_list + immutable: false + name: Simple list with a keyword + tie_breaker_id: f7e7dbaa-daf7-4c9a-a3dc-56643923ef68 + type: keyword + updated_at: '2025-01-09T18:24:55.786Z' + updated_by: elastic + version: 1 + keyword_custom_format: + value: + _version: WzIsMV0= + '@timestamp': '2025-01-09T18:25:39.604Z' + created_at: '2025-01-09T18:25:39.604Z' + created_by: elastic + description: This parses the first found ipv4 only + deserializer: '{{value}}' + id: keyword_custom_format_list + immutable: false + name: Simple list with a keyword using a custom format + serializer: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + tie_breaker_id: 8247ae63-b780-47b8-9a89-948b643e9ec2 + type: keyword + updated_at: '2025-01-09T18:25:39.604Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: To create a list, the data stream must exist first. Data stream \".lists-default\" does not exist + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -17550,33 +17781,55 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [POST /api/lists] 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 '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'list id: "keyword_custom_format_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List already exists response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Create a list + summary: Create a value list tags: - Security Lists API put: description: | - Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted. + Update a value list using the list `id`. The original list is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. operationId: UpdateList @@ -17584,10 +17837,14 @@ paths: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + description: Latest list of bad ips + id: ip_list + name: Bad ips - updated type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' description: $ref: '#/components/schemas/Security_Lists_API_ListDescription' id: @@ -17597,24 +17854,45 @@ paths: name: $ref: '#/components/schemas/Security_Lists_API_ListName' version: - minimum: 1 - type: integer + $ref: '#/components/schemas/Security_Lists_API_ListVersion' required: - id - name - description - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzIsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: Latest list of bad ips + id: ip_list + immutable: false + name: Bad ips - updated + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T05:39:39.292Z' + updated_by: elastic + version: 3 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -17623,53 +17901,80 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [PUT /api/lists] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Update a list + summary: Update a value list tags: - Security Lists API /api/lists/_find: get: - description: Get a paginated subset of lists. By default, the first page is returned, with 20 results per page. + description: Get a paginated subset of value lists. By default, the first page is returned, with 20 results per page. operationId: FindLists parameters: - - description: The page number to return + - description: The page number to return. in: query name: page required: false schema: + example: 1 type: integer - - description: The number of lists to return per page + - description: The number of value lists to return per page. in: query name: per_page required: false schema: + example: 20 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. in: query name: sort_field required: false schema: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + example: name + format: nonempty + minLength: 1 + type: string - description: Determines the sort order, which can be `desc` or `asc` in: query name: sort_order @@ -17678,11 +17983,9 @@ paths: enum: - desc - asc + example: asc type: string - - description: | - Returns the list that come after the last list returned in the previous call - (use the cursor value returned in the previous call). This parameter uses - the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. + - description: Returns the lists that come after the last lists returned in the previous call (use the `cursor` value returned in the previous call). This parameter uses the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. in: query name: cursor required: false @@ -17700,6 +18003,30 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ipList: + value: + cursor: WzIwLFsiZjU1MDgxODgtYjFlOS00ZTZlLTk2NjItZDAzOWE3ZDg5ODk5Il1d + data: + - _version: WzAsMV0= + '@timestamp': | + 2025-01-08T04:47:34.273Z + created_at: | + 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: Simple list with an ip + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: | + 2025-01-08T04:47:34.273Z + updated_by: elastic + version: 1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -17728,6 +18055,12 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: page: Expected number, received nan' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -17736,22 +18069,39 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists/_find?page=1&per_page=20] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get lists + summary: Get value lists tags: - Security Lists API /api/lists/index: @@ -17781,6 +18131,12 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response @@ -17799,10 +18155,15 @@ paths: '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Delete list data streams + summary: Delete value list data streams tags: - Security Lists API get: @@ -17834,6 +18195,12 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response @@ -17852,10 +18219,15 @@ paths: '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get status of list data streams + summary: Get status of value list data streams tags: - Security Lists API post: @@ -17884,6 +18256,13 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response @@ -17896,12 +18275,22 @@ paths: '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'data stream: \".lists-default\" and \".items-default\" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List data stream exists response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response @@ -17910,28 +18299,29 @@ paths: - Security Lists API /api/lists/items: delete: - description: Delete a list item using its `id`, or its `list_id` and `value` fields. + description: Delete a value list item using its `id`, or its `list_id` and `value` fields. operationId: DeleteListItem parameters: - - description: Required if `list_id` and `value` are not specified + - description: Value list item's identifier. Required if `list_id` and `value` are not specified. in: query name: id required: false schema: - $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: Required if `id` is not specified + $ref: '#/components/schemas/Security_Lists_API_ListItemId' + - description: Value list's identifier. Required if `id` is not specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: Required if `id` is not specified + - description: The value used to evaluate exceptions. Required if `id` is not specified. in: query name: value required: false schema: + example: 255.255.255.255 type: string - - description: Determines when changes made by the request are made visible to search + - description: Determines when changes made by the request are made visible to search. in: query name: refresh required: false @@ -17941,11 +18331,26 @@ paths: - 'true' - 'false' - wait_for + example: false type: string responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzIwLDFd + '@timestamp': '2025-01-08T05:15:05.159Z' + created_at: '2025-01-08T05:15:05.159Z' + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: '2025-01-08T05:44:14.009Z' + updated_by: elastic + value: 255.255.255.255 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_ListItem' @@ -17956,6 +18361,11 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + message: Either \"list_id\" or \"id\" needs to be defined in the request + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -17964,56 +18374,93 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [DELETE /api/lists/items?id=pd1WRJQBs4HAK3VQeHFI] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list item with id: \"pd1WRJQBs4HAK3VQeHFI\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Delete a list item + summary: Delete a value list item tags: - Security Lists API get: - description: Get the details of a list item. + description: Get the details of a value list item. operationId: ReadListItem parameters: - - description: Required if `list_id` and `value` are not specified + - description: Value list item identifier. Required if `list_id` and `value` are not specified. in: query name: id required: false schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: Required if `id` is not specified + - description: Value list item list's `id` identfier. Required if `id` is not specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: Required if `id` is not specified + - description: The value used to evaluate exceptions. Required if `id` is not specified. in: query name: value required: false schema: + example: 127.0.0.2 type: string responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzExLDFd + '@timestamp': '2025-01-08T05:16:25.882Z' + created_at: '2025-01-08T05:16:25.882Z' + created_by: elastic + id: qN1XRJQBs4HAK3VQs3Gc + list_id: ip_list + tie_breaker_id: a9a34c02-a385-436e-86a0-02a3942f3537 + type: ip + updated_at: '2025-01-08T05:16:25.882Z' + updated_by: elastic + value: 127.0.0.2 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_ListItem' @@ -18024,6 +18471,11 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + message: Either \"list_id\" or \"id\" needs to be defined in the request + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -18032,47 +18484,72 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists/items?id=qN1XRJQBs4HAK3VQs3Gc] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get a list item + summary: Get a value list item tags: - Security Lists API patch: - description: Update specific fields of an existing list item using the list item ID. + description: Update specific fields of an existing value list item using the item `id`. operationId: PatchListItem requestBody: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + id: pd1WRJQBs4HAK3VQeHFI + value: 255.255.255.255 type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' id: $ref: '#/components/schemas/Security_Lists_API_ListItemId' meta: $ref: '#/components/schemas/Security_Lists_API_ListItemMetadata' refresh: - description: Determines when changes made by the request are made visible to search + description: Determines when changes made by the request are made visible to search. enum: - 'true' - 'false' @@ -18082,18 +18559,37 @@ paths: $ref: '#/components/schemas/Security_Lists_API_ListItemValue' required: - id - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ipItem: + value: + _version: WzE5LDFd + '@timestamp': '2025-01-08T05:15:05.159Z' + created_at: '2025-01-08T05:15:05.159Z' + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: '2025-01-08T05:23:37.602Z' + updated_by: elastic + value: 255.255.255.255 schema: $ref: '#/components/schemas/Security_Lists_API_ListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + message: '{"took":15,"timed_out":false,"total":1,"updated":0,"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,"failures":[{"index":".ds-.items-default-2025.01.09-000001","id":"ip_item","cause":{"type":"document_parsing_exception","reason":"[1:107] failed to parse field [ip] of type [ip] in document with id ip_item. Preview of fields value: 2","caused_by":{"type":"illegal_argument_exception","reason":"2 is not an IP string literal."}},"status":400}]}' + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -18102,41 +18598,76 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [PATCH /api/lists/items] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Patch a list item + summary: Patch a value list item tags: - Security Lists API post: description: | - Create a list item and associate it with the specified list. + Create a value list item and associate it with the specified value list. - All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. + All value list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. > info > Before creating a list item, you must create a list. operationId: CreateListItem requestBody: content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + list_id: ip_list + value: 127.0.0.1 + ip_range: + value: + list_id: ip_range_list + value: 192.168.0.0/16 + keyword: + value: + list_id: keyword_list + value: zeek schema: type: object properties: @@ -18147,29 +18678,76 @@ paths: meta: $ref: '#/components/schemas/Security_Lists_API_ListItemMetadata' refresh: - description: Determines when changes made by the request are made visible to search + description: Determines when changes made by the request are made visible to search. enum: - 'true' - 'false' - wait_for + example: wait_for type: string value: $ref: '#/components/schemas/Security_Lists_API_ListItemValue' required: - list_id - value - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': '2025-01-08T04:59:06.154Z' + created_at: '2025-01-08T04:59:06.154Z' + created_by: elastic + id: 21b01cfb-058d-44b9-838c-282be16c91cc + list_id: ip_list + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + type: ip + updated_at: '2025-01-08T04:59:06.154Z' + updated_by: elastic + value: 127.0.0.1 + ip_range: + value: + _version: WzEsMV0= + '@timestamp': '2025-01-09T18:33:08.202Z' + created_at: '2025-01-09T18:33:08.202Z' + created_by: elastic + id: ip_range_item + list_id: ip_range_list + tie_breaker_id: ea1b4189-efda-4637-b8f9-74655a5ebb61 + type: ip_range + updated_at: '2025-01-09T18:33:08.202Z' + updated_by: elastic + value: 192.168.0.0/16 + keyword: + value: + _version: WzIsMV0= + '@timestamp': '2025-01-09T18:34:29.422Z' + created_at: '2025-01-09T18:34:29.422Z' + created_by: elastic + id: 7f24737d-1da8-4626-a568-33070591bb4e + list_id: keyword_list + tie_breaker_id: 2108ced2-5e5d-401e-a88e-4dd69fc5fa27 + type: keyword + updated_at: '2025-01-09T18:34:29.422Z' + updated_by: elastic + value: zeek schema: $ref: '#/components/schemas/Security_Lists_API_ListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: uri [/api/lists/items] with method [post] exists but is not available with the current configuration + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -18178,44 +18756,80 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [POST /api/lists/items] 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 + '404': + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + listNotFound: + value: + message: 'list id: \"ip_list\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'list item id: \"ip_item\" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item already exists response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Create a list item + summary: Create a value list item tags: - Security Lists API put: description: | - Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. + Update a value list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. operationId: UpdateListItem requestBody: content: application/json; Elastic-Api-Version=2023-10-31: + example: + id: ip_item + value: 255.255.255.255 schema: type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' id: $ref: '#/components/schemas/Security_Lists_API_ListItemId' meta: @@ -18225,18 +18839,38 @@ paths: required: - id - value - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzIwLDFd + '@timestamp': '2025-01-08T05:15:05.159Z' + created_at: '2025-01-08T05:15:05.159Z' + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: '2025-01-08T05:44:14.009Z' + updated_by: elastic + value: 255.255.255.255 schema: $ref: '#/components/schemas/Security_Lists_API_ListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -18245,36 +18879,58 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [PATCH /api/lists/items] 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 '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: List item not found response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Update a list item + summary: Update a value list item tags: - Security Lists API /api/lists/items/_export: post: - description: Export list item values from the specified list. + description: Export list item values from the specified value list. operationId: ExportListItems parameters: - - description: List's id to export + - description: Value list's `id` to export. in: query name: list_id required: true @@ -18286,12 +18942,27 @@ paths: application/ndjson; Elastic-Api-Version=2023-10-31: schema: description: A `.txt` file containing list items from the specified list + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 format: binary type: string description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: 'Bad Request","message":"[request query]: list_id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -18300,12 +18971,24 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [POST /api/lists/items/_export?list_id=ips.txt] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response @@ -18318,41 +19001,50 @@ paths: '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Export list items + summary: Export value list items tags: - Security Lists API /api/lists/items/_find: get: - description: Get all list items in the specified list. + description: Get all value list items in the specified list. operationId: FindListItems parameters: - - description: List's id - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/Security_Lists_API_ListId' - - description: The page number to return + - description: The page number to return. in: query name: page required: false schema: + example: 1 type: integer - - description: The number of list items to return per page + - description: The number of list items to return per page. in: query name: per_page required: false schema: + example: 20 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. in: query name: sort_field required: false schema: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + example: value + format: nonempty + minLength: 1 + type: string - description: Determines the sort order, which can be `desc` or `asc` in: query name: sort_order @@ -18361,12 +19053,9 @@ paths: enum: - desc - asc + example: asc type: string - - description: | - Returns the list that come after the last list returned in the previous call - (use the cursor value returned in the previous call). This parameter uses - the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. - in: query + - in: query name: cursor required: false schema: @@ -18383,6 +19072,25 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + cursor: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + data: + - _version: WzAsMV0= + '@timestamp': '2025-01-08T04:59:06.154Z' + created_at: '2025-01-08T04:59:06.154Z' + created_by: elastic + id: 21b01cfb-058d-44b9-838c-282be16c91cc + list_id: ip_list + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + type: ip + updated_at: '2025-01-08T04:59:06.154Z' + updated_by: elastic + value: 127.0.0.1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -18411,6 +19119,12 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request, + message: '[request query]: list_id: Required' + statusCode: 400, schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -18419,28 +19133,45 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists/items/_find?list_id=ip_list&page=1&per_page=20] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get list items + summary: Get value list items tags: - Security Lists API /api/lists/items/_import: post: description: | - Import list items from a TXT or CSV file. The maximum file size is 9 million bytes. + Import value list items from a TXT or CSV file. The maximum file size is 9 million bytes. You can import items to a new or existing list. operationId: ImportListItems @@ -18457,23 +19188,39 @@ paths: - description: | Type of the importing list. - Required when importing a new list that is `list_id` is not specified. + Required when importing a new list whose list `id` is not specified. + examples: + ip: + value: ip in: query name: type required: false schema: $ref: '#/components/schemas/Security_Lists_API_ListType' - - in: query + - description: | + Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups: + + - `(?.+)` - Single value item types, such as ip, long, date, keyword, and text. + - `(?.+)-(?.+)|(?.+)` - Range value item types, such as `date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + in: query name: serializer required: false schema: + example: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) type: string - - in: query + - description: | + Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions: + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, and `text`. + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + - `{{{gte}}},{{{lte}}}` - Date range values. + in: query name: deserializer required: false schema: + example: '{{value}}' type: string - - description: Determines when changes made by the request are made visible to search + - description: Determines when changes made by the request are made visible to search. in: query name: refresh required: false @@ -18482,6 +19229,7 @@ paths: - 'true' - 'false' - wait_for + example: true type: string requestBody: content: @@ -18490,7 +19238,17 @@ paths: type: object properties: file: - description: A `.txt` or `.csv` file containing newline separated list items + description: A `.txt` or `.csv` file containing newline separated list items. + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 format: binary type: string required: true @@ -18498,12 +19256,33 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': '2025-01-08T04:47:34.273Z' + created_at: '2025-01-08T04:47:34.273Z' + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: Simple list with an ip + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: '2025-01-08T04:47:34.273Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Lists_API_List' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + message: Either type or list_id need to be defined in the query + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' @@ -18512,12 +19291,24 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [POST /api/lists/items/_import?list_id=ip_list] 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 @@ -18530,10 +19321,15 @@ paths: '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Import list items + summary: Import value list items tags: - Security Lists API /api/lists/privileges: @@ -18543,6 +19339,74 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + privileges: + value: + is_authenticated: true + listItems: + application: {} + cluster: + all: true + manage: true + manage_api_key: true + manage_index_templates: true + manage_ml: true + manage_own_api_key: true + manage_pipeline: true + manage_security: true + manage_transform: true + monitor: true + monitor_ml: true + monitor_transform: true + has_all_requested: true + index: + .items-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + username: elastic + lists: + application: {} + cluster: + all: true + manage: true + manage_api_key: true + manage_index_templates: true + manage_ml: true + manage_own_api_key: true + manage_pipeline: true + manage_security: true + manage_transform: true + monitor: true + monitor_ml: true + monitor_transform: true + has_all_requested: true + index: + .lists-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + username: elastic schema: type: object properties: @@ -18568,22 +19432,39 @@ paths: '401': content: application/json; Elastic-Api-Version=2023-10-31: + 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_Lists_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + error: Forbidden + message: API [GET /api/lists/privileges] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Lists_API_PlatformErrorResponse' description: Not enough privileges response '500': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/Security_Lists_API_SiemErrorResponse' description: Internal server error response - summary: Get list privileges + summary: Get value list privileges tags: - Security Lists API /api/ml/saved_objects/sync: @@ -39597,8 +40478,18 @@ components: Security_Endpoint_Exceptions_API_FindEndpointListItemsFilter: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' Security_Endpoint_Exceptions_API_ListId: - $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string Security_Endpoint_Exceptions_API_ListType: + description: | + Specifies the Elasticsearch data type of excludes the list container holds. Some common examples: + + - `keyword`: Many ECS fields are Elasticsearch keywords + - `ip`: IP addresses + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR notation) enum: - binary - boolean @@ -41116,8 +42007,18 @@ components: example: exception-list.attributes.name:%Detection%20List type: string Security_Exceptions_API_ListId: - $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string Security_Exceptions_API_ListType: + description: | + Specifies the Elasticsearch data type of excludes the list container holds. Some common examples: + + - `keyword`: Many ECS fields are Elasticsearch keywords + - `ip`: IP addresses + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR notation) enum: - binary - boolean @@ -41191,30 +42092,44 @@ components: format: uuid type: string Security_Lists_API_FindListItemsCursor: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Returns the items that come after the last item returned in the previous call (use the `cursor` value returned in the previous call). This parameter uses the `tie_breaker_id` field to ensure all items are sorted and returned correctly. + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + format: nonempty + minLength: 1 + type: string Security_Lists_API_FindListItemsFilter: + example: value:127.0.0.1 type: string Security_Lists_API_FindListsCursor: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + format: nonempty + minLength: 1 + type: string Security_Lists_API_FindListsFilter: + example: value:127.0.0.1 type: string Security_Lists_API_List: type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' '@timestamp': + example: '2025-01-08T04:47:34.273Z' format: date-time type: string created_at: + description: Autogenerated date of object creation. + example: '2025-01-08T04:47:34.273Z' format: date-time type: string created_by: + description: Autogenerated value - user that created object. + example: elastic type: string description: $ref: '#/components/schemas/Security_Lists_API_ListDescription' deserializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListDeserializer' id: $ref: '#/components/schemas/Security_Lists_API_ListId' immutable: @@ -41224,19 +42139,24 @@ components: name: $ref: '#/components/schemas/Security_Lists_API_ListName' serializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListSerializer' tie_breaker_id: + description: Field used in search to ensure all containers are sorted and returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 type: string type: $ref: '#/components/schemas/Security_Lists_API_ListType' updated_at: + description: Autogenerated date of last object update. + example: '2025-01-08T04:47:34.273Z' format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. + example: elastic type: string version: - minimum: 1 - type: integer + $ref: '#/components/schemas/Security_Lists_API_ListVersion' required: - id - type @@ -41250,24 +42170,45 @@ components: - updated_at - updated_by Security_Lists_API_ListDescription: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Describes the value list. + format: nonempty + minLength: 1 + type: string + Security_Lists_API_ListDeserializer: + description: | + Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions: + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, and `text`. + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + - `{{{gte}}},{{{lte}}}` - Date range values. + example: '{{value}}' + type: string Security_Lists_API_ListId: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string Security_Lists_API_ListItem: type: object properties: _version: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListVersionId' '@timestamp': + example: '2025-01-08T04:47:34.273Z' format: date-time type: string created_at: + description: Autogenerated date of object creation. + example: '2025-01-08T04:47:34.273Z' format: date-time type: string created_by: + description: Autogenerated value - user that created object. + example: elastic type: string deserializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListDeserializer' id: $ref: '#/components/schemas/Security_Lists_API_ListItemId' list_id: @@ -41275,15 +42216,21 @@ components: meta: $ref: '#/components/schemas/Security_Lists_API_ListItemMetadata' serializer: - type: string + $ref: '#/components/schemas/Security_Lists_API_ListSerializer' tie_breaker_id: + description: Field used in search to ensure all containers are sorted and returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 type: string type: $ref: '#/components/schemas/Security_Lists_API_ListType' updated_at: + description: Autogenerated date of last object update. + example: '2025-01-08T04:47:34.273Z' format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. + example: elastic type: string value: $ref: '#/components/schemas/Security_Lists_API_ListItemValue' @@ -41298,9 +42245,14 @@ components: - updated_at - updated_by Security_Lists_API_ListItemId: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Value list item's identifier. + example: 54b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string Security_Lists_API_ListItemMetadata: additionalProperties: true + description: Placeholder for metadata about the value list item. type: object Security_Lists_API_ListItemPrivileges: type: object @@ -41330,12 +42282,20 @@ components: - index - application Security_Lists_API_ListItemValue: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: The value used to evaluate exceptions. + format: nonempty + minLength: 1 + type: string Security_Lists_API_ListMetadata: additionalProperties: true + description: Placeholder for metadata about the value list. type: object Security_Lists_API_ListName: - $ref: '#/components/schemas/Security_Lists_API_NonEmptyString' + description: Value list's name. + example: List of bad IPs + format: nonempty + minLength: 1 + type: string Security_Lists_API_ListPrivileges: type: object properties: @@ -41363,7 +42323,21 @@ components: - cluster - index - application + Security_Lists_API_ListSerializer: + description: | + Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups: + + - `(?.+)` - Single value item types, such as ip, long, date, keyword, and text. + - `(?.+)-(?.+)|(?.+)` - Range value item types, such as `date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + example: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + type: string Security_Lists_API_ListType: + description: | + Specifies the Elasticsearch data type of excludes the list container holds. Some common examples: + + - `keyword`: Many ECS fields are Elasticsearch keywords + - `ip`: IP addresses + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR notation) enum: - binary - boolean @@ -41389,10 +42363,15 @@ components: - short - text type: string - Security_Lists_API_NonEmptyString: - description: A string that does not contain only whitespace characters - format: nonempty - minLength: 1 + Security_Lists_API_ListVersion: + description: The document version number. + example: 1 + minimum: 1 + type: integer + Security_Lists_API_ListVersionId: + description: | + The version id, normally returned by the API when the document is retrieved. Use it ensure updates are done against the latest version. + example: WzIsMV0= type: string Security_Lists_API_PlatformErrorResponse: type: object diff --git a/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml index 4613043012a32..2b4a318d6f21c 100644 --- a/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml @@ -891,8 +891,23 @@ components: FindEndpointListItemsFilter: $ref: '#/components/schemas/NonEmptyString' ListId: - $ref: '#/components/schemas/NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string ListType: + description: > + Specifies the Elasticsearch data type of excludes the list container + holds. Some common examples: + + + - `keyword`: Many ECS fields are Elasticsearch keywords + + - `ip`: IP addresses + + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR + notation) enum: - binary - boolean diff --git a/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml index 734761b8f4cdf..ec6009a8222fb 100644 --- a/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml @@ -891,8 +891,23 @@ components: FindEndpointListItemsFilter: $ref: '#/components/schemas/NonEmptyString' ListId: - $ref: '#/components/schemas/NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string ListType: + description: > + Specifies the Elasticsearch data type of excludes the list container + holds. Some common examples: + + + - `keyword`: Many ECS fields are Elasticsearch keywords + + - `ip`: IP addresses + + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR + notation) enum: - binary - boolean diff --git a/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml index 21e9be05a9a7e..c3e461e3ad6fc 100644 --- a/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml @@ -3259,8 +3259,23 @@ components: example: 'exception-list.attributes.name:%Detection%20List' type: string ListId: - $ref: '#/components/schemas/NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string ListType: + description: > + Specifies the Elasticsearch data type of excludes the list container + holds. Some common examples: + + + - `keyword`: Many ECS fields are Elasticsearch keywords + + - `ip`: IP addresses + + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR + notation) enum: - binary - boolean diff --git a/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml index 119da3ee7cd85..913e1d9b9196a 100644 --- a/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml @@ -3259,8 +3259,23 @@ components: example: 'exception-list.attributes.name:%Detection%20List' type: string ListId: - $ref: '#/components/schemas/NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string ListType: + description: > + Specifies the Elasticsearch data type of excludes the list container + holds. Some common examples: + + + - `keyword`: Many ECS fields are Elasticsearch keywords + + - `ip`: IP addresses + + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR + notation) enum: - binary - boolean diff --git a/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts b/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts index ce05117c33082..84c90fc71a9b0 100644 --- a/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Create list API endpoint + * title: Create value list API endpoint * version: 2023-10-31 */ @@ -23,6 +23,8 @@ import { ListName, ListDescription, ListType, + ListSerializer, + ListDeserializer, ListMetadata, } from '../model/list_common.gen'; import { List } from '../model/list_schemas.gen'; @@ -33,8 +35,8 @@ export const CreateListRequestBody = z.object({ name: ListName, description: ListDescription, type: ListType, - serializer: z.string().optional(), - deserializer: z.string().optional(), + serializer: ListSerializer.optional(), + deserializer: ListDeserializer.optional(), meta: ListMetadata.optional(), version: z.number().int().min(1).optional().default(1), }); diff --git a/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml index 191e973beba61..995780e6ed2d2 100644 --- a/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Create list API endpoint + title: Create value list API endpoint version: '2023-10-31' paths: /api/lists: @@ -8,10 +8,10 @@ paths: x-labels: [serverless, ess] operationId: CreateList x-codegen-enabled: true - summary: Create a list - description: Create a new list. + summary: Create a value list + description: Create a new value list. requestBody: - description: List's properties + description: Value list's properties required: true content: application/json: @@ -27,9 +27,9 @@ paths: type: $ref: '../model/list_common.schema.yaml#/components/schemas/ListType' serializer: - type: string + $ref: '../model/list_common.schema.yaml#/components/schemas/ListSerializer' deserializer: - type: string + $ref: '../model/list_common.schema.yaml#/components/schemas/ListDeserializer' meta: $ref: '../model/list_common.schema.yaml#/components/schemas/ListMetadata' version: @@ -40,6 +40,34 @@ paths: - name - description - type + examples: + ip: + value: + id: ip_list + name: Simple list with ips + description: This list describes bad internet ips + type: ip + ip_range: + value: + id: ip_range_list + name: Simple list with ip ranges + description: This list has ip ranges + type: ip_range + keyword: + value: + id: keyword_list + name: Simple list with a keyword + description: This list describes bad host names + type: keyword + keyword_custom_format: + value: + id: keyword_custom_format_list + name: Simple list with a keyword using a custom format + description: This parses the first found ipv4 only + serializer: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + deserializer: '{{value}}' + type: keyword + responses: 200: description: Successful response @@ -47,6 +75,69 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/List' + examples: + ip: + value: + id: ip_list + type: ip + name: Simple list with ips + description: This list describes bad internet ips + immutable: false + '@timestamp': 2025-01-08T04:47:34.273Z + version: 1 + _version: WzAsMV0= + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + updated_at: 2025-01-08T04:47:34.273Z + updated_by: elastic + ip_range: + value: + id: ip_range_list + type: ip_range + name: Simple list with ip ranges + description: This list has ip ranges + immutable: false + '@timestamp': 2025-01-09T18:23:52.241Z + version: 1 + _version: WzAsMV0= + tie_breaker_id: 74aebdaf-601f-4940-b351-155728ff7003 + created_at: 2025-01-09T18:23:52.241Z + created_by: elastic + updated_at: 2025-01-09T18:23:52.241Z + updated_by: elastic + keyword: + value: + id: keyword_list + type: keyword + name: Simple list with a keyword + description: This list describes bad host names + immutable: false + '@timestamp': 2025-01-09T18:24:55.786Z + version: 1 + _version: WzEsMV0= + tie_breaker_id: f7e7dbaa-daf7-4c9a-a3dc-56643923ef68 + created_at: 2025-01-09T18:24:55.786Z + created_by: elastic + updated_at: 2025-01-09T18:24:55.786Z + updated_by: elastic + keyword_custom_format: + value: + id: keyword_custom_format_list + type: keyword + name: Simple list with a keyword using a custom format + description: This parses the first found ipv4 only + serializer: '(?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?))' + deserializer: '{{value}}' + immutable: false + '@timestamp': 2025-01-09T18:25:39.604Z + version: 1 + _version: WzIsMV0= + tie_breaker_id: 8247ae63-b780-47b8-9a89-948b643e9ec2 + created_at: 2025-01-09T18:25:39.604Z + created_by: elastic + updated_at: 2025-01-09T18:25:39.604Z + updated_by: elastic 400: description: Invalid input data response content: @@ -55,27 +146,54 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: To create a list, the data stream must exist first. Data stream \".lists-default\" does not exist + status_code: 400 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 409: description: List already exists response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + alreadyExists: + value: + message: 'list id: "keyword_custom_format_list" already exists' + status_code: 409 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml b/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml index c775a9c7d873f..a991e2070fff1 100644 --- a/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml @@ -35,6 +35,13 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: @@ -47,9 +54,19 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + alreadyExists: + value: + message: 'data stream: \".lists-default\" and \".items-default\" already exists' + status_code: 409 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts b/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts index 4ebafd6568571..d158657568afd 100644 --- a/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Create list item API endpoint + * title: Create value list item API endpoint * version: 2023-10-31 */ @@ -28,7 +28,7 @@ export const CreateListItemRequestBody = z.object({ value: ListItemValue, meta: ListItemMetadata.optional(), /** - * Determines when changes made by the request are made visible to search + * Determines when changes made by the request are made visible to search. */ refresh: z.enum(['true', 'false', 'wait_for']).optional(), }); diff --git a/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml index 01121d0143925..55bce31572940 100644 --- a/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Create list item API endpoint + title: Create value list item API endpoint version: '2023-10-31' paths: /api/lists/items: @@ -8,15 +8,15 @@ paths: x-labels: [serverless, ess] operationId: CreateListItem x-codegen-enabled: true - summary: Create a list item + summary: Create a value list item description: | - Create a list item and associate it with the specified list. - - All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. + Create a value list item and associate it with the specified value list. + + All value list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. > info > Before creating a list item, you must create a list. requestBody: - description: List item's properties + description: Value list item's properties required: true content: application/json: @@ -37,10 +37,24 @@ paths: - 'true' - 'false' - wait_for - description: Determines when changes made by the request are made visible to search + description: Determines when changes made by the request are made visible to search. + example: wait_for required: - list_id - value + examples: + ip: + value: + list_id: ip_list + value: 127.0.0.1 + ip_range: + value: + list_id: ip_range_list + value: 192.168.0.0/16 + keyword: + value: + list_id: keyword_list + value: zeek responses: 200: description: Successful response @@ -48,6 +62,46 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/ListItem' + examples: + ip: + value: + id: 21b01cfb-058d-44b9-838c-282be16c91cc + type: ip + list_id: ip_list + value: 127.0.0.1 + '@timestamp': 2025-01-08T04:59:06.154Z + _version: WzAsMV0= + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + created_at: 2025-01-08T04:59:06.154Z + created_by: elastic + updated_at: 2025-01-08T04:59:06.154Z + updated_by: elastic + ip_range: + value: + id: ip_range_item + type: ip_range + list_id: ip_range_list + value: 192.168.0.0/16 + '@timestamp': 2025-01-09T18:33:08.202Z + _version: WzEsMV0= + tie_breaker_id: ea1b4189-efda-4637-b8f9-74655a5ebb61 + created_at: 2025-01-09T18:33:08.202Z + created_by: elastic + updated_at: 2025-01-09T18:33:08.202Z + updated_by: elastic + keyword: + value: + id: 7f24737d-1da8-4626-a568-33070591bb4e + type: keyword + list_id: keyword_list + value: zeek + '@timestamp': 2025-01-09T18:34:29.422Z + _version: WzIsMV0= + tie_breaker_id: 2108ced2-5e5d-401e-a88e-4dd69fc5fa27 + created_at: 2025-01-09T18:34:29.422Z + created_by: elastic + updated_at: 2025-01-09T18:34:29.422Z + updated_by: elastic 400: description: Invalid input data response content: @@ -56,27 +110,66 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: 'uri [/api/lists/items] with method [post] exists but is not available with the current configuration' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' + 404: + description: Not enough privileges response + content: + application/json: + schema: + $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + listNotFound: + value: + message: 'list id: \"ip_list\" does not exist' + status_code: 404 409: description: List item already exists response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + alreadyExists: + value: + message: 'list item id: \"ip_item\" already exists' + status_code: 409 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts b/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts index 109e6c58a1163..c900a35576ac1 100644 --- a/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Delete list API endpoint + * title: Delete value list API endpoint * version: 2023-10-31 */ @@ -24,11 +24,14 @@ import { List } from '../model/list_schemas.gen'; export type DeleteListRequestQuery = z.infer; export const DeleteListRequestQuery = z.object({ + id: ListId, /** - * List's `id` value + * Determines whether exception items referencing this value list should be deleted. */ - id: ListId, deleteReferences: BooleanFromString.optional().default(false), + /** + * Determines whether to delete value list without performing any additional checks of where this list may be utilized. + */ ignoreReferences: BooleanFromString.optional().default(false), }); export type DeleteListRequestQueryInput = z.input; diff --git a/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml index 7098753636379..f59660ee5993c 100644 --- a/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Delete list API endpoint + title: Delete value list API endpoint version: '2023-10-31' paths: /api/lists: @@ -8,16 +8,15 @@ paths: x-labels: [serverless, ess] operationId: DeleteList x-codegen-enabled: true - summary: Delete a list + summary: Delete a value list description: | - Delete a list using the list ID. + Delete a value list using the list ID. > info > When you delete a list, all of its list items are also deleted. parameters: - name: id in: query required: true - description: List's `id` value schema: $ref: '../model/list_common.schema.yaml#/components/schemas/ListId' - name: deleteReferences @@ -26,12 +25,16 @@ paths: schema: type: boolean default: false + example: false + description: Determines whether exception items referencing this value list should be deleted. - name: ignoreReferences in: query required: false schema: type: boolean default: false + example: false + description: Determines whether to delete value list without performing any additional checks of where this list may be utilized. responses: 200: description: Successful response @@ -39,6 +42,22 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/List' + examples: + ipList: + value: + id: 21b01cfb-058d-44b9-838c-282be16c91cd + type: ip + name: Bad ips + description: List of bad internet ips. + immutable: false + '@timestamp': 2025-01-08T04:47:34.273Z + version: 3 + _version: WzIsMV0= + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + updated_at: 2025-01-08T05:39:39.292Z + updated_by: elastic 400: description: Invalid input data response content: @@ -47,27 +66,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request query]: id: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [DELETE /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: List not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'list id: \"ip_list\" was not found' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.gen.ts b/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.gen.ts index 314c1e81bc6a9..1c4d32e004a3a 100644 --- a/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Delete list DS API endpoint + * title: Delete value list DS API endpoint * version: 2023-10-31 */ diff --git a/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml b/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml index 4f4b0f00e8817..d61d6c68f56d0 100644 --- a/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Delete list DS API endpoint + title: Delete value list DS API endpoint version: '2023-10-31' paths: /api/lists/index: @@ -8,7 +8,7 @@ paths: x-labels: [serverless, ess] operationId: DeleteListIndex x-codegen-enabled: true - summary: Delete list data streams + summary: Delete value list data streams description: Delete the `.lists` and `.items` data streams. responses: 200: @@ -35,6 +35,12 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: @@ -53,3 +59,8 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.gen.ts b/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.gen.ts index 178641cd8d6af..f51b0bdab21dc 100644 --- a/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.gen.ts @@ -12,31 +12,31 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Delete list item API endpoint + * title: Delete value list item API endpoint * version: 2023-10-31 */ import { z } from '@kbn/zod'; -import { ListId } from '../model/list_common.gen'; +import { ListItemId, ListId } from '../model/list_common.gen'; import { ListItem } from '../model/list_schemas.gen'; export type DeleteListItemRequestQuery = z.infer; export const DeleteListItemRequestQuery = z.object({ /** - * Required if `list_id` and `value` are not specified + * Value list item's identifier. Required if `list_id` and `value` are not specified. */ - id: ListId.optional(), + id: ListItemId.optional(), /** - * Required if `id` is not specified + * Value list's identifier. Required if `id` is not specified. */ list_id: ListId.optional(), /** - * Required if `id` is not specified + * The value used to evaluate exceptions. Required if `id` is not specified. */ value: z.string().optional(), /** - * Determines when changes made by the request are made visible to search + * Determines when changes made by the request are made visible to search. */ refresh: z.enum(['true', 'false', 'wait_for']).optional().default('false'), }); diff --git a/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml index 28913259387dd..fa2aac21e5166 100644 --- a/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Delete list item API endpoint + title: Delete value list item API endpoint version: '2023-10-31' paths: /api/lists/items: @@ -8,35 +8,37 @@ paths: x-labels: [serverless, ess] operationId: DeleteListItem x-codegen-enabled: true - summary: Delete a list item - description: Delete a list item using its `id`, or its `list_id` and `value` fields. + summary: Delete a value list item + description: Delete a value list item using its `id`, or its `list_id` and `value` fields. parameters: - name: id in: query required: false - description: Required if `list_id` and `value` are not specified + description: Value list item's identifier. Required if `list_id` and `value` are not specified. schema: - $ref: '../model/list_common.schema.yaml#/components/schemas/ListId' + $ref: '../model/list_common.schema.yaml#/components/schemas/ListItemId' - name: list_id in: query required: false - description: Required if `id` is not specified + description: Value list's identifier. Required if `id` is not specified. schema: $ref: '../model/list_common.schema.yaml#/components/schemas/ListId' - name: value in: query required: false - description: Required if `id` is not specified + description: The value used to evaluate exceptions. Required if `id` is not specified. schema: type: string + example: 255.255.255.255 - name: refresh in: query required: false - description: Determines when changes made by the request are made visible to search + description: Determines when changes made by the request are made visible to search. schema: type: string enum: ['true', 'false', 'wait_for'] default: 'false' + example: false responses: 200: description: Successful response @@ -48,6 +50,20 @@ paths: - type: array items: $ref: '../model/list_schemas.schema.yaml#/components/schemas/ListItem' + examples: + ip: + value: + id: pd1WRJQBs4HAK3VQeHFI + type: ip + list_id: ip_list + value: 255.255.255.255 + '@timestamp': 2025-01-08T05:15:05.159Z + _version: WzIwLDFd + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + updated_at: 2025-01-08T05:44:14.009Z + updated_by: elastic 400: description: Invalid input data response content: @@ -56,27 +72,54 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + message: 'Either \"list_id\" or \"id\" needs to be defined in the request' + status_code: 400 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [DELETE /api/lists/items?id=pd1WRJQBs4HAK3VQeHFI] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: List item not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'list item with id: \"pd1WRJQBs4HAK3VQeHFI\" not found' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.gen.ts b/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.gen.ts index 4e514abefccc2..76dafb96a7364 100644 --- a/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Export list items API endpoint + * title: Export value list items API endpoint * version: 2023-10-31 */ @@ -23,7 +23,7 @@ import { ListId } from '../model/list_common.gen'; export type ExportListItemsRequestQuery = z.infer; export const ExportListItemsRequestQuery = z.object({ /** - * List's id to export + * Value list's `id` to export. */ list_id: ListId, }); diff --git a/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml b/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml index 8d185a23b64c9..a8652c680eeee 100644 --- a/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Export list items API endpoint + title: Export value list items API endpoint version: '2023-10-31' paths: /api/lists/items/_export: @@ -8,13 +8,13 @@ paths: x-labels: [serverless, ess] operationId: ExportListItems x-codegen-enabled: true - summary: Export list items - description: Export list item values from the specified list. + summary: Export value list items + description: Export list item values from the specified value list. parameters: - name: list_id in: query required: true - description: List's id to export + description: Value list's `id` to export. schema: $ref: '../model/list_common.schema.yaml#/components/schemas/ListId' responses: @@ -26,6 +26,16 @@ paths: type: string format: binary description: A `.txt` file containing list items from the specified list + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 400: description: Invalid input data response content: @@ -34,18 +44,35 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: 'Bad Request","message":"[request query]: list_id: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/lists/items/_export?list_id=ips.txt] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 404: description: List not found response content: @@ -58,3 +85,8 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts b/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts index f693965e91e2e..a1dd60b259ee2 100644 --- a/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts @@ -17,45 +17,39 @@ */ import { z } from '@kbn/zod'; +import { isNonEmptyString } from '@kbn/zod-helpers'; -import { NonEmptyString } from '@kbn/openapi-common/schemas/primitives.gen'; import { ListId } from '../model/list_common.gen'; import { ListItem } from '../model/list_schemas.gen'; +/** + * Returns the items that come after the last item returned in the previous call (use the `cursor` value returned in the previous call). This parameter uses the `tie_breaker_id` field to ensure all items are sorted and returned correctly. + */ export type FindListItemsCursor = z.infer; -export const FindListItemsCursor = NonEmptyString; +export const FindListItemsCursor = z.string().min(1).superRefine(isNonEmptyString); export type FindListItemsFilter = z.infer; export const FindListItemsFilter = z.string(); export type FindListItemsRequestQuery = z.infer; export const FindListItemsRequestQuery = z.object({ - /** - * List's id - */ list_id: ListId, /** - * The page number to return + * The page number to return. */ page: z.coerce.number().int().optional(), /** - * The number of list items to return per page + * The number of list items to return per page. */ per_page: z.coerce.number().int().optional(), /** - * Determines which field is used to sort the results + * Determines which field is used to sort the results. */ - sort_field: NonEmptyString.optional(), + sort_field: z.string().min(1).superRefine(isNonEmptyString).optional(), /** * Determines the sort order, which can be `desc` or `asc` */ sort_order: z.enum(['desc', 'asc']).optional(), - /** - * Returns the list that come after the last list returned in the previous call -(use the cursor value returned in the previous call). This parameter uses -the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. - - */ cursor: FindListItemsCursor.optional(), /** * Filters the returned results according to the value of the specified field, diff --git a/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml b/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml index 21cf4ffd61841..7d84fbdea1737 100644 --- a/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml @@ -8,33 +8,37 @@ paths: x-labels: [serverless, ess] operationId: FindListItems x-codegen-enabled: true - summary: Get list items - description: Get all list items in the specified list. + summary: Get value list items + description: Get all value list items in the specified list. parameters: - name: list_id in: query required: true - description: List's id schema: $ref: '../model/list_common.schema.yaml#/components/schemas/ListId' - name: page in: query required: false - description: The page number to return + description: The page number to return. schema: type: integer + example: 1 - name: per_page in: query required: false - description: The number of list items to return per page + description: The number of list items to return per page. schema: type: integer + example: 20 - name: sort_field in: query required: false - description: Determines which field is used to sort the results + description: Determines which field is used to sort the results. schema: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + example: value - name: sort_order in: query required: false @@ -42,13 +46,10 @@ paths: schema: type: string enum: [desc, asc] + example: asc - name: cursor in: query required: false - description: | - Returns the list that come after the last list returned in the previous call - (use the cursor value returned in the previous call). This parameter uses - the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. schema: $ref: '#/components/schemas/FindListItemsCursor' - name: filter @@ -88,6 +89,25 @@ paths: - per_page - total - cursor + examples: + ip: + value: + data: + - id: 21b01cfb-058d-44b9-838c-282be16c91cc + type: ip + list_id: ip_list + value: 127.0.0.1 + '@timestamp': 2025-01-08T04:59:06.154Z + _version: WzAsMV0= + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + created_at: 2025-01-08T04:59:06.154Z + created_by: elastic + updated_at: 2025-01-08T04:59:06.154Z + updated_by: elastic + page: 1 + per_page: 20 + total: 1 + cursor: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d 400: description: Invalid input data response content: @@ -96,29 +116,57 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400, + error: Bad Request, + message: '[request query]: list_id: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists/items/_find?list_id=ip_list&page=1&per_page=20] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: schemas: FindListItemsCursor: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: 'Returns the items that come after the last item returned in the previous call (use the `cursor` value returned in the previous call). This parameter uses the `tie_breaker_id` field to ensure all items are sorted and returned correctly.' + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d FindListItemsFilter: type: string + example: 'value:127.0.0.1' diff --git a/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.gen.ts b/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.gen.ts index ec104f2e6c2b1..e9ff80529ab8e 100644 --- a/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.gen.ts @@ -12,17 +12,17 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Find lists API endpoint + * title: Find value lists API endpoint * version: 2023-10-31 */ import { z } from '@kbn/zod'; +import { isNonEmptyString } from '@kbn/zod-helpers'; -import { NonEmptyString } from '@kbn/openapi-common/schemas/primitives.gen'; import { List } from '../model/list_schemas.gen'; export type FindListsCursor = z.infer; -export const FindListsCursor = NonEmptyString; +export const FindListsCursor = z.string().min(1).superRefine(isNonEmptyString); export type FindListsFilter = z.infer; export const FindListsFilter = z.string(); @@ -30,27 +30,24 @@ export const FindListsFilter = z.string(); export type FindListsRequestQuery = z.infer; export const FindListsRequestQuery = z.object({ /** - * The page number to return + * The page number to return. */ page: z.coerce.number().int().optional(), /** - * The number of lists to return per page + * The number of value lists to return per page. */ per_page: z.coerce.number().int().optional(), /** - * Determines which field is used to sort the results + * Determines which field is used to sort the results. */ - sort_field: NonEmptyString.optional(), + sort_field: z.string().min(1).superRefine(isNonEmptyString).optional(), /** * Determines the sort order, which can be `desc` or `asc` */ sort_order: z.enum(['desc', 'asc']).optional(), - /** - * Returns the list that come after the last list returned in the previous call -(use the cursor value returned in the previous call). This parameter uses -the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. - - */ + /** + * Returns the lists that come after the last lists returned in the previous call (use the `cursor` value returned in the previous call). This parameter uses the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. + */ cursor: FindListsCursor.optional(), /** * Filters the returned results according to the value of the specified field, diff --git a/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml b/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml index 3bb55decacff6..8ffbee3fbfc4c 100644 --- a/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Find lists API endpoint + title: Find value lists API endpoint version: '2023-10-31' paths: /api/lists/_find: @@ -8,27 +8,32 @@ paths: x-labels: [serverless, ess] operationId: FindLists x-codegen-enabled: true - summary: Get lists - description: Get a paginated subset of lists. By default, the first page is returned, with 20 results per page. + summary: Get value lists + description: Get a paginated subset of value lists. By default, the first page is returned, with 20 results per page. parameters: - name: page in: query required: false - description: The page number to return + description: The page number to return. schema: type: integer + example: 1 - name: per_page in: query required: false - description: The number of lists to return per page + description: The number of value lists to return per page. schema: type: integer + example: 20 - name: sort_field in: query required: false - description: Determines which field is used to sort the results + description: Determines which field is used to sort the results. schema: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + example: name - name: sort_order in: query required: false @@ -36,13 +41,11 @@ paths: schema: type: string enum: [desc, asc] + example: asc - name: cursor in: query required: false - description: | - Returns the list that come after the last list returned in the previous call - (use the cursor value returned in the previous call). This parameter uses - the `tie_breaker_id` field to ensure all lists are sorted and returned correctly. + description: 'Returns the lists that come after the last lists returned in the previous call (use the `cursor` value returned in the previous call). This parameter uses the `tie_breaker_id` field to ensure all lists are sorted and returned correctly.' schema: $ref: '#/components/schemas/FindListsCursor' - name: filter @@ -82,6 +85,30 @@ paths: - per_page - total - cursor + examples: + ipList: + value: + data: + - id: ip_list + type: ip + name: Simple list with an ip + description: This list describes bad internet ip + immutable: false + '@timestamp': | + 2025-01-08T04:47:34.273Z + version: 1 + _version: WzAsMV0= + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + created_at: | + 2025-01-08T04:47:34.273Z + created_by: elastic + updated_at: | + 2025-01-08T04:47:34.273Z + updated_by: elastic + page: 1 + per_page: 20 + total: 1 + cursor: WzIwLFsiZjU1MDgxODgtYjFlOS00ZTZlLTk2NjItZDAzOWE3ZDg5ODk5Il1d 400: description: Invalid input data response content: @@ -90,29 +117,56 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request query]: page: Expected number, received nan' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists/_find?page=1&per_page=20] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: schemas: FindListsCursor: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d FindListsFilter: type: string + example: 'value:127.0.0.1' diff --git a/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.gen.ts b/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.gen.ts index b71b05bd75955..eef0d24dddb4a 100644 --- a/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Import list items API endpoint + * title: Import value list items API endpoint * version: 2023-10-31 */ @@ -33,14 +33,29 @@ Required when importing to an existing list. /** * Type of the importing list. -Required when importing a new list that is `list_id` is not specified. +Required when importing a new list whose list `id` is not specified. */ type: ListType.optional(), + /** + * Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups: + +- `(?.+)` - Single value item types, such as ip, long, date, keyword, and text. +- `(?.+)-(?.+)|(?.+)` - Range value item types, such as `date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + + */ serializer: z.string().optional(), + /** + * Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions: + +- `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, and `text`. +- `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. +- `{{{gte}}},{{{lte}}}` - Date range values. + + */ deserializer: z.string().optional(), /** - * Determines when changes made by the request are made visible to search + * Determines when changes made by the request are made visible to search. */ refresh: z.enum(['true', 'false', 'wait_for']).optional(), }); diff --git a/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml b/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml index 520213e949c1d..3e96a9a3e64cd 100644 --- a/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Import list items API endpoint + title: Import value list items API endpoint version: '2023-10-31' paths: /api/lists/items/_import: @@ -8,9 +8,9 @@ paths: x-labels: [serverless, ess] operationId: ImportListItems x-codegen-enabled: true - summary: Import list items + summary: Import value list items description: | - Import list items from a TXT or CSV file. The maximum file size is 9 million bytes. + Import value list items from a TXT or CSV file. The maximum file size is 9 million bytes. You can import items to a new or existing list. requestBody: @@ -23,7 +23,17 @@ paths: file: type: string format: binary - description: A `.txt` or `.csv` file containing newline separated list items + description: A `.txt` or `.csv` file containing newline separated list items. + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 parameters: - name: list_id in: query @@ -40,26 +50,43 @@ paths: description: | Type of the importing list. - Required when importing a new list that is `list_id` is not specified. + Required when importing a new list whose list `id` is not specified. schema: $ref: '../model/list_common.schema.yaml#/components/schemas/ListType' + examples: + ip: + value: ip - name: serializer in: query required: false + description: | + Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups: + + - `(?.+)` - Single value item types, such as ip, long, date, keyword, and text. + - `(?.+)-(?.+)|(?.+)` - Range value item types, such as `date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. schema: type: string + example: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) - name: deserializer in: query required: false + description: | + Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions: + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, and `text`. + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + - `{{{gte}}},{{{lte}}}` - Date range values. schema: type: string + example: '{{value}}' - name: refresh in: query required: false - description: Determines when changes made by the request are made visible to search + description: Determines when changes made by the request are made visible to search. schema: type: string enum: ['true', 'false', 'wait_for'] + example: true responses: 200: description: Successful response @@ -67,6 +94,22 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/List' + examples: + ip: + value: + id: ip_list + type: ip + name: Simple list with an ip + description: This list describes bad internet ip + immutable: false + '@timestamp': 2025-01-08T04:47:34.273Z + version: 1 + _version: WzAsMV0= + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + updated_at: 2025-01-08T04:47:34.273Z + updated_by: elastic 400: description: Invalid input data response content: @@ -75,18 +118,35 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + message: 'Either type or list_id need to be defined in the query' + status_code: 400 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/lists/items/_import?list_id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 409: description: List with specified list_id does not exist response content: @@ -99,3 +159,8 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/model/list_common.gen.ts b/packages/kbn-securitysolution-lists-common/api/model/list_common.gen.ts index 9a51bd0eeb5ad..826037c7b46fd 100644 --- a/packages/kbn-securitysolution-lists-common/api/model/list_common.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/model/list_common.gen.ts @@ -12,17 +12,27 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Common List Attributes + * title: Common Value List Attributes * version: not applicable */ import { z } from '@kbn/zod'; +import { isNonEmptyString } from '@kbn/zod-helpers'; -import { NonEmptyString } from '@kbn/openapi-common/schemas/primitives.gen'; - +/** + * Value list's identifier. + */ export type ListId = z.infer; -export const ListId = NonEmptyString; +export const ListId = z.string().min(1).superRefine(isNonEmptyString); + +/** + * Specifies the Elasticsearch data type of excludes the list container holds. Some common examples: +- `keyword`: Many ECS fields are Elasticsearch keywords +- `ip`: IP addresses +- `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR notation) + + */ export type ListType = z.infer; export const ListType = z.enum([ 'binary', @@ -52,23 +62,78 @@ export const ListType = z.enum([ export type ListTypeEnum = typeof ListType.enum; export const ListTypeEnum = ListType.enum; +/** + * Value list's name. + */ export type ListName = z.infer; -export const ListName = NonEmptyString; +export const ListName = z.string().min(1).superRefine(isNonEmptyString); +/** + * Describes the value list. + */ export type ListDescription = z.infer; -export const ListDescription = NonEmptyString; +export const ListDescription = z.string().min(1).superRefine(isNonEmptyString); +/** + * Placeholder for metadata about the value list. + */ export type ListMetadata = z.infer; export const ListMetadata = z.object({}).catchall(z.unknown()); +/** + * Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups: + +- `(?.+)` - Single value item types, such as ip, long, date, keyword, and text. +- `(?.+)-(?.+)|(?.+)` - Range value item types, such as `date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + + */ +export type ListSerializer = z.infer; +export const ListSerializer = z.string(); + +/** + * Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions: + +- `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, and `text`. +- `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. +- `{{{gte}}},{{{lte}}}` - Date range values. + + */ +export type ListDeserializer = z.infer; +export const ListDeserializer = z.string(); + +/** + * The document version number. + */ +export type ListVersion = z.infer; +export const ListVersion = z.number().int().min(1); + +/** + * The version id, normally returned by the API when the document is retrieved. Use it ensure updates are done against the latest version. + + */ +export type ListVersionId = z.infer; +export const ListVersionId = z.string(); + +/** + * Value list item's identifier. + */ export type ListItemId = z.infer; -export const ListItemId = NonEmptyString; +export const ListItemId = z.string().min(1).superRefine(isNonEmptyString); +/** + * The value used to evaluate exceptions. + */ export type ListItemValue = z.infer; -export const ListItemValue = NonEmptyString; +export const ListItemValue = z.string().min(1).superRefine(isNonEmptyString); +/** + * Describes the value list item. + */ export type ListItemDescription = z.infer; -export const ListItemDescription = NonEmptyString; +export const ListItemDescription = z.string().min(1).superRefine(isNonEmptyString); +/** + * Placeholder for metadata about the value list item. + */ export type ListItemMetadata = z.infer; export const ListItemMetadata = z.object({}).catchall(z.unknown()); diff --git a/packages/kbn-securitysolution-lists-common/api/model/list_common.schema.yaml b/packages/kbn-securitysolution-lists-common/api/model/list_common.schema.yaml index 6fb160105bb5a..3b995fec9e2ac 100644 --- a/packages/kbn-securitysolution-lists-common/api/model/list_common.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/model/list_common.schema.yaml @@ -1,12 +1,16 @@ openapi: 3.0.0 info: - title: Common List Attributes + title: Common Value List Attributes version: 'not applicable' paths: {} components: schemas: ListId: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd ListType: type: string @@ -34,26 +38,83 @@ components: - shape - short - text + description: | + Specifies the Elasticsearch data type of excludes the list container holds. Some common examples: + + - `keyword`: Many ECS fields are Elasticsearch keywords + - `ip`: IP addresses + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR notation) ListName: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Value list's name. + example: 'List of bad IPs' ListDescription: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Describes the value list. ListMetadata: type: object additionalProperties: true + description: Placeholder for metadata about the value list. + + ListSerializer: + type: string + description: | + Determines how uploaded list item values are parsed. By default, list items are parsed using these named regex groups: + + - `(?.+)` - Single value item types, such as ip, long, date, keyword, and text. + - `(?.+)-(?.+)|(?.+)` - Range value item types, such as `date_range`, `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + example: (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + + ListDeserializer: + type: string + description: | + Determines how retrieved list item values are presented. By default list items are presented using these Handelbar expressions: + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, `keyword`, and `text`. + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, `double_range`, `float_range`, `integer_range`, and `long_range`. + - `{{{gte}}},{{{lte}}}` - Date range values. + example: '{{value}}' + + ListVersion: + type: integer + minimum: 1 + description: The document version number. + example: 1 + + ListVersionId: + type: string + description: | + The version id, normally returned by the API when the document is retrieved. Use it ensure updates are done against the latest version. + example: WzIsMV0= ListItemId: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Value list item's identifier. + example: 54b01cfb-058d-44b9-838c-282be16c91cd ListItemValue: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: The value used to evaluate exceptions. ListItemDescription: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Describes the value list item. + example: Value list description. ListItemMetadata: type: object additionalProperties: true + description: Placeholder for metadata about the value list item. diff --git a/packages/kbn-securitysolution-lists-common/api/model/list_schemas.gen.ts b/packages/kbn-securitysolution-lists-common/api/model/list_schemas.gen.ts index 14d9547c35b59..6bc044b449661 100644 --- a/packages/kbn-securitysolution-lists-common/api/model/list_schemas.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/model/list_schemas.gen.ts @@ -23,7 +23,11 @@ import { ListType, ListName, ListDescription, + ListSerializer, + ListDeserializer, ListMetadata, + ListVersion, + ListVersionId, ListItemId, ListItemValue, ListItemMetadata, @@ -35,17 +39,32 @@ export const List = z.object({ type: ListType, name: ListName, description: ListDescription, - serializer: z.string().optional(), - deserializer: z.string().optional(), + serializer: ListSerializer.optional(), + deserializer: ListDeserializer.optional(), immutable: z.boolean(), meta: ListMetadata.optional(), '@timestamp': z.string().datetime().optional(), - version: z.number().int().min(1), - _version: z.string().optional(), + version: ListVersion, + _version: ListVersionId.optional(), + /** + * Field used in search to ensure all containers are sorted and returned correctly. + */ tie_breaker_id: z.string(), + /** + * Autogenerated date of object creation. + */ created_at: z.string().datetime(), + /** + * Autogenerated value - user that created object. + */ created_by: z.string(), + /** + * Autogenerated date of last object update. + */ updated_at: z.string().datetime(), + /** + * Autogenerated value - user that last updated object. + */ updated_by: z.string(), }); @@ -55,14 +74,29 @@ export const ListItem = z.object({ type: ListType, list_id: ListId, value: ListItemValue, - serializer: z.string().optional(), - deserializer: z.string().optional(), + serializer: ListSerializer.optional(), + deserializer: ListDeserializer.optional(), meta: ListItemMetadata.optional(), '@timestamp': z.string().datetime().optional(), - _version: z.string().optional(), + _version: ListVersionId.optional(), + /** + * Field used in search to ensure all containers are sorted and returned correctly. + */ tie_breaker_id: z.string(), + /** + * Autogenerated date of object creation. + */ created_at: z.string().datetime(), + /** + * Autogenerated value - user that created object. + */ created_by: z.string(), + /** + * Autogenerated date of last object update. + */ updated_at: z.string().datetime(), + /** + * Autogenerated value - user that last updated object. + */ updated_by: z.string(), }); diff --git a/packages/kbn-securitysolution-lists-common/api/model/list_schemas.schema.yaml b/packages/kbn-securitysolution-lists-common/api/model/list_schemas.schema.yaml index 838dc5e4edea0..65f03c7befb89 100644 --- a/packages/kbn-securitysolution-lists-common/api/model/list_schemas.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/model/list_schemas.schema.yaml @@ -17,9 +17,9 @@ components: description: $ref: './list_common.schema.yaml#/components/schemas/ListDescription' serializer: - type: string + $ref: './list_common.schema.yaml#/components/schemas/ListSerializer' deserializer: - type: string + $ref: './list_common.schema.yaml#/components/schemas/ListDeserializer' immutable: type: boolean meta: @@ -27,23 +27,33 @@ components: '@timestamp': type: string format: date-time + example: 2025-01-08T04:47:34.273Z version: - type: integer - minimum: 1 + $ref: './list_common.schema.yaml#/components/schemas/ListVersion' _version: - type: string + $ref: './list_common.schema.yaml#/components/schemas/ListVersionId' tie_breaker_id: type: string + description: Field used in search to ensure all containers are sorted and returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 created_at: type: string format: date-time + description: Autogenerated date of object creation. + example: 2025-01-08T04:47:34.273Z created_by: type: string + description: Autogenerated value - user that created object. + example: elastic updated_at: type: string format: date-time + description: Autogenerated date of last object update. + example: 2025-01-08T04:47:34.273Z updated_by: type: string + description: Autogenerated value - user that last updated object. + example: elastic required: - id - type @@ -69,28 +79,39 @@ components: value: $ref: './list_common.schema.yaml#/components/schemas/ListItemValue' serializer: - type: string + $ref: './list_common.schema.yaml#/components/schemas/ListSerializer' deserializer: - type: string + $ref: './list_common.schema.yaml#/components/schemas/ListDeserializer' meta: $ref: './list_common.schema.yaml#/components/schemas/ListItemMetadata' '@timestamp': type: string format: date-time + example: 2025-01-08T04:47:34.273Z _version: - type: string + $ref: './list_common.schema.yaml#/components/schemas/ListVersionId' tie_breaker_id: type: string + description: Field used in search to ensure all containers are sorted and returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 created_at: type: string format: date-time + description: Autogenerated date of object creation. + example: 2025-01-08T04:47:34.273Z created_by: type: string + description: Autogenerated value - user that created object. + example: elastic updated_at: type: string format: date-time + description: Autogenerated date of last object update. + example: 2025-01-08T04:47:34.273Z updated_by: type: string + description: Autogenerated value - user that last updated object. + example: elastic required: - id - type diff --git a/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.gen.ts b/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.gen.ts index d7c955e6daac3..4d7d3b838e40d 100644 --- a/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.gen.ts @@ -12,13 +12,20 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Patch list API endpoint + * title: Patch value list API endpoint * version: 2023-10-31 */ import { z } from '@kbn/zod'; -import { ListId, ListName, ListDescription, ListMetadata } from '../model/list_common.gen'; +import { + ListId, + ListName, + ListDescription, + ListMetadata, + ListVersion, + ListVersionId, +} from '../model/list_common.gen'; import { List } from '../model/list_schemas.gen'; export type PatchListRequestBody = z.infer; @@ -27,8 +34,8 @@ export const PatchListRequestBody = z.object({ name: ListName.optional(), description: ListDescription.optional(), meta: ListMetadata.optional(), - version: z.number().int().min(1).optional(), - _version: z.string().optional(), + version: ListVersion.optional(), + _version: ListVersionId.optional(), }); export type PatchListRequestBodyInput = z.input; diff --git a/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml index b98b34e6347eb..728288bb9e1a9 100644 --- a/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Patch list API endpoint + title: Patch value list API endpoint version: '2023-10-31' paths: /api/lists: @@ -8,10 +8,10 @@ paths: x-labels: [serverless, ess] operationId: PatchList x-codegen-enabled: true - summary: Patch a list - description: Update specific fields of an existing list using the list ID. + summary: Patch a value list + description: Update specific fields of an existing list using the list `id`. requestBody: - description: List's properties + description: Value list's properties required: true content: application/json: @@ -27,12 +27,14 @@ paths: meta: $ref: '../model/list_common.schema.yaml#/components/schemas/ListMetadata' version: - type: integer - minimum: 1 + $ref: '../model/list_common.schema.yaml#/components/schemas/ListVersion' _version: - type: string + $ref: '../model/list_common.schema.yaml#/components/schemas/ListVersionId' required: - id + example: + id: ip_list + name: Bad ips list - UPDATED responses: 200: description: Successful response @@ -40,6 +42,22 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/List' + examples: + ip: + value: + id: ip_list + type: ip + name: Bad ips list - UPDATED + description: This list describes bad internet ips + immutable: false + '@timestamp': 2025-01-08T04:47:34.273Z + version: 2 + _version: WzEsMV0= + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + updated_at: 2025-01-08T05:21:53.843Z + updated_by: elastic 400: description: Invalid input data response content: @@ -48,27 +66,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: name: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [PATCH /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: List not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.gen.ts b/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.gen.ts index 9943a9999a898..31b0665bbfb57 100644 --- a/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.gen.ts @@ -12,13 +12,18 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Patch list item API endpoint + * title: Patch value list item API endpoint * version: 2023-10-31 */ import { z } from '@kbn/zod'; -import { ListItemId, ListItemValue, ListItemMetadata } from '../model/list_common.gen'; +import { + ListItemId, + ListItemValue, + ListItemMetadata, + ListVersionId, +} from '../model/list_common.gen'; import { ListItem } from '../model/list_schemas.gen'; export type PatchListItemRequestBody = z.infer; @@ -26,9 +31,9 @@ export const PatchListItemRequestBody = z.object({ id: ListItemId, value: ListItemValue.optional(), meta: ListItemMetadata.optional(), - _version: z.string().optional(), + _version: ListVersionId.optional(), /** - * Determines when changes made by the request are made visible to search + * Determines when changes made by the request are made visible to search. */ refresh: z.enum(['true', 'false', 'wait_for']).optional(), }); diff --git a/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml index f79efc4691dde..2ccd18ab43ca9 100644 --- a/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Patch list item API endpoint + title: Patch value list item API endpoint version: '2023-10-31' paths: /api/lists/items: @@ -8,10 +8,10 @@ paths: x-labels: [serverless, ess] operationId: PatchListItem x-codegen-enabled: true - summary: Patch a list item - description: Update specific fields of an existing list item using the list item ID. + summary: Patch a value list item + description: Update specific fields of an existing value list item using the item `id`. requestBody: - description: List item's properties + description: Value list item's properties required: true content: application/json: @@ -25,16 +25,19 @@ paths: meta: $ref: '../model/list_common.schema.yaml#/components/schemas/ListItemMetadata' _version: - type: string + $ref: '../model/list_common.schema.yaml#/components/schemas/ListVersionId' refresh: type: string enum: - 'true' - 'false' - wait_for - description: Determines when changes made by the request are made visible to search + description: Determines when changes made by the request are made visible to search. required: - id + example: + id: pd1WRJQBs4HAK3VQeHFI + value: 255.255.255.255 responses: 200: description: Successful response @@ -42,6 +45,20 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/ListItem' + examples: + ipItem: + value: + id: pd1WRJQBs4HAK3VQeHFI + type: ip + list_id: ip_list + value: '255.255.255.255' + '@timestamp': 2025-01-08T05:15:05.159Z + _version: WzE5LDFd + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + updated_at: 2025-01-08T05:23:37.602Z + updated_by: elastic 400: description: Invalid input data response content: @@ -50,27 +67,54 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + message: '{"took":15,"timed_out":false,"total":1,"updated":0,"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,"failures":[{"index":".ds-.items-default-2025.01.09-000001","id":"ip_item","cause":{"type":"document_parsing_exception","reason":"[1:107] failed to parse field [ip] of type [ip] in document with id ip_item. Preview of fields value: 2","caused_by":{"type":"illegal_argument_exception","reason":"2 is not an IP string literal."}},"status":400}]}' + status_code: 400 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [PATCH /api/lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: List item not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts b/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts index 7bf343d935f2c..97d700111edbc 100644 --- a/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts @@ -78,7 +78,7 @@ export class Client { this.log = options.log; } /** - * Create a new list. + * Create a new value list. */ async createList(props: CreateListProps) { this.log.info(`${new Date().toISOString()} Calling API CreateList`); @@ -109,9 +109,9 @@ export class Client { .catch(catchAxiosErrorFormatAndThrow); } /** - * Create a list item and associate it with the specified list. + * Create a value list item and associate it with the specified value list. -All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. +All value list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. > info > Before creating a list item, you must create a list. @@ -130,7 +130,7 @@ All list items in the same list must be the same type. For example, each list it .catch(catchAxiosErrorFormatAndThrow); } /** - * Delete a list using the list ID. + * Delete a value list using the list ID. > info > When you delete a list, all of its list items are also deleted. @@ -165,7 +165,7 @@ All list items in the same list must be the same type. For example, each list it .catch(catchAxiosErrorFormatAndThrow); } /** - * Delete a list item using its `id`, or its `list_id` and `value` fields. + * Delete a value list item using its `id`, or its `list_id` and `value` fields. */ async deleteListItem(props: DeleteListItemProps) { this.log.info(`${new Date().toISOString()} Calling API DeleteListItem`); @@ -182,7 +182,7 @@ All list items in the same list must be the same type. For example, each list it .catch(catchAxiosErrorFormatAndThrow); } /** - * Export list item values from the specified list. + * Export list item values from the specified value list. */ async exportListItems(props: ExportListItemsProps) { this.log.info(`${new Date().toISOString()} Calling API ExportListItems`); @@ -199,7 +199,7 @@ All list items in the same list must be the same type. For example, each list it .catch(catchAxiosErrorFormatAndThrow); } /** - * Get all list items in the specified list. + * Get all value list items in the specified list. */ async findListItems(props: FindListItemsProps) { this.log.info(`${new Date().toISOString()} Calling API FindListItems`); @@ -216,7 +216,7 @@ All list items in the same list must be the same type. For example, each list it .catch(catchAxiosErrorFormatAndThrow); } /** - * Get a paginated subset of lists. By default, the first page is returned, with 20 results per page. + * Get a paginated subset of value lists. By default, the first page is returned, with 20 results per page. */ async findLists(props: FindListsProps) { this.log.info(`${new Date().toISOString()} Calling API FindLists`); @@ -233,7 +233,7 @@ All list items in the same list must be the same type. For example, each list it .catch(catchAxiosErrorFormatAndThrow); } /** - * Import list items from a TXT or CSV file. The maximum file size is 9 million bytes. + * Import value list items from a TXT or CSV file. The maximum file size is 9 million bytes. You can import items to a new or existing list. @@ -253,7 +253,7 @@ You can import items to a new or existing list. .catch(catchAxiosErrorFormatAndThrow); } /** - * Update specific fields of an existing list using the list ID. + * Update specific fields of an existing list using the list `id`. */ async patchList(props: PatchListProps) { this.log.info(`${new Date().toISOString()} Calling API PatchList`); @@ -269,7 +269,7 @@ You can import items to a new or existing list. .catch(catchAxiosErrorFormatAndThrow); } /** - * Update specific fields of an existing list item using the list item ID. + * Update specific fields of an existing value list item using the item `id`. */ async patchListItem(props: PatchListItemProps) { this.log.info(`${new Date().toISOString()} Calling API PatchListItem`); @@ -285,7 +285,7 @@ You can import items to a new or existing list. .catch(catchAxiosErrorFormatAndThrow); } /** - * Get the details of a list using the list ID. + * Get the details of a value list using the list ID. */ async readList(props: ReadListProps) { this.log.info(`${new Date().toISOString()} Calling API ReadList`); @@ -317,7 +317,7 @@ You can import items to a new or existing list. .catch(catchAxiosErrorFormatAndThrow); } /** - * Get the details of a list item. + * Get the details of a value list item. */ async readListItem(props: ReadListItemProps) { this.log.info(`${new Date().toISOString()} Calling API ReadListItem`); @@ -346,7 +346,7 @@ You can import items to a new or existing list. .catch(catchAxiosErrorFormatAndThrow); } /** - * Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted. + * Update a value list using the list `id`. The original list is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. @@ -365,7 +365,7 @@ You can import items to a new or existing list. .catch(catchAxiosErrorFormatAndThrow); } /** - * Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. + * Update a value list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. diff --git a/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts b/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts index d744eb15c9b50..c88bfc184e58e 100644 --- a/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Read list API endpoint + * title: Read value list API endpoint * version: 2023-10-31 */ @@ -23,9 +23,6 @@ import { List } from '../model/list_schemas.gen'; export type ReadListRequestQuery = z.infer; export const ReadListRequestQuery = z.object({ - /** - * List's `id` value - */ id: ListId, }); export type ReadListRequestQueryInput = z.input; diff --git a/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml index d932e16f528a5..e3ccaa750e736 100644 --- a/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Read list API endpoint + title: Read value list API endpoint version: '2023-10-31' paths: /api/lists: @@ -8,13 +8,12 @@ paths: x-labels: [serverless, ess] operationId: ReadList x-codegen-enabled: true - summary: Get list details - description: Get the details of a list using the list ID. + summary: Get value list details + description: Get the details of a value list using the list ID. parameters: - name: id in: query required: true - description: List's `id` value schema: $ref: '../model/list_common.schema.yaml#/components/schemas/ListId' responses: @@ -24,6 +23,22 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/List' + examples: + ip: + value: + id: ip_list + type: ip + name: My bad ips + description: This list describes bad internet ip + immutable: false + '@timestamp': 2025-01-08T04:47:34.273Z + version: 1 + _version: WzEsMV0= + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + updated_at: 2025-01-08T05:21:53.843Z + updated_by: elastic 400: description: Invalid input data response content: @@ -32,27 +47,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request query]: id: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists?id=ip_list] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 404: description: List not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.gen.ts b/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.gen.ts index 8a5068f72f234..64586d6846074 100644 --- a/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Read list DS existence status API endpoint + * title: Read value list DS existence status API endpoint * version: 2023-10-31 */ diff --git a/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml b/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml index b675264600157..909912f749d0e 100644 --- a/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Read list DS existence status API endpoint + title: Read value list DS existence status API endpoint version: '2023-10-31' paths: /api/lists/index: @@ -8,7 +8,7 @@ paths: x-labels: [serverless, ess] operationId: ReadListIndex x-codegen-enabled: true - summary: Get status of list data streams + summary: Get status of value list data streams description: Verify that `.lists` and `.items` data streams exist. responses: 200: @@ -37,6 +37,12 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: @@ -55,3 +61,8 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.gen.ts b/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.gen.ts index cd0c1d8fca26d..ce611d96e9bba 100644 --- a/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Read list item API endpoint + * title: Read value list item API endpoint * version: 2023-10-31 */ @@ -24,15 +24,15 @@ import { ListItem } from '../model/list_schemas.gen'; export type ReadListItemRequestQuery = z.infer; export const ReadListItemRequestQuery = z.object({ /** - * Required if `list_id` and `value` are not specified + * Value list item identifier. Required if `list_id` and `value` are not specified. */ id: ListId.optional(), /** - * Required if `id` is not specified + * Value list item list's `id` identfier. Required if `id` is not specified. */ list_id: ListId.optional(), /** - * Required if `id` is not specified + * The value used to evaluate exceptions. Required if `id` is not specified. */ value: z.string().optional(), }); diff --git a/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml index 4d686f5452e0c..052cf21531c6a 100644 --- a/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Read list item API endpoint + title: Read value list item API endpoint version: '2023-10-31' paths: /api/lists/items: @@ -8,27 +8,28 @@ paths: x-labels: [serverless, ess] operationId: ReadListItem x-codegen-enabled: true - summary: Get a list item - description: Get the details of a list item. + summary: Get a value list item + description: Get the details of a value list item. parameters: - name: id in: query required: false - description: Required if `list_id` and `value` are not specified + description: Value list item identifier. Required if `list_id` and `value` are not specified. schema: $ref: '../model/list_common.schema.yaml#/components/schemas/ListId' - name: list_id in: query required: false - description: Required if `id` is not specified + description: Value list item list's `id` identfier. Required if `id` is not specified. schema: $ref: '../model/list_common.schema.yaml#/components/schemas/ListId' - name: value in: query required: false - description: Required if `id` is not specified + description: The value used to evaluate exceptions. Required if `id` is not specified. schema: type: string + example: 127.0.0.2 responses: 200: description: Successful response @@ -40,6 +41,20 @@ paths: - type: array items: $ref: '../model/list_schemas.schema.yaml#/components/schemas/ListItem' + examples: + ip: + value: + id: qN1XRJQBs4HAK3VQs3Gc + type: ip + list_id: ip_list + value: 127.0.0.2 + '@timestamp': 2025-01-08T05:16:25.882Z + _version: WzExLDFd + tie_breaker_id: a9a34c02-a385-436e-86a0-02a3942f3537 + created_at: 2025-01-08T05:16:25.882Z + created_by: elastic + updated_at: 2025-01-08T05:16:25.882Z + updated_by: elastic 400: description: Invalid input data response content: @@ -48,27 +63,54 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + message: 'Either \"list_id\" or \"id\" needs to be defined in the request' + status_code: 400 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists/items?id=qN1XRJQBs4HAK3VQs3Gc] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 404: description: List item not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.gen.ts b/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.gen.ts index 356915ba03cff..23faf85cb94da 100644 --- a/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Read list privileges API endpoint + * title: Read value list privileges API endpoint * version: 2023-10-31 */ diff --git a/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml b/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml index ec8604e80694e..1c4b7d7e73c21 100644 --- a/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Read list privileges API endpoint + title: Read value list privileges API endpoint version: '2023-10-31' paths: /api/lists/privileges: @@ -8,7 +8,7 @@ paths: x-labels: [serverless, ess] operationId: ReadListPrivileges x-codegen-enabled: true - summary: Get list privileges + summary: Get value list privileges responses: 200: description: Successful response @@ -27,6 +27,74 @@ paths: - lists - listItems - is_authenticated + examples: + privileges: + value: + listItems: + username: elastic + has_all_requested: true + cluster: + all: true + monitor_ml: true + manage_transform: true + manage_index_templates: true + monitor_transform: true + manage_ml: true + monitor: true + manage_pipeline: true + manage_api_key: true + manage_security: true + manage_own_api_key: true + manage: true + index: + .items-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + application: {} + lists: + username: elastic + has_all_requested: true + cluster: + all: true + monitor_ml: true + manage_transform: true + manage_index_templates: true + monitor_transform: true + manage_ml: true + monitor: true + manage_pipeline: true + manage_api_key: true + manage_security: true + manage_own_api_key: true + manage: true + index: + .lists-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + application: {} + is_authenticated: true 400: description: Invalid input data response content: @@ -41,18 +109,35 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists/privileges] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: schemas: diff --git a/packages/kbn-securitysolution-lists-common/api/update_list/update_list.gen.ts b/packages/kbn-securitysolution-lists-common/api/update_list/update_list.gen.ts index f5eb085fe4aa5..ff89fbf22df6a 100644 --- a/packages/kbn-securitysolution-lists-common/api/update_list/update_list.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/update_list/update_list.gen.ts @@ -12,13 +12,20 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Update list API endpoint + * title: Update value list API endpoint * version: 2023-10-31 */ import { z } from '@kbn/zod'; -import { ListId, ListName, ListDescription, ListMetadata } from '../model/list_common.gen'; +import { + ListId, + ListName, + ListDescription, + ListMetadata, + ListVersion, + ListVersionId, +} from '../model/list_common.gen'; import { List } from '../model/list_schemas.gen'; export type UpdateListRequestBody = z.infer; @@ -27,8 +34,8 @@ export const UpdateListRequestBody = z.object({ name: ListName, description: ListDescription, meta: ListMetadata.optional(), - version: z.number().int().min(1).optional(), - _version: z.string().optional(), + version: ListVersion.optional(), + _version: ListVersionId.optional(), }); export type UpdateListRequestBodyInput = z.input; diff --git a/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml b/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml index c41b52427b63d..f723dd0ae5910 100644 --- a/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Update list API endpoint + title: Update value list API endpoint version: '2023-10-31' paths: /api/lists: @@ -8,13 +8,13 @@ paths: x-labels: [serverless, ess] operationId: UpdateList x-codegen-enabled: true - summary: Update a list + summary: Update a value list description: | - Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted. + Update a value list using the list `id`. The original list is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. requestBody: - description: List's properties + description: Value list's properties required: true content: application/json: @@ -30,14 +30,17 @@ paths: meta: $ref: '../model/list_common.schema.yaml#/components/schemas/ListMetadata' version: - type: integer - minimum: 1 + $ref: '../model/list_common.schema.yaml#/components/schemas/ListVersion' _version: - type: string + $ref: '../model/list_common.schema.yaml#/components/schemas/ListVersionId' required: - id - name - description + example: + id: ip_list + name: Bad ips - updated + description: Latest list of bad ips responses: 200: description: Successful response @@ -45,6 +48,22 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/List' + examples: + ip: + value: + id: ip_list + type: ip + name: Bad ips - updated + description: Latest list of bad ips + immutable: false + '@timestamp': 2025-01-08T04:47:34.273Z + version: 3 + _version: WzIsMV0= + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + updated_at: 2025-01-08T05:39:39.292Z + updated_by: elastic 400: description: Invalid input data response content: @@ -53,27 +72,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [PUT /api/lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: List not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.gen.ts b/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.gen.ts index 052c4c979e844..4348394b5c18e 100644 --- a/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.gen.ts +++ b/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.gen.ts @@ -12,13 +12,18 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Update list item API endpoint + * title: Update value list item API endpoint * version: 2023-10-31 */ import { z } from '@kbn/zod'; -import { ListItemId, ListItemValue, ListItemMetadata } from '../model/list_common.gen'; +import { + ListItemId, + ListItemValue, + ListItemMetadata, + ListVersionId, +} from '../model/list_common.gen'; import { ListItem } from '../model/list_schemas.gen'; export type UpdateListItemRequestBody = z.infer; @@ -26,7 +31,7 @@ export const UpdateListItemRequestBody = z.object({ id: ListItemId, value: ListItemValue, meta: ListItemMetadata.optional(), - _version: z.string().optional(), + _version: ListVersionId.optional(), }); export type UpdateListItemRequestBodyInput = z.input; diff --git a/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml b/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml index 6b05e01f35aab..d7b985f74648b 100644 --- a/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Update list item API endpoint + title: Update value list item API endpoint version: '2023-10-31' paths: /api/lists/items: @@ -8,13 +8,13 @@ paths: x-labels: [serverless, ess] operationId: UpdateListItem x-codegen-enabled: true - summary: Update a list item + summary: Update a value list item description: | - Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. + Update a value list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. requestBody: - description: List item's properties + description: Value list item's properties required: true content: application/json: @@ -28,10 +28,13 @@ paths: meta: $ref: '../model/list_common.schema.yaml#/components/schemas/ListItemMetadata' _version: - type: string + $ref: '../model/list_common.schema.yaml#/components/schemas/ListVersionId' required: - id - value + example: + id: ip_item + value: 255.255.255.255 responses: 200: description: Successful response @@ -39,6 +42,20 @@ paths: application/json: schema: $ref: '../model/list_schemas.schema.yaml#/components/schemas/ListItem' + examples: + ip: + value: + id: pd1WRJQBs4HAK3VQeHFI + type: ip + list_id: ip_list + value: 255.255.255.255 + '@timestamp': 2025-01-08T05:15:05.159Z + _version: WzIwLDFd + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + updated_at: 2025-01-08T05:44:14.009Z + updated_by: elastic 400: description: Invalid input data response content: @@ -47,27 +64,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/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: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [PATCH /api/lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: List item not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml index bdf6df3e520b3..afa6b132a0222 100644 --- a/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml @@ -14,39 +14,68 @@ paths: /api/lists: delete: description: | - Delete a list using the list ID. + Delete a value list using the list ID. > info > When you delete a list, all of its list items are also deleted. operationId: DeleteList parameters: - - description: List's `id` value - in: query + - in: query name: id required: true schema: $ref: '#/components/schemas/ListId' - - in: query + - description: >- + Determines whether exception items referencing this value list + should be deleted. + in: query name: deleteReferences required: false schema: default: false + example: false type: boolean - - in: query + - description: >- + Determines whether to delete value list without performing any + additional checks of where this list may be utilized. + in: query name: ignoreReferences required: false schema: default: false + example: false type: boolean responses: '200': content: application/json: + examples: + ipList: + value: + _version: WzIsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: List of bad internet ips. + id: 21b01cfb-058d-44b9-838c-282be16c91cd + immutable: false + name: Bad ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T05:39:39.292Z + updated_by: elastic + version: 3 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -55,36 +84,65 @@ 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: + error: Forbidden + message: >- + API [DELETE /api/lists?id=ip_list] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list id: \"ip_list\" was not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List not found 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: Delete a list + summary: Delete a value list tags: - Security Lists API get: - description: Get the details of a list using the list ID. + description: Get the details of a value list using the list ID. operationId: ReadList parameters: - - description: List's `id` value - in: query + - in: query name: id required: true schema: @@ -93,12 +151,34 @@ paths: '200': content: application/json: + examples: + ip: + value: + _version: WzEsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: My bad ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T05:21:53.843Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -107,41 +187,69 @@ 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: + error: Forbidden + message: >- + API [GET /api/lists?id=ip_list] is unauthorized for user, + this action is granted by the Kibana privileges + [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '404': content: application/json: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List not found 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: Get list details + summary: Get value list details tags: - Security Lists API patch: - description: Update specific fields of an existing list using the list ID. + description: Update specific fields of an existing list using the list `id`. operationId: PatchList requestBody: content: application/json: schema: + example: + id: ip_list + name: Bad ips list - UPDATED type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' description: $ref: '#/components/schemas/ListDescription' id: @@ -151,22 +259,43 @@ paths: name: $ref: '#/components/schemas/ListName' version: - minimum: 1 - type: integer + $ref: '#/components/schemas/ListVersion' required: - id - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzEsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ips + id: ip_list + immutable: false + name: Bad ips list - UPDATED + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T05:21:53.843Z + updated_by: elastic + version: 2 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: name: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -175,43 +304,100 @@ 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: + error: Forbidden + message: >- + API [PATCH /api/lists] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List not found 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: Patch a list + summary: Patch a value list tags: - Security Lists API post: - description: Create a new list. + description: Create a new value list. operationId: CreateList requestBody: content: application/json: + examples: + ip: + value: + description: This list describes bad internet ips + id: ip_list + name: Simple list with ips + type: ip + ip_range: + value: + description: This list has ip ranges + id: ip_range_list + name: Simple list with ip ranges + type: ip_range + keyword: + value: + description: This list describes bad host names + id: keyword_list + name: Simple list with a keyword + type: keyword + keyword_custom_format: + value: + description: This parses the first found ipv4 only + deserializer: '{{value}}' + id: keyword_custom_format_list + name: Simple list with a keyword using a custom format + serializer: >- + (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + type: keyword schema: type: object properties: description: $ref: '#/components/schemas/ListDescription' deserializer: - type: string + $ref: '#/components/schemas/ListDeserializer' id: $ref: '#/components/schemas/ListId' meta: @@ -219,7 +405,7 @@ paths: name: $ref: '#/components/schemas/ListName' serializer: - type: string + $ref: '#/components/schemas/ListSerializer' type: $ref: '#/components/schemas/ListType' version: @@ -230,18 +416,89 @@ paths: - name - description - type - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ips + id: ip_list + immutable: false + name: Simple list with ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T04:47:34.273Z + updated_by: elastic + version: 1 + ip_range: + value: + _version: WzAsMV0= + '@timestamp': 2025-01-09T18:23:52.241Z + created_at: 2025-01-09T18:23:52.241Z + created_by: elastic + description: This list has ip ranges + id: ip_range_list + immutable: false + name: Simple list with ip ranges + tie_breaker_id: 74aebdaf-601f-4940-b351-155728ff7003 + type: ip_range + updated_at: 2025-01-09T18:23:52.241Z + updated_by: elastic + version: 1 + keyword: + value: + _version: WzEsMV0= + '@timestamp': 2025-01-09T18:24:55.786Z + created_at: 2025-01-09T18:24:55.786Z + created_by: elastic + description: This list describes bad host names + id: keyword_list + immutable: false + name: Simple list with a keyword + tie_breaker_id: f7e7dbaa-daf7-4c9a-a3dc-56643923ef68 + type: keyword + updated_at: 2025-01-09T18:24:55.786Z + updated_by: elastic + version: 1 + keyword_custom_format: + value: + _version: WzIsMV0= + '@timestamp': 2025-01-09T18:25:39.604Z + created_at: 2025-01-09T18:25:39.604Z + created_by: elastic + description: This parses the first found ipv4 only + deserializer: '{{value}}' + id: keyword_custom_format_list + immutable: false + name: Simple list with a keyword using a custom format + serializer: >- + (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + tie_breaker_id: 8247ae63-b780-47b8-9a89-948b643e9ec2 + type: keyword + updated_at: 2025-01-09T18:25:39.604Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + notFound: + value: + message: >- + To create a list, the data stream must exist first. Data + stream \".lists-default\" does not exist + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -250,34 +507,63 @@ 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: + error: Forbidden + message: >- + API [POST /api/lists] 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 '409': content: application/json: + examples: + alreadyExists: + value: + message: 'list id: "keyword_custom_format_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List already exists 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: Create a list + summary: Create a value list tags: - Security Lists API put: description: > - Update a list using the list ID. The original list is replaced, and all - unspecified fields are deleted. + Update a value list using the list `id`. The original list is replaced, + and all unspecified fields are deleted. > info @@ -287,10 +573,14 @@ paths: content: application/json: schema: + example: + description: Latest list of bad ips + id: ip_list + name: Bad ips - updated type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' description: $ref: '#/components/schemas/ListDescription' id: @@ -300,24 +590,45 @@ paths: name: $ref: '#/components/schemas/ListName' version: - minimum: 1 - type: integer + $ref: '#/components/schemas/ListVersion' required: - id - name - description - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzIsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: Latest list of bad ips + id: ip_list + immutable: false + name: Bad ips - updated + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T05:39:39.292Z + updated_by: elastic + version: 3 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -326,55 +637,89 @@ 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: + error: Forbidden + message: >- + API [PUT /api/lists] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List not found 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: Update a list + summary: Update a value list tags: - Security Lists API /api/lists/_find: get: description: >- - Get a paginated subset of lists. By default, the first page is returned, - with 20 results per page. + Get a paginated subset of value lists. By default, the first page is + returned, with 20 results per page. operationId: FindLists parameters: - - description: The page number to return + - description: The page number to return. in: query name: page required: false schema: + example: 1 type: integer - - description: The number of lists to return per page + - description: The number of value lists to return per page. in: query name: per_page required: false schema: + example: 20 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. in: query name: sort_field required: false schema: - $ref: '#/components/schemas/NonEmptyString' + example: name + format: nonempty + minLength: 1 + type: string - description: 'Determines the sort order, which can be `desc` or `asc`' in: query name: sort_order @@ -383,16 +728,13 @@ paths: enum: - desc - asc + example: asc type: string - - description: > - Returns the list that come after the last list returned in the - previous call - - (use the cursor value returned in the previous call). This parameter - uses - - the `tie_breaker_id` field to ensure all lists are sorted and - returned correctly. + - description: >- + Returns the lists that come after the last lists returned in the + previous call (use the `cursor` value returned in the previous + call). This parameter uses the `tie_breaker_id` field to ensure all + lists are sorted and returned correctly. in: query name: cursor required: false @@ -412,6 +754,31 @@ paths: '200': content: application/json: + examples: + ipList: + value: + cursor: >- + WzIwLFsiZjU1MDgxODgtYjFlOS00ZTZlLTk2NjItZDAzOWE3ZDg5ODk5Il1d + data: + - _version: WzAsMV0= + '@timestamp': | + 2025-01-08T04:47:34.273Z + created_at: | + 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: Simple list with an ip + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: | + 2025-01-08T04:47:34.273Z + updated_by: elastic + version: 1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -440,6 +807,12 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: page: Expected number, received nan' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -448,22 +821,47 @@ 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: + error: Forbidden + message: >- + API [GET /api/lists/_find?page=1&per_page=20] is + unauthorized for user, this action is granted by the + Kibana privileges [lists-read] + 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: Get lists + summary: Get value lists tags: - Security Lists API /api/lists/index: @@ -493,6 +891,17 @@ 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 @@ -511,10 +920,15 @@ paths: '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: Delete list data streams + summary: Delete value list data streams tags: - Security Lists API get: @@ -546,6 +960,17 @@ 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 @@ -564,10 +989,15 @@ paths: '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: Get status of list data streams + summary: Get status of value list data streams tags: - Security Lists API post: @@ -596,6 +1026,17 @@ 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 @@ -608,12 +1049,24 @@ paths: '409': content: application/json: + examples: + alreadyExists: + value: + message: >- + data stream: \".lists-default\" and \".items-default\" + already exists + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List data stream exists 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 @@ -622,30 +1075,37 @@ paths: - Security Lists API /api/lists/items: delete: - description: 'Delete a list item using its `id`, or its `list_id` and `value` fields.' + description: >- + Delete a value list item using its `id`, or its `list_id` and `value` + fields. operationId: DeleteListItem parameters: - - description: Required if `list_id` and `value` are not specified + - description: >- + Value list item's identifier. Required if `list_id` and `value` are + not specified. in: query name: id required: false schema: - $ref: '#/components/schemas/ListId' - - description: Required if `id` is not specified + $ref: '#/components/schemas/ListItemId' + - description: Value list's identifier. Required if `id` is not specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/ListId' - - description: Required if `id` is not specified + - description: >- + The value used to evaluate exceptions. Required if `id` is not + specified. in: query name: value required: false schema: + example: 255.255.255.255 type: string - description: >- Determines when changes made by the request are made visible to - search + search. in: query name: refresh required: false @@ -655,11 +1115,26 @@ paths: - 'true' - 'false' - wait_for + example: false type: string responses: '200': content: application/json: + examples: + ip: + value: + _version: WzIwLDFd + '@timestamp': 2025-01-08T05:15:05.159Z + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: 2025-01-08T05:44:14.009Z + updated_by: elastic + value: 255.255.255.255 schema: oneOf: - $ref: '#/components/schemas/ListItem' @@ -670,6 +1145,13 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + message: >- + Either \"list_id\" or \"id\" needs to be defined in the + request + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -678,56 +1160,107 @@ 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: + error: Forbidden + message: >- + API [DELETE /api/lists/items?id=pd1WRJQBs4HAK3VQeHFI] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list item with id: \"pd1WRJQBs4HAK3VQeHFI\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item not found 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: Delete a list item + summary: Delete a value list item tags: - Security Lists API get: - description: Get the details of a list item. + description: Get the details of a value list item. operationId: ReadListItem parameters: - - description: Required if `list_id` and `value` are not specified + - description: >- + Value list item identifier. Required if `list_id` and `value` are + not specified. in: query name: id required: false schema: $ref: '#/components/schemas/ListId' - - description: Required if `id` is not specified + - description: >- + Value list item list's `id` identfier. Required if `id` is not + specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/ListId' - - description: Required if `id` is not specified + - description: >- + The value used to evaluate exceptions. Required if `id` is not + specified. in: query name: value required: false schema: + example: 127.0.0.2 type: string responses: '200': content: application/json: + examples: + ip: + value: + _version: WzExLDFd + '@timestamp': 2025-01-08T05:16:25.882Z + created_at: 2025-01-08T05:16:25.882Z + created_by: elastic + id: qN1XRJQBs4HAK3VQs3Gc + list_id: ip_list + tie_breaker_id: a9a34c02-a385-436e-86a0-02a3942f3537 + type: ip + updated_at: 2025-01-08T05:16:25.882Z + updated_by: elastic + value: 127.0.0.2 schema: oneOf: - $ref: '#/components/schemas/ListItem' @@ -738,6 +1271,13 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + message: >- + Either \"list_id\" or \"id\" needs to be defined in the + request + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -746,41 +1286,76 @@ 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: + error: Forbidden + message: >- + API [GET /api/lists/items?id=qN1XRJQBs4HAK3VQs3Gc] is + unauthorized for user, this action is granted by the + Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '404': content: application/json: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item not found 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: Get a list item + summary: Get a value list item tags: - Security Lists API patch: - description: Update specific fields of an existing list item using the list item ID. + description: >- + Update specific fields of an existing value list item using the item + `id`. operationId: PatchListItem requestBody: content: application/json: schema: + example: + id: pd1WRJQBs4HAK3VQeHFI + value: 255.255.255.255 type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' id: $ref: '#/components/schemas/ListItemId' meta: @@ -788,7 +1363,7 @@ paths: refresh: description: >- Determines when changes made by the request are made visible - to search + to search. enum: - 'true' - 'false' @@ -798,18 +1373,42 @@ paths: $ref: '#/components/schemas/ListItemValue' required: - id - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json: + examples: + ipItem: + value: + _version: WzE5LDFd + '@timestamp': 2025-01-08T05:15:05.159Z + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: 2025-01-08T05:23:37.602Z + updated_by: elastic + value: 255.255.255.255 schema: $ref: '#/components/schemas/ListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + message: >- + {"took":15,"timed_out":false,"total":1,"updated":0,"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,"failures":[{"index":".ds-.items-default-2025.01.09-000001","id":"ip_item","cause":{"type":"document_parsing_exception","reason":"[1:107] + failed to parse field [ip] of type [ip] in document with + id ip_item. Preview of fields value: + 2","caused_by":{"type":"illegal_argument_exception","reason":"2 + is not an IP string literal."}},"status":400}]} + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -818,37 +1417,68 @@ 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: + error: Forbidden + message: >- + API [PATCH /api/lists/items] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item not found 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: Patch a list item + summary: Patch a value list item tags: - Security Lists API post: description: > - Create a list item and associate it with the specified list. + Create a value list item and associate it with the specified value list. - All list items in the same list must be the same type. For example, each - list item in an `ip` list must define a specific IP address. + All value list items in the same list must be the same type. For + example, each list item in an `ip` list must define a specific IP + address. > info @@ -857,6 +1487,19 @@ paths: requestBody: content: application/json: + examples: + ip: + value: + list_id: ip_list + value: 127.0.0.1 + ip_range: + value: + list_id: ip_range_list + value: 192.168.0.0/16 + keyword: + value: + list_id: keyword_list + value: zeek schema: type: object properties: @@ -869,29 +1512,78 @@ paths: refresh: description: >- Determines when changes made by the request are made visible - to search + to search. enum: - 'true' - 'false' - wait_for + example: wait_for type: string value: $ref: '#/components/schemas/ListItemValue' required: - list_id - value - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': 2025-01-08T04:59:06.154Z + created_at: 2025-01-08T04:59:06.154Z + created_by: elastic + id: 21b01cfb-058d-44b9-838c-282be16c91cc + list_id: ip_list + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + type: ip + updated_at: 2025-01-08T04:59:06.154Z + updated_by: elastic + value: 127.0.0.1 + ip_range: + value: + _version: WzEsMV0= + '@timestamp': 2025-01-09T18:33:08.202Z + created_at: 2025-01-09T18:33:08.202Z + created_by: elastic + id: ip_range_item + list_id: ip_range_list + tie_breaker_id: ea1b4189-efda-4637-b8f9-74655a5ebb61 + type: ip_range + updated_at: 2025-01-09T18:33:08.202Z + updated_by: elastic + value: 192.168.0.0/16 + keyword: + value: + _version: WzIsMV0= + '@timestamp': 2025-01-09T18:34:29.422Z + created_at: 2025-01-09T18:34:29.422Z + created_by: elastic + id: 7f24737d-1da8-4626-a568-33070591bb4e + list_id: keyword_list + tie_breaker_id: 2108ced2-5e5d-401e-a88e-4dd69fc5fa27 + type: keyword + updated_at: 2025-01-09T18:34:29.422Z + updated_by: elastic + value: zeek schema: $ref: '#/components/schemas/ListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + uri [/api/lists/items] with method [post] exists but is + not available with the current configuration + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -900,34 +1592,74 @@ 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: + error: Forbidden + message: >- + API [POST /api/lists/items] 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 + '404': + content: + application/json: + examples: + listNotFound: + value: + message: 'list id: \"ip_list\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '409': content: application/json: + examples: + alreadyExists: + value: + message: 'list item id: \"ip_item\" already exists' + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item already exists 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: Create a list item + summary: Create a value list item tags: - Security Lists API put: description: > - Update a list item using the list item ID. The original list item is - replaced, and all unspecified fields are deleted. + Update a value list item using the list item ID. The original list item + is replaced, and all unspecified fields are deleted. > info @@ -936,11 +1668,14 @@ paths: requestBody: content: application/json: + example: + id: ip_item + value: 255.255.255.255 schema: type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' id: $ref: '#/components/schemas/ListItemId' meta: @@ -950,18 +1685,38 @@ paths: required: - id - value - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzIwLDFd + '@timestamp': 2025-01-08T05:15:05.159Z + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: 2025-01-08T05:44:14.009Z + updated_by: elastic + value: 255.255.255.255 schema: $ref: '#/components/schemas/ListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -970,36 +1725,66 @@ 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: + error: Forbidden + message: >- + API [PATCH /api/lists/items] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item not found 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: Update a list item + summary: Update a value list item tags: - Security Lists API /api/lists/items/_export: post: - description: Export list item values from the specified list. + description: Export list item values from the specified value list. operationId: ExportListItems parameters: - - description: List's id to export + - description: Value list's `id` to export. in: query name: list_id required: true @@ -1011,12 +1796,27 @@ paths: application/ndjson: schema: description: A `.txt` file containing list items from the specified list + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 format: binary type: string description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: 'Bad Request","message":"[request query]: list_id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1025,12 +1825,32 @@ 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: + error: Forbidden + message: >- + API [POST /api/lists/items/_export?list_id=ips.txt] is + unauthorized for user, this action is granted by the + Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response @@ -1043,41 +1863,50 @@ paths: '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: Export list items + summary: Export value list items tags: - Security Lists API /api/lists/items/_find: get: - description: Get all list items in the specified list. + description: Get all value list items in the specified list. operationId: FindListItems parameters: - - description: List's id - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/ListId' - - description: The page number to return + - description: The page number to return. in: query name: page required: false schema: + example: 1 type: integer - - description: The number of list items to return per page + - description: The number of list items to return per page. in: query name: per_page required: false schema: + example: 20 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. in: query name: sort_field required: false schema: - $ref: '#/components/schemas/NonEmptyString' + example: value + format: nonempty + minLength: 1 + type: string - description: 'Determines the sort order, which can be `desc` or `asc`' in: query name: sort_order @@ -1086,17 +1915,9 @@ paths: enum: - desc - asc + example: asc type: string - - description: > - Returns the list that come after the last list returned in the - previous call - - (use the cursor value returned in the previous call). This parameter - uses - - the `tie_breaker_id` field to ensure all lists are sorted and - returned correctly. - in: query + - in: query name: cursor required: false schema: @@ -1115,6 +1936,26 @@ paths: '200': content: application/json: + examples: + ip: + value: + cursor: >- + WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + data: + - _version: WzAsMV0= + '@timestamp': 2025-01-08T04:59:06.154Z + created_at: 2025-01-08T04:59:06.154Z + created_by: elastic + id: 21b01cfb-058d-44b9-838c-282be16c91cc + list_id: ip_list + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + type: ip + updated_at: 2025-01-08T04:59:06.154Z + updated_by: elastic + value: 127.0.0.1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -1143,6 +1984,12 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: 'Bad Request,' + message: '[request query]: list_id: Required' + statusCode: '400,' schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1151,29 +1998,55 @@ 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: + error: Forbidden + message: >- + API [GET + /api/lists/items/_find?list_id=ip_list&page=1&per_page=20] + is unauthorized for user, this action is granted by the + Kibana privileges [lists-read] + 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: Get list items + summary: Get value list items tags: - Security Lists API /api/lists/items/_import: post: description: > - Import list items from a TXT or CSV file. The maximum file size is 9 - million bytes. + Import value list items from a TXT or CSV file. The maximum file size is + 9 million bytes. You can import items to a new or existing list. @@ -1188,30 +2061,58 @@ paths: required: false schema: $ref: '#/components/schemas/ListId' - - description: > + - description: | Type of the importing list. - - Required when importing a new list that is `list_id` is not - specified. + Required when importing a new list whose list `id` is not specified. + examples: + ip: + value: ip in: query name: type required: false schema: $ref: '#/components/schemas/ListType' - - in: query + - description: > + Determines how uploaded list item values are parsed. By default, + list items are parsed using these named regex groups: + + + - `(?.+)` - Single value item types, such as ip, long, date, + keyword, and text. + + - `(?.+)-(?.+)|(?.+)` - Range value item types, + such as `date_range`, `ip_range`, `double_range`, `float_range`, + `integer_range`, and `long_range`. + in: query name: serializer required: false schema: + example: >- + (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) type: string - - in: query + - description: > + Determines how retrieved list item values are presented. By default + list items are presented using these Handelbar expressions: + + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, + `date`, `keyword`, and `text`. + + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as + `ip_range`, `double_range`, `float_range`, `integer_range`, and + `long_range`. + + - `{{{gte}}},{{{lte}}}` - Date range values. + in: query name: deserializer required: false schema: + example: '{{value}}' type: string - description: >- Determines when changes made by the request are made visible to - search + search. in: query name: refresh required: false @@ -1220,6 +2121,7 @@ paths: - 'true' - 'false' - wait_for + example: true type: string requestBody: content: @@ -1230,7 +2132,17 @@ paths: file: description: >- A `.txt` or `.csv` file containing newline separated list - items + items. + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 format: binary type: string required: true @@ -1238,12 +2150,33 @@ paths: '200': content: application/json: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: Simple list with an ip + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T04:47:34.273Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + message: Either type or list_id need to be defined in the query + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1252,12 +2185,32 @@ 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: + error: Forbidden + message: >- + API [POST /api/lists/items/_import?list_id=ip_list] 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 @@ -1270,10 +2223,15 @@ paths: '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: Import list items + summary: Import value list items tags: - Security Lists API /api/lists/privileges: @@ -1283,6 +2241,74 @@ paths: '200': content: application/json: + examples: + privileges: + value: + is_authenticated: true + listItems: + application: {} + cluster: + all: true + manage: true + manage_api_key: true + manage_index_templates: true + manage_ml: true + manage_own_api_key: true + manage_pipeline: true + manage_security: true + manage_transform: true + monitor: true + monitor_ml: true + monitor_transform: true + has_all_requested: true + index: + .items-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + username: elastic + lists: + application: {} + cluster: + all: true + manage: true + manage_api_key: true + manage_index_templates: true + manage_ml: true + manage_own_api_key: true + manage_pipeline: true + manage_security: true + manage_transform: true + monitor: true + monitor_ml: true + monitor_transform: true + has_all_requested: true + index: + .lists-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + username: elastic schema: type: object properties: @@ -1308,51 +2334,94 @@ 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: + error: Forbidden + message: >- + API [GET /api/lists/privileges] is unauthorized for user, + this action is granted by the Kibana privileges + [lists-read] + 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: Get list privileges + summary: Get value list privileges tags: - Security Lists API components: schemas: FindListItemsCursor: - $ref: '#/components/schemas/NonEmptyString' + description: >- + Returns the items that come after the last item returned in the previous + call (use the `cursor` value returned in the previous call). This + parameter uses the `tie_breaker_id` field to ensure all items are sorted + and returned correctly. + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + format: nonempty + minLength: 1 + type: string FindListItemsFilter: + example: 'value:127.0.0.1' type: string FindListsCursor: - $ref: '#/components/schemas/NonEmptyString' + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + format: nonempty + minLength: 1 + type: string FindListsFilter: + example: 'value:127.0.0.1' type: string List: type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' '@timestamp': + example: 2025-01-08T04:47:34.273Z format: date-time type: string created_at: + description: Autogenerated date of object creation. + example: 2025-01-08T04:47:34.273Z format: date-time type: string created_by: + description: Autogenerated value - user that created object. + example: elastic type: string description: $ref: '#/components/schemas/ListDescription' deserializer: - type: string + $ref: '#/components/schemas/ListDeserializer' id: $ref: '#/components/schemas/ListId' immutable: @@ -1362,19 +2431,26 @@ components: name: $ref: '#/components/schemas/ListName' serializer: - type: string + $ref: '#/components/schemas/ListSerializer' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 type: string type: $ref: '#/components/schemas/ListType' updated_at: + description: Autogenerated date of last object update. + example: 2025-01-08T04:47:34.273Z format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. + example: elastic type: string version: - minimum: 1 - type: integer + $ref: '#/components/schemas/ListVersion' required: - id - type @@ -1388,24 +2464,51 @@ components: - updated_at - updated_by ListDescription: - $ref: '#/components/schemas/NonEmptyString' + description: Describes the value list. + format: nonempty + minLength: 1 + type: string + ListDeserializer: + description: > + Determines how retrieved list item values are presented. By default list + items are presented using these Handelbar expressions: + + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, + `keyword`, and `text`. + + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, + `double_range`, `float_range`, `integer_range`, and `long_range`. + + - `{{{gte}}},{{{lte}}}` - Date range values. + example: '{{value}}' + type: string ListId: - $ref: '#/components/schemas/NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string ListItem: type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' '@timestamp': + example: 2025-01-08T04:47:34.273Z format: date-time type: string created_at: + description: Autogenerated date of object creation. + example: 2025-01-08T04:47:34.273Z format: date-time type: string created_by: + description: Autogenerated value - user that created object. + example: elastic type: string deserializer: - type: string + $ref: '#/components/schemas/ListDeserializer' id: $ref: '#/components/schemas/ListItemId' list_id: @@ -1413,15 +2516,23 @@ components: meta: $ref: '#/components/schemas/ListItemMetadata' serializer: - type: string + $ref: '#/components/schemas/ListSerializer' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 type: string type: $ref: '#/components/schemas/ListType' updated_at: + description: Autogenerated date of last object update. + example: 2025-01-08T04:47:34.273Z format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. + example: elastic type: string value: $ref: '#/components/schemas/ListItemValue' @@ -1436,9 +2547,14 @@ components: - updated_at - updated_by ListItemId: - $ref: '#/components/schemas/NonEmptyString' + description: Value list item's identifier. + example: 54b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string ListItemMetadata: additionalProperties: true + description: Placeholder for metadata about the value list item. type: object ListItemPrivileges: type: object @@ -1468,12 +2584,20 @@ components: - index - application ListItemValue: - $ref: '#/components/schemas/NonEmptyString' + description: The value used to evaluate exceptions. + format: nonempty + minLength: 1 + type: string ListMetadata: additionalProperties: true + description: Placeholder for metadata about the value list. type: object ListName: - $ref: '#/components/schemas/NonEmptyString' + description: Value list's name. + example: List of bad IPs + format: nonempty + minLength: 1 + type: string ListPrivileges: type: object properties: @@ -1501,7 +2625,33 @@ components: - cluster - index - application + ListSerializer: + description: > + Determines how uploaded list item values are parsed. By default, list + items are parsed using these named regex groups: + + + - `(?.+)` - Single value item types, such as ip, long, date, + keyword, and text. + + - `(?.+)-(?.+)|(?.+)` - Range value item types, such as + `date_range`, `ip_range`, `double_range`, `float_range`, + `integer_range`, and `long_range`. + example: >- + (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + type: string ListType: + description: > + Specifies the Elasticsearch data type of excludes the list container + holds. Some common examples: + + + - `keyword`: Many ECS fields are Elasticsearch keywords + + - `ip`: IP addresses + + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR + notation) enum: - binary - boolean @@ -1527,10 +2677,16 @@ components: - short - text type: string - NonEmptyString: - description: A string that does not contain only whitespace characters - format: nonempty - minLength: 1 + ListVersion: + description: The document version number. + example: 1 + minimum: 1 + type: integer + ListVersionId: + description: > + The version id, normally returned by the API when the document is + retrieved. Use it ensure updates are done against the latest version. + example: WzIsMV0= type: string PlatformErrorResponse: type: object diff --git a/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml index 5a031582bace2..e9d22905f14b9 100644 --- a/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml @@ -14,39 +14,68 @@ paths: /api/lists: delete: description: | - Delete a list using the list ID. + Delete a value list using the list ID. > info > When you delete a list, all of its list items are also deleted. operationId: DeleteList parameters: - - description: List's `id` value - in: query + - in: query name: id required: true schema: $ref: '#/components/schemas/ListId' - - in: query + - description: >- + Determines whether exception items referencing this value list + should be deleted. + in: query name: deleteReferences required: false schema: default: false + example: false type: boolean - - in: query + - description: >- + Determines whether to delete value list without performing any + additional checks of where this list may be utilized. + in: query name: ignoreReferences required: false schema: default: false + example: false type: boolean responses: '200': content: application/json: + examples: + ipList: + value: + _version: WzIsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: List of bad internet ips. + id: 21b01cfb-058d-44b9-838c-282be16c91cd + immutable: false + name: Bad ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T05:39:39.292Z + updated_by: elastic + version: 3 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -55,36 +84,65 @@ 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: + error: Forbidden + message: >- + API [DELETE /api/lists?id=ip_list] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list id: \"ip_list\" was not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List not found 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: Delete a list + summary: Delete a value list tags: - Security Lists API get: - description: Get the details of a list using the list ID. + description: Get the details of a value list using the list ID. operationId: ReadList parameters: - - description: List's `id` value - in: query + - in: query name: id required: true schema: @@ -93,12 +151,34 @@ paths: '200': content: application/json: + examples: + ip: + value: + _version: WzEsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: My bad ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T05:21:53.843Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -107,41 +187,69 @@ 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: + error: Forbidden + message: >- + API [GET /api/lists?id=ip_list] is unauthorized for user, + this action is granted by the Kibana privileges + [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '404': content: application/json: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List not found 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: Get list details + summary: Get value list details tags: - Security Lists API patch: - description: Update specific fields of an existing list using the list ID. + description: Update specific fields of an existing list using the list `id`. operationId: PatchList requestBody: content: application/json: schema: + example: + id: ip_list + name: Bad ips list - UPDATED type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' description: $ref: '#/components/schemas/ListDescription' id: @@ -151,22 +259,43 @@ paths: name: $ref: '#/components/schemas/ListName' version: - minimum: 1 - type: integer + $ref: '#/components/schemas/ListVersion' required: - id - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzEsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ips + id: ip_list + immutable: false + name: Bad ips list - UPDATED + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T05:21:53.843Z + updated_by: elastic + version: 2 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: name: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -175,43 +304,100 @@ 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: + error: Forbidden + message: >- + API [PATCH /api/lists] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List not found 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: Patch a list + summary: Patch a value list tags: - Security Lists API post: - description: Create a new list. + description: Create a new value list. operationId: CreateList requestBody: content: application/json: + examples: + ip: + value: + description: This list describes bad internet ips + id: ip_list + name: Simple list with ips + type: ip + ip_range: + value: + description: This list has ip ranges + id: ip_range_list + name: Simple list with ip ranges + type: ip_range + keyword: + value: + description: This list describes bad host names + id: keyword_list + name: Simple list with a keyword + type: keyword + keyword_custom_format: + value: + description: This parses the first found ipv4 only + deserializer: '{{value}}' + id: keyword_custom_format_list + name: Simple list with a keyword using a custom format + serializer: >- + (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + type: keyword schema: type: object properties: description: $ref: '#/components/schemas/ListDescription' deserializer: - type: string + $ref: '#/components/schemas/ListDeserializer' id: $ref: '#/components/schemas/ListId' meta: @@ -219,7 +405,7 @@ paths: name: $ref: '#/components/schemas/ListName' serializer: - type: string + $ref: '#/components/schemas/ListSerializer' type: $ref: '#/components/schemas/ListType' version: @@ -230,18 +416,89 @@ paths: - name - description - type - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ips + id: ip_list + immutable: false + name: Simple list with ips + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T04:47:34.273Z + updated_by: elastic + version: 1 + ip_range: + value: + _version: WzAsMV0= + '@timestamp': 2025-01-09T18:23:52.241Z + created_at: 2025-01-09T18:23:52.241Z + created_by: elastic + description: This list has ip ranges + id: ip_range_list + immutable: false + name: Simple list with ip ranges + tie_breaker_id: 74aebdaf-601f-4940-b351-155728ff7003 + type: ip_range + updated_at: 2025-01-09T18:23:52.241Z + updated_by: elastic + version: 1 + keyword: + value: + _version: WzEsMV0= + '@timestamp': 2025-01-09T18:24:55.786Z + created_at: 2025-01-09T18:24:55.786Z + created_by: elastic + description: This list describes bad host names + id: keyword_list + immutable: false + name: Simple list with a keyword + tie_breaker_id: f7e7dbaa-daf7-4c9a-a3dc-56643923ef68 + type: keyword + updated_at: 2025-01-09T18:24:55.786Z + updated_by: elastic + version: 1 + keyword_custom_format: + value: + _version: WzIsMV0= + '@timestamp': 2025-01-09T18:25:39.604Z + created_at: 2025-01-09T18:25:39.604Z + created_by: elastic + description: This parses the first found ipv4 only + deserializer: '{{value}}' + id: keyword_custom_format_list + immutable: false + name: Simple list with a keyword using a custom format + serializer: >- + (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + tie_breaker_id: 8247ae63-b780-47b8-9a89-948b643e9ec2 + type: keyword + updated_at: 2025-01-09T18:25:39.604Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + notFound: + value: + message: >- + To create a list, the data stream must exist first. Data + stream \".lists-default\" does not exist + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -250,34 +507,63 @@ 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: + error: Forbidden + message: >- + API [POST /api/lists] 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 '409': content: application/json: + examples: + alreadyExists: + value: + message: 'list id: "keyword_custom_format_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List already exists 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: Create a list + summary: Create a value list tags: - Security Lists API put: description: > - Update a list using the list ID. The original list is replaced, and all - unspecified fields are deleted. + Update a value list using the list `id`. The original list is replaced, + and all unspecified fields are deleted. > info @@ -287,10 +573,14 @@ paths: content: application/json: schema: + example: + description: Latest list of bad ips + id: ip_list + name: Bad ips - updated type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' description: $ref: '#/components/schemas/ListDescription' id: @@ -300,24 +590,45 @@ paths: name: $ref: '#/components/schemas/ListName' version: - minimum: 1 - type: integer + $ref: '#/components/schemas/ListVersion' required: - id - name - description - description: List's properties + description: Value list's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzIsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: Latest list of bad ips + id: ip_list + immutable: false + name: Bad ips - updated + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T05:39:39.292Z + updated_by: elastic + version: 3 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -326,55 +637,89 @@ 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: + error: Forbidden + message: >- + API [PUT /api/lists] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List not found 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: Update a list + summary: Update a value list tags: - Security Lists API /api/lists/_find: get: description: >- - Get a paginated subset of lists. By default, the first page is returned, - with 20 results per page. + Get a paginated subset of value lists. By default, the first page is + returned, with 20 results per page. operationId: FindLists parameters: - - description: The page number to return + - description: The page number to return. in: query name: page required: false schema: + example: 1 type: integer - - description: The number of lists to return per page + - description: The number of value lists to return per page. in: query name: per_page required: false schema: + example: 20 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. in: query name: sort_field required: false schema: - $ref: '#/components/schemas/NonEmptyString' + example: name + format: nonempty + minLength: 1 + type: string - description: 'Determines the sort order, which can be `desc` or `asc`' in: query name: sort_order @@ -383,16 +728,13 @@ paths: enum: - desc - asc + example: asc type: string - - description: > - Returns the list that come after the last list returned in the - previous call - - (use the cursor value returned in the previous call). This parameter - uses - - the `tie_breaker_id` field to ensure all lists are sorted and - returned correctly. + - description: >- + Returns the lists that come after the last lists returned in the + previous call (use the `cursor` value returned in the previous + call). This parameter uses the `tie_breaker_id` field to ensure all + lists are sorted and returned correctly. in: query name: cursor required: false @@ -412,6 +754,31 @@ paths: '200': content: application/json: + examples: + ipList: + value: + cursor: >- + WzIwLFsiZjU1MDgxODgtYjFlOS00ZTZlLTk2NjItZDAzOWE3ZDg5ODk5Il1d + data: + - _version: WzAsMV0= + '@timestamp': | + 2025-01-08T04:47:34.273Z + created_at: | + 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: Simple list with an ip + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: | + 2025-01-08T04:47:34.273Z + updated_by: elastic + version: 1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -440,6 +807,12 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: page: Expected number, received nan' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -448,22 +821,47 @@ 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: + error: Forbidden + message: >- + API [GET /api/lists/_find?page=1&per_page=20] is + unauthorized for user, this action is granted by the + Kibana privileges [lists-read] + 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: Get lists + summary: Get value lists tags: - Security Lists API /api/lists/index: @@ -493,6 +891,17 @@ 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 @@ -511,10 +920,15 @@ paths: '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: Delete list data streams + summary: Delete value list data streams tags: - Security Lists API get: @@ -546,6 +960,17 @@ 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 @@ -564,10 +989,15 @@ paths: '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: Get status of list data streams + summary: Get status of value list data streams tags: - Security Lists API post: @@ -596,6 +1026,17 @@ 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 @@ -608,12 +1049,24 @@ paths: '409': content: application/json: + examples: + alreadyExists: + value: + message: >- + data stream: \".lists-default\" and \".items-default\" + already exists + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List data stream exists 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 @@ -622,30 +1075,37 @@ paths: - Security Lists API /api/lists/items: delete: - description: 'Delete a list item using its `id`, or its `list_id` and `value` fields.' + description: >- + Delete a value list item using its `id`, or its `list_id` and `value` + fields. operationId: DeleteListItem parameters: - - description: Required if `list_id` and `value` are not specified + - description: >- + Value list item's identifier. Required if `list_id` and `value` are + not specified. in: query name: id required: false schema: - $ref: '#/components/schemas/ListId' - - description: Required if `id` is not specified + $ref: '#/components/schemas/ListItemId' + - description: Value list's identifier. Required if `id` is not specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/ListId' - - description: Required if `id` is not specified + - description: >- + The value used to evaluate exceptions. Required if `id` is not + specified. in: query name: value required: false schema: + example: 255.255.255.255 type: string - description: >- Determines when changes made by the request are made visible to - search + search. in: query name: refresh required: false @@ -655,11 +1115,26 @@ paths: - 'true' - 'false' - wait_for + example: false type: string responses: '200': content: application/json: + examples: + ip: + value: + _version: WzIwLDFd + '@timestamp': 2025-01-08T05:15:05.159Z + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: 2025-01-08T05:44:14.009Z + updated_by: elastic + value: 255.255.255.255 schema: oneOf: - $ref: '#/components/schemas/ListItem' @@ -670,6 +1145,13 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + message: >- + Either \"list_id\" or \"id\" needs to be defined in the + request + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -678,56 +1160,107 @@ 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: + error: Forbidden + message: >- + API [DELETE /api/lists/items?id=pd1WRJQBs4HAK3VQeHFI] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list item with id: \"pd1WRJQBs4HAK3VQeHFI\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item not found 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: Delete a list item + summary: Delete a value list item tags: - Security Lists API get: - description: Get the details of a list item. + description: Get the details of a value list item. operationId: ReadListItem parameters: - - description: Required if `list_id` and `value` are not specified + - description: >- + Value list item identifier. Required if `list_id` and `value` are + not specified. in: query name: id required: false schema: $ref: '#/components/schemas/ListId' - - description: Required if `id` is not specified + - description: >- + Value list item list's `id` identfier. Required if `id` is not + specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/ListId' - - description: Required if `id` is not specified + - description: >- + The value used to evaluate exceptions. Required if `id` is not + specified. in: query name: value required: false schema: + example: 127.0.0.2 type: string responses: '200': content: application/json: + examples: + ip: + value: + _version: WzExLDFd + '@timestamp': 2025-01-08T05:16:25.882Z + created_at: 2025-01-08T05:16:25.882Z + created_by: elastic + id: qN1XRJQBs4HAK3VQs3Gc + list_id: ip_list + tie_breaker_id: a9a34c02-a385-436e-86a0-02a3942f3537 + type: ip + updated_at: 2025-01-08T05:16:25.882Z + updated_by: elastic + value: 127.0.0.2 schema: oneOf: - $ref: '#/components/schemas/ListItem' @@ -738,6 +1271,13 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + message: >- + Either \"list_id\" or \"id\" needs to be defined in the + request + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -746,41 +1286,76 @@ 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: + error: Forbidden + message: >- + API [GET /api/lists/items?id=qN1XRJQBs4HAK3VQs3Gc] is + unauthorized for user, this action is granted by the + Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '404': content: application/json: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item not found 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: Get a list item + summary: Get a value list item tags: - Security Lists API patch: - description: Update specific fields of an existing list item using the list item ID. + description: >- + Update specific fields of an existing value list item using the item + `id`. operationId: PatchListItem requestBody: content: application/json: schema: + example: + id: pd1WRJQBs4HAK3VQeHFI + value: 255.255.255.255 type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' id: $ref: '#/components/schemas/ListItemId' meta: @@ -788,7 +1363,7 @@ paths: refresh: description: >- Determines when changes made by the request are made visible - to search + to search. enum: - 'true' - 'false' @@ -798,18 +1373,42 @@ paths: $ref: '#/components/schemas/ListItemValue' required: - id - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json: + examples: + ipItem: + value: + _version: WzE5LDFd + '@timestamp': 2025-01-08T05:15:05.159Z + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: 2025-01-08T05:23:37.602Z + updated_by: elastic + value: 255.255.255.255 schema: $ref: '#/components/schemas/ListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + message: >- + {"took":15,"timed_out":false,"total":1,"updated":0,"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,"failures":[{"index":".ds-.items-default-2025.01.09-000001","id":"ip_item","cause":{"type":"document_parsing_exception","reason":"[1:107] + failed to parse field [ip] of type [ip] in document with + id ip_item. Preview of fields value: + 2","caused_by":{"type":"illegal_argument_exception","reason":"2 + is not an IP string literal."}},"status":400}]} + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -818,37 +1417,68 @@ 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: + error: Forbidden + message: >- + API [PATCH /api/lists/items] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item not found 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: Patch a list item + summary: Patch a value list item tags: - Security Lists API post: description: > - Create a list item and associate it with the specified list. + Create a value list item and associate it with the specified value list. - All list items in the same list must be the same type. For example, each - list item in an `ip` list must define a specific IP address. + All value list items in the same list must be the same type. For + example, each list item in an `ip` list must define a specific IP + address. > info @@ -857,6 +1487,19 @@ paths: requestBody: content: application/json: + examples: + ip: + value: + list_id: ip_list + value: 127.0.0.1 + ip_range: + value: + list_id: ip_range_list + value: 192.168.0.0/16 + keyword: + value: + list_id: keyword_list + value: zeek schema: type: object properties: @@ -869,29 +1512,78 @@ paths: refresh: description: >- Determines when changes made by the request are made visible - to search + to search. enum: - 'true' - 'false' - wait_for + example: wait_for type: string value: $ref: '#/components/schemas/ListItemValue' required: - list_id - value - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': 2025-01-08T04:59:06.154Z + created_at: 2025-01-08T04:59:06.154Z + created_by: elastic + id: 21b01cfb-058d-44b9-838c-282be16c91cc + list_id: ip_list + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + type: ip + updated_at: 2025-01-08T04:59:06.154Z + updated_by: elastic + value: 127.0.0.1 + ip_range: + value: + _version: WzEsMV0= + '@timestamp': 2025-01-09T18:33:08.202Z + created_at: 2025-01-09T18:33:08.202Z + created_by: elastic + id: ip_range_item + list_id: ip_range_list + tie_breaker_id: ea1b4189-efda-4637-b8f9-74655a5ebb61 + type: ip_range + updated_at: 2025-01-09T18:33:08.202Z + updated_by: elastic + value: 192.168.0.0/16 + keyword: + value: + _version: WzIsMV0= + '@timestamp': 2025-01-09T18:34:29.422Z + created_at: 2025-01-09T18:34:29.422Z + created_by: elastic + id: 7f24737d-1da8-4626-a568-33070591bb4e + list_id: keyword_list + tie_breaker_id: 2108ced2-5e5d-401e-a88e-4dd69fc5fa27 + type: keyword + updated_at: 2025-01-09T18:34:29.422Z + updated_by: elastic + value: zeek schema: $ref: '#/components/schemas/ListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + uri [/api/lists/items] with method [post] exists but is + not available with the current configuration + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -900,34 +1592,74 @@ 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: + error: Forbidden + message: >- + API [POST /api/lists/items] 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 + '404': + content: + application/json: + examples: + listNotFound: + value: + message: 'list id: \"ip_list\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '409': content: application/json: + examples: + alreadyExists: + value: + message: 'list item id: \"ip_item\" already exists' + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item already exists 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: Create a list item + summary: Create a value list item tags: - Security Lists API put: description: > - Update a list item using the list item ID. The original list item is - replaced, and all unspecified fields are deleted. + Update a value list item using the list item ID. The original list item + is replaced, and all unspecified fields are deleted. > info @@ -936,11 +1668,14 @@ paths: requestBody: content: application/json: + example: + id: ip_item + value: 255.255.255.255 schema: type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' id: $ref: '#/components/schemas/ListItemId' meta: @@ -950,18 +1685,38 @@ paths: required: - id - value - description: List item's properties + description: Value list item's properties required: true responses: '200': content: application/json: + examples: + ip: + value: + _version: WzIwLDFd + '@timestamp': 2025-01-08T05:15:05.159Z + created_at: 2025-01-08T05:15:05.159Z + created_by: elastic + id: pd1WRJQBs4HAK3VQeHFI + list_id: ip_list + tie_breaker_id: eee41dc7-1666-4876-982f-8b0f7b59eca3 + type: ip + updated_at: 2025-01-08T05:44:14.009Z + updated_by: elastic + value: 255.255.255.255 schema: $ref: '#/components/schemas/ListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -970,36 +1725,66 @@ 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: + error: Forbidden + message: >- + API [PATCH /api/lists/items] 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 '404': content: application/json: + examples: + notFound: + value: + message: 'list item id: \"foo\" not found' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: List item not found 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: Update a list item + summary: Update a value list item tags: - Security Lists API /api/lists/items/_export: post: - description: Export list item values from the specified list. + description: Export list item values from the specified value list. operationId: ExportListItems parameters: - - description: List's id to export + - description: Value list's `id` to export. in: query name: list_id required: true @@ -1011,12 +1796,27 @@ paths: application/ndjson: schema: description: A `.txt` file containing list items from the specified list + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 format: binary type: string description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: 'Bad Request","message":"[request query]: list_id: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1025,12 +1825,32 @@ 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: + error: Forbidden + message: >- + API [POST /api/lists/items/_export?list_id=ips.txt] is + unauthorized for user, this action is granted by the + Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response @@ -1043,41 +1863,50 @@ paths: '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: Export list items + summary: Export value list items tags: - Security Lists API /api/lists/items/_find: get: - description: Get all list items in the specified list. + description: Get all value list items in the specified list. operationId: FindListItems parameters: - - description: List's id - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/ListId' - - description: The page number to return + - description: The page number to return. in: query name: page required: false schema: + example: 1 type: integer - - description: The number of list items to return per page + - description: The number of list items to return per page. in: query name: per_page required: false schema: + example: 20 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. in: query name: sort_field required: false schema: - $ref: '#/components/schemas/NonEmptyString' + example: value + format: nonempty + minLength: 1 + type: string - description: 'Determines the sort order, which can be `desc` or `asc`' in: query name: sort_order @@ -1086,17 +1915,9 @@ paths: enum: - desc - asc + example: asc type: string - - description: > - Returns the list that come after the last list returned in the - previous call - - (use the cursor value returned in the previous call). This parameter - uses - - the `tie_breaker_id` field to ensure all lists are sorted and - returned correctly. - in: query + - in: query name: cursor required: false schema: @@ -1115,6 +1936,26 @@ paths: '200': content: application/json: + examples: + ip: + value: + cursor: >- + WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + data: + - _version: WzAsMV0= + '@timestamp': 2025-01-08T04:59:06.154Z + created_at: 2025-01-08T04:59:06.154Z + created_by: elastic + id: 21b01cfb-058d-44b9-838c-282be16c91cc + list_id: ip_list + tie_breaker_id: b57c762c-3036-465c-9bfb-7bfb5e6e515a + type: ip + updated_at: 2025-01-08T04:59:06.154Z + updated_by: elastic + value: 127.0.0.1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -1143,6 +1984,12 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: 'Bad Request,' + message: '[request query]: list_id: Required' + statusCode: '400,' schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1151,29 +1998,55 @@ 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: + error: Forbidden + message: >- + API [GET + /api/lists/items/_find?list_id=ip_list&page=1&per_page=20] + is unauthorized for user, this action is granted by the + Kibana privileges [lists-read] + 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: Get list items + summary: Get value list items tags: - Security Lists API /api/lists/items/_import: post: description: > - Import list items from a TXT or CSV file. The maximum file size is 9 - million bytes. + Import value list items from a TXT or CSV file. The maximum file size is + 9 million bytes. You can import items to a new or existing list. @@ -1188,30 +2061,58 @@ paths: required: false schema: $ref: '#/components/schemas/ListId' - - description: > + - description: | Type of the importing list. - - Required when importing a new list that is `list_id` is not - specified. + Required when importing a new list whose list `id` is not specified. + examples: + ip: + value: ip in: query name: type required: false schema: $ref: '#/components/schemas/ListType' - - in: query + - description: > + Determines how uploaded list item values are parsed. By default, + list items are parsed using these named regex groups: + + + - `(?.+)` - Single value item types, such as ip, long, date, + keyword, and text. + + - `(?.+)-(?.+)|(?.+)` - Range value item types, + such as `date_range`, `ip_range`, `double_range`, `float_range`, + `integer_range`, and `long_range`. + in: query name: serializer required: false schema: + example: >- + (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) type: string - - in: query + - description: > + Determines how retrieved list item values are presented. By default + list items are presented using these Handelbar expressions: + + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, + `date`, `keyword`, and `text`. + + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as + `ip_range`, `double_range`, `float_range`, `integer_range`, and + `long_range`. + + - `{{{gte}}},{{{lte}}}` - Date range values. + in: query name: deserializer required: false schema: + example: '{{value}}' type: string - description: >- Determines when changes made by the request are made visible to - search + search. in: query name: refresh required: false @@ -1220,6 +2121,7 @@ paths: - 'true' - 'false' - wait_for + example: true type: string requestBody: content: @@ -1230,7 +2132,17 @@ paths: file: description: >- A `.txt` or `.csv` file containing newline separated list - items + items. + example: | + 127.0.0.1 + 127.0.0.2 + 127.0.0.3 + 127.0.0.4 + 127.0.0.5 + 127.0.0.6 + 127.0.0.7 + 127.0.0.8 + 127.0.0.9 format: binary type: string required: true @@ -1238,12 +2150,33 @@ paths: '200': content: application/json: + examples: + ip: + value: + _version: WzAsMV0= + '@timestamp': 2025-01-08T04:47:34.273Z + created_at: 2025-01-08T04:47:34.273Z + created_by: elastic + description: This list describes bad internet ip + id: ip_list + immutable: false + name: Simple list with an ip + tie_breaker_id: f5508188-b1e9-4e6e-9662-d039a7d89899 + type: ip + updated_at: 2025-01-08T04:47:34.273Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/List' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + message: Either type or list_id need to be defined in the query + status_code: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1252,12 +2185,32 @@ 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: + error: Forbidden + message: >- + API [POST /api/lists/items/_import?list_id=ip_list] 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 @@ -1270,10 +2223,15 @@ paths: '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: Import list items + summary: Import value list items tags: - Security Lists API /api/lists/privileges: @@ -1283,6 +2241,74 @@ paths: '200': content: application/json: + examples: + privileges: + value: + is_authenticated: true + listItems: + application: {} + cluster: + all: true + manage: true + manage_api_key: true + manage_index_templates: true + manage_ml: true + manage_own_api_key: true + manage_pipeline: true + manage_security: true + manage_transform: true + monitor: true + monitor_ml: true + monitor_transform: true + has_all_requested: true + index: + .items-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + username: elastic + lists: + application: {} + cluster: + all: true + manage: true + manage_api_key: true + manage_index_templates: true + manage_ml: true + manage_own_api_key: true + manage_pipeline: true + manage_security: true + manage_transform: true + monitor: true + monitor_ml: true + monitor_transform: true + has_all_requested: true + index: + .lists-default: + all: true + create: true + create_doc: true + create_index: true + delete: true + delete_index: true + index: true + maintenance: true + manage: true + monitor: true + read: true + view_index_metadata: true + write: true + username: elastic schema: type: object properties: @@ -1308,51 +2334,94 @@ 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: + error: Forbidden + message: >- + API [GET /api/lists/privileges] is unauthorized for user, + this action is granted by the Kibana privileges + [lists-read] + 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: Get list privileges + summary: Get value list privileges tags: - Security Lists API components: schemas: FindListItemsCursor: - $ref: '#/components/schemas/NonEmptyString' + description: >- + Returns the items that come after the last item returned in the previous + call (use the `cursor` value returned in the previous call). This + parameter uses the `tie_breaker_id` field to ensure all items are sorted + and returned correctly. + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + format: nonempty + minLength: 1 + type: string FindListItemsFilter: + example: 'value:127.0.0.1' type: string FindListsCursor: - $ref: '#/components/schemas/NonEmptyString' + example: WzIwLFsiYjU3Yzc2MmMtMzAzNi00NjVjLTliZmItN2JmYjVlNmU1MTVhIl1d + format: nonempty + minLength: 1 + type: string FindListsFilter: + example: 'value:127.0.0.1' type: string List: type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' '@timestamp': + example: 2025-01-08T04:47:34.273Z format: date-time type: string created_at: + description: Autogenerated date of object creation. + example: 2025-01-08T04:47:34.273Z format: date-time type: string created_by: + description: Autogenerated value - user that created object. + example: elastic type: string description: $ref: '#/components/schemas/ListDescription' deserializer: - type: string + $ref: '#/components/schemas/ListDeserializer' id: $ref: '#/components/schemas/ListId' immutable: @@ -1362,19 +2431,26 @@ components: name: $ref: '#/components/schemas/ListName' serializer: - type: string + $ref: '#/components/schemas/ListSerializer' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 type: string type: $ref: '#/components/schemas/ListType' updated_at: + description: Autogenerated date of last object update. + example: 2025-01-08T04:47:34.273Z format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. + example: elastic type: string version: - minimum: 1 - type: integer + $ref: '#/components/schemas/ListVersion' required: - id - type @@ -1388,24 +2464,51 @@ components: - updated_at - updated_by ListDescription: - $ref: '#/components/schemas/NonEmptyString' + description: Describes the value list. + format: nonempty + minLength: 1 + type: string + ListDeserializer: + description: > + Determines how retrieved list item values are presented. By default list + items are presented using these Handelbar expressions: + + + - `{{{value}}}` - Single value item types, such as `ip`, `long`, `date`, + `keyword`, and `text`. + + - `{{{gte}}}-{{{lte}}}` - Range value item types, such as `ip_range`, + `double_range`, `float_range`, `integer_range`, and `long_range`. + + - `{{{gte}}},{{{lte}}}` - Date range values. + example: '{{value}}' + type: string ListId: - $ref: '#/components/schemas/NonEmptyString' + description: Value list's identifier. + example: 21b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string ListItem: type: object properties: _version: - type: string + $ref: '#/components/schemas/ListVersionId' '@timestamp': + example: 2025-01-08T04:47:34.273Z format: date-time type: string created_at: + description: Autogenerated date of object creation. + example: 2025-01-08T04:47:34.273Z format: date-time type: string created_by: + description: Autogenerated value - user that created object. + example: elastic type: string deserializer: - type: string + $ref: '#/components/schemas/ListDeserializer' id: $ref: '#/components/schemas/ListItemId' list_id: @@ -1413,15 +2516,23 @@ components: meta: $ref: '#/components/schemas/ListItemMetadata' serializer: - type: string + $ref: '#/components/schemas/ListSerializer' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. + example: f5508188-b1e9-4e6e-9662-d039a7d89899 type: string type: $ref: '#/components/schemas/ListType' updated_at: + description: Autogenerated date of last object update. + example: 2025-01-08T04:47:34.273Z format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. + example: elastic type: string value: $ref: '#/components/schemas/ListItemValue' @@ -1436,9 +2547,14 @@ components: - updated_at - updated_by ListItemId: - $ref: '#/components/schemas/NonEmptyString' + description: Value list item's identifier. + example: 54b01cfb-058d-44b9-838c-282be16c91cd + format: nonempty + minLength: 1 + type: string ListItemMetadata: additionalProperties: true + description: Placeholder for metadata about the value list item. type: object ListItemPrivileges: type: object @@ -1468,12 +2584,20 @@ components: - index - application ListItemValue: - $ref: '#/components/schemas/NonEmptyString' + description: The value used to evaluate exceptions. + format: nonempty + minLength: 1 + type: string ListMetadata: additionalProperties: true + description: Placeholder for metadata about the value list. type: object ListName: - $ref: '#/components/schemas/NonEmptyString' + description: Value list's name. + example: List of bad IPs + format: nonempty + minLength: 1 + type: string ListPrivileges: type: object properties: @@ -1501,7 +2625,33 @@ components: - cluster - index - application + ListSerializer: + description: > + Determines how uploaded list item values are parsed. By default, list + items are parsed using these named regex groups: + + + - `(?.+)` - Single value item types, such as ip, long, date, + keyword, and text. + + - `(?.+)-(?.+)|(?.+)` - Range value item types, such as + `date_range`, `ip_range`, `double_range`, `float_range`, + `integer_range`, and `long_range`. + example: >- + (?((25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?).){3}(25[0-5]|2[0-4][0-9]|[01]?[0-9][0-9]?)) + type: string ListType: + description: > + Specifies the Elasticsearch data type of excludes the list container + holds. Some common examples: + + + - `keyword`: Many ECS fields are Elasticsearch keywords + + - `ip`: IP addresses + + - `ip_range`: Range of IP addresses (supports IPv4, IPv6, and CIDR + notation) enum: - binary - boolean @@ -1527,10 +2677,16 @@ components: - short - text type: string - NonEmptyString: - description: A string that does not contain only whitespace characters - format: nonempty - minLength: 1 + ListVersion: + description: The document version number. + example: 1 + minimum: 1 + type: integer + ListVersionId: + description: > + The version id, normally returned by the API when the document is + retrieved. Use it ensure updates are done against the latest version. + example: WzIsMV0= type: string PlatformErrorResponse: type: object diff --git a/packages/kbn-securitysolution-lists-common/tsconfig.json b/packages/kbn-securitysolution-lists-common/tsconfig.json index e8149be083552..06cf90b27f4b4 100644 --- a/packages/kbn-securitysolution-lists-common/tsconfig.json +++ b/packages/kbn-securitysolution-lists-common/tsconfig.json @@ -8,7 +8,6 @@ "include": ["**/*.ts"], "kbn_references": [ "@kbn/zod-helpers", - "@kbn/openapi-common", "@kbn/test", "@kbn/tooling-log", "@kbn/core-http-common", diff --git a/x-pack/test/api_integration/services/security_solution_lists_api.gen.ts b/x-pack/test/api_integration/services/security_solution_lists_api.gen.ts index 703dbebcf28ec..eb130a1d65805 100644 --- a/x-pack/test/api_integration/services/security_solution_lists_api.gen.ts +++ b/x-pack/test/api_integration/services/security_solution_lists_api.gen.ts @@ -41,7 +41,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) return { /** - * Create a new list. + * Create a new value list. */ createList(props: CreateListProps, kibanaSpace: string = 'default') { return supertest @@ -62,9 +62,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana'); }, /** - * Create a list item and associate it with the specified list. + * Create a value list item and associate it with the specified value list. -All list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. +All value list items in the same list must be the same type. For example, each list item in an `ip` list must define a specific IP address. > info > Before creating a list item, you must create a list. @@ -78,7 +78,7 @@ All list items in the same list must be the same type. For example, each list it .send(props.body as object); }, /** - * Delete a list using the list ID. + * Delete a value list using the list ID. > info > When you delete a list, all of its list items are also deleted. @@ -102,7 +102,7 @@ All list items in the same list must be the same type. For example, each list it .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana'); }, /** - * Delete a list item using its `id`, or its `list_id` and `value` fields. + * Delete a value list item using its `id`, or its `list_id` and `value` fields. */ deleteListItem(props: DeleteListItemProps, kibanaSpace: string = 'default') { return supertest @@ -113,7 +113,7 @@ All list items in the same list must be the same type. For example, each list it .query(props.query); }, /** - * Export list item values from the specified list. + * Export list item values from the specified value list. */ exportListItems(props: ExportListItemsProps, kibanaSpace: string = 'default') { return supertest @@ -124,7 +124,7 @@ All list items in the same list must be the same type. For example, each list it .query(props.query); }, /** - * Get all list items in the specified list. + * Get all value list items in the specified list. */ findListItems(props: FindListItemsProps, kibanaSpace: string = 'default') { return supertest @@ -135,7 +135,7 @@ All list items in the same list must be the same type. For example, each list it .query(props.query); }, /** - * Get a paginated subset of lists. By default, the first page is returned, with 20 results per page. + * Get a paginated subset of value lists. By default, the first page is returned, with 20 results per page. */ findLists(props: FindListsProps, kibanaSpace: string = 'default') { return supertest @@ -146,7 +146,7 @@ All list items in the same list must be the same type. For example, each list it .query(props.query); }, /** - * Import list items from a TXT or CSV file. The maximum file size is 9 million bytes. + * Import value list items from a TXT or CSV file. The maximum file size is 9 million bytes. You can import items to a new or existing list. @@ -160,7 +160,7 @@ You can import items to a new or existing list. .query(props.query); }, /** - * Update specific fields of an existing list using the list ID. + * Update specific fields of an existing list using the list `id`. */ patchList(props: PatchListProps, kibanaSpace: string = 'default') { return supertest @@ -171,7 +171,7 @@ You can import items to a new or existing list. .send(props.body as object); }, /** - * Update specific fields of an existing list item using the list item ID. + * Update specific fields of an existing value list item using the item `id`. */ patchListItem(props: PatchListItemProps, kibanaSpace: string = 'default') { return supertest @@ -182,7 +182,7 @@ You can import items to a new or existing list. .send(props.body as object); }, /** - * Get the details of a list using the list ID. + * Get the details of a value list using the list ID. */ readList(props: ReadListProps, kibanaSpace: string = 'default') { return supertest @@ -203,7 +203,7 @@ You can import items to a new or existing list. .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana'); }, /** - * Get the details of a list item. + * Get the details of a value list item. */ readListItem(props: ReadListItemProps, kibanaSpace: string = 'default') { return supertest @@ -221,7 +221,7 @@ You can import items to a new or existing list. .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana'); }, /** - * Update a list using the list ID. The original list is replaced, and all unspecified fields are deleted. + * Update a value list using the list `id`. The original list is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value. @@ -235,7 +235,7 @@ You can import items to a new or existing list. .send(props.body as object); }, /** - * Update a list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. + * Update a value list item using the list item ID. The original list item is replaced, and all unspecified fields are deleted. > info > You cannot modify the `id` value.