diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index 57112d6d0be8e..9b71581c70cfe 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -8863,6 +8863,9 @@ paths: operationId: CreateRuleExceptionListItems parameters: - description: Detection rule's identifier + examples: + id: + value: 330bdd28-eedf-40e1-bed0-f10176c7f9e0 in: path name: id required: true @@ -8872,6 +8875,28 @@ paths: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + items: + - description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + type: simple type: object properties: items: @@ -8880,12 +8905,43 @@ paths: type: array required: - items - description: Rule exception list items + description: Rule exception items. required: true responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + ruleExceptionItems: + value: + - _version: WzQsMV0= + comments: [] + created_at: '2025-01-07T20:07:33.119Z' + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: '2025-01-07T20:07:33.119Z' + updated_by: elastic schema: items: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItem' @@ -8894,6 +8950,17 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badPayload: + value: + error: Bad Request + message: Invalid request payload JSON format + statusCode: 400 + badRequest: + value: + error: Bad Request + message: '[request params]: id: Invalid uuid' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -8902,22 +8969,38 @@ 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_Exceptions_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + message: Unable to create exception-list + status_code: 403 schema: $ref: '#/components/schemas/Security_Exceptions_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_Exceptions_API_SiemErrorResponse' description: Internal server error response - summary: Create rule exception list items + summary: Create rule exception items tags: - Security Exceptions API /api/detection_engine/rules/prepackaged: @@ -11217,19 +11300,29 @@ paths: description: Delete an exception list using the `id` or `list_id` field. operationId: DeleteExceptionList parameters: - - description: Either `id` or `list_id` must be specified + - description: Exception list's identifier. Either `id` or `list_id` must be specified. in: query name: id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListId' - - description: Either `id` or `list_id` must be specified + - description: Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified. + examples: + autogeneratedId: + value: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + list_id: + value: simple_list in: query name: list_id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -11239,12 +11332,39 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + detectionExceptionList: + value: + _version: WzIsMV0= + created_at: '2025-01-07T19:34:27.942Z' + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: '2025-01-07T19:34:27.942Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionList' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob''' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -11253,24 +11373,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_Exceptions_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/exception_lists?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'exception list list_id: "foo" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11281,19 +11423,24 @@ paths: description: Get the details of an exception list using the `id` or `list_id` field. operationId: ReadExceptionList parameters: - - description: Either `id` or `list_id` must be specified + - description: Exception list's identifier. Either `id` or `list_id` must be specified. in: query name: id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListId' - - description: Either `id` or `list_id` must be specified + - description: Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -11303,12 +11450,39 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + detectionType: + value: + _version: WzIsMV0= + created_at: '2025-01-07T19:34:27.942Z' + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: '2025-01-07T19:34:27.942Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionList' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob''' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -11317,24 +11491,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_Exceptions_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/exception_lists?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11343,7 +11539,7 @@ paths: - Security Exceptions API post: description: | - An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists. + An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules. > info > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item. operationId: CreateExceptionList @@ -11351,6 +11547,16 @@ paths: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + description: This is a sample detection type exception list. + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + type: detection type: object properties: description: @@ -11384,12 +11590,98 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + autogeneratedListId: + value: + _version: WzMsMV0= + created_at: '2025-01-09T01:05:23.019Z' + created_by: elastic + description: This is a sample detection type exception with an autogenerated list_id. + id: 28243c2f-624a-4443-823d-c0b894880931 + immutable: false + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Sample Detection Exception List + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: ad94de31-39f7-4ad7-b8e4-988bfa95f338 + type: detection + updated_at: '2025-01-09T01:05:23.020Z' + updated_by: elastic + version: 1 + namespaceAgnostic: + value: + _version: WzUsMV0= + created_at: '2025-01-09T01:10:36.369Z' + created_by: elastic + description: This is a sample agnostic endpoint type exception. + id: 1a744e77-22ca-4b6b-9085-54f55275ebe5 + immutable: false + list_id: b935eb55-7b21-4c1c-b235-faa1df23b3d6 + name: Sample Agnostic Endpoint Exception List + namespace_type: agnostic + os_types: + - linux + tags: + - malware + tie_breaker_id: 49ea0adc-a2b8-4d83-a8f3-2fb98301dea3 + type: endpoint + updated_at: '2025-01-09T01:10:36.369Z' + updated_by: elastic + version: 1 + typeDetection: + value: + _version: WzIsMV0= + created_at: '2025-01-07T19:34:27.942Z' + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: '2025-01-07T19:34:27.942Z' + updated_by: elastic + version: 1 + typeEndpoint: + value: + _version: WzQsMV0= + created_at: '2025-01-09T01:07:49.658Z' + created_by: elastic + description: This is a sample endpoint type exception list. + id: a79f4730-6e32-4278-abfc-349c0add7d54 + immutable: false + list_id: endpoint_list + name: Sample Endpoint Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 94a028af-8f47-427a-aca5-ffaf829e64ee + type: endpoint + updated_at: '2025-01-09T01:07:49.658Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionList' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -11398,24 +11690,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_Exceptions_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/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'exception list id: "simple_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11429,9 +11743,19 @@ paths: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + description: Different description + list_id: simple_list + name: Updated exception list name + os_types: + - linux + tags: + - draft malware + type: detection type: object properties: _version: + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. type: string description: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListDescription' @@ -11465,12 +11789,38 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + simpleList: + value: + _version: WzExLDFd + created_at: '2025-01-07T20:43:55.264Z' + created_by: elastic + description: Different description + id: fa7f545f-191b-4d32-b1f0-c7cd62a79e55 + immutable: false + list_id: simple_list + name: Updated exception list name + namespace_type: single + os_types: [] + tags: + - draft malware + tie_breaker_id: 319fe983-acdd-4806-b6c4-3098eae9392f + type: detection + updated_at: '2025-01-07T21:32:03.726Z' + updated_by: elastic + version: 2 schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionList' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -11479,24 +11829,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_Exceptions_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/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11508,18 +11880,22 @@ paths: description: Duplicate an existing exception list. operationId: DuplicateExceptionList parameters: - - description: Exception list's human identifier - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: true schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionNamespaceType' - - description: Determines whether to include expired exceptions in the exported list + - description: Determines whether to include expired exceptions in the duplicated list. Expiration date defined by `expire_time`. in: query name: include_expired_exceptions required: true @@ -11528,17 +11904,44 @@ paths: enum: - 'true' - 'false' + example: true type: string responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + detectionExceptionList: + value: + _version: WzExNDY1LDFd + created_at: '2025-01-09T16:19:50.280Z' + created_by: elastic + description: This is a sample detection type exception + id: b2f4a715-6ab1-444c-8b1e-3fa1b1049429 + immutable: false + list_id: d6390d60-bce3-4a48-9002-52db600f329c + name: Sample Detection Exception List [Duplicate] + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 6fa670bd-666d-4c9c-9f1e-d1dbc516e985 + type: detection + updated_at: '2025-01-09T16:19:50.280Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionList' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: namespace_type: Invalid enum value. Expected ''agnostic'' | ''single'', received ''foo''' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -11547,15 +11950,38 @@ 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_Exceptions_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/exception_lists/_duplicate] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response + '404': + content: + application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 + schema: + $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' + description: Exception list not found '405': content: application/json; Elastic-Api-Version=2023-10-31: @@ -11565,6 +11991,11 @@ 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11576,24 +12007,28 @@ paths: description: Export an exception list and its associated items to an NDJSON file. operationId: ExportExceptionList parameters: - - description: Exception list's identifier - in: query + - in: query name: id required: true schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListId' - - description: Exception list's human identifier - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: true schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionNamespaceType' - - description: Determines whether to include expired exceptions in the exported list + - description: Determines whether to include expired exceptions in the exported list. Expiration date defined by `expire_time`. + example: true in: query name: include_expired_exceptions required: true @@ -11607,6 +12042,12 @@ paths: '200': content: application/ndjson; Elastic-Api-Version=2023-10-31: + examples: + exportSavedObjectsResponse: + value: | + {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This is a sample detection type exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample Detection Exception List","namespace_type":"single","os_types":[],"tags":["user added string for a tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1} + {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This is a sample endpoint type exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some host","another host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample Endpoint Exception List","namespace_type":"single","os_types":["linux"],"tags":["user added string for a tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"} + {"exported_exception_list_count":1,"exported_exception_list_item_count":1,"missing_exception_list_item_count":0,"missing_exception_list_items":[],"missing_exception_lists":[],"missing_exception_lists_count":0} schema: description: A `.ndjson` file containing specified exception list and its items format: binary @@ -11615,6 +12056,12 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: list_id: Required, namespace_type: Required' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -11623,24 +12070,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_Exceptions_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/exception_lists/_export] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11649,7 +12118,7 @@ paths: - Security Exceptions API /api/exception_lists/_find: get: - description: Get a list of all exception lists. + description: Get a list of all exception list containers. operationId: FindExceptionLists parameters: - description: | @@ -11667,6 +12136,11 @@ paths: - description: | Determines whether the returned containers are Kibana associated with a Kibana space or available in all spaces (`agnostic` or `single`) + examples: + agnostic: + value: agnostic + single: + value: single in: query name: namespace_type required: false @@ -11681,6 +12155,7 @@ paths: name: page required: false schema: + example: 1 minimum: 1 type: integer - description: The number of exception lists to return per page @@ -11688,15 +12163,17 @@ paths: name: per_page required: false schema: + example: 20 minimum: 1 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: + example: name type: string - - description: Determines the sort order, which can be `desc` or `asc` + - description: Determines the sort order, which can be `desc` or `asc`. in: query name: sort_order required: false @@ -11704,11 +12181,36 @@ paths: enum: - desc - asc + example: desc type: string responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + simpleLists: + value: + data: + - _version: WzIsMV0= + created_at: '2025-01-07T19:34:27.942Z' + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Detection Exception List + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: '2025-01-07T19:34:27.942Z' + updated_by: elastic + version: 1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -11734,6 +12236,12 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob''' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -11742,18 +12250,35 @@ 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_Exceptions_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/exception_lists/_find?namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11773,18 +12298,7 @@ paths: required: false schema: default: false - type: boolean - - in: query - name: overwrite_exceptions - required: false - schema: - default: false - type: boolean - - in: query - name: overwrite_action_connectors - required: false - schema: - default: false + example: false type: boolean - description: | Determines whether the list being imported will have a new `list_id` generated. @@ -11795,6 +12309,7 @@ paths: required: false schema: default: false + example: false type: boolean requestBody: content: @@ -11804,6 +12319,9 @@ paths: properties: file: description: A `.ndjson` file containing the exception list + example: | + {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This is a sample detection type exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample Detection Exception List","namespace_type":"single","os_types":[],"tags":["user added string for a tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1} + {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This is a sample endpoint type exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some host","another host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample Endpoint Exception List","namespace_type":"single","os_types":["linux"],"tags":["user added string for a tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"} format: binary type: string required: true @@ -11811,6 +12329,34 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + withErrors: + value: + errors: + - error: + message: 'Error found importing exception list: Invalid value \"4\" supplied to \"list_id\"' + status_code: 400 + list_id: (unknown list_id) + - error: + message: 'Found that item_id: \"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\" already exists. Import of item_id: \"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\" skipped.' + status_code: 409 + item_id: f7fd00bb-dba8-4c93-9d59-6cbd427b6330 + list_id: 7d7cccb8-db72-4667-b1f3-648efad7c1ee + success: false, + success_count: 0, + success_count_exception_list_items: 0 + success_count_exception_lists: 0, + success_exception_list_items: false, + success_exception_lists: false, + withoutErrors: + value: + errors: [] + success: true + success_count: 2 + success_count_exception_list_items: 1 + success_count_exception_lists: 1 + success_exception_list_items: true + success_exception_lists: true, schema: type: object properties: @@ -11851,18 +12397,35 @@ 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_Exceptions_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/exception_lists/_import] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11874,19 +12437,24 @@ paths: description: Delete an exception list item using the `id` or `item_id` field. operationId: DeleteExceptionListItem parameters: - - description: Either `id` or `item_id` must be specified + - description: Exception item's identifier. Either `id` or `item_id` must be specified in: query name: id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemId' - - description: Either `id` or `item_id` must be specified + - description: Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified in: query name: item_id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -11896,6 +12464,37 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + simpleExceptionItem: + value: + _version: WzQsMV0= + comments: [] + created_at: '2025-01-07T20:07:33.119Z' + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: '2025-01-07T20:07:33.119Z' + updated_by: elastic schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItem' description: Successful response @@ -11903,6 +12502,10 @@ paths: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + error: Bad Request + message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob''' + statusCode: 400 oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' - $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' @@ -11910,24 +12513,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_Exceptions_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/exception_lists/items?item_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -11938,19 +12563,24 @@ paths: description: Get the details of an exception list item using the `id` or `item_id` field. operationId: ReadExceptionListItem parameters: - - description: Either `id` or `item_id` must be specified + - description: Exception list item's identifier. Either `id` or `item_id` must be specified. in: query name: id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemId' - - description: Either `id` or `item_id` must be specified + - description: Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified. in: query name: item_id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -11960,12 +12590,49 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + simpleListItem: + value: + _version: WzQsMV0= + comments: [] + created_at: '2025-01-07T20:07:33.119Z' + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: '2025-01-07T20:07:33.119Z' + updated_by: elastic schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob''' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -11974,24 +12641,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_Exceptions_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/exception_lists/items?item_id=&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -12008,6 +12697,27 @@ paths: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + type: simple type: object properties: comments: @@ -12018,8 +12728,7 @@ paths: entries: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemExpireTime' item_id: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemHumanId' list_id: @@ -12051,12 +12760,200 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + autogeneratedItemId: + value: + _version: WzYsMV0= + comments: [] + created_at: '2025-01-09T01:16:23.322Z' + created_by: elastic + description: This is a sample exception that has no item_id so it is autogenerated. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 323faa75-c657-4fa0-9084-8827612c207b + item_id: 80e6edf7-4b13-4414-858f-2fa74aa52b37 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Sample Autogenerated Exception List Item ID + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: d6799986-3a23-4213-bc6d-ed9463a32f23 + type: simple + updated_at: '2025-01-09T01:16:23.322Z' + updated_by: elastic + detectionExceptionListItem: + value: + _version: WzQsMV0= + comments: [] + created_at: '2025-01-07T20:07:33.119Z' + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: '2025-01-07T20:07:33.119Z' + updated_by: elastic + withExistEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: '2025-01-07T20:07:33.119Z' + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: '2025-01-07T20:07:33.119Z' + updated_by: elastic + withMatchAnyEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: '2025-01-07T20:07:33.119Z' + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: '2025-01-07T20:07:33.119Z' + updated_by: elastic + withMatchEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: '2025-01-07T20:07:33.119Z' + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: included + type: match + value: Elastic N.V. + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: '2025-01-07T20:07:33.119Z' + updated_by: elastic + withNestedEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: '2025-01-07T20:07:33.119Z' + created_by: elastic + description: This is a sample detection type exception item. + entries: + - entries: + - field: signer + operator: included + type: match + value: Evil + - field: trusted + operator: included + type: match + value: true + field: file.signature + type: nested + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: '2025-01-07T20:07:33.119Z' + updated_by: elastic + withValueListEntry: + value: + _version: WzcsMV0= + comments: [] + created_at: '2025-01-09T01:31:12.614Z' + created_by: elastic + description: Don't signal when agent.name is rock01 and source.ip is in the goodguys.txt list + entries: + - field: source.ip + list: + id: goodguys.txt + type: ip + operator: excluded + type: list + id: deb26876-297d-4677-8a1f-35467d2f1c4f + item_id: 686b129e-9b8d-4c59-8d8d-c93a9ea82c71 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Filter out good guys ip and agent.name rock01 + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 5e0288ce-6657-4c18-9dcc-00ec9e8cc6c8 + type: simple + updated_at: '2025-01-09T01:31:12.614Z' + updated_by: elastic schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request, + message: '[request body]: list_id: Expected string, received number' + statusCode: 400, schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -12065,24 +12962,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_Exceptions_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/exception_lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'exception list item id: \"simple_list_item\" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -12095,10 +13014,24 @@ paths: requestBody: content: application/json; Elastic-Api-Version=2023-10-31: + example: + comments: [] + description: Updated description + entries: + - field: host.name + operator: included + type: match + value: rock01 + item_id: simple_list_item + name: Updated name + namespace_type: single + tags: [] + type: simple schema: type: object properties: _version: + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. type: string comments: $ref: '#/components/schemas/Security_Exceptions_API_UpdateExceptionListItemCommentArray' @@ -12108,8 +13041,7 @@ paths: entries: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemExpireTime' id: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemId' description: Either `id` or `item_id` must be specified @@ -12143,12 +13075,42 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + simpleListItem: + value: + _version: WzEyLDFd + comments: [] + created_at: '2025-01-07T21:12:25.512Z' + created_by: elastic + description: Updated description + entries: + - field: host.name + operator: included + type: match + value: rock01 + id: 459c5e7e-f8b2-4f0b-b136-c1fc702f72da + item_id: simple_list_item + list_id: simple_list + name: Updated name + namespace_type: single + os_types: [] + tags: [] + tie_breaker_id: ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0 + type: simple + updated_at: '2025-01-07T21:34:50.233Z' + updated_by: elastic schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItem' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: item_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -12157,24 +13119,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_Exceptions_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/exception_lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -12186,7 +13170,7 @@ paths: description: Get a list of all exception list items in the specified list. operationId: FindExceptionListItems parameters: - - description: List's id + - description: The `list_id`s of the items to fetch. in: query name: list_id required: true @@ -12197,6 +13181,10 @@ paths: - description: | Filters the returned results according to the value of the specified field, using the `:` syntax. + examples: + singleFilter: + value: + - exception-list.attributes.name:%My%20item in: query name: filter required: false @@ -12208,6 +13196,10 @@ paths: - description: | Determines whether the returned containers are Kibana associated with a Kibana space or available in all spaces (`agnostic` or `single`) + examples: + single: + value: + - single in: query name: namespace_type required: false @@ -12221,12 +13213,14 @@ paths: name: search required: false schema: + example: host.name type: string - description: The page number to return in: query name: page required: false schema: + example: 1 minimum: 0 type: integer - description: The number of exception list items to return per page @@ -12234,15 +13228,17 @@ paths: name: per_page required: false schema: + example: 20 minimum: 0 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. + example: name in: query name: sort_field required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' - - description: Determines the sort order, which can be `desc` or `asc` + - description: Determines the sort order, which can be `desc` or `asc`. in: query name: sort_order required: false @@ -12250,11 +13246,47 @@ paths: enum: - desc - asc + example: desc type: string responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + simpleListItems: + value: + data: + - _version: WzgsMV0= + comments: [] + created_at: '2025-01-07T21:12:25.512Z' + created_by: elastic + description: This is a sample exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - jupiter + - saturn + id: 459c5e7e-f8b2-4f0b-b136-c1fc702f72da + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0 + type: simple + updated_at: '2025-01-07T21:12:25.512Z' + updated_by: elastic + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -12282,6 +13314,12 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob''' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -12290,24 +13328,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_Exceptions_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/exception_lists/items/_find?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message: 'exception list list_id: "foo" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -12319,19 +13379,24 @@ paths: description: Get a summary of the specified exception list. operationId: ReadExceptionListSummary parameters: - - description: Exception list's identifier generated upon creation + - description: Exception list's identifier generated upon creation. in: query name: id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListId' - - description: Exception list's human readable identifier + - description: Exception list's human readable identifier. in: query name: list_id required: false schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -12342,11 +13407,19 @@ paths: name: filter required: false schema: + example: exception-list-agnostic.attributes.tags:"policy:policy-1" OR exception-list-agnostic.attributes.tags:"policy:all" type: string responses: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + summary: + value: + linux: 0 + macos: 0 + total: 0 + windows: 0 schema: type: object properties: @@ -12366,6 +13439,12 @@ paths: '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request query]: namespace_type.0: Invalid enum value. Expected ''agnostic'' | ''single'', received ''blob''' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -12374,24 +13453,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_Exceptions_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/exception_lists/summary?list_id=simple_list&namespace_type=agnostic] is unauthorized for user, this action is granted by the Kibana privileges [lists-summary] + statusCode: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '404': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -12409,6 +13510,15 @@ paths: content: application/json; Elastic-Api-Version=2023-10-31: schema: + example: + description: This is a sample detection type exception list. + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware type: object properties: description: @@ -12423,12 +13533,39 @@ paths: '200': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + sharedList: + value: + _version: WzIsMV0= + created_at: '2025-01-07T19:34:27.942Z' + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: '2025-01-07T19:34:27.942Z' + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionList' description: Successful response '400': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' @@ -12437,24 +13574,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_Exceptions_API_PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + forbidden: + value: + message: Unable to create exception-list + status_code: 403 schema: $ref: '#/components/schemas/Security_Exceptions_API_PlatformErrorResponse' description: Not enough privileges response '409': content: application/json; Elastic-Api-Version=2023-10-31: + examples: + alreadyExists: + value: + message: 'exception list id: "simple_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/Security_Exceptions_API_SiemErrorResponse' description: Exception 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_Exceptions_API_SiemErrorResponse' description: Internal server error response @@ -38390,11 +39548,14 @@ components: type: object properties: _version: + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. type: string created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListDescription' @@ -38415,13 +39576,16 @@ components: tags: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListTags' tie_breaker_id: + description: Field used in search to ensure all containers are sorted and returned correctly. type: string type: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string version: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListVersion' @@ -38440,31 +39604,42 @@ components: - updated_at - updated_by Security_Endpoint_Exceptions_API_ExceptionListDescription: + description: Describes the exception list. + example: This list tracks allowlisted values. type: string Security_Endpoint_Exceptions_API_ExceptionListHumanId: - $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' - description: Human readable string identifier, e.g. `trusted-linux-processes` + description: Exception list's human readable string identifier, e.g. `trusted-linux-processes`. + example: simple_list + format: nonempty + minLength: 1 + type: string Security_Endpoint_Exceptions_API_ExceptionListId: - $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' + description: Exception list's identifier. + example: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + format: nonempty + minLength: 1 + type: string Security_Endpoint_Exceptions_API_ExceptionListItem: type: object properties: _version: + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. type: string comments: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemCommentArray' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemDescription' entries: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemExpireTime' id: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemId' item_id: @@ -38482,13 +39657,16 @@ components: tags: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemTags' tie_breaker_id: + description: Field used in search to ensure all containers are sorted and returned correctly. type: string type: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string required: - id @@ -38511,6 +39689,7 @@ components: comment: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: @@ -38518,6 +39697,7 @@ components: id: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: @@ -38528,10 +39708,15 @@ components: - created_at - created_by Security_Endpoint_Exceptions_API_ExceptionListItemCommentArray: + description: | + Array of comment fields: + + - comment (string): Comments about the exception item. items: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListItemComment' type: array Security_Endpoint_Exceptions_API_ExceptionListItemDescription: + description: Describes the exception list. type: string Security_Endpoint_Exceptions_API_ExceptionListItemEntry: anyOf: @@ -38673,22 +39858,40 @@ components: - excluded - included type: string + Security_Endpoint_Exceptions_API_ExceptionListItemExpireTime: + description: The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. + format: date-time + type: string Security_Endpoint_Exceptions_API_ExceptionListItemHumanId: - $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' + description: Human readable string identifier, e.g. `trusted-linux-processes` + example: simple_list_item + format: nonempty + minLength: 1 + type: string Security_Endpoint_Exceptions_API_ExceptionListItemId: - $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' + description: Exception's identifier. + example: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + format: nonempty + minLength: 1 + type: string Security_Endpoint_Exceptions_API_ExceptionListItemMeta: additionalProperties: true type: object Security_Endpoint_Exceptions_API_ExceptionListItemName: - $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' + description: Exception list name. + format: nonempty + minLength: 1 + type: string Security_Endpoint_Exceptions_API_ExceptionListItemOsTypeArray: items: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListOsType' type: array Security_Endpoint_Exceptions_API_ExceptionListItemTags: items: - $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_NonEmptyString' + description: String array containing words and phrases to help categorize exception items. + format: nonempty + minLength: 1 + type: string type: array Security_Endpoint_Exceptions_API_ExceptionListItemType: enum: @@ -38696,24 +39899,31 @@ components: type: string Security_Endpoint_Exceptions_API_ExceptionListMeta: additionalProperties: true + description: Placeholder for metadata about the list container. type: object Security_Endpoint_Exceptions_API_ExceptionListName: + description: The name of the exception list. + example: My exception list type: string Security_Endpoint_Exceptions_API_ExceptionListOsType: + description: Use this field to specify the operating system. enum: - linux - macos - windows type: string Security_Endpoint_Exceptions_API_ExceptionListOsTypeArray: + description: Use this field to specify the operating system. Only enter one value. items: $ref: '#/components/schemas/Security_Endpoint_Exceptions_API_ExceptionListOsType' type: array Security_Endpoint_Exceptions_API_ExceptionListTags: + description: String array containing words and phrases to help categorize exception containers. items: type: string type: array Security_Endpoint_Exceptions_API_ExceptionListType: + description: The type of exception list to be created. Different list types may denote where they can be utilized. enum: - detection - rule_default @@ -38724,6 +39934,7 @@ components: - endpoint_blocklists type: string Security_Endpoint_Exceptions_API_ExceptionListVersion: + description: The document version, automatically increasd on updates. minimum: 1 type: integer Security_Endpoint_Exceptions_API_ExceptionNamespaceType: @@ -39835,11 +41046,14 @@ components: type: object properties: _version: + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. type: string created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListDescription' @@ -39860,13 +41074,16 @@ components: tags: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListTags' tie_breaker_id: + description: Field used in search to ensure all containers are sorted and returned correctly. type: string type: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string version: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListVersion' @@ -39885,31 +41102,42 @@ components: - updated_at - updated_by Security_Exceptions_API_ExceptionListDescription: + description: Describes the exception list. + example: This list tracks allowlisted values. type: string Security_Exceptions_API_ExceptionListHumanId: - $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' - description: Human readable string identifier, e.g. `trusted-linux-processes` + description: Exception list's human readable string identifier, e.g. `trusted-linux-processes`. + example: simple_list + format: nonempty + minLength: 1 + type: string Security_Exceptions_API_ExceptionListId: - $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' + description: Exception list's identifier. + example: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + format: nonempty + minLength: 1 + type: string Security_Exceptions_API_ExceptionListItem: type: object properties: _version: + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. type: string comments: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemCommentArray' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemDescription' entries: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemExpireTime' id: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemId' item_id: @@ -39927,13 +41155,16 @@ components: tags: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemTags' tie_breaker_id: + description: Field used in search to ensure all containers are sorted and returned correctly. type: string type: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string required: - id @@ -39956,6 +41187,7 @@ components: comment: $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: @@ -39963,6 +41195,7 @@ components: id: $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: @@ -39973,10 +41206,15 @@ components: - created_at - created_by Security_Exceptions_API_ExceptionListItemCommentArray: + description: | + Array of comment fields: + + - comment (string): Comments about the exception item. items: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListItemComment' type: array Security_Exceptions_API_ExceptionListItemDescription: + description: Describes the exception list. type: string Security_Exceptions_API_ExceptionListItemEntry: anyOf: @@ -40118,22 +41356,40 @@ components: - excluded - included type: string + Security_Exceptions_API_ExceptionListItemExpireTime: + description: The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. + format: date-time + type: string Security_Exceptions_API_ExceptionListItemHumanId: - $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' + description: Human readable string identifier, e.g. `trusted-linux-processes` + example: simple_list_item + format: nonempty + minLength: 1 + type: string Security_Exceptions_API_ExceptionListItemId: - $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' + description: Exception's identifier. + example: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + format: nonempty + minLength: 1 + type: string Security_Exceptions_API_ExceptionListItemMeta: additionalProperties: true type: object Security_Exceptions_API_ExceptionListItemName: - $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' + description: Exception list name. + format: nonempty + minLength: 1 + type: string Security_Exceptions_API_ExceptionListItemOsTypeArray: items: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListOsType' type: array Security_Exceptions_API_ExceptionListItemTags: items: - $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' + description: String array containing words and phrases to help categorize exception items. + format: nonempty + minLength: 1 + type: string type: array Security_Exceptions_API_ExceptionListItemType: enum: @@ -40141,16 +41397,21 @@ components: type: string Security_Exceptions_API_ExceptionListMeta: additionalProperties: true + description: Placeholder for metadata about the list container. type: object Security_Exceptions_API_ExceptionListName: + description: The name of the exception list. + example: My exception list type: string Security_Exceptions_API_ExceptionListOsType: + description: Use this field to specify the operating system. enum: - linux - macos - windows type: string Security_Exceptions_API_ExceptionListOsTypeArray: + description: Use this field to specify the operating system. Only enter one value. items: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListOsType' type: array @@ -40180,10 +41441,12 @@ components: $ref: '#/components/schemas/Security_Exceptions_API_ExceptionListsImportBulkError' type: array Security_Exceptions_API_ExceptionListTags: + description: String array containing words and phrases to help categorize exception containers. items: type: string type: array Security_Exceptions_API_ExceptionListType: + description: The type of exception list to be created. Different list types may denote where they can be utilized. enum: - detection - rule_default @@ -40194,6 +41457,7 @@ components: - endpoint_blocklists type: string Security_Exceptions_API_ExceptionListVersion: + description: The document version, automatically increasd on updates. minimum: 1 type: integer Security_Exceptions_API_ExceptionNamespaceType: @@ -40210,6 +41474,7 @@ components: Security_Exceptions_API_FindExceptionListItemsFilter: $ref: '#/components/schemas/Security_Exceptions_API_NonEmptyString' Security_Exceptions_API_FindExceptionListsFilter: + example: exception-list.attributes.name:%Detection%20List type: string Security_Exceptions_API_ListId: description: Value list's identifier. diff --git a/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml index 012447d48ad57..2b4a318d6f21c 100644 --- a/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/ess/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml @@ -464,11 +464,17 @@ components: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item was + retrieved. Use it ensure updates are done against the latest + version. type: string created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/ExceptionListDescription' @@ -489,13 +495,18 @@ components: tags: $ref: '#/components/schemas/ExceptionListTags' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. type: string type: $ref: '#/components/schemas/ExceptionListType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string version: $ref: '#/components/schemas/ExceptionListVersion' @@ -514,31 +525,47 @@ components: - updated_at - updated_by ExceptionListDescription: + description: Describes the exception list. + example: This list tracks allowlisted values. type: string ExceptionListHumanId: - $ref: '#/components/schemas/NonEmptyString' - description: 'Human readable string identifier, e.g. `trusted-linux-processes`' + description: >- + Exception list's human readable string identifier, e.g. + `trusted-linux-processes`. + example: simple_list + format: nonempty + minLength: 1 + type: string ExceptionListId: - $ref: '#/components/schemas/NonEmptyString' + description: Exception list's identifier. + example: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + format: nonempty + minLength: 1 + type: string ExceptionListItem: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item was + retrieved. Use it ensure updates are done against the latest + version. type: string comments: $ref: '#/components/schemas/ExceptionListItemCommentArray' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/ExceptionListItemDescription' entries: $ref: '#/components/schemas/ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/ExceptionListItemExpireTime' id: $ref: '#/components/schemas/ExceptionListItemId' item_id: @@ -556,13 +583,18 @@ components: tags: $ref: '#/components/schemas/ExceptionListItemTags' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. type: string type: $ref: '#/components/schemas/ExceptionListItemType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string required: - id @@ -585,6 +617,7 @@ components: comment: $ref: '#/components/schemas/NonEmptyString' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: @@ -592,6 +625,7 @@ components: id: $ref: '#/components/schemas/NonEmptyString' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: @@ -602,10 +636,15 @@ components: - created_at - created_by ExceptionListItemCommentArray: + description: | + Array of comment fields: + + - comment (string): Comments about the exception item. items: $ref: '#/components/schemas/ExceptionListItemComment' type: array ExceptionListItemDescription: + description: Describes the exception list. type: string ExceptionListItemEntry: anyOf: @@ -747,22 +786,44 @@ components: - excluded - included type: string + ExceptionListItemExpireTime: + description: >- + The exception item’s expiration date, in ISO format. This field is only + available for regular exception items, not endpoint exceptions. + format: date-time + type: string ExceptionListItemHumanId: - $ref: '#/components/schemas/NonEmptyString' + description: 'Human readable string identifier, e.g. `trusted-linux-processes`' + example: simple_list_item + format: nonempty + minLength: 1 + type: string ExceptionListItemId: - $ref: '#/components/schemas/NonEmptyString' + description: Exception's identifier. + example: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + format: nonempty + minLength: 1 + type: string ExceptionListItemMeta: additionalProperties: true type: object ExceptionListItemName: - $ref: '#/components/schemas/NonEmptyString' + description: Exception list name. + format: nonempty + minLength: 1 + type: string ExceptionListItemOsTypeArray: items: $ref: '#/components/schemas/ExceptionListOsType' type: array ExceptionListItemTags: items: - $ref: '#/components/schemas/NonEmptyString' + description: >- + String array containing words and phrases to help categorize exception + items. + format: nonempty + minLength: 1 + type: string type: array ExceptionListItemType: enum: @@ -770,24 +831,35 @@ components: type: string ExceptionListMeta: additionalProperties: true + description: Placeholder for metadata about the list container. type: object ExceptionListName: + description: The name of the exception list. + example: My exception list type: string ExceptionListOsType: + description: Use this field to specify the operating system. enum: - linux - macos - windows type: string ExceptionListOsTypeArray: + description: Use this field to specify the operating system. Only enter one value. items: $ref: '#/components/schemas/ExceptionListOsType' type: array ExceptionListTags: + description: >- + String array containing words and phrases to help categorize exception + containers. items: type: string type: array ExceptionListType: + description: >- + The type of exception list to be created. Different list types may + denote where they can be utilized. enum: - detection - rule_default @@ -798,6 +870,7 @@ components: - endpoint_blocklists type: string ExceptionListVersion: + description: 'The document version, automatically increasd on updates.' minimum: 1 type: integer ExceptionNamespaceType: diff --git a/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml index 668fc81f545ba..ec6009a8222fb 100644 --- a/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-endpoint-exceptions-common/docs/openapi/serverless/security_solution_endpoint_exceptions_api_2023_10_31.bundled.schema.yaml @@ -464,11 +464,17 @@ components: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item was + retrieved. Use it ensure updates are done against the latest + version. type: string created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/ExceptionListDescription' @@ -489,13 +495,18 @@ components: tags: $ref: '#/components/schemas/ExceptionListTags' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. type: string type: $ref: '#/components/schemas/ExceptionListType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string version: $ref: '#/components/schemas/ExceptionListVersion' @@ -514,31 +525,47 @@ components: - updated_at - updated_by ExceptionListDescription: + description: Describes the exception list. + example: This list tracks allowlisted values. type: string ExceptionListHumanId: - $ref: '#/components/schemas/NonEmptyString' - description: 'Human readable string identifier, e.g. `trusted-linux-processes`' + description: >- + Exception list's human readable string identifier, e.g. + `trusted-linux-processes`. + example: simple_list + format: nonempty + minLength: 1 + type: string ExceptionListId: - $ref: '#/components/schemas/NonEmptyString' + description: Exception list's identifier. + example: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + format: nonempty + minLength: 1 + type: string ExceptionListItem: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item was + retrieved. Use it ensure updates are done against the latest + version. type: string comments: $ref: '#/components/schemas/ExceptionListItemCommentArray' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/ExceptionListItemDescription' entries: $ref: '#/components/schemas/ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/ExceptionListItemExpireTime' id: $ref: '#/components/schemas/ExceptionListItemId' item_id: @@ -556,13 +583,18 @@ components: tags: $ref: '#/components/schemas/ExceptionListItemTags' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. type: string type: $ref: '#/components/schemas/ExceptionListItemType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string required: - id @@ -585,6 +617,7 @@ components: comment: $ref: '#/components/schemas/NonEmptyString' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: @@ -592,6 +625,7 @@ components: id: $ref: '#/components/schemas/NonEmptyString' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: @@ -602,10 +636,15 @@ components: - created_at - created_by ExceptionListItemCommentArray: + description: | + Array of comment fields: + + - comment (string): Comments about the exception item. items: $ref: '#/components/schemas/ExceptionListItemComment' type: array ExceptionListItemDescription: + description: Describes the exception list. type: string ExceptionListItemEntry: anyOf: @@ -747,22 +786,44 @@ components: - excluded - included type: string + ExceptionListItemExpireTime: + description: >- + The exception item’s expiration date, in ISO format. This field is only + available for regular exception items, not endpoint exceptions. + format: date-time + type: string ExceptionListItemHumanId: - $ref: '#/components/schemas/NonEmptyString' + description: 'Human readable string identifier, e.g. `trusted-linux-processes`' + example: simple_list_item + format: nonempty + minLength: 1 + type: string ExceptionListItemId: - $ref: '#/components/schemas/NonEmptyString' + description: Exception's identifier. + example: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + format: nonempty + minLength: 1 + type: string ExceptionListItemMeta: additionalProperties: true type: object ExceptionListItemName: - $ref: '#/components/schemas/NonEmptyString' + description: Exception list name. + format: nonempty + minLength: 1 + type: string ExceptionListItemOsTypeArray: items: $ref: '#/components/schemas/ExceptionListOsType' type: array ExceptionListItemTags: items: - $ref: '#/components/schemas/NonEmptyString' + description: >- + String array containing words and phrases to help categorize exception + items. + format: nonempty + minLength: 1 + type: string type: array ExceptionListItemType: enum: @@ -770,24 +831,35 @@ components: type: string ExceptionListMeta: additionalProperties: true + description: Placeholder for metadata about the list container. type: object ExceptionListName: + description: The name of the exception list. + example: My exception list type: string ExceptionListOsType: + description: Use this field to specify the operating system. enum: - linux - macos - windows type: string ExceptionListOsTypeArray: + description: Use this field to specify the operating system. Only enter one value. items: $ref: '#/components/schemas/ExceptionListOsType' type: array ExceptionListTags: + description: >- + String array containing words and phrases to help categorize exception + containers. items: type: string type: array ExceptionListType: + description: >- + The type of exception list to be created. Different list types may + denote where they can be utilized. enum: - detection - rule_default @@ -798,6 +870,7 @@ components: - endpoint_blocklists type: string ExceptionListVersion: + description: 'The document version, automatically increasd on updates.' minimum: 1 type: integer ExceptionNamespaceType: diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml index 5925d0bd923c0..28e98f91aa39d 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/create_exception_list/create_exception_list.schema.yaml @@ -10,7 +10,7 @@ paths: x-codegen-enabled: true summary: Create an exception list description: | - An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists. + An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules. > info > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item. requestBody: @@ -20,6 +20,14 @@ paths: application/json: schema: type: object + example: + list_id: simple_list + type: detection + name: Sample Detection Exception List + description: This is a sample detection type exception list. + namespace_type: single + tags: [malware] + os_types: [linux] properties: list_id: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId' @@ -53,6 +61,79 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionList' + examples: + typeDetection: + value: + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + list_id: simple_list + type: detection + name: Sample Detection Exception List + description: This is a sample detection type exception list. + immutable: false + namespace_type: single + os_types: [linux] + tags: [malware] + version: 1 + _version: WzIsMV0= + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + typeEndpoint: + value: + id: a79f4730-6e32-4278-abfc-349c0add7d54 + list_id: endpoint_list + type: endpoint + name: Sample Endpoint Exception List + description: This is a sample endpoint type exception list. + immutable: false + namespace_type: single + os_types: [linux] + tags: [malware] + version: 1 + _version: WzQsMV0= + tie_breaker_id: 94a028af-8f47-427a-aca5-ffaf829e64ee + created_at: 2025-01-09T01:07:49.658Z + created_by: elastic + updated_at: 2025-01-09T01:07:49.658Z + updated_by: elastic + namespaceAgnostic: + value: + id: 1a744e77-22ca-4b6b-9085-54f55275ebe5 + list_id: b935eb55-7b21-4c1c-b235-faa1df23b3d6 + type: endpoint + name: Sample Agnostic Endpoint Exception List + description: This is a sample agnostic endpoint type exception. + immutable: false + namespace_type: agnostic + os_types: [linux] + tags: [malware] + version: 1 + _version: WzUsMV0= + tie_breaker_id: 49ea0adc-a2b8-4d83-a8f3-2fb98301dea3 + created_at: 2025-01-09T01:10:36.369Z + created_by: elastic + updated_at: 2025-01-09T01:10:36.369Z + updated_by: elastic + autogeneratedListId: + value: + id: 28243c2f-624a-4443-823d-c0b894880931 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + type: detection + name: Sample Detection Exception List + description: This is a sample detection type exception with an autogenerated list_id. + immutable: false + namespace_type: single + os_types: [] + tags: [malware] + version: 1 + _version: WzMsMV0= + tie_breaker_id: ad94de31-39f7-4ad7-b8e4-988bfa95f338 + created_at: 2025-01-09T01:05:23.019Z + created_by: elastic + updated_at: 2025-01-09T01:05:23.020Z + updated_by: elastic 400: description: Invalid input data response content: @@ -61,27 +142,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: list_id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]" 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 409: description: Exception list already exists response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + alreadyExists: + value: + message: 'exception list id: "simple_list" already exists' + status_code: 409 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.gen.ts index 9adf64b6b083f..3e64efee48a05 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.gen.ts @@ -29,6 +29,7 @@ import { ExceptionListItemOsTypeArray, ExceptionListItemTags, ExceptionListItemMeta, + ExceptionListItemExpireTime, ExceptionListItem, } from '../model/exception_list_common.gen'; import { ExceptionListItemEntryArray } from '../model/exception_list_item_entry.gen'; @@ -55,7 +56,7 @@ export const CreateExceptionListItemRequestBody = z.object({ os_types: ExceptionListItemOsTypeArray.optional().default([]), tags: ExceptionListItemTags.optional().default([]), meta: ExceptionListItemMeta.optional(), - expire_time: z.string().datetime().optional(), + expire_time: ExceptionListItemExpireTime.optional(), comments: CreateExceptionListItemCommentArray.optional().default([]), }); export type CreateExceptionListItemRequestBodyInput = z.input< diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml index 47fa2895d27c6..76a7c20924479 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/create_exception_list_item/create_exception_list_item.schema.yaml @@ -20,6 +20,23 @@ paths: application/json: schema: type: object + example: + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + - type: match_any + field: host.name + value: [saturn, jupiter] + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] properties: item_id: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemHumanId' @@ -45,8 +62,7 @@ paths: meta: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemMeta' expire_time: - type: string - format: date-time + $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemExpireTime' comments: $ref: '#/components/schemas/CreateExceptionListItemCommentArray' default: [] @@ -63,6 +79,174 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItem' + examples: + detectionExceptionListItem: + value: + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzQsMV0= + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + autogeneratedItemId: + value: + id: 323faa75-c657-4fa0-9084-8827612c207b + item_id: 80e6edf7-4b13-4414-858f-2fa74aa52b37 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + type: simple + name: Sample Autogenerated Exception List Item ID + description: This is a sample exception that has no item_id so it is autogenerated. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + namespace_type: single + os_types: [] + tags: [malware] + comments: [] + _version: WzYsMV0= + tie_breaker_id: d6799986-3a23-4213-bc6d-ed9463a32f23 + created_at: 2025-01-09T01:16:23.322Z + created_by: elastic + updated_at: 2025-01-09T01:16:23.322Z + updated_by: elastic + withMatchAnyEntry: + value: + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: match_any + field: host.name + value: [saturn, jupiter] + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzQsMV0= + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withMatchEntry: + value: + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: match + field: actingProcess.file.signer + value: Elastic N.V. + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzQsMV0= + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withNestedEntry: + value: + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: nested + field: file.signature + entries: + - type: match + field: signer + value: Evil + operator: included + - type: match + field: trusted + value: true + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzQsMV0= + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withExistEntry: + value: + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzQsMV0= + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withValueListEntry: + value: + id: deb26876-297d-4677-8a1f-35467d2f1c4f + item_id: 686b129e-9b8d-4c59-8d8d-c93a9ea82c71 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + type: simple + name: Filter out good guys ip and agent.name rock01 + description: Don't signal when agent.name is rock01 and source.ip is in the goodguys.txt list + entries: + - type: list + field: source.ip + list: + id: goodguys.txt + type: ip + operator: excluded + namespace_type: single + os_types: [] + tags: [malware] + comments: [] + _version: WzcsMV0= + tie_breaker_id: 5e0288ce-6657-4c18-9dcc-00ec9e8cc6c8 + created_at: 2025-01-09T01:31:12.614Z + created_by: elastic + updated_at: 2025-01-09T01:31:12.614Z + updated_by: elastic 400: description: Invalid input data response content: @@ -71,30 +255,58 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400, + error: Bad Request, + message: '[request body]: list_id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/exception_lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 409: description: Exception list item already exists response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + alreadyExists: + value: + message: 'exception list item id: \"simple_list_item\" already exists' + status_code: 409 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: x-codegen-enabled: true diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.gen.ts index 77437ff51618c..7040907f4976d 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.gen.ts @@ -12,7 +12,7 @@ * This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator. * * info: - * title: Create rule exception list items API endpoint + * title: Create rule exception items API endpoint * version: 2023-10-31 */ diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml index 6162d00d78ae8..cad7710ad74fd 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/create_rule_exceptions/create_rule_exceptions.schema.yaml @@ -1,6 +1,6 @@ openapi: 3.0.0 info: - title: Create rule exception list items API endpoint + title: Create rule exception items API endpoint version: '2023-10-31' paths: /api/detection_engine/rules/{id}/exceptions: @@ -8,8 +8,8 @@ paths: x-labels: [serverless, ess] operationId: CreateRuleExceptionListItems x-codegen-enabled: true - summary: Create rule exception list items - description: Create exception items that apply to a single detection rule. + summary: Create rule exception items + description: Create exception items that apply to a single detection rule. parameters: - name: id in: path @@ -17,8 +17,11 @@ paths: description: Detection rule's identifier schema: $ref: '#/components/schemas/RuleId' + examples: + id: + value: 330bdd28-eedf-40e1-bed0-f10176c7f9e0 requestBody: - description: Rule exception list items + description: Rule exception items. required: true content: application/json: @@ -30,6 +33,24 @@ paths: items: $ref: '#/components/schemas/CreateRuleExceptionListItemProps' required: [items] + example: + items: + - item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + - type: match_any + field: host.name + value: [saturn, jupiter] + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] responses: 200: description: Successful response @@ -39,6 +60,33 @@ paths: type: array items: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItem' + examples: + ruleExceptionItems: + value: + - id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + - type: match_any + field: host.name + value: [saturn, jupiter] + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzQsMV0= + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic 400: description: Invalid input data response content: @@ -47,24 +95,51 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request params]: id: Invalid uuid' + badPayload: + value: + statusCode: 400 + error: Bad Request + message: 'Invalid request payload JSON format' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + message: 'Unable to create exception-list' + status_code: 403 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: schemas: diff --git a/packages/kbn-securitysolution-exceptions-common/api/create_shared_exceptions_list/create_shared_exceptions_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/create_shared_exceptions_list/create_shared_exceptions_list.schema.yaml index c4cee089e5836..065580534a0a0 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/create_shared_exceptions_list/create_shared_exceptions_list.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/create_shared_exceptions_list/create_shared_exceptions_list.schema.yaml @@ -27,6 +27,13 @@ paths: required: - name - description + example: + list_id: simple_list + name: Sample Detection Exception List + description: This is a sample detection type exception list. + namespace_type: single + tags: [malware] + os_types: [linux] responses: 200: description: Successful response @@ -34,6 +41,25 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionList' + examples: + sharedList: + value: + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + list_id: simple_list + type: detection + name: Sample Detection Exception List + description: This is a sample detection type exception list. + immutable: false + namespace_type: single + os_types: [linux] + tags: [malware] + version: 1 + _version: WzIsMV0= + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic 400: description: Invalid input data response content: @@ -42,27 +68,54 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: list_id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]" 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + message: 'Unable to create exception-list' + status_code: 403 409: description: Exception list already exists response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + alreadyExists: + value: + message: 'exception list id: "simple_list" already exists' + status_code: 409 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.gen.ts index a12512aab1374..6c7014a80ac55 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.gen.ts @@ -28,11 +28,11 @@ import { export type DeleteExceptionListRequestQuery = z.infer; export const DeleteExceptionListRequestQuery = z.object({ /** - * Either `id` or `list_id` must be specified + * Exception list's identifier. Either `id` or `list_id` must be specified. */ id: ExceptionListId.optional(), /** - * Either `id` or `list_id` must be specified + * Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified. */ list_id: ExceptionListHumanId.optional(), namespace_type: ExceptionNamespaceType.optional().default('single'), diff --git a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml index 92afc3232efee..4708df543546b 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list/delete_exception_list.schema.yaml @@ -14,21 +14,31 @@ paths: - name: id in: query required: false - description: Either `id` or `list_id` must be specified + description: Exception list's identifier. Either `id` or `list_id` must be specified. schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListId' - name: list_id in: query required: false - description: Either `id` or `list_id` must be specified + description: Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified. schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId' + examples: + list_id: + value: simple_list + autogeneratedId: + value: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 - name: namespace_type in: query required: false schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' default: single + examples: + single: + value: single + agnostic: + value: agnostic responses: 200: description: Successful response @@ -36,6 +46,25 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionList' + examples: + detectionExceptionList: + value: + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + list_id: simple_list + type: detection + name: Sample Detection Exception List + description: This is a sample detection type exception list. + immutable: false + namespace_type: single + os_types: [linux] + tags: [malware] + version: 1 + _version: WzIsMV0= + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic 400: description: Invalid input data response content: @@ -44,27 +73,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'" 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [DELETE /api/exception_lists?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: Exception list not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'exception list list_id: "foo" does not exist' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.gen.ts index a93af0cf3d4c2..654a6c1d55dec 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.gen.ts @@ -30,11 +30,11 @@ export type DeleteExceptionListItemRequestQuery = z.infer< >; export const DeleteExceptionListItemRequestQuery = z.object({ /** - * Either `id` or `item_id` must be specified + * Exception item's identifier. Either `id` or `item_id` must be specified */ id: ExceptionListItemId.optional(), /** - * Either `id` or `item_id` must be specified + * Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified */ item_id: ExceptionListItemHumanId.optional(), namespace_type: ExceptionNamespaceType.optional().default('single'), diff --git a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml index 9f57afcd5ab1c..c38ed4dea41bf 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/delete_exception_list_item/delete_exception_list_item.schema.yaml @@ -14,13 +14,13 @@ paths: - name: id in: query required: false - description: Either `id` or `item_id` must be specified + description: Exception item's identifier. Either `id` or `item_id` must be specified schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemId' - name: item_id in: query required: false - description: Either `id` or `item_id` must be specified + description: Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemHumanId' - name: namespace_type @@ -29,6 +29,11 @@ paths: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' default: single + examples: + single: + value: single + agnostic: + value: agnostic responses: 200: description: Successful response @@ -36,6 +41,33 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItem' + examples: + simpleExceptionItem: + value: + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + - type: match_any + field: host.name + value: [saturn, jupiter] + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzQsMV0= + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic 400: description: Invalid input data response content: @@ -44,27 +76,53 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + example: + statusCode: 400 + error: Bad Request + message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'" 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [DELETE /api/exception_lists/items?item_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: Exception list item not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.gen.ts index 61de17abe06f8..3f30edfdfa72a 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.gen.ts @@ -26,13 +26,10 @@ import { export type DuplicateExceptionListRequestQuery = z.infer; export const DuplicateExceptionListRequestQuery = z.object({ - /** - * Exception list's human identifier - */ list_id: ExceptionListHumanId, namespace_type: ExceptionNamespaceType, /** - * Determines whether to include expired exceptions in the exported list + * Determines whether to include expired exceptions in the duplicated list. Expiration date defined by `expire_time`. */ include_expired_exceptions: z.enum(['true', 'false']).default('true'), }); diff --git a/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml index 758171327ee4c..87c1a55a920ec 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/duplicate_exception_list/duplicate_exception_list.schema.yaml @@ -14,7 +14,6 @@ paths: - name: list_id in: query required: true - description: Exception list's human identifier schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId' - name: namespace_type @@ -22,14 +21,20 @@ paths: required: true schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' + examples: + single: + value: single + agnostic: + value: agnostic - name: include_expired_exceptions in: query required: true - description: Determines whether to include expired exceptions in the exported list + description: Determines whether to include expired exceptions in the duplicated list. Expiration date defined by `expire_time`. schema: type: string enum: ['true', 'false'] default: 'true' + example: true responses: 200: description: Successful response @@ -37,6 +42,25 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionList' + examples: + detectionExceptionList: + value: + id: b2f4a715-6ab1-444c-8b1e-3fa1b1049429 + list_id: d6390d60-bce3-4a48-9002-52db600f329c + type: detection + name: Sample Detection Exception List [Duplicate] + description: This is a sample detection type exception + immutable: false + namespace_type: single + os_types: [] + tags: [malware] + version: 1 + _version: WzExNDY1LDFd + tie_breaker_id: 6fa670bd-666d-4c9c-9f1e-d1dbc516e985 + created_at: 2025-01-09T16:19:50.280Z + created_by: elastic + updated_at: 2025-01-09T16:19:50.280Z + updated_by: elastic 400: description: Invalid input data response content: @@ -45,18 +69,47 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: "[request query]: namespace_type: Invalid enum value. Expected 'agnostic' | 'single', received 'foo'" 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/exception_lists/_duplicate] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' + 404: + description: Exception list not found + content: + application/json: + schema: + $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 405: description: Exception list to duplicate not found response content: @@ -69,3 +122,8 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.gen.ts index 9645b8ac793cb..a390003fceb99 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.gen.ts @@ -26,17 +26,11 @@ import { export type ExportExceptionListRequestQuery = z.infer; export const ExportExceptionListRequestQuery = z.object({ - /** - * Exception list's identifier - */ id: ExceptionListId, - /** - * Exception list's human identifier - */ list_id: ExceptionListHumanId, namespace_type: ExceptionNamespaceType, /** - * Determines whether to include expired exceptions in the exported list + * Determines whether to include expired exceptions in the exported list. Expiration date defined by `expire_time`. */ include_expired_exceptions: z.enum(['true', 'false']).default('true'), }); diff --git a/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml index 3232f46c238c8..24c025cbcf347 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/export_exception_list/export_exception_list.schema.yaml @@ -14,13 +14,11 @@ paths: - name: id in: query required: true - description: Exception list's identifier schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListId' - name: list_id in: query required: true - description: Exception list's human identifier schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId' - name: namespace_type @@ -28,14 +26,20 @@ paths: required: true schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' + examples: + single: + value: single + agnostic: + value: agnostic - name: include_expired_exceptions in: query required: true - description: Determines whether to include expired exceptions in the exported list + description: Determines whether to include expired exceptions in the exported list. Expiration date defined by `expire_time`. schema: type: string enum: ['true', 'false'] default: 'true' + example: true responses: 200: description: Successful response @@ -45,6 +49,12 @@ paths: type: string format: binary description: A `.ndjson` file containing specified exception list and its items + examples: + exportSavedObjectsResponse: + value: | + {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This is a sample detection type exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample Detection Exception List","namespace_type":"single","os_types":[],"tags":["user added string for a tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1} + {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This is a sample endpoint type exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some host","another host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample Endpoint Exception List","namespace_type":"single","os_types":["linux"],"tags":["user added string for a tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"} + {"exported_exception_list_count":1,"exported_exception_list_item_count":1,"missing_exception_list_item_count":0,"missing_exception_list_items":[],"missing_exception_lists":[],"missing_exception_lists_count":0} 400: description: Invalid input data response content: @@ -53,27 +63,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request query]: list_id: Required, namespace_type: Required' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/exception_lists/_export] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: Exception list not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.gen.ts index 99ed1b3a31ddc..d86622bccc3f8 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.gen.ts @@ -32,7 +32,7 @@ export const FindExceptionListItemsFilter = NonEmptyString; export type FindExceptionListItemsRequestQuery = z.infer; export const FindExceptionListItemsRequestQuery = z.object({ /** - * List's id + * The `list_id`s of the items to fetch. */ list_id: ArrayFromString(ExceptionListHumanId), /** @@ -57,11 +57,11 @@ or available in all spaces (`agnostic` or `single`) */ per_page: z.coerce.number().int().min(0).optional(), /** - * Determines which field is used to sort the results + * Determines which field is used to sort the results. */ sort_field: NonEmptyString.optional(), /** - * Determines the sort order, which can be `desc` or `asc` + * Determines the sort order, which can be `desc` or `asc`. */ sort_order: z.enum(['desc', 'asc']).optional(), }); diff --git a/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml index e40f780af03ef..a4afbc23bbdbe 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/find_exception_list_items/find_exception_list_items.schema.yaml @@ -14,7 +14,7 @@ paths: - name: list_id in: query required: true - description: List's id + description: The `list_id`s of the items to fetch. schema: type: array items: @@ -30,6 +30,9 @@ paths: items: $ref: '#/components/schemas/FindExceptionListItemsFilter' default: [] + examples: + singleFilter: + value: [exception-list.attributes.name:%My%20item] - name: namespace_type in: query required: false @@ -41,11 +44,15 @@ paths: items: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' default: [single] + examples: + single: + value: [single] - name: search in: query required: false schema: type: string + example: host.name - name: page in: query required: false @@ -53,6 +60,7 @@ paths: schema: type: integer minimum: 0 + example: 1 - name: per_page in: query required: false @@ -60,19 +68,22 @@ paths: schema: type: integer minimum: 0 + example: 20 - name: sort_field in: query required: false - description: Determines which field is used to sort the results + description: Determines which field is used to sort the results. schema: $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + example: 'name' - name: sort_order in: query required: false - description: Determines the sort order, which can be `desc` or `asc` + description: Determines the sort order, which can be `desc` or `asc`. schema: type: string enum: [desc, asc] + example: desc responses: 200: description: Successful response @@ -101,6 +112,37 @@ paths: - page - per_page - total + examples: + simpleListItems: + value: + data: + - id: 459c5e7e-f8b2-4f0b-b136-c1fc702f72da + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample exception item. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + - type: match_any + field: host.name + value: [jupiter, saturn] + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzgsMV0= + tie_breaker_id: ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0 + created_at: 2025-01-07T21:12:25.512Z + created_by: elastic + updated_at: 2025-01-07T21:12:25.512Z + updated_by: elastic + page: 1 + per_page: 20 + total: 1 400: description: Invalid input data response content: @@ -109,30 +151,58 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'" 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/exception_lists/items/_find?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 404: description: Exception list not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'exception list list_id: "foo" does not exist' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: schemas: diff --git a/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.gen.ts index 83a68b4232e8b..27491cacc986b 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.gen.ts @@ -51,11 +51,11 @@ or available in all spaces (`agnostic` or `single`) */ per_page: z.coerce.number().int().min(1).optional(), /** - * Determines which field is used to sort the results + * Determines which field is used to sort the results. */ sort_field: z.string().optional(), /** - * Determines the sort order, which can be `desc` or `asc` + * Determines the sort order, which can be `desc` or `asc`. */ sort_order: z.enum(['desc', 'asc']).optional(), }); diff --git a/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.schema.yaml index c46dacbab01d0..3d75ccb392c0c 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/find_exception_lists/find_exception_lists.schema.yaml @@ -9,7 +9,7 @@ paths: operationId: FindExceptionLists x-codegen-enabled: true summary: Get exception lists - description: Get a list of all exception lists. + description: Get a list of all exception list containers. parameters: - name: filter in: query @@ -34,6 +34,11 @@ paths: items: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' default: [single] + examples: + single: + value: single + agnostic: + value: agnostic - name: page in: query required: false @@ -41,6 +46,7 @@ paths: schema: type: integer minimum: 1 + example: 1 - name: per_page in: query required: false @@ -48,19 +54,22 @@ paths: schema: type: integer minimum: 1 + 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: type: string + example: 'name' - name: sort_order in: query required: false - description: Determines the sort order, which can be `desc` or `asc` + description: Determines the sort order, which can be `desc` or `asc`. schema: type: string enum: [desc, asc] + example: 'desc' responses: 200: description: Successful response @@ -87,6 +96,29 @@ paths: - page - per_page - total + examples: + simpleLists: + value: + data: + - id: '9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85' + list_id: 'simple_list' + type: 'detection' + name: 'Detection Exception List' + description: 'This is a sample detection type exception list.' + immutable: false + namespace_type: 'single' + os_types: [] + tags: ['malware'] + version: 1 + _version: 'WzIsMV0=' + tie_breaker_id: '78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3' + created_at: 2025-01-07T19:34:27.942Z + created_by: 'elastic' + updated_at: 2025-01-07T19:34:27.942Z + updated_by: 'elastic' + page: 1 + per_page: 20 + total: 1 400: description: Invalid input data response content: @@ -95,26 +127,50 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'" 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/exception_lists/_find?namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: schemas: FindExceptionListsFilter: type: string + example: exception-list.attributes.name:%Detection%20List diff --git a/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.gen.ts index ea24803e79456..447ab21bab9b7 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.gen.ts @@ -47,8 +47,6 @@ If any exception items have the same `item_id`, those are also overwritten. */ overwrite: BooleanFromString.optional().default(false), - overwrite_exceptions: BooleanFromString.optional().default(false), - overwrite_action_connectors: BooleanFromString.optional().default(false), /** * Determines whether the list being imported will have a new `list_id` generated. Additional `item_id`'s are generated for each exception item. Both the exception diff --git a/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml index 8ae3ac1aa2c0c..0e5da5455dbd5 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/import_exceptions/import_exceptions.schema.yaml @@ -21,6 +21,9 @@ paths: type: string format: binary description: A `.ndjson` file containing the exception list + example: | + {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This is a sample detection type exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample Detection Exception List","namespace_type":"single","os_types":[],"tags":["user added string for a tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1} + {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This is a sample endpoint type exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some host","another host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample Endpoint Exception List","namespace_type":"single","os_types":["linux"],"tags":["user added string for a tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"} parameters: - name: overwrite in: query @@ -31,18 +34,7 @@ paths: schema: type: boolean default: false - - name: overwrite_exceptions - in: query - required: false - schema: - type: boolean - default: false - - name: overwrite_action_connectors - in: query - required: false - schema: - type: boolean - default: false + example: false - name: as_new_list in: query required: false @@ -53,6 +45,7 @@ paths: schema: type: boolean default: false + example: false responses: 200: description: Successful response @@ -86,6 +79,34 @@ paths: - success_count_exception_lists - success_exception_list_items - success_count_exception_list_items + examples: + withoutErrors: + value: + errors: [] + success: true + success_count: 2 + success_exception_lists: true, + success_count_exception_lists: 1 + success_exception_list_items: true + success_count_exception_list_items: 1 + withErrors: + value: + errors: + - error: + status_code: 400 + message: 'Error found importing exception list: Invalid value \"4\" supplied to \"list_id\"' + list_id: (unknown list_id) + - error: + status_code: 409 + message: 'Found that item_id: \"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\" already exists. Import of item_id: \"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\" skipped.' + list_id: 7d7cccb8-db72-4667-b1f3-648efad7c1ee + item_id: f7fd00bb-dba8-4c93-9d59-6cbd427b6330 + success: false, + success_count: 0, + success_exception_lists: false, + success_count_exception_lists: 0, + success_exception_list_items: false, + success_count_exception_list_items: 0 400: description: Invalid input data response content: @@ -100,18 +121,35 @@ paths: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [POST /api/exception_lists/_import] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: schemas: diff --git a/packages/kbn-securitysolution-exceptions-common/api/model/exception_list_common.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/model/exception_list_common.gen.ts index 1f2d9e7387da3..20bfdfa28ef51 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/model/exception_list_common.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/model/exception_list_common.gen.ts @@ -17,19 +17,26 @@ */ import { z } from '@kbn/zod'; +import { isNonEmptyString } from '@kbn/zod-helpers'; import { NonEmptyString } from '@kbn/openapi-common/schemas/primitives.gen'; import { ExceptionListItemEntryArray } from './exception_list_item_entry.gen'; +/** + * Exception list's identifier. + */ export type ExceptionListId = z.infer; -export const ExceptionListId = NonEmptyString; +export const ExceptionListId = z.string().min(1).superRefine(isNonEmptyString); /** - * Human readable string identifier, e.g. `trusted-linux-processes` + * Exception list's human readable string identifier, e.g. `trusted-linux-processes`. */ export type ExceptionListHumanId = z.infer; -export const ExceptionListHumanId = NonEmptyString; +export const ExceptionListHumanId = z.string().min(1).superRefine(isNonEmptyString); +/** + * The type of exception list to be created. Different list types may denote where they can be utilized. + */ export type ExceptionListType = z.infer; export const ExceptionListType = z.enum([ 'detection', @@ -43,12 +50,21 @@ export const ExceptionListType = z.enum([ export type ExceptionListTypeEnum = typeof ExceptionListType.enum; export const ExceptionListTypeEnum = ExceptionListType.enum; +/** + * The name of the exception list. + */ export type ExceptionListName = z.infer; export const ExceptionListName = z.string(); +/** + * Describes the exception list. + */ export type ExceptionListDescription = z.infer; export const ExceptionListDescription = z.string(); +/** + * Placeholder for metadata about the list container. + */ export type ExceptionListMeta = z.infer; export const ExceptionListMeta = z.object({}).catchall(z.unknown()); @@ -65,17 +81,29 @@ export const ExceptionNamespaceType = z.enum(['agnostic', 'single']); export type ExceptionNamespaceTypeEnum = typeof ExceptionNamespaceType.enum; export const ExceptionNamespaceTypeEnum = ExceptionNamespaceType.enum; +/** + * String array containing words and phrases to help categorize exception containers. + */ export type ExceptionListTags = z.infer; export const ExceptionListTags = z.array(z.string()); +/** + * Use this field to specify the operating system. + */ export type ExceptionListOsType = z.infer; export const ExceptionListOsType = z.enum(['linux', 'macos', 'windows']); export type ExceptionListOsTypeEnum = typeof ExceptionListOsType.enum; export const ExceptionListOsTypeEnum = ExceptionListOsType.enum; +/** + * Use this field to specify the operating system. Only enter one value. + */ export type ExceptionListOsTypeArray = z.infer; export const ExceptionListOsTypeArray = z.array(ExceptionListOsType); +/** + * The document version, automatically increasd on updates. + */ export type ExceptionListVersion = z.infer; export const ExceptionListVersion = z.number().int().min(1); @@ -92,34 +120,70 @@ export const ExceptionList = z.object({ tags: ExceptionListTags.optional(), meta: ExceptionListMeta.optional(), version: ExceptionListVersion, + /** + * The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. + */ _version: z.string().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(), }); +/** + * Exception's identifier. + */ export type ExceptionListItemId = z.infer; -export const ExceptionListItemId = NonEmptyString; +export const ExceptionListItemId = z.string().min(1).superRefine(isNonEmptyString); +/** + * Human readable string identifier, e.g. `trusted-linux-processes` + */ export type ExceptionListItemHumanId = z.infer; -export const ExceptionListItemHumanId = NonEmptyString; +export const ExceptionListItemHumanId = z.string().min(1).superRefine(isNonEmptyString); export type ExceptionListItemType = z.infer; export const ExceptionListItemType = z.literal('simple'); +/** + * Exception list name. + */ export type ExceptionListItemName = z.infer; -export const ExceptionListItemName = NonEmptyString; +export const ExceptionListItemName = z.string().min(1).superRefine(isNonEmptyString); +/** + * Describes the exception list. + */ export type ExceptionListItemDescription = z.infer; export const ExceptionListItemDescription = z.string(); export type ExceptionListItemMeta = z.infer; export const ExceptionListItemMeta = z.object({}).catchall(z.unknown()); +/** + * The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. + */ +export type ExceptionListItemExpireTime = z.infer; +export const ExceptionListItemExpireTime = z.string().datetime(); + export type ExceptionListItemTags = z.infer; -export const ExceptionListItemTags = z.array(NonEmptyString); +export const ExceptionListItemTags = z.array(z.string().min(1).superRefine(isNonEmptyString)); export type ExceptionListItemOsType = z.infer; export const ExceptionListItemOsType = z.enum(['linux', 'macos', 'windows']); @@ -133,12 +197,24 @@ export type ExceptionListItemComment = z.infer; export const ExceptionListItemComment = z.object({ id: NonEmptyString, comment: NonEmptyString, + /** + * Autogenerated date of object creation. + */ created_at: z.string().datetime(), created_by: NonEmptyString, + /** + * Autogenerated date of last object update. + */ updated_at: z.string().datetime().optional(), updated_by: NonEmptyString.optional(), }); +/** + * Array of comment fields: + +- comment (string): Comments about the exception item. + + */ export type ExceptionListItemCommentArray = z.infer; export const ExceptionListItemCommentArray = z.array(ExceptionListItemComment); @@ -155,13 +231,31 @@ export const ExceptionListItem = z.object({ os_types: ExceptionListItemOsTypeArray.optional(), tags: ExceptionListItemTags.optional(), meta: ExceptionListItemMeta.optional(), - expire_time: z.string().datetime().optional(), + expire_time: ExceptionListItemExpireTime.optional(), comments: ExceptionListItemCommentArray, + /** + * The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. + */ _version: z.string().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(), }); @@ -178,11 +272,23 @@ export const ExceptionListSO = z.object({ os_types: ExceptionListItemOsTypeArray.optional(), tags: ExceptionListItemTags.optional(), meta: ExceptionListItemMeta.optional(), - expire_time: z.string().datetime().optional(), + expire_time: ExceptionListItemExpireTime.optional(), comments: ExceptionListItemCommentArray.optional(), version: NonEmptyString.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 value - user that last updated object. + */ updated_by: z.string(), }); diff --git a/packages/kbn-securitysolution-exceptions-common/api/model/exception_list_common.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/model/exception_list_common.schema.yaml index ebcecc9c916f7..ca47b652cc944 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/model/exception_list_common.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/model/exception_list_common.schema.yaml @@ -7,14 +7,22 @@ components: x-codegen-enabled: true schemas: ExceptionListId: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Exception list's identifier. + example: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 ExceptionListHumanId: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' - description: Human readable string identifier, e.g. `trusted-linux-processes` + type: string + minLength: 1 + format: nonempty + description: Exception list's human readable string identifier, e.g. `trusted-linux-processes`. + example: 'simple_list' ExceptionListType: type: string + description: The type of exception list to be created. Different list types may denote where they can be utilized. enum: - detection - rule_default @@ -26,13 +34,18 @@ components: ExceptionListName: type: string + description: The name of the exception list. + example: 'My exception list' ExceptionListDescription: type: string + description: Describes the exception list. + example: 'This list tracks allowlisted values.' ExceptionListMeta: type: object additionalProperties: true + description: Placeholder for metadata about the list container. ExceptionNamespaceType: type: string @@ -50,6 +63,7 @@ components: type: array items: type: string + description: String array containing words and phrases to help categorize exception containers. ExceptionListOsType: type: string @@ -57,15 +71,18 @@ components: - linux - macos - windows + description: Use this field to specify the operating system. ExceptionListOsTypeArray: type: array items: $ref: '#/components/schemas/ExceptionListOsType' + description: Use this field to specify the operating system. Only enter one value. ExceptionListVersion: type: integer minimum: 1 + description: The document version, automatically increasd on updates. ExceptionList: type: object @@ -94,18 +111,24 @@ components: $ref: '#/components/schemas/ExceptionListVersion' _version: type: string + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. tie_breaker_id: type: string + description: Field used in search to ensure all containers are sorted and returned correctly. created_at: type: string format: date-time + description: Autogenerated date of object creation. created_by: type: string + description: Autogenerated value - user that created object. updated_at: type: string format: date-time + description: Autogenerated date of last object update. updated_by: type: string + description: Autogenerated value - user that last updated object. required: - id - list_id @@ -122,29 +145,49 @@ components: - updated_by ExceptionListItemId: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Exception's identifier. + example: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 ExceptionListItemHumanId: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Human readable string identifier, e.g. `trusted-linux-processes` + example: simple_list_item ExceptionListItemType: type: string enum: [simple] ExceptionListItemName: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: Exception list name. ExceptionListItemDescription: type: string + description: Describes the exception list. ExceptionListItemMeta: type: object additionalProperties: true + ExceptionListItemExpireTime: + type: string + format: date-time + description: The exception item’s expiration date, in ISO format. This field is only available for regular exception items, not endpoint exceptions. + ExceptionListItemTags: type: array items: - $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' + type: string + minLength: 1 + format: nonempty + description: String array containing words and phrases to help categorize exception items. ExceptionListItemOsType: type: string @@ -168,11 +211,13 @@ components: created_at: type: string format: date-time + description: Autogenerated date of object creation. created_by: $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' updated_at: type: string format: date-time + description: Autogenerated date of last object update. updated_by: $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' required: @@ -183,6 +228,10 @@ components: ExceptionListItemCommentArray: type: array + description: | + Array of comment fields: + + - comment (string): Comments about the exception item. items: $ref: '#/components/schemas/ExceptionListItemComment' @@ -212,24 +261,29 @@ components: meta: $ref: '#/components/schemas/ExceptionListItemMeta' expire_time: - type: string - format: date-time + $ref: '#/components/schemas/ExceptionListItemExpireTime' comments: $ref: '#/components/schemas/ExceptionListItemCommentArray' _version: type: string + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. tie_breaker_id: type: string + description: Field used in search to ensure all containers are sorted and returned correctly. created_at: type: string format: date-time + description: Autogenerated date of object creation. created_by: type: string + description: Autogenerated value - user that created object. updated_at: type: string format: date-time + description: Autogenerated date of last object update. updated_by: type: string + description: Autogenerated value - user that last updated object. required: - id - item_id @@ -273,21 +327,24 @@ components: meta: $ref: '#/components/schemas/ExceptionListItemMeta' expire_time: - type: string - format: date-time + $ref: '#/components/schemas/ExceptionListItemExpireTime' comments: $ref: '#/components/schemas/ExceptionListItemCommentArray' version: $ref: '../../../kbn-openapi-common/schemas/primitives.schema.yaml#/components/schemas/NonEmptyString' tie_breaker_id: type: string + description: Field used in search to ensure all containers are sorted and returned correctly. created_at: type: string format: date-time + description: Autogenerated date of object creation. created_by: type: string + description: Autogenerated value - user that created object. updated_by: type: string + description: Autogenerated value - user that last updated object. required: - list_id - list_type diff --git a/packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts index 4827baab85e90..d9be7432b6f92 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts @@ -99,7 +99,7 @@ export class Client { this.log = options.log; } /** - * An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists. + * An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules. > info > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item. @@ -257,7 +257,7 @@ export class Client { .catch(catchAxiosErrorFormatAndThrow); } /** - * Get a list of all exception lists. + * Get a list of all exception list containers. */ async findExceptionLists(props: FindExceptionListsProps) { this.log.info(`${new Date().toISOString()} Calling API FindExceptionLists`); diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.gen.ts index 67a832b01195c..3783d5659d3f7 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.gen.ts @@ -28,11 +28,11 @@ import { export type ReadExceptionListRequestQuery = z.infer; export const ReadExceptionListRequestQuery = z.object({ /** - * Either `id` or `list_id` must be specified + * Exception list's identifier. Either `id` or `list_id` must be specified. */ id: ExceptionListId.optional(), /** - * Either `id` or `list_id` must be specified + * Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified. */ list_id: ExceptionListHumanId.optional(), namespace_type: ExceptionNamespaceType.optional().default('single'), diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml index 0bf082c1713bd..e27df49a929d4 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list/read_exception_list.schema.yaml @@ -14,13 +14,13 @@ paths: - name: id in: query required: false - description: Either `id` or `list_id` must be specified + description: Exception list's identifier. Either `id` or `list_id` must be specified. schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListId' - name: list_id in: query required: false - description: Either `id` or `list_id` must be specified + description: Human readable exception list string identifier, e.g. `trusted-linux-processes`. Either `id` or `list_id` must be specified. schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId' - name: namespace_type @@ -29,6 +29,11 @@ paths: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' default: single + examples: + single: + value: single + agnostic: + value: agnostic responses: 200: description: Successful response @@ -36,6 +41,25 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionList' + examples: + detectionType: + value: + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + list_id: simple_list + type: detection + name: Sample Detection Exception List + description: This is a sample detection type exception list. + immutable: false + namespace_type: single + os_types: [linux] + tags: [malware] + version: 1 + _version: WzIsMV0= + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic 400: description: Invalid input data response content: @@ -44,27 +68,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'" 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/exception_lists?list_id=simple_list&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 404: description: Exception list item not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.gen.ts index 4de512301cd83..b81511d54b59a 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.gen.ts @@ -28,11 +28,11 @@ import { export type ReadExceptionListItemRequestQuery = z.infer; export const ReadExceptionListItemRequestQuery = z.object({ /** - * Either `id` or `item_id` must be specified + * Exception list item's identifier. Either `id` or `item_id` must be specified. */ id: ExceptionListItemId.optional(), /** - * Either `id` or `item_id` must be specified + * Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified. */ item_id: ExceptionListItemHumanId.optional(), namespace_type: ExceptionNamespaceType.optional().default('single'), diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml index c271016a87eb5..3c8e1a5619093 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_item/read_exception_list_item.schema.yaml @@ -14,13 +14,13 @@ paths: - name: id in: query required: false - description: Either `id` or `item_id` must be specified + description: Exception list item's identifier. Either `id` or `item_id` must be specified. schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemId' - name: item_id in: query required: false - description: Either `id` or `item_id` must be specified + description: Human readable exception item string identifier, e.g. `trusted-linux-processes`. Either `id` or `item_id` must be specified. schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemHumanId' - name: namespace_type @@ -29,6 +29,11 @@ paths: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' default: single + examples: + single: + value: single + agnostic: + value: agnostic responses: 200: description: Successful response @@ -36,6 +41,33 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItem' + examples: + simpleListItem: + value: + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + type: simple + name: Sample Exception List Item + description: This is a sample detection type exception item. + entries: + - type: exists + field: actingProcess.file.signer + operator: excluded + - type: match_any + field: host.name + value: [saturn, jupiter] + operator: included + namespace_type: single + os_types: [linux] + tags: [malware] + comments: [] + _version: WzQsMV0= + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic 400: description: Invalid input data response content: @@ -44,27 +76,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'" 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/exception_lists/items?item_id=&namespace_type=single] is unauthorized for user, this action is granted by the Kibana privileges [lists-read]' 404: description: Exception list item not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.gen.ts index 3e3230dddb0aa..745575fa4a87d 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.gen.ts @@ -29,11 +29,11 @@ export type ReadExceptionListSummaryRequestQuery = z.infer< >; export const ReadExceptionListSummaryRequestQuery = z.object({ /** - * Exception list's identifier generated upon creation + * Exception list's identifier generated upon creation. */ id: ExceptionListId.optional(), /** - * Exception list's human readable identifier + * Exception list's human readable identifier. */ list_id: ExceptionListHumanId.optional(), namespace_type: ExceptionNamespaceType.optional().default('single'), diff --git a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml index b0627111e877f..efc1717340300 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/read_exception_list_summary/read_exception_list_summary.schema.yaml @@ -14,13 +14,13 @@ paths: - name: id in: query required: false - description: Exception list's identifier generated upon creation + description: Exception list's identifier generated upon creation. schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListId' - name: list_id in: query required: false - description: Exception list's human readable identifier + description: Exception list's human readable identifier. schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListHumanId' - name: namespace_type @@ -29,12 +29,18 @@ paths: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionNamespaceType' default: single + examples: + single: + value: single + agnostic: + value: agnostic - name: filter in: query required: false description: Search filter clause schema: type: string + example: exception-list-agnostic.attributes.tags:"policy:policy-1" OR exception-list-agnostic.attributes.tags:"policy:all" responses: 200: description: Successful response @@ -55,6 +61,13 @@ paths: total: type: integer minimum: 0 + examples: + summary: + value: + windows: 0 + linux: 0 + macos: 0 + total: 0 400: description: Invalid input data response content: @@ -63,27 +76,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: "[request query]: namespace_type.0: Invalid enum value. Expected 'agnostic' | 'single', received 'blob'" 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [GET /api/exception_lists/summary?list_id=simple_list&namespace_type=agnostic] is unauthorized for user, this action is granted by the Kibana privileges [lists-summary]' 404: description: Exception list not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.gen.ts index 2f38661cc9587..085a8e0f7053a 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.gen.ts @@ -44,6 +44,9 @@ export const UpdateExceptionListRequestBody = z.object({ tags: ExceptionListTags.optional(), meta: ExceptionListMeta.optional(), version: ExceptionListVersion.optional(), + /** + * The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. + */ _version: z.string().optional(), }); export type UpdateExceptionListRequestBodyInput = z.input; diff --git a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml index 5e8f3dfd8b509..46121d590d653 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list/update_exception_list.schema.yaml @@ -42,10 +42,18 @@ paths: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListVersion' _version: type: string + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. required: - name - description - type + example: + list_id: simple_list + tags: [draft malware] + type: detection + os_types: [linux] + description: Different description + name: Updated exception list name responses: 200: description: Successful response @@ -53,6 +61,28 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionList' + examples: + simpleList: + value: + id: fa7f545f-191b-4d32-b1f0-c7cd62a79e55 + list_id: simple_list + type: detection + name: Updated exception list name + description: Different description + immutable: false + namespace_type: single + os_types: [] + tags: [ + draft + malware, + ] + version: 2 + _version: WzExLDFd + tie_breaker_id: 319fe983-acdd-4806-b6c4-3098eae9392f + created_at: 2025-01-07T20:43:55.264Z + created_by: elastic + updated_at: 2025-01-07T21:32:03.726Z + updated_by: elastic 400: description: Invalid input data response content: @@ -61,27 +91,55 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: list_id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [PUT /api/exception_lists] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: Exception list not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 diff --git a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.gen.ts b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.gen.ts index 651c1dc1f2d49..ed87a8e374522 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.gen.ts @@ -30,6 +30,7 @@ import { ExceptionListItemOsTypeArray, ExceptionListItemTags, ExceptionListItemMeta, + ExceptionListItemExpireTime, ExceptionListItem, } from '../model/exception_list_common.gen'; import { ExceptionListItemEntryArray } from '../model/exception_list_item_entry.gen'; @@ -64,8 +65,11 @@ export const UpdateExceptionListItemRequestBody = z.object({ os_types: ExceptionListItemOsTypeArray.optional().default([]), tags: ExceptionListItemTags.optional(), meta: ExceptionListItemMeta.optional(), - expire_time: z.string().datetime().optional(), + expire_time: ExceptionListItemExpireTime.optional(), comments: UpdateExceptionListItemCommentArray.optional().default([]), + /** + * The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. + */ _version: z.string().optional(), }); export type UpdateExceptionListItemRequestBodyInput = z.input< diff --git a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml index 2b8182aeb5c34..5c10ec69a8f21 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/api/update_exception_list_item/update_exception_list_item.schema.yaml @@ -45,18 +45,31 @@ paths: meta: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemMeta' expire_time: - type: string - format: date-time + $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItemExpireTime' comments: $ref: '#/components/schemas/UpdateExceptionListItemCommentArray' default: [] _version: type: string + description: The version id, normally returned by the API when the item was retrieved. Use it ensure updates are done against the latest version. required: - type - name - description - entries + example: + comments: [] + description: Updated description + entries: + - field: host.name + type: match + value: rock01 + operator: included + item_id: simple_list_item + name: Updated name + namespace_type: single + tags: [] + type: simple responses: 200: description: Successful response @@ -64,6 +77,30 @@ paths: application/json: schema: $ref: '../model/exception_list_common.schema.yaml#/components/schemas/ExceptionListItem' + examples: + simpleListItem: + value: + id: 459c5e7e-f8b2-4f0b-b136-c1fc702f72da + item_id: simple_list_item + list_id: simple_list + type: simple + name: Updated name + description: Updated description + entries: + - type: match + field: host.name + value: rock01 + operator: included + namespace_type: single + os_types: [] + tags: [] + comments: [] + _version: WzEyLDFd + tie_breaker_id: ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0 + created_at: 2025-01-07T21:12:25.512Z + created_by: elastic + updated_at: 2025-01-07T21:34:50.233Z + updated_by: elastic 400: description: Invalid input data response content: @@ -72,30 +109,58 @@ paths: oneOf: - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + badRequest: + value: + statusCode: 400 + error: Bad Request + message: '[request body]: item_id: Expected string, received number' 401: description: Unsuccessful authentication response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + unauthorized: + value: + statusCode: 401 + error: Unauthorized + message: '[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]' 403: description: Not enough privileges response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + examples: + forbidden: + value: + statusCode: 403 + error: Forbidden + message: 'API [PUT /api/exception_lists/items] is unauthorized for user, this action is granted by the Kibana privileges [lists-all]' 404: description: Exception list item not found response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + notFound: + value: + message: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 500: description: Internal server error response content: application/json: schema: $ref: '../../../kbn-openapi-common/schemas/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 components: x-codegen-enabled: true diff --git a/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml index 9ef3c7ffc6524..c3e461e3ad6fc 100644 --- a/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/docs/openapi/ess/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml @@ -20,6 +20,9 @@ paths: operationId: CreateRuleExceptionListItems parameters: - description: Detection rule's identifier + examples: + id: + value: 330bdd28-eedf-40e1-bed0-f10176c7f9e0 in: path name: id required: true @@ -29,6 +32,28 @@ paths: content: application/json: schema: + example: + items: + - description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + type: simple type: object properties: items: @@ -37,12 +62,43 @@ paths: type: array required: - items - description: Rule exception list items + description: Rule exception items. required: true responses: '200': content: application/json: + examples: + ruleExceptionItems: + value: + - _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic schema: items: $ref: '#/components/schemas/ExceptionListItem' @@ -51,6 +107,17 @@ paths: '400': content: application/json: + examples: + badPayload: + value: + error: Bad Request + message: Invalid request payload JSON format + statusCode: 400 + badRequest: + value: + error: Bad Request + message: '[request params]: id: Invalid uuid' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -59,22 +126,43 @@ paths: '401': content: application/json: + examples: + unauthorized: + value: + error: Unauthorized + message: >- + [security_exception\n\tRoot + causes:\n\t\tsecurity_exception: unable to authenticate + user [elastic] for REST request + [/_security/_authenticate]]: unable to authenticate user + [elastic] for REST request [/_security/_authenticate] + statusCode: 401 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json: + examples: + forbidden: + value: + message: Unable to create exception-list + status_code: 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: Create rule exception list items + summary: Create rule exception items tags: - Security Exceptions API /api/exception_lists: @@ -82,19 +170,34 @@ paths: description: Delete an exception list using the `id` or `list_id` field. operationId: DeleteExceptionList parameters: - - description: Either `id` or `list_id` must be specified + - description: >- + Exception list's identifier. Either `id` or `list_id` must be + specified. in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListId' - - description: Either `id` or `list_id` must be specified + - description: >- + Human readable exception list string identifier, e.g. + `trusted-linux-processes`. Either `id` or `list_id` must be + specified. + examples: + autogeneratedId: + value: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + list_id: + value: simple_list in: query name: list_id required: false schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -104,12 +207,41 @@ paths: '200': content: application/json: + examples: + detectionExceptionList: + value: + _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -118,24 +250,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 [DELETE + /api/exception_lists?list_id=simple_list&namespace_type=single] + 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: 'exception list list_id: "foo" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -146,19 +309,29 @@ paths: description: Get the details of an exception list using the `id` or `list_id` field. operationId: ReadExceptionList parameters: - - description: Either `id` or `list_id` must be specified + - description: >- + Exception list's identifier. Either `id` or `list_id` must be + specified. in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListId' - - description: Either `id` or `list_id` must be specified + - description: >- + Human readable exception list string identifier, e.g. + `trusted-linux-processes`. Either `id` or `list_id` must be + specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -168,12 +341,41 @@ paths: '200': content: application/json: + examples: + detectionType: + value: + _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -182,24 +384,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/exception_lists?list_id=simple_list&namespace_type=single] + 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": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -209,8 +442,8 @@ paths: post: description: > An exception list groups exception items and can be associated with - detection rules. You can assign detection rules with multiple exception - lists. + detection rules. You can assign exception lists to multiple detection + rules. > info @@ -225,6 +458,16 @@ paths: content: application/json: schema: + example: + description: This is a sample detection type exception list. + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + type: detection type: object properties: description: @@ -258,12 +501,100 @@ paths: '200': content: application/json: + examples: + autogeneratedListId: + value: + _version: WzMsMV0= + created_at: 2025-01-09T01:05:23.019Z + created_by: elastic + description: >- + This is a sample detection type exception with an + autogenerated list_id. + id: 28243c2f-624a-4443-823d-c0b894880931 + immutable: false + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Sample Detection Exception List + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: ad94de31-39f7-4ad7-b8e4-988bfa95f338 + type: detection + updated_at: 2025-01-09T01:05:23.020Z + updated_by: elastic + version: 1 + namespaceAgnostic: + value: + _version: WzUsMV0= + created_at: 2025-01-09T01:10:36.369Z + created_by: elastic + description: This is a sample agnostic endpoint type exception. + id: 1a744e77-22ca-4b6b-9085-54f55275ebe5 + immutable: false + list_id: b935eb55-7b21-4c1c-b235-faa1df23b3d6 + name: Sample Agnostic Endpoint Exception List + namespace_type: agnostic + os_types: + - linux + tags: + - malware + tie_breaker_id: 49ea0adc-a2b8-4d83-a8f3-2fb98301dea3 + type: endpoint + updated_at: 2025-01-09T01:10:36.369Z + updated_by: elastic + version: 1 + typeDetection: + value: + _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 + typeEndpoint: + value: + _version: WzQsMV0= + created_at: 2025-01-09T01:07:49.658Z + created_by: elastic + description: This is a sample endpoint type exception list. + id: a79f4730-6e32-4278-abfc-349c0add7d54 + immutable: false + list_id: endpoint_list + name: Sample Endpoint Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 94a028af-8f47-427a-aca5-ffaf829e64ee + type: endpoint + updated_at: 2025-01-09T01:07:49.658Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -272,24 +603,49 @@ 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/exception_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: 'exception list id: "simple_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -303,9 +659,22 @@ paths: content: application/json: schema: + example: + description: Different description + list_id: simple_list + name: Updated exception list name + os_types: + - linux + tags: + - draft malware + type: detection type: object properties: _version: + description: >- + The version id, normally returned by the API when the item + was retrieved. Use it ensure updates are done against the + latest version. type: string description: $ref: '#/components/schemas/ExceptionListDescription' @@ -339,12 +708,38 @@ paths: '200': content: application/json: + examples: + simpleList: + value: + _version: WzExLDFd + created_at: 2025-01-07T20:43:55.264Z + created_by: elastic + description: Different description + id: fa7f545f-191b-4d32-b1f0-c7cd62a79e55 + immutable: false + list_id: simple_list + name: Updated exception list name + namespace_type: single + os_types: [] + tags: + - draft malware + tie_breaker_id: 319fe983-acdd-4806-b6c4-3098eae9392f + type: detection + updated_at: 2025-01-07T21:32:03.726Z + updated_by: elastic + version: 2 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -353,24 +748,54 @@ 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/exception_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": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -382,20 +807,24 @@ paths: description: Duplicate an existing exception list. operationId: DuplicateExceptionList parameters: - - description: Exception list's human identifier - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: true schema: $ref: '#/components/schemas/ExceptionNamespaceType' - description: >- - Determines whether to include expired exceptions in the exported - list + Determines whether to include expired exceptions in the duplicated + list. Expiration date defined by `expire_time`. in: query name: include_expired_exceptions required: true @@ -404,17 +833,46 @@ paths: enum: - 'true' - 'false' + example: true type: string responses: '200': content: application/json: + examples: + detectionExceptionList: + value: + _version: WzExNDY1LDFd + created_at: 2025-01-09T16:19:50.280Z + created_by: elastic + description: This is a sample detection type exception + id: b2f4a715-6ab1-444c-8b1e-3fa1b1049429 + immutable: false + list_id: d6390d60-bce3-4a48-9002-52db600f329c + name: 'Sample Detection Exception List [Duplicate]' + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 6fa670bd-666d-4c9c-9f1e-d1dbc516e985 + type: detection + updated_at: 2025-01-09T16:19:50.280Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type: Invalid enum value. + Expected 'agnostic' | 'single', received 'foo' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -423,15 +881,46 @@ 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/exception_lists/_duplicate] 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": 'exception list id: "foo" does not exist' + status_code": 404 + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Exception list not found '405': content: application/json: @@ -441,6 +930,11 @@ 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 @@ -452,26 +946,30 @@ paths: description: Export an exception list and its associated items to an NDJSON file. operationId: ExportExceptionList parameters: - - description: Exception list's identifier - in: query + - in: query name: id required: true schema: $ref: '#/components/schemas/ExceptionListId' - - description: Exception list's human identifier - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: true schema: $ref: '#/components/schemas/ExceptionNamespaceType' - description: >- Determines whether to include expired exceptions in the exported - list + list. Expiration date defined by `expire_time`. + example: true in: query name: include_expired_exceptions required: true @@ -485,6 +983,28 @@ paths: '200': content: application/ndjson: + examples: + exportSavedObjectsResponse: + value: > + {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This + is a sample detection type + exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample + Detection Exception + List","namespace_type":"single","os_types":[],"tags":["user + added string for a + tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1} + + {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This + is a sample endpoint type + exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some + host","another + host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample + Endpoint Exception + List","namespace_type":"single","os_types":["linux"],"tags":["user + added string for a + tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"} + + {"exported_exception_list_count":1,"exported_exception_list_item_count":1,"missing_exception_list_item_count":0,"missing_exception_list_items":[],"missing_exception_lists":[],"missing_exception_lists_count":0} schema: description: >- A `.ndjson` file containing specified exception list and its @@ -495,6 +1015,14 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: list_id: Required, namespace_type: + Required + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -503,24 +1031,54 @@ 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/exception_lists/_export] 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": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -529,7 +1087,7 @@ paths: - Security Exceptions API /api/exception_lists/_find: get: - description: Get a list of all exception lists. + description: Get a list of all exception list containers. operationId: FindExceptionLists parameters: - description: > @@ -555,6 +1113,11 @@ paths: with a Kibana space or available in all spaces (`agnostic` or `single`) + examples: + agnostic: + value: agnostic + single: + value: single in: query name: namespace_type required: false @@ -569,6 +1132,7 @@ paths: name: page required: false schema: + example: 1 minimum: 1 type: integer - description: The number of exception lists to return per page @@ -576,15 +1140,17 @@ paths: name: per_page required: false schema: + example: 20 minimum: 1 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: + example: name type: string - - description: 'Determines the sort order, which can be `desc` or `asc`' + - description: 'Determines the sort order, which can be `desc` or `asc`.' in: query name: sort_order required: false @@ -592,11 +1158,36 @@ paths: enum: - desc - asc + example: desc type: string responses: '200': content: application/json: + examples: + simpleLists: + value: + data: + - _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Detection Exception List + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -622,6 +1213,14 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -630,18 +1229,43 @@ 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/exception_lists/_find?namespace_type=single] + 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 @@ -664,18 +1288,7 @@ paths: required: false schema: default: false - type: boolean - - in: query - name: overwrite_exceptions - required: false - schema: - default: false - type: boolean - - in: query - name: overwrite_action_connectors - required: false - schema: - default: false + example: false type: boolean - description: > Determines whether the list being imported will have a new `list_id` @@ -690,6 +1303,7 @@ paths: required: false schema: default: false + example: false type: boolean requestBody: content: @@ -699,6 +1313,24 @@ paths: properties: file: description: A `.ndjson` file containing the exception list + example: > + {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This + is a sample detection type + exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample + Detection Exception + List","namespace_type":"single","os_types":[],"tags":["user + added string for a + tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1} + + {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This + is a sample endpoint type + exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some + host","another + host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample + Endpoint Exception + List","namespace_type":"single","os_types":["linux"],"tags":["user + added string for a + tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"} format: binary type: string required: true @@ -706,6 +1338,40 @@ paths: '200': content: application/json: + examples: + withErrors: + value: + errors: + - error: + message: >- + Error found importing exception list: Invalid value + \"4\" supplied to \"list_id\" + status_code: 400 + list_id: (unknown list_id) + - error: + message: >- + Found that item_id: + \"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\" already + exists. Import of item_id: + \"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\" skipped. + status_code: 409 + item_id: f7fd00bb-dba8-4c93-9d59-6cbd427b6330 + list_id: 7d7cccb8-db72-4667-b1f3-648efad7c1ee + success: 'false,' + success_count: '0,' + success_count_exception_list_items: 0 + success_count_exception_lists: '0,' + success_exception_list_items: 'false,' + success_exception_lists: 'false,' + withoutErrors: + value: + errors: [] + success: true + success_count: 2 + success_count_exception_list_items: 1 + success_count_exception_lists: 1 + success_exception_list_items: true + success_exception_lists: 'true,' schema: type: object properties: @@ -746,18 +1412,43 @@ 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/exception_lists/_import] 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 '500': content: application/json: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response @@ -769,19 +1460,29 @@ paths: description: Delete an exception list item using the `id` or `item_id` field. operationId: DeleteExceptionListItem parameters: - - description: Either `id` or `item_id` must be specified + - description: >- + Exception item's identifier. Either `id` or `item_id` must be + specified in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListItemId' - - description: Either `id` or `item_id` must be specified + - description: >- + Human readable exception item string identifier, e.g. + `trusted-linux-processes`. Either `id` or `item_id` must be + specified in: query name: item_id required: false schema: $ref: '#/components/schemas/ExceptionListItemHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -791,6 +1492,37 @@ paths: '200': content: application/json: + examples: + simpleExceptionItem: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic schema: $ref: '#/components/schemas/ExceptionListItem' description: Successful response @@ -798,6 +1530,12 @@ paths: content: application/json: schema: + example: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' - $ref: '#/components/schemas/SiemErrorResponse' @@ -805,24 +1543,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 [DELETE + /api/exception_lists/items?item_id=simple_list&namespace_type=single] + 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: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -835,19 +1604,29 @@ paths: field. operationId: ReadExceptionListItem parameters: - - description: Either `id` or `item_id` must be specified + - description: >- + Exception list item's identifier. Either `id` or `item_id` must be + specified. in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListItemId' - - description: Either `id` or `item_id` must be specified + - description: >- + Human readable exception item string identifier, e.g. + `trusted-linux-processes`. Either `id` or `item_id` must be + specified. in: query name: item_id required: false schema: $ref: '#/components/schemas/ExceptionListItemHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -857,12 +1636,51 @@ paths: '200': content: application/json: + examples: + simpleListItem: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic schema: $ref: '#/components/schemas/ExceptionListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -871,24 +1689,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/exception_lists/items?item_id=&namespace_type=single] + 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: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -908,6 +1757,27 @@ paths: content: application/json: schema: + example: + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + type: simple type: object properties: comments: @@ -918,8 +1788,7 @@ paths: entries: $ref: '#/components/schemas/ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/ExceptionListItemExpireTime' item_id: $ref: '#/components/schemas/ExceptionListItemHumanId' list_id: @@ -951,12 +1820,204 @@ paths: '200': content: application/json: + examples: + autogeneratedItemId: + value: + _version: WzYsMV0= + comments: [] + created_at: 2025-01-09T01:16:23.322Z + created_by: elastic + description: >- + This is a sample exception that has no item_id so it is + autogenerated. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 323faa75-c657-4fa0-9084-8827612c207b + item_id: 80e6edf7-4b13-4414-858f-2fa74aa52b37 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Sample Autogenerated Exception List Item ID + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: d6799986-3a23-4213-bc6d-ed9463a32f23 + type: simple + updated_at: 2025-01-09T01:16:23.322Z + updated_by: elastic + detectionExceptionListItem: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withExistEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withMatchAnyEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withMatchEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: included + type: match + value: Elastic N.V. + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withNestedEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - entries: + - field: signer + operator: included + type: match + value: Evil + - field: trusted + operator: included + type: match + value: true + field: file.signature + type: nested + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withValueListEntry: + value: + _version: WzcsMV0= + comments: [] + created_at: 2025-01-09T01:31:12.614Z + created_by: elastic + description: >- + Don't signal when agent.name is rock01 and source.ip is in + the goodguys.txt list + entries: + - field: source.ip + list: + id: goodguys.txt + type: ip + operator: excluded + type: list + id: deb26876-297d-4677-8a1f-35467d2f1c4f + item_id: 686b129e-9b8d-4c59-8d8d-c93a9ea82c71 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Filter out good guys ip and agent.name rock01 + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 5e0288ce-6657-4c18-9dcc-00ec9e8cc6c8 + type: simple + updated_at: 2025-01-09T01:31:12.614Z + updated_by: elastic schema: $ref: '#/components/schemas/ExceptionListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: 'Bad Request,' + message: '[request body]: list_id: Expected string, received number' + statusCode: '400,' schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -965,24 +2026,56 @@ 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/exception_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 '409': content: application/json: + examples: + alreadyExists: + value: + message: >- + exception list item id: \"simple_list_item\" already + exists + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -995,10 +2088,27 @@ paths: requestBody: content: application/json: + example: + comments: [] + description: Updated description + entries: + - field: host.name + operator: included + type: match + value: rock01 + item_id: simple_list_item + name: Updated name + namespace_type: single + tags: [] + type: simple schema: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item + was retrieved. Use it ensure updates are done against the + latest version. type: string comments: $ref: '#/components/schemas/UpdateExceptionListItemCommentArray' @@ -1008,8 +2118,7 @@ paths: entries: $ref: '#/components/schemas/ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/ExceptionListItemExpireTime' id: $ref: '#/components/schemas/ExceptionListItemId' description: Either `id` or `item_id` must be specified @@ -1043,12 +2152,42 @@ paths: '200': content: application/json: + examples: + simpleListItem: + value: + _version: WzEyLDFd + comments: [] + created_at: 2025-01-07T21:12:25.512Z + created_by: elastic + description: Updated description + entries: + - field: host.name + operator: included + type: match + value: rock01 + id: 459c5e7e-f8b2-4f0b-b136-c1fc702f72da + item_id: simple_list_item + list_id: simple_list + name: Updated name + namespace_type: single + os_types: [] + tags: [] + tie_breaker_id: ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0 + type: simple + updated_at: 2025-01-07T21:34:50.233Z + updated_by: elastic schema: $ref: '#/components/schemas/ExceptionListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: item_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1057,24 +2196,54 @@ 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/exception_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: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -1086,7 +2255,7 @@ paths: description: Get a list of all exception list items in the specified list. operationId: FindExceptionListItems parameters: - - description: List's id + - description: The `list_id`s of the items to fetch. in: query name: list_id required: true @@ -1099,6 +2268,10 @@ paths: field, using the `:` syntax. + examples: + singleFilter: + value: + - 'exception-list.attributes.name:%My%20item' in: query name: filter required: false @@ -1112,6 +2285,10 @@ paths: with a Kibana space or available in all spaces (`agnostic` or `single`) + examples: + single: + value: + - single in: query name: namespace_type required: false @@ -1125,12 +2302,14 @@ paths: name: search required: false schema: + example: host.name type: string - description: The page number to return in: query name: page required: false schema: + example: 1 minimum: 0 type: integer - description: The number of exception list items to return per page @@ -1138,15 +2317,17 @@ paths: name: per_page required: false schema: + example: 20 minimum: 0 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. + example: name in: query name: sort_field required: false schema: $ref: '#/components/schemas/NonEmptyString' - - description: 'Determines the sort order, which can be `desc` or `asc`' + - description: 'Determines the sort order, which can be `desc` or `asc`.' in: query name: sort_order required: false @@ -1154,11 +2335,47 @@ paths: enum: - desc - asc + example: desc type: string responses: '200': content: application/json: + examples: + simpleListItems: + value: + data: + - _version: WzgsMV0= + comments: [] + created_at: 2025-01-07T21:12:25.512Z + created_by: elastic + description: This is a sample exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - jupiter + - saturn + id: 459c5e7e-f8b2-4f0b-b136-c1fc702f72da + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0 + type: simple + updated_at: 2025-01-07T21:12:25.512Z + updated_by: elastic + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -1186,6 +2403,14 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1194,24 +2419,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/exception_lists/items/_find?list_id=simple_list&namespace_type=single] + 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: 'exception list list_id: "foo" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -1223,19 +2479,24 @@ paths: description: Get a summary of the specified exception list. operationId: ReadExceptionListSummary parameters: - - description: Exception list's identifier generated upon creation + - description: Exception list's identifier generated upon creation. in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListId' - - description: Exception list's human readable identifier + - description: Exception list's human readable identifier. in: query name: list_id required: false schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -1246,11 +2507,21 @@ paths: name: filter required: false schema: + example: >- + exception-list-agnostic.attributes.tags:"policy:policy-1" OR + exception-list-agnostic.attributes.tags:"policy:all" type: string responses: '200': content: application/json: + examples: + summary: + value: + linux: 0 + macos: 0 + total: 0 + windows: 0 schema: type: object properties: @@ -1270,6 +2541,14 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1278,24 +2557,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/exception_lists/summary?list_id=simple_list&namespace_type=agnostic] + is unauthorized for user, this action is granted by the + Kibana privileges [lists-summary] + statusCode: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '404': content: application/json: + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -1322,6 +2632,15 @@ paths: content: application/json: schema: + example: + description: This is a sample detection type exception list. + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware type: object properties: description: @@ -1336,12 +2655,39 @@ paths: '200': content: application/json: + examples: + sharedList: + value: + _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1350,24 +2696,45 @@ paths: '401': content: application/json: + examples: + unauthorized: + value: + error: Unauthorized + message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]" + statusCode: 401 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json: + examples: + forbidden: + value: + message: Unable to create exception-list + status_code: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '409': content: application/json: + examples: + alreadyExists: + value: + message: 'exception list id: "simple_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -1437,11 +2804,17 @@ components: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item was + retrieved. Use it ensure updates are done against the latest + version. type: string created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/ExceptionListDescription' @@ -1462,13 +2835,18 @@ components: tags: $ref: '#/components/schemas/ExceptionListTags' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. type: string type: $ref: '#/components/schemas/ExceptionListType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string version: $ref: '#/components/schemas/ExceptionListVersion' @@ -1487,31 +2865,47 @@ components: - updated_at - updated_by ExceptionListDescription: + description: Describes the exception list. + example: This list tracks allowlisted values. type: string ExceptionListHumanId: - $ref: '#/components/schemas/NonEmptyString' - description: 'Human readable string identifier, e.g. `trusted-linux-processes`' + description: >- + Exception list's human readable string identifier, e.g. + `trusted-linux-processes`. + example: simple_list + format: nonempty + minLength: 1 + type: string ExceptionListId: - $ref: '#/components/schemas/NonEmptyString' + description: Exception list's identifier. + example: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + format: nonempty + minLength: 1 + type: string ExceptionListItem: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item was + retrieved. Use it ensure updates are done against the latest + version. type: string comments: $ref: '#/components/schemas/ExceptionListItemCommentArray' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/ExceptionListItemDescription' entries: $ref: '#/components/schemas/ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/ExceptionListItemExpireTime' id: $ref: '#/components/schemas/ExceptionListItemId' item_id: @@ -1529,13 +2923,18 @@ components: tags: $ref: '#/components/schemas/ExceptionListItemTags' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. type: string type: $ref: '#/components/schemas/ExceptionListItemType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string required: - id @@ -1558,6 +2957,7 @@ components: comment: $ref: '#/components/schemas/NonEmptyString' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: @@ -1565,6 +2965,7 @@ components: id: $ref: '#/components/schemas/NonEmptyString' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: @@ -1575,10 +2976,15 @@ components: - created_at - created_by ExceptionListItemCommentArray: + description: | + Array of comment fields: + + - comment (string): Comments about the exception item. items: $ref: '#/components/schemas/ExceptionListItemComment' type: array ExceptionListItemDescription: + description: Describes the exception list. type: string ExceptionListItemEntry: anyOf: @@ -1720,22 +3126,44 @@ components: - excluded - included type: string + ExceptionListItemExpireTime: + description: >- + The exception item’s expiration date, in ISO format. This field is only + available for regular exception items, not endpoint exceptions. + format: date-time + type: string ExceptionListItemHumanId: - $ref: '#/components/schemas/NonEmptyString' + description: 'Human readable string identifier, e.g. `trusted-linux-processes`' + example: simple_list_item + format: nonempty + minLength: 1 + type: string ExceptionListItemId: - $ref: '#/components/schemas/NonEmptyString' + description: Exception's identifier. + example: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + format: nonempty + minLength: 1 + type: string ExceptionListItemMeta: additionalProperties: true type: object ExceptionListItemName: - $ref: '#/components/schemas/NonEmptyString' + description: Exception list name. + format: nonempty + minLength: 1 + type: string ExceptionListItemOsTypeArray: items: $ref: '#/components/schemas/ExceptionListOsType' type: array ExceptionListItemTags: items: - $ref: '#/components/schemas/NonEmptyString' + description: >- + String array containing words and phrases to help categorize exception + items. + format: nonempty + minLength: 1 + type: string type: array ExceptionListItemType: enum: @@ -1743,16 +3171,21 @@ components: type: string ExceptionListMeta: additionalProperties: true + description: Placeholder for metadata about the list container. type: object ExceptionListName: + description: The name of the exception list. + example: My exception list type: string ExceptionListOsType: + description: Use this field to specify the operating system. enum: - linux - macos - windows type: string ExceptionListOsTypeArray: + description: Use this field to specify the operating system. Only enter one value. items: $ref: '#/components/schemas/ExceptionListOsType' type: array @@ -1782,10 +3215,16 @@ components: $ref: '#/components/schemas/ExceptionListsImportBulkError' type: array ExceptionListTags: + description: >- + String array containing words and phrases to help categorize exception + containers. items: type: string type: array ExceptionListType: + description: >- + The type of exception list to be created. Different list types may + denote where they can be utilized. enum: - detection - rule_default @@ -1796,6 +3235,7 @@ components: - endpoint_blocklists type: string ExceptionListVersion: + description: 'The document version, automatically increasd on updates.' minimum: 1 type: integer ExceptionNamespaceType: @@ -1816,6 +3256,7 @@ components: FindExceptionListItemsFilter: $ref: '#/components/schemas/NonEmptyString' FindExceptionListsFilter: + example: 'exception-list.attributes.name:%Detection%20List' type: string ListId: description: Value list's identifier. diff --git a/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml b/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml index d70f6692690c0..913e1d9b9196a 100644 --- a/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml +++ b/packages/kbn-securitysolution-exceptions-common/docs/openapi/serverless/security_solution_exceptions_api_2023_10_31.bundled.schema.yaml @@ -20,6 +20,9 @@ paths: operationId: CreateRuleExceptionListItems parameters: - description: Detection rule's identifier + examples: + id: + value: 330bdd28-eedf-40e1-bed0-f10176c7f9e0 in: path name: id required: true @@ -29,6 +32,28 @@ paths: content: application/json: schema: + example: + items: + - description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + type: simple type: object properties: items: @@ -37,12 +62,43 @@ paths: type: array required: - items - description: Rule exception list items + description: Rule exception items. required: true responses: '200': content: application/json: + examples: + ruleExceptionItems: + value: + - _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic schema: items: $ref: '#/components/schemas/ExceptionListItem' @@ -51,6 +107,17 @@ paths: '400': content: application/json: + examples: + badPayload: + value: + error: Bad Request + message: Invalid request payload JSON format + statusCode: 400 + badRequest: + value: + error: Bad Request + message: '[request params]: id: Invalid uuid' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -59,22 +126,43 @@ paths: '401': content: application/json: + examples: + unauthorized: + value: + error: Unauthorized + message: >- + [security_exception\n\tRoot + causes:\n\t\tsecurity_exception: unable to authenticate + user [elastic] for REST request + [/_security/_authenticate]]: unable to authenticate user + [elastic] for REST request [/_security/_authenticate] + statusCode: 401 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json: + examples: + forbidden: + value: + message: Unable to create exception-list + status_code: 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: Create rule exception list items + summary: Create rule exception items tags: - Security Exceptions API /api/exception_lists: @@ -82,19 +170,34 @@ paths: description: Delete an exception list using the `id` or `list_id` field. operationId: DeleteExceptionList parameters: - - description: Either `id` or `list_id` must be specified + - description: >- + Exception list's identifier. Either `id` or `list_id` must be + specified. in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListId' - - description: Either `id` or `list_id` must be specified + - description: >- + Human readable exception list string identifier, e.g. + `trusted-linux-processes`. Either `id` or `list_id` must be + specified. + examples: + autogeneratedId: + value: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + list_id: + value: simple_list in: query name: list_id required: false schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -104,12 +207,41 @@ paths: '200': content: application/json: + examples: + detectionExceptionList: + value: + _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -118,24 +250,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 [DELETE + /api/exception_lists?list_id=simple_list&namespace_type=single] + 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: 'exception list list_id: "foo" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -146,19 +309,29 @@ paths: description: Get the details of an exception list using the `id` or `list_id` field. operationId: ReadExceptionList parameters: - - description: Either `id` or `list_id` must be specified + - description: >- + Exception list's identifier. Either `id` or `list_id` must be + specified. in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListId' - - description: Either `id` or `list_id` must be specified + - description: >- + Human readable exception list string identifier, e.g. + `trusted-linux-processes`. Either `id` or `list_id` must be + specified. in: query name: list_id required: false schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -168,12 +341,41 @@ paths: '200': content: application/json: + examples: + detectionType: + value: + _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -182,24 +384,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/exception_lists?list_id=simple_list&namespace_type=single] + 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": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -209,8 +442,8 @@ paths: post: description: > An exception list groups exception items and can be associated with - detection rules. You can assign detection rules with multiple exception - lists. + detection rules. You can assign exception lists to multiple detection + rules. > info @@ -225,6 +458,16 @@ paths: content: application/json: schema: + example: + description: This is a sample detection type exception list. + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + type: detection type: object properties: description: @@ -258,12 +501,100 @@ paths: '200': content: application/json: + examples: + autogeneratedListId: + value: + _version: WzMsMV0= + created_at: 2025-01-09T01:05:23.019Z + created_by: elastic + description: >- + This is a sample detection type exception with an + autogenerated list_id. + id: 28243c2f-624a-4443-823d-c0b894880931 + immutable: false + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Sample Detection Exception List + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: ad94de31-39f7-4ad7-b8e4-988bfa95f338 + type: detection + updated_at: 2025-01-09T01:05:23.020Z + updated_by: elastic + version: 1 + namespaceAgnostic: + value: + _version: WzUsMV0= + created_at: 2025-01-09T01:10:36.369Z + created_by: elastic + description: This is a sample agnostic endpoint type exception. + id: 1a744e77-22ca-4b6b-9085-54f55275ebe5 + immutable: false + list_id: b935eb55-7b21-4c1c-b235-faa1df23b3d6 + name: Sample Agnostic Endpoint Exception List + namespace_type: agnostic + os_types: + - linux + tags: + - malware + tie_breaker_id: 49ea0adc-a2b8-4d83-a8f3-2fb98301dea3 + type: endpoint + updated_at: 2025-01-09T01:10:36.369Z + updated_by: elastic + version: 1 + typeDetection: + value: + _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 + typeEndpoint: + value: + _version: WzQsMV0= + created_at: 2025-01-09T01:07:49.658Z + created_by: elastic + description: This is a sample endpoint type exception list. + id: a79f4730-6e32-4278-abfc-349c0add7d54 + immutable: false + list_id: endpoint_list + name: Sample Endpoint Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 94a028af-8f47-427a-aca5-ffaf829e64ee + type: endpoint + updated_at: 2025-01-09T01:07:49.658Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -272,24 +603,49 @@ 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/exception_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: 'exception list id: "simple_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -303,9 +659,22 @@ paths: content: application/json: schema: + example: + description: Different description + list_id: simple_list + name: Updated exception list name + os_types: + - linux + tags: + - draft malware + type: detection type: object properties: _version: + description: >- + The version id, normally returned by the API when the item + was retrieved. Use it ensure updates are done against the + latest version. type: string description: $ref: '#/components/schemas/ExceptionListDescription' @@ -339,12 +708,38 @@ paths: '200': content: application/json: + examples: + simpleList: + value: + _version: WzExLDFd + created_at: 2025-01-07T20:43:55.264Z + created_by: elastic + description: Different description + id: fa7f545f-191b-4d32-b1f0-c7cd62a79e55 + immutable: false + list_id: simple_list + name: Updated exception list name + namespace_type: single + os_types: [] + tags: + - draft malware + tie_breaker_id: 319fe983-acdd-4806-b6c4-3098eae9392f + type: detection + updated_at: 2025-01-07T21:32:03.726Z + updated_by: elastic + version: 2 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -353,24 +748,54 @@ 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/exception_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": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -382,20 +807,24 @@ paths: description: Duplicate an existing exception list. operationId: DuplicateExceptionList parameters: - - description: Exception list's human identifier - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: true schema: $ref: '#/components/schemas/ExceptionNamespaceType' - description: >- - Determines whether to include expired exceptions in the exported - list + Determines whether to include expired exceptions in the duplicated + list. Expiration date defined by `expire_time`. in: query name: include_expired_exceptions required: true @@ -404,17 +833,46 @@ paths: enum: - 'true' - 'false' + example: true type: string responses: '200': content: application/json: + examples: + detectionExceptionList: + value: + _version: WzExNDY1LDFd + created_at: 2025-01-09T16:19:50.280Z + created_by: elastic + description: This is a sample detection type exception + id: b2f4a715-6ab1-444c-8b1e-3fa1b1049429 + immutable: false + list_id: d6390d60-bce3-4a48-9002-52db600f329c + name: 'Sample Detection Exception List [Duplicate]' + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 6fa670bd-666d-4c9c-9f1e-d1dbc516e985 + type: detection + updated_at: 2025-01-09T16:19:50.280Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type: Invalid enum value. + Expected 'agnostic' | 'single', received 'foo' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -423,15 +881,46 @@ 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/exception_lists/_duplicate] 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": 'exception list id: "foo" does not exist' + status_code": 404 + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Exception list not found '405': content: application/json: @@ -441,6 +930,11 @@ 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 @@ -452,26 +946,30 @@ paths: description: Export an exception list and its associated items to an NDJSON file. operationId: ExportExceptionList parameters: - - description: Exception list's identifier - in: query + - in: query name: id required: true schema: $ref: '#/components/schemas/ExceptionListId' - - description: Exception list's human identifier - in: query + - in: query name: list_id required: true schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: true schema: $ref: '#/components/schemas/ExceptionNamespaceType' - description: >- Determines whether to include expired exceptions in the exported - list + list. Expiration date defined by `expire_time`. + example: true in: query name: include_expired_exceptions required: true @@ -485,6 +983,28 @@ paths: '200': content: application/ndjson: + examples: + exportSavedObjectsResponse: + value: > + {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This + is a sample detection type + exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample + Detection Exception + List","namespace_type":"single","os_types":[],"tags":["user + added string for a + tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1} + + {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This + is a sample endpoint type + exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some + host","another + host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample + Endpoint Exception + List","namespace_type":"single","os_types":["linux"],"tags":["user + added string for a + tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"} + + {"exported_exception_list_count":1,"exported_exception_list_item_count":1,"missing_exception_list_item_count":0,"missing_exception_list_items":[],"missing_exception_lists":[],"missing_exception_lists_count":0} schema: description: >- A `.ndjson` file containing specified exception list and its @@ -495,6 +1015,14 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: list_id: Required, namespace_type: + Required + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -503,24 +1031,54 @@ 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/exception_lists/_export] 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": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -529,7 +1087,7 @@ paths: - Security Exceptions API /api/exception_lists/_find: get: - description: Get a list of all exception lists. + description: Get a list of all exception list containers. operationId: FindExceptionLists parameters: - description: > @@ -555,6 +1113,11 @@ paths: with a Kibana space or available in all spaces (`agnostic` or `single`) + examples: + agnostic: + value: agnostic + single: + value: single in: query name: namespace_type required: false @@ -569,6 +1132,7 @@ paths: name: page required: false schema: + example: 1 minimum: 1 type: integer - description: The number of exception lists to return per page @@ -576,15 +1140,17 @@ paths: name: per_page required: false schema: + example: 20 minimum: 1 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: + example: name type: string - - description: 'Determines the sort order, which can be `desc` or `asc`' + - description: 'Determines the sort order, which can be `desc` or `asc`.' in: query name: sort_order required: false @@ -592,11 +1158,36 @@ paths: enum: - desc - asc + example: desc type: string responses: '200': content: application/json: + examples: + simpleLists: + value: + data: + - _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Detection Exception List + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -622,6 +1213,14 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -630,18 +1229,43 @@ 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/exception_lists/_find?namespace_type=single] + 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 @@ -664,18 +1288,7 @@ paths: required: false schema: default: false - type: boolean - - in: query - name: overwrite_exceptions - required: false - schema: - default: false - type: boolean - - in: query - name: overwrite_action_connectors - required: false - schema: - default: false + example: false type: boolean - description: > Determines whether the list being imported will have a new `list_id` @@ -690,6 +1303,7 @@ paths: required: false schema: default: false + example: false type: boolean requestBody: content: @@ -699,6 +1313,24 @@ paths: properties: file: description: A `.ndjson` file containing the exception list + example: > + {"_version":"WzExNDU5LDFd","created_at":"2025-01-09T16:18:17.757Z","created_by":"elastic","description":"This + is a sample detection type + exception","id":"c86c2da0-2ab6-4343-b81c-216ef27e8d75","immutable":false,"list_id":"simple_list","name":"Sample + Detection Exception + List","namespace_type":"single","os_types":[],"tags":["user + added string for a + tag","malware"],"tie_breaker_id":"cf4a7b92-732d-47f0-a0d5-49a35a1736bf","type":"detection","updated_at":"2025-01-09T16:18:17.757Z","updated_by":"elastic","version":1} + + {"_version":"WzExNDYxLDFd","comments":[],"created_at":"2025-01-09T16:18:42.308Z","created_by":"elastic","description":"This + is a sample endpoint type + exception","entries":[{"type":"exists","field":"actingProcess.file.signer","operator":"excluded"},{"type":"match_any","field":"host.name","value":["some + host","another + host"],"operator":"included"}],"id":"f37597ce-eaa7-4b64-9100-4301118f6806","item_id":"simple_list_item","list_id":"simple_list","name":"Sample + Endpoint Exception + List","namespace_type":"single","os_types":["linux"],"tags":["user + added string for a + tag","malware"],"tie_breaker_id":"4ca3ef3e-9721-42c0-8107-cf47e094d40f","type":"simple","updated_at":"2025-01-09T16:18:42.308Z","updated_by":"elastic"} format: binary type: string required: true @@ -706,6 +1338,40 @@ paths: '200': content: application/json: + examples: + withErrors: + value: + errors: + - error: + message: >- + Error found importing exception list: Invalid value + \"4\" supplied to \"list_id\" + status_code: 400 + list_id: (unknown list_id) + - error: + message: >- + Found that item_id: + \"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\" already + exists. Import of item_id: + \"f7fd00bb-dba8-4c93-9d59-6cbd427b6330\" skipped. + status_code: 409 + item_id: f7fd00bb-dba8-4c93-9d59-6cbd427b6330 + list_id: 7d7cccb8-db72-4667-b1f3-648efad7c1ee + success: 'false,' + success_count: '0,' + success_count_exception_list_items: 0 + success_count_exception_lists: '0,' + success_exception_list_items: 'false,' + success_exception_lists: 'false,' + withoutErrors: + value: + errors: [] + success: true + success_count: 2 + success_count_exception_list_items: 1 + success_count_exception_lists: 1 + success_exception_list_items: true + success_exception_lists: 'true,' schema: type: object properties: @@ -746,18 +1412,43 @@ 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/exception_lists/_import] 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 '500': content: application/json: + examples: + serverError: + value: + message: Internal Server Error + status_code: 500 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response @@ -769,19 +1460,29 @@ paths: description: Delete an exception list item using the `id` or `item_id` field. operationId: DeleteExceptionListItem parameters: - - description: Either `id` or `item_id` must be specified + - description: >- + Exception item's identifier. Either `id` or `item_id` must be + specified in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListItemId' - - description: Either `id` or `item_id` must be specified + - description: >- + Human readable exception item string identifier, e.g. + `trusted-linux-processes`. Either `id` or `item_id` must be + specified in: query name: item_id required: false schema: $ref: '#/components/schemas/ExceptionListItemHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -791,6 +1492,37 @@ paths: '200': content: application/json: + examples: + simpleExceptionItem: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic schema: $ref: '#/components/schemas/ExceptionListItem' description: Successful response @@ -798,6 +1530,12 @@ paths: content: application/json: schema: + example: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' - $ref: '#/components/schemas/SiemErrorResponse' @@ -805,24 +1543,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 [DELETE + /api/exception_lists/items?item_id=simple_list&namespace_type=single] + 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: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -835,19 +1604,29 @@ paths: field. operationId: ReadExceptionListItem parameters: - - description: Either `id` or `item_id` must be specified + - description: >- + Exception list item's identifier. Either `id` or `item_id` must be + specified. in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListItemId' - - description: Either `id` or `item_id` must be specified + - description: >- + Human readable exception item string identifier, e.g. + `trusted-linux-processes`. Either `id` or `item_id` must be + specified. in: query name: item_id required: false schema: $ref: '#/components/schemas/ExceptionListItemHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -857,12 +1636,51 @@ paths: '200': content: application/json: + examples: + simpleListItem: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic schema: $ref: '#/components/schemas/ExceptionListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -871,24 +1689,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/exception_lists/items?item_id=&namespace_type=single] + 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: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -908,6 +1757,27 @@ paths: content: application/json: schema: + example: + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + type: simple type: object properties: comments: @@ -918,8 +1788,7 @@ paths: entries: $ref: '#/components/schemas/ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/ExceptionListItemExpireTime' item_id: $ref: '#/components/schemas/ExceptionListItemHumanId' list_id: @@ -951,12 +1820,204 @@ paths: '200': content: application/json: + examples: + autogeneratedItemId: + value: + _version: WzYsMV0= + comments: [] + created_at: 2025-01-09T01:16:23.322Z + created_by: elastic + description: >- + This is a sample exception that has no item_id so it is + autogenerated. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 323faa75-c657-4fa0-9084-8827612c207b + item_id: 80e6edf7-4b13-4414-858f-2fa74aa52b37 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Sample Autogenerated Exception List Item ID + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: d6799986-3a23-4213-bc6d-ed9463a32f23 + type: simple + updated_at: 2025-01-09T01:16:23.322Z + updated_by: elastic + detectionExceptionListItem: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withExistEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withMatchAnyEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: host.name + operator: included + type: match_any + value: + - saturn + - jupiter + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withMatchEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - field: actingProcess.file.signer + operator: included + type: match + value: Elastic N.V. + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withNestedEntry: + value: + _version: WzQsMV0= + comments: [] + created_at: 2025-01-07T20:07:33.119Z + created_by: elastic + description: This is a sample detection type exception item. + entries: + - entries: + - field: signer + operator: included + type: match + value: Evil + - field: trusted + operator: included + type: match + value: true + field: file.signature + type: nested + id: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 09434836-9db9-4942-a234-5a9268e0b34c + type: simple + updated_at: 2025-01-07T20:07:33.119Z + updated_by: elastic + withValueListEntry: + value: + _version: WzcsMV0= + comments: [] + created_at: 2025-01-09T01:31:12.614Z + created_by: elastic + description: >- + Don't signal when agent.name is rock01 and source.ip is in + the goodguys.txt list + entries: + - field: source.ip + list: + id: goodguys.txt + type: ip + operator: excluded + type: list + id: deb26876-297d-4677-8a1f-35467d2f1c4f + item_id: 686b129e-9b8d-4c59-8d8d-c93a9ea82c71 + list_id: 8c1aae4c-1ef5-4bce-a2e3-16584b501783 + name: Filter out good guys ip and agent.name rock01 + namespace_type: single + os_types: [] + tags: + - malware + tie_breaker_id: 5e0288ce-6657-4c18-9dcc-00ec9e8cc6c8 + type: simple + updated_at: 2025-01-09T01:31:12.614Z + updated_by: elastic schema: $ref: '#/components/schemas/ExceptionListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: 'Bad Request,' + message: '[request body]: list_id: Expected string, received number' + statusCode: '400,' schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -965,24 +2026,56 @@ 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/exception_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 '409': content: application/json: + examples: + alreadyExists: + value: + message: >- + exception list item id: \"simple_list_item\" already + exists + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -995,10 +2088,27 @@ paths: requestBody: content: application/json: + example: + comments: [] + description: Updated description + entries: + - field: host.name + operator: included + type: match + value: rock01 + item_id: simple_list_item + name: Updated name + namespace_type: single + tags: [] + type: simple schema: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item + was retrieved. Use it ensure updates are done against the + latest version. type: string comments: $ref: '#/components/schemas/UpdateExceptionListItemCommentArray' @@ -1008,8 +2118,7 @@ paths: entries: $ref: '#/components/schemas/ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/ExceptionListItemExpireTime' id: $ref: '#/components/schemas/ExceptionListItemId' description: Either `id` or `item_id` must be specified @@ -1043,12 +2152,42 @@ paths: '200': content: application/json: + examples: + simpleListItem: + value: + _version: WzEyLDFd + comments: [] + created_at: 2025-01-07T21:12:25.512Z + created_by: elastic + description: Updated description + entries: + - field: host.name + operator: included + type: match + value: rock01 + id: 459c5e7e-f8b2-4f0b-b136-c1fc702f72da + item_id: simple_list_item + list_id: simple_list + name: Updated name + namespace_type: single + os_types: [] + tags: [] + tie_breaker_id: ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0 + type: simple + updated_at: 2025-01-07T21:34:50.233Z + updated_by: elastic schema: $ref: '#/components/schemas/ExceptionListItem' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: item_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1057,24 +2196,54 @@ 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/exception_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: 'exception list item item_id: \"foo\" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -1086,7 +2255,7 @@ paths: description: Get a list of all exception list items in the specified list. operationId: FindExceptionListItems parameters: - - description: List's id + - description: The `list_id`s of the items to fetch. in: query name: list_id required: true @@ -1099,6 +2268,10 @@ paths: field, using the `:` syntax. + examples: + singleFilter: + value: + - 'exception-list.attributes.name:%My%20item' in: query name: filter required: false @@ -1112,6 +2285,10 @@ paths: with a Kibana space or available in all spaces (`agnostic` or `single`) + examples: + single: + value: + - single in: query name: namespace_type required: false @@ -1125,12 +2302,14 @@ paths: name: search required: false schema: + example: host.name type: string - description: The page number to return in: query name: page required: false schema: + example: 1 minimum: 0 type: integer - description: The number of exception list items to return per page @@ -1138,15 +2317,17 @@ paths: name: per_page required: false schema: + example: 20 minimum: 0 type: integer - - description: Determines which field is used to sort the results + - description: Determines which field is used to sort the results. + example: name in: query name: sort_field required: false schema: $ref: '#/components/schemas/NonEmptyString' - - description: 'Determines the sort order, which can be `desc` or `asc`' + - description: 'Determines the sort order, which can be `desc` or `asc`.' in: query name: sort_order required: false @@ -1154,11 +2335,47 @@ paths: enum: - desc - asc + example: desc type: string responses: '200': content: application/json: + examples: + simpleListItems: + value: + data: + - _version: WzgsMV0= + comments: [] + created_at: 2025-01-07T21:12:25.512Z + created_by: elastic + description: This is a sample exception item. + entries: + - field: actingProcess.file.signer + operator: excluded + type: exists + - field: host.name + operator: included + type: match_any + value: + - jupiter + - saturn + id: 459c5e7e-f8b2-4f0b-b136-c1fc702f72da + item_id: simple_list_item + list_id: simple_list + name: Sample Exception List Item + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: ad0754ff-7b19-49ca-b73e-e6aff6bfa2d0 + type: simple + updated_at: 2025-01-07T21:12:25.512Z + updated_by: elastic + page: 1 + per_page: 20 + total: 1 schema: type: object properties: @@ -1186,6 +2403,14 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1194,24 +2419,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/exception_lists/items/_find?list_id=simple_list&namespace_type=single] + 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: 'exception list list_id: "foo" does not exist' + status_code: 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -1223,19 +2479,24 @@ paths: description: Get a summary of the specified exception list. operationId: ReadExceptionListSummary parameters: - - description: Exception list's identifier generated upon creation + - description: Exception list's identifier generated upon creation. in: query name: id required: false schema: $ref: '#/components/schemas/ExceptionListId' - - description: Exception list's human readable identifier + - description: Exception list's human readable identifier. in: query name: list_id required: false schema: $ref: '#/components/schemas/ExceptionListHumanId' - - in: query + - examples: + agnostic: + value: agnostic + single: + value: single + in: query name: namespace_type required: false schema: @@ -1246,11 +2507,21 @@ paths: name: filter required: false schema: + example: >- + exception-list-agnostic.attributes.tags:"policy:policy-1" OR + exception-list-agnostic.attributes.tags:"policy:all" type: string responses: '200': content: application/json: + examples: + summary: + value: + linux: 0 + macos: 0 + total: 0 + windows: 0 schema: type: object properties: @@ -1270,6 +2541,14 @@ paths: '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: >- + [request query]: namespace_type.0: Invalid enum value. + Expected 'agnostic' | 'single', received 'blob' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1278,24 +2557,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/exception_lists/summary?list_id=simple_list&namespace_type=agnostic] + is unauthorized for user, this action is granted by the + Kibana privileges [lists-summary] + statusCode: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '404': content: application/json: + examples: + notFound: + value: + message": 'exception list id: "foo" does not exist' + status_code": 404 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -1322,6 +2632,15 @@ paths: content: application/json: schema: + example: + description: This is a sample detection type exception list. + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware type: object properties: description: @@ -1336,12 +2655,39 @@ paths: '200': content: application/json: + examples: + sharedList: + value: + _version: WzIsMV0= + created_at: 2025-01-07T19:34:27.942Z + created_by: elastic + description: This is a sample detection type exception list. + id: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + immutable: false + list_id: simple_list + name: Sample Detection Exception List + namespace_type: single + os_types: + - linux + tags: + - malware + tie_breaker_id: 78f1aca1-f8ee-4eb5-9ceb-f5c3ee656cb3 + type: detection + updated_at: 2025-01-07T19:34:27.942Z + updated_by: elastic + version: 1 schema: $ref: '#/components/schemas/ExceptionList' description: Successful response '400': content: application/json: + examples: + badRequest: + value: + error: Bad Request + message: '[request body]: list_id: Expected string, received number' + statusCode: 400 schema: oneOf: - $ref: '#/components/schemas/PlatformErrorResponse' @@ -1350,24 +2696,45 @@ paths: '401': content: application/json: + examples: + unauthorized: + value: + error: Unauthorized + message: "[security_exception\n\tRoot causes:\n\t\tsecurity_exception: unable to authenticate user [elastic] for REST request [/_security/_authenticate]]: unable to authenticate user [elastic] for REST request [/_security/_authenticate]" + statusCode: 401 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Unsuccessful authentication response '403': content: application/json: + examples: + forbidden: + value: + message: Unable to create exception-list + status_code: 403 schema: $ref: '#/components/schemas/PlatformErrorResponse' description: Not enough privileges response '409': content: application/json: + examples: + alreadyExists: + value: + message: 'exception list id: "simple_list" already exists' + status_code: 409 schema: $ref: '#/components/schemas/SiemErrorResponse' description: Exception 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 @@ -1437,11 +2804,17 @@ components: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item was + retrieved. Use it ensure updates are done against the latest + version. type: string created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/ExceptionListDescription' @@ -1462,13 +2835,18 @@ components: tags: $ref: '#/components/schemas/ExceptionListTags' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. type: string type: $ref: '#/components/schemas/ExceptionListType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string version: $ref: '#/components/schemas/ExceptionListVersion' @@ -1487,31 +2865,47 @@ components: - updated_at - updated_by ExceptionListDescription: + description: Describes the exception list. + example: This list tracks allowlisted values. type: string ExceptionListHumanId: - $ref: '#/components/schemas/NonEmptyString' - description: 'Human readable string identifier, e.g. `trusted-linux-processes`' + description: >- + Exception list's human readable string identifier, e.g. + `trusted-linux-processes`. + example: simple_list + format: nonempty + minLength: 1 + type: string ExceptionListId: - $ref: '#/components/schemas/NonEmptyString' + description: Exception list's identifier. + example: 9e5fc75a-a3da-46c5-96e3-a2ec59c6bb85 + format: nonempty + minLength: 1 + type: string ExceptionListItem: type: object properties: _version: + description: >- + The version id, normally returned by the API when the item was + retrieved. Use it ensure updates are done against the latest + version. type: string comments: $ref: '#/components/schemas/ExceptionListItemCommentArray' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: + description: Autogenerated value - user that created object. type: string description: $ref: '#/components/schemas/ExceptionListItemDescription' entries: $ref: '#/components/schemas/ExceptionListItemEntryArray' expire_time: - format: date-time - type: string + $ref: '#/components/schemas/ExceptionListItemExpireTime' id: $ref: '#/components/schemas/ExceptionListItemId' item_id: @@ -1529,13 +2923,18 @@ components: tags: $ref: '#/components/schemas/ExceptionListItemTags' tie_breaker_id: + description: >- + Field used in search to ensure all containers are sorted and + returned correctly. type: string type: $ref: '#/components/schemas/ExceptionListItemType' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: + description: Autogenerated value - user that last updated object. type: string required: - id @@ -1558,6 +2957,7 @@ components: comment: $ref: '#/components/schemas/NonEmptyString' created_at: + description: Autogenerated date of object creation. format: date-time type: string created_by: @@ -1565,6 +2965,7 @@ components: id: $ref: '#/components/schemas/NonEmptyString' updated_at: + description: Autogenerated date of last object update. format: date-time type: string updated_by: @@ -1575,10 +2976,15 @@ components: - created_at - created_by ExceptionListItemCommentArray: + description: | + Array of comment fields: + + - comment (string): Comments about the exception item. items: $ref: '#/components/schemas/ExceptionListItemComment' type: array ExceptionListItemDescription: + description: Describes the exception list. type: string ExceptionListItemEntry: anyOf: @@ -1720,22 +3126,44 @@ components: - excluded - included type: string + ExceptionListItemExpireTime: + description: >- + The exception item’s expiration date, in ISO format. This field is only + available for regular exception items, not endpoint exceptions. + format: date-time + type: string ExceptionListItemHumanId: - $ref: '#/components/schemas/NonEmptyString' + description: 'Human readable string identifier, e.g. `trusted-linux-processes`' + example: simple_list_item + format: nonempty + minLength: 1 + type: string ExceptionListItemId: - $ref: '#/components/schemas/NonEmptyString' + description: Exception's identifier. + example: 71a9f4b2-c85c-49b4-866f-c71eb9e67da2 + format: nonempty + minLength: 1 + type: string ExceptionListItemMeta: additionalProperties: true type: object ExceptionListItemName: - $ref: '#/components/schemas/NonEmptyString' + description: Exception list name. + format: nonempty + minLength: 1 + type: string ExceptionListItemOsTypeArray: items: $ref: '#/components/schemas/ExceptionListOsType' type: array ExceptionListItemTags: items: - $ref: '#/components/schemas/NonEmptyString' + description: >- + String array containing words and phrases to help categorize exception + items. + format: nonempty + minLength: 1 + type: string type: array ExceptionListItemType: enum: @@ -1743,16 +3171,21 @@ components: type: string ExceptionListMeta: additionalProperties: true + description: Placeholder for metadata about the list container. type: object ExceptionListName: + description: The name of the exception list. + example: My exception list type: string ExceptionListOsType: + description: Use this field to specify the operating system. enum: - linux - macos - windows type: string ExceptionListOsTypeArray: + description: Use this field to specify the operating system. Only enter one value. items: $ref: '#/components/schemas/ExceptionListOsType' type: array @@ -1782,10 +3215,16 @@ components: $ref: '#/components/schemas/ExceptionListsImportBulkError' type: array ExceptionListTags: + description: >- + String array containing words and phrases to help categorize exception + containers. items: type: string type: array ExceptionListType: + description: >- + The type of exception list to be created. Different list types may + denote where they can be utilized. enum: - detection - rule_default @@ -1796,6 +3235,7 @@ components: - endpoint_blocklists type: string ExceptionListVersion: + description: 'The document version, automatically increasd on updates.' minimum: 1 type: integer ExceptionNamespaceType: @@ -1816,6 +3256,7 @@ components: FindExceptionListItemsFilter: $ref: '#/components/schemas/NonEmptyString' FindExceptionListsFilter: + example: 'exception-list.attributes.name:%Detection%20List' type: string ListId: description: Value list's identifier. diff --git a/x-pack/test/api_integration/services/security_solution_exceptions_api.gen.ts b/x-pack/test/api_integration/services/security_solution_exceptions_api.gen.ts index e9c26ad55ebf3..6b0d8dad51ef2 100644 --- a/x-pack/test/api_integration/services/security_solution_exceptions_api.gen.ts +++ b/x-pack/test/api_integration/services/security_solution_exceptions_api.gen.ts @@ -47,7 +47,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) return { /** - * An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists. + * An exception list groups exception items and can be associated with detection rules. You can assign exception lists to multiple detection rules. > info > All exception items added to the same list are evaluated using `OR` logic. That is, if any of the items in a list evaluate to `true`, the exception prevents the rule from generating an alert. Likewise, `OR` logic is used for evaluating exceptions when more than one exception list is assigned to a rule. To use the `AND` operator, you can define multiple clauses (`entries`) in a single exception item. @@ -166,7 +166,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .query(props.query); }, /** - * Get a list of all exception lists. + * Get a list of all exception list containers. */ findExceptionLists(props: FindExceptionListsProps, kibanaSpace: string = 'default') { return supertest