diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml index 6f6870a9860eb..055f79a13988e 100644 --- a/oas_docs/output/kibana.serverless.yaml +++ b/oas_docs/output/kibana.serverless.yaml @@ -885,7 +885,7 @@ paths: description: Indicates whether the action is a summary. type: boolean throttle: - description: 'The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if ''notify_when'' is set to ''onThrottleInterval''. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.' + description: "The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values." nullable: true type: string required: @@ -1812,7 +1812,7 @@ paths: description: Indicates whether the action is a summary. type: boolean throttle: - description: 'The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if ''notify_when'' is set to ''onThrottleInterval''. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.' + description: "The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values." nullable: true type: string required: @@ -2714,7 +2714,7 @@ paths: description: Indicates whether the action is a summary. type: boolean throttle: - description: 'The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if ''notify_when'' is set to ''onThrottleInterval''. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.' + description: "The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values." nullable: true type: string required: @@ -3776,7 +3776,7 @@ paths: description: Indicates whether the action is a summary. type: boolean throttle: - description: 'The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if ''notify_when'' is set to ''onThrottleInterval''. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values.' + description: "The throttle interval, which defines how often an alert generates repeated actions. It is specified in seconds, minutes, hours, or days and is applicable only if 'notify_when' is set to 'onThrottleInterval'. NOTE: You cannot specify the throttle interval at both the rule and action level. The recommended method is to set it for each action. If you set it at the rule level then update the rule in Kibana, it is automatically changed to use action-specific values." nullable: true type: string required: @@ -32435,39 +32435,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' @@ -32476,37 +32501,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: @@ -32515,12 +32561,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' @@ -32529,42 +32597,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: @@ -32574,22 +32667,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' @@ -32598,44 +32712,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: @@ -32643,7 +32806,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: @@ -32654,18 +32817,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' @@ -32674,34 +32905,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 @@ -32709,10 +32962,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: @@ -32722,24 +32979,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' @@ -32748,54 +33026,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 @@ -32804,11 +33109,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 @@ -32826,6 +33129,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: @@ -32854,6 +33181,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' @@ -32862,22 +33195,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 @@ -32908,6 +33258,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 @@ -32926,10 +33282,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 @@ -32962,6 +33323,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 @@ -32980,10 +33347,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 @@ -33013,6 +33385,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 @@ -33025,12 +33404,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 @@ -33040,28 +33429,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 @@ -33071,11 +33461,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' @@ -33086,6 +33491,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' @@ -33094,57 +33504,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' @@ -33155,6 +33602,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' @@ -33163,48 +33615,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' @@ -33214,18 +33691,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' @@ -33234,42 +33730,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: @@ -33280,29 +33811,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' @@ -33311,45 +33889,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: @@ -33359,18 +33973,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' @@ -33379,37 +34013,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 @@ -33421,12 +34077,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' @@ -33435,12 +34106,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 @@ -33453,42 +34136,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 @@ -33497,12 +34189,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: @@ -33519,6 +34208,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: @@ -33547,6 +34255,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' @@ -33555,29 +34269,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 @@ -33594,23 +34325,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 @@ -33619,6 +34366,7 @@ paths: - 'true' - 'false' - wait_for + example: true type: string requestBody: content: @@ -33627,7 +34375,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 @@ -33635,12 +34393,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' @@ -33649,12 +34428,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 @@ -33667,10 +34458,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 @@ -33681,6 +34477,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: @@ -33706,22 +34570,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 @@ -47691,7 +48572,7 @@ components: minimum: 1 type: integer Security_Detections_API_ThrottleForBulkActions: - description: 'The condition for throttling the notification: ''rule'', ''no_actions'', or time duration' + description: "The condition for throttling the notification: 'rule', 'no_actions', or time duration" enum: - rule - 1h @@ -48149,8 +49030,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 @@ -49882,8 +50773,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 @@ -49957,30 +50858,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: @@ -49990,19 +50905,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 @@ -50016,24 +50936,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: @@ -50041,15 +50982,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' @@ -50064,9 +51011,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 @@ -50096,12 +51048,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: @@ -50129,7 +51089,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 @@ -50155,10 +51129,15 @@ components: - short - text type: string - Security_Lists_API_NonEmptyString: - description: A string that is not empty and does not contain only whitespace - minLength: 1 - pattern: ^(?! *$).+$ + 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 @@ -51222,7 +52201,7 @@ components: example: Bad Request type: string message: - example: 'Invalid value ''foo'' supplied to: [...]' + example: "Invalid value 'foo' supplied to: [...]" type: string statusCode: example: 400 diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index 0897cba0beefa..06577aece7449 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -15910,39 +15910,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' @@ -15951,36 +15976,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: @@ -15989,12 +16035,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' @@ -16003,41 +16071,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: @@ -16047,22 +16140,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' @@ -16071,43 +16185,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: @@ -16115,7 +16278,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: @@ -16126,18 +16289,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' @@ -16146,33 +16377,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 @@ -16180,10 +16433,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: @@ -16193,24 +16450,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' @@ -16219,53 +16497,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 @@ -16274,11 +16579,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 @@ -16296,6 +16599,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: @@ -16324,6 +16651,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' @@ -16332,22 +16665,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: @@ -16377,6 +16727,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 @@ -16395,10 +16751,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: @@ -16430,6 +16791,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 @@ -16448,10 +16815,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: @@ -16480,6 +16852,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 @@ -16492,12 +16871,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 @@ -16506,28 +16895,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 @@ -16537,11 +16927,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' @@ -16552,6 +16957,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' @@ -16560,56 +16970,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' @@ -16620,6 +17067,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' @@ -16628,47 +17080,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' @@ -16678,18 +17155,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' @@ -16698,41 +17194,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: @@ -16743,29 +17274,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' @@ -16774,44 +17352,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: @@ -16821,18 +17435,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' @@ -16841,36 +17475,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 @@ -16882,12 +17538,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' @@ -16896,12 +17567,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 @@ -16914,41 +17597,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 @@ -16957,12 +17649,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: @@ -16979,6 +17668,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: @@ -17007,6 +17715,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' @@ -17015,28 +17729,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 @@ -17053,23 +17784,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 @@ -17078,6 +17825,7 @@ paths: - 'true' - 'false' - wait_for + example: true type: string requestBody: content: @@ -17086,7 +17834,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 @@ -17094,12 +17852,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' @@ -17108,12 +17887,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 @@ -17126,10 +17917,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: @@ -17139,6 +17935,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: @@ -17164,22 +18028,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: @@ -36523,8 +37404,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 @@ -38273,8 +39164,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 @@ -38348,30 +39249,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: @@ -38381,19 +39296,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 @@ -38407,24 +39327,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: @@ -38432,15 +39373,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' @@ -38455,9 +39402,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 @@ -38487,12 +39439,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: @@ -38520,7 +39480,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 @@ -38546,10 +39520,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/x-pack/solutions/security/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/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/x-pack/solutions/security/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/solutions/security/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/x-pack/solutions/security/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/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/x-pack/solutions/security/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/solutions/security/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/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml index 21e9be05a9a7e..c3e461e3ad6fc 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml @@ -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/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml index 119da3ee7cd85..913e1d9b9196a 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml @@ -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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts index cf603f3ac3bdb..961be81c29e28 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.gen.ts @@ -10,7 +10,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 */ @@ -21,6 +21,8 @@ import { ListName, ListDescription, ListType, + ListSerializer, + ListDeserializer, ListMetadata, } from '../model/list_common.gen'; import { List } from '../model/list_schemas.gen'; @@ -31,8 +33,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml index 3c1d090687fe6..addb3f856a71e 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list/create_list.schema.yaml +++ b/x-pack/solutions/security/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + 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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/lists] 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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml index 8f79811144374..b8e93f70bce3a 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_index/create_list_index.schema.yaml @@ -35,6 +35,13 @@ paths: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts index ce4744f3c4418..8d223b54008af 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.gen.ts @@ -10,7 +10,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 */ @@ -26,7 +26,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml index bdf266c8926f6..f3adc7d1739ef 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/create_list_item/create_list_item.schema.yaml +++ b/x-pack/solutions/security/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. + 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. 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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/lists/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts index 3dd638be564ee..b22ae640021aa 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.gen.ts @@ -10,7 +10,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 */ @@ -22,11 +22,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml index d8440aa347cde..7328710896ab7 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list/delete_list.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request query]: id: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [DELETE /api/lists?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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.gen.ts index 4ffd90f6fb8b0..1f4197bf9aa21 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.gen.ts @@ -10,7 +10,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml index 8773925e358b1..c695245938927 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_index/delete_list_index.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.gen.ts index fe9f7bee0e688..eb223feee28cf 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.gen.ts @@ -10,31 +10,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml index 752a246bdd9b3..31e96ee1ed3dc 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/delete_list_item/delete_list_item.schema.yaml +++ b/x-pack/solutions/security/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + message: '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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [DELETE /api/lists/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.gen.ts index 87e05bd24e481..61e8536485a77 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.gen.ts @@ -10,7 +10,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 */ @@ -21,7 +21,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml index 2dd518904d0f8..f5e13d627fe76 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/export_list_items/export_list_items.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: 'Bad Request","message":"[request query]: list_id: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/lists/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts index e40c6fe9e2fc1..a091d08b41f07 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.gen.ts @@ -15,45 +15,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml index 5cb15220e17cc..25ec88a78cd46 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_list_items/find_list_items.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400, + error: Bad Request, + message: '[request query]: list_id: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.gen.ts index 74f8ba0217d68..adc646a3c46d3 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.gen.ts @@ -10,17 +10,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(); @@ -28,27 +28,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml index 44713827d29f9..3c7016812fd79 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/find_lists/find_lists.schema.yaml +++ b/x-pack/solutions/security/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request query]: page: Expected number, received nan' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists/_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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.gen.ts index baf9d9308a93c..549dd8f12ddfc 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.gen.ts @@ -10,7 +10,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 */ @@ -31,14 +31,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml index 78f44f7dd7f71..58f732a823b36 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/import_list_items/import_list_items.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + message: '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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/lists/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_common.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_common.gen.ts index 536e0b859e45a..542e445c6e18e 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_common.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_common.gen.ts @@ -10,17 +10,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', @@ -50,23 +60,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_common.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_common.schema.yaml index ef29224a5b73c..3b995fec9e2ac 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_common.schema.yaml +++ b/x-pack/solutions/security/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_schemas.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_schemas.gen.ts index cd95d20853c11..2edd2556d7356 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_schemas.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_schemas.gen.ts @@ -21,7 +21,11 @@ import { ListType, ListName, ListDescription, + ListSerializer, + ListDeserializer, ListMetadata, + ListVersion, + ListVersionId, ListItemId, ListItemValue, ListItemMetadata, @@ -33,17 +37,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(), }); @@ -53,14 +72,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_schemas.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_schemas.schema.yaml index 838dc5e4edea0..65f03c7befb89 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/model/list_schemas.schema.yaml +++ b/x-pack/solutions/security/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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.gen.ts index f2a67181d396d..d79a3e722c6f3 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.gen.ts @@ -10,13 +10,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; @@ -25,8 +32,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml index be8c5871413fc..c0b39a662262d 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list/patch_list.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: name: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.gen.ts index e5c06ddd7c251..be4605bd39b76 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.gen.ts @@ -10,13 +10,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; @@ -24,9 +29,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml index 7802133dc4b16..ada1d17e6ef6a 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/patch_list_item/patch_list_item.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + message: '{"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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts index 232f4b00540c5..c117a3c3466d5 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/quickstart_client.gen.ts @@ -76,7 +76,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`); @@ -107,9 +107,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. @@ -128,7 +128,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. @@ -163,7 +163,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`); @@ -180,7 +180,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`); @@ -197,7 +197,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`); @@ -214,7 +214,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`); @@ -231,7 +231,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. @@ -251,7 +251,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`); @@ -267,7 +267,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`); @@ -283,7 +283,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`); @@ -315,7 +315,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`); @@ -344,7 +344,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. @@ -363,7 +363,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts index d2967d71d57e5..91b6ece8c13ce 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.gen.ts @@ -10,7 +10,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 */ @@ -21,9 +21,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml index e4a72d6555096..4cf25bd80be38 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list/read_list.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request query]: id: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists?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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.gen.ts index bf0aec4dc6bcf..8f0a61a5c1244 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.gen.ts @@ -10,7 +10,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml index b06b78ac34147..ddd5d347d4750 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_index/read_list_index.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.gen.ts index d22ee46022266..63cc2c189800d 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.gen.ts @@ -10,7 +10,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 */ @@ -22,15 +22,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml index c1bb0697152bd..63b55ddd8cdba 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_item/read_list_item.schema.yaml +++ b/x-pack/solutions/security/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + message: '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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.gen.ts index da6e7e95076da..c3410b8c0d0f9 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.gen.ts @@ -10,7 +10,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml index d51e420aa4a94..d83d5d837647b 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/read_list_privileges/read_list_privileges.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/lists/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: '../../../../../../../src/platform/packages/shared/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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.gen.ts index ffb28c3d0b530..9bded0dd5d203 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.gen.ts @@ -10,13 +10,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; @@ -25,8 +32,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml index 077a96d25d9ed..e20081f5f4b59 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list/update_list.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.gen.ts b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.gen.ts index f5667676ab4c6..8d559e845e3c0 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.gen.ts +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.gen.ts @@ -10,13 +10,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; @@ -24,7 +29,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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml index 8971372210475..ef17a470f6595 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/api/update_list_item/update_list_item.schema.yaml @@ -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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/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: '../../../../../../../src/platform/packages/shared/kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml index bdf6df3e520b3..afa6b132a0222 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/ess/security_solution_lists_api_2023_10_31.bundled.schema.yaml @@ -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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml index 5a031582bace2..e9d22905f14b9 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/docs/openapi/serverless/security_solution_lists_api_2023_10_31.bundled.schema.yaml @@ -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/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/tsconfig.json b/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/tsconfig.json index 6a6637ff64a2c..7c3ddc51f2926 100644 --- a/x-pack/solutions/security/packages/kbn-securitysolution-lists-common/tsconfig.json +++ b/x-pack/solutions/security/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.