From c676d2bd72f87fceecd8d459335ed56e36acf661 Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Date: Thu, 19 Sep 2024 09:13:14 +0100 Subject: [PATCH] Improves Exceptions API docs content (#193040) ## Summary Resolves https://github.com/elastic/security-docs-internal/issues/33 by improving the Exceptions API docs content. Adds missing and improves existing operation summaries and operation descriptions to adhere to our [OAS standards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs). --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> --- .../create_exception_list.schema.yaml | 6 +- .../create_exception_list_item.schema.yaml | 6 +- .../create_rule_exceptions.schema.yaml | 3 +- .../create_shared_exceptions_list.schema.yaml | 6 +- .../delete_exception_list.schema.yaml | 3 +- .../delete_exception_list_item.schema.yaml | 3 +- .../duplicate_exception_list.schema.yaml | 3 +- .../export_exception_list.schema.yaml | 4 +- .../find_exception_list_items.schema.yaml | 3 +- .../find_exception_lists.schema.yaml | 3 +- .../import_exceptions.schema.yaml | 4 +- .../api/quickstart_client.gen.ts | 55 ++++++++++++- .../read_exception_list.schema.yaml | 3 +- .../read_exception_list_item.schema.yaml | 3 +- .../read_exception_list_summary.schema.yaml | 3 +- .../update_exception_list.schema.yaml | 3 +- .../update_exception_list_item.schema.yaml | 3 +- ...eptions_api_2023_10_31.bundled.schema.yaml | 82 +++++++++++++++---- ...eptions_api_2023_10_31.bundled.schema.yaml | 82 +++++++++++++++---- .../security_solution_exceptions_api.gen.ts | 55 ++++++++++++- 20 files changed, 275 insertions(+), 58 deletions(-) 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 463009b233af1..5925d0bd923c0 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 @@ -8,7 +8,11 @@ paths: x-labels: [serverless, ess] operationId: CreateExceptionList x-codegen-enabled: true - summary: Creates an exception list + 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. + > 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: description: Exception list's properties required: true 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 f7eb416f953a6..47fa2895d27c6 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 @@ -8,7 +8,11 @@ paths: x-labels: [serverless, ess] operationId: CreateExceptionListItem x-codegen-enabled: true - summary: Creates an exception list item + summary: Create an exception list item + description: | + Create an exception item and associate it with the specified exception list. + > info + > Before creating exception items, you must create an exception list. requestBody: description: Exception list item's properties required: true 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 0928d9e7f4e21..6162d00d78ae8 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: CreateRuleExceptionListItems x-codegen-enabled: true - summary: Creates rule exception list items + summary: Create rule exception list items + description: Create exception items that apply to a single detection rule. parameters: - name: id in: path 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 e76ec4c50c5c8..c4cee089e5836 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 @@ -8,7 +8,11 @@ paths: x-labels: [serverless, ess] operationId: CreateSharedExceptionList x-codegen-enabled: true - summary: Creates a shared exception list + summary: Create a shared exception list + description: | + An exception list groups exception items and can be associated with detection rules. A shared exception list can apply 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: required: true content: 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 ccc0749dd206e..92afc3232efee 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: DeleteExceptionList x-codegen-enabled: true - summary: Deletes an exception list + summary: Delete an exception list + description: Delete an exception list using the `id` or `list_id` field. parameters: - name: id in: query 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 e9d7fa0687044..9f57afcd5ab1c 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: DeleteExceptionListItem x-codegen-enabled: true - summary: Deletes an exception list item + summary: Delete an exception list item + description: Delete an exception list item using the `id` or `item_id` field. parameters: - name: id in: query 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 f041fcb1d1062..758171327ee4c 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: DuplicateExceptionList x-codegen-enabled: true - summary: Duplicates an exception list + summary: Duplicate an exception list + description: Duplicate an existing exception list. parameters: - name: list_id in: query 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 41637963d9923..3232f46c238c8 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 @@ -8,8 +8,8 @@ paths: x-labels: [serverless, ess] operationId: ExportExceptionList x-codegen-enabled: true - summary: Exports an exception list - description: Exports an exception list and its associated items to an .ndjson file + summary: Export an exception list + description: Export an exception list and its associated items to an NDJSON file. parameters: - name: id in: query 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 f2b3aafdee107..e40f780af03ef 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: FindExceptionListItems x-codegen-enabled: true - summary: Finds exception list items + summary: Get exception list items + description: Get a list of all exception list items in the specified list. parameters: - name: list_id in: query 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 a1df1d12a27ea..c46dacbab01d0 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: FindExceptionLists x-codegen-enabled: true - summary: Finds exception lists + summary: Get exception lists + description: Get a list of all exception lists. parameters: - name: filter in: query 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 dc67d1386475f..8ae3ac1aa2c0c 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 @@ -8,8 +8,8 @@ paths: x-labels: [serverless, ess] operationId: ImportExceptionList x-codegen-enabled: true - summary: Imports an exception list - description: Imports an exception list and associated items + summary: Import an exception list + description: Import an exception list and its associated items from an NDJSON file. requestBody: required: true content: 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 52e11f1ea4033..4827baab85e90 100644 --- a/packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts +++ b/packages/kbn-securitysolution-exceptions-common/api/quickstart_client.gen.ts @@ -98,6 +98,12 @@ export class Client { this.kbnClient = options.kbnClient; 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. +> 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. + + */ async createExceptionList(props: CreateExceptionListProps) { this.log.info(`${new Date().toISOString()} Calling API CreateExceptionList`); return this.kbnClient @@ -111,6 +117,12 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Create an exception item and associate it with the specified exception list. +> info +> Before creating exception items, you must create an exception list. + + */ async createExceptionListItem(props: CreateExceptionListItemProps) { this.log.info(`${new Date().toISOString()} Calling API CreateExceptionListItem`); return this.kbnClient @@ -124,6 +136,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Create exception items that apply to a single detection rule. + */ async createRuleExceptionListItems(props: CreateRuleExceptionListItemsProps) { this.log.info(`${new Date().toISOString()} Calling API CreateRuleExceptionListItems`); return this.kbnClient @@ -137,6 +152,12 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * An exception list groups exception items and can be associated with detection rules. A shared exception list can apply 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. + + */ async createSharedExceptionList(props: CreateSharedExceptionListProps) { this.log.info(`${new Date().toISOString()} Calling API CreateSharedExceptionList`); return this.kbnClient @@ -150,6 +171,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Delete an exception list using the `id` or `list_id` field. + */ async deleteExceptionList(props: DeleteExceptionListProps) { this.log.info(`${new Date().toISOString()} Calling API DeleteExceptionList`); return this.kbnClient @@ -164,6 +188,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Delete an exception list item using the `id` or `item_id` field. + */ async deleteExceptionListItem(props: DeleteExceptionListItemProps) { this.log.info(`${new Date().toISOString()} Calling API DeleteExceptionListItem`); return this.kbnClient @@ -178,6 +205,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Duplicate an existing exception list. + */ async duplicateExceptionList(props: DuplicateExceptionListProps) { this.log.info(`${new Date().toISOString()} Calling API DuplicateExceptionList`); return this.kbnClient @@ -193,7 +223,7 @@ export class Client { .catch(catchAxiosErrorFormatAndThrow); } /** - * Exports an exception list and its associated items to an .ndjson file + * Export an exception list and its associated items to an NDJSON file. */ async exportExceptionList(props: ExportExceptionListProps) { this.log.info(`${new Date().toISOString()} Calling API ExportExceptionList`); @@ -209,6 +239,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Get a list of all exception list items in the specified list. + */ async findExceptionListItems(props: FindExceptionListItemsProps) { this.log.info(`${new Date().toISOString()} Calling API FindExceptionListItems`); return this.kbnClient @@ -223,6 +256,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Get a list of all exception lists. + */ async findExceptionLists(props: FindExceptionListsProps) { this.log.info(`${new Date().toISOString()} Calling API FindExceptionLists`); return this.kbnClient @@ -238,7 +274,7 @@ export class Client { .catch(catchAxiosErrorFormatAndThrow); } /** - * Imports an exception list and associated items + * Import an exception list and its associated items from an NDJSON file. */ async importExceptionList(props: ImportExceptionListProps) { this.log.info(`${new Date().toISOString()} Calling API ImportExceptionList`); @@ -254,6 +290,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Get the details of an exception list using the `id` or `list_id` field. + */ async readExceptionList(props: ReadExceptionListProps) { this.log.info(`${new Date().toISOString()} Calling API ReadExceptionList`); return this.kbnClient @@ -268,6 +307,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Get the details of an exception list item using the `id` or `item_id` field. + */ async readExceptionListItem(props: ReadExceptionListItemProps) { this.log.info(`${new Date().toISOString()} Calling API ReadExceptionListItem`); return this.kbnClient @@ -282,6 +324,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Get a summary of the specified exception list. + */ async readExceptionListSummary(props: ReadExceptionListSummaryProps) { this.log.info(`${new Date().toISOString()} Calling API ReadExceptionListSummary`); return this.kbnClient @@ -296,6 +341,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Update an exception list using the `id` or `list_id` field. + */ async updateExceptionList(props: UpdateExceptionListProps) { this.log.info(`${new Date().toISOString()} Calling API UpdateExceptionList`); return this.kbnClient @@ -309,6 +357,9 @@ export class Client { }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Update an exception list item using the `id` or `item_id` field. + */ async updateExceptionListItem(props: UpdateExceptionListItemProps) { this.log.info(`${new Date().toISOString()} Calling API UpdateExceptionListItem`); return this.kbnClient 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 69f5b4a9a8aa2..0bf082c1713bd 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: ReadExceptionList x-codegen-enabled: true - summary: Retrieves an exception list using its `id` or `list_id` field + summary: Get exception list details + description: Get the details of an exception list using the `id` or `list_id` field. parameters: - name: id in: query 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 9cc6b79b91e63..c271016a87eb5 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: ReadExceptionListItem x-codegen-enabled: true - summary: Gets an exception list item + summary: Get an exception list item + description: Get the details of an exception list item using the `id` or `item_id` field. parameters: - name: id in: query 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 bae534bf3260b..b0627111e877f 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: ReadExceptionListSummary x-codegen-enabled: true - summary: Retrieves an exception list summary + summary: Get an exception list summary + description: Get a summary of the specified exception list. parameters: - name: id in: query 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 a58caeb465428..5e8f3dfd8b509 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: UpdateExceptionList x-codegen-enabled: true - summary: Updates an exception list + summary: Update an exception list + description: Update an exception list using the `id` or `list_id` field. requestBody: description: Exception list's properties required: true 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 180d4865f887b..2b8182aeb5c34 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 @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: UpdateExceptionListItem x-codegen-enabled: true - summary: Updates an exception list item + summary: Update an exception list item + description: Update an exception list item using the `id` or `item_id` field. requestBody: description: Exception list item's properties required: 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 8acc028520f11..bf0c2502ae80f 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 @@ -16,6 +16,7 @@ servers: paths: '/api/detection_engine/rules/{id}/exceptions': post: + description: Create exception items that apply to a single detection rule. operationId: CreateRuleExceptionListItems parameters: - description: Detection rule's identifier @@ -73,11 +74,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Creates rule exception list items + summary: Create rule exception list items tags: - Security Solution Exceptions API /api/exception_lists: delete: + description: Delete an exception list using the `id` or `list_id` field. operationId: DeleteExceptionList parameters: - description: Either `id` or `list_id` must be specified @@ -137,10 +139,11 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Deletes an exception list + summary: Delete an exception list tags: - Security Solution Exceptions API get: + 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 @@ -200,10 +203,23 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Retrieves an exception list using its `id` or `list_id` field + summary: Get exception list details tags: - Security Solution 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. + + > 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 requestBody: content: @@ -277,10 +293,11 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Creates an exception list + summary: Create an exception list tags: - Security Solution Exceptions API put: + description: Update an exception list using the `id` or `list_id` field. operationId: UpdateExceptionList requestBody: content: @@ -357,11 +374,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Updates an exception list + summary: Update an exception list tags: - Security Solution Exceptions API /api/exception_lists/_duplicate: post: + description: Duplicate an existing exception list. operationId: DuplicateExceptionList parameters: - description: Exception list's human identifier @@ -426,12 +444,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Duplicates an exception list + summary: Duplicate an exception list tags: - Security Solution Exceptions API /api/exception_lists/_export: post: - description: Exports an exception list and its associated items to an .ndjson file + description: Export an exception list and its associated items to an NDJSON file. operationId: ExportExceptionList parameters: - description: Exception list's identifier @@ -506,11 +524,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Exports an exception list + summary: Export an exception list tags: - Security Solution Exceptions API /api/exception_lists/_find: get: + description: Get a list of all exception lists. operationId: FindExceptionLists parameters: - description: > @@ -626,12 +645,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Finds exception lists + summary: Get exception lists tags: - Security Solution Exceptions API /api/exception_lists/_import: post: - description: Imports an exception list and associated items + description: Import an exception list and its associated items from an NDJSON file. operationId: ImportExceptionList parameters: - description: > @@ -742,11 +761,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Imports an exception list + summary: Import an exception list tags: - Security Solution Exceptions API /api/exception_lists/items: delete: + 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 @@ -806,10 +826,13 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Deletes an exception list item + summary: Delete an exception list item tags: - Security Solution Exceptions API get: + 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 @@ -869,10 +892,17 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Gets an exception list item + summary: Get an exception list item tags: - Security Solution Exceptions API post: + description: > + Create an exception item and associate it with the specified exception + list. + + > info + + > Before creating exception items, you must create an exception list. operationId: CreateExceptionListItem requestBody: content: @@ -956,10 +986,11 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Creates an exception list item + summary: Create an exception list item tags: - Security Solution Exceptions API put: + description: Update an exception list item using the `id` or `item_id` field. operationId: UpdateExceptionListItem requestBody: content: @@ -1047,11 +1078,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Updates an exception list item + summary: Update an exception list item tags: - Security Solution Exceptions API /api/exception_lists/items/_find: get: + description: Get a list of all exception list items in the specified list. operationId: FindExceptionListItems parameters: - description: List's id @@ -1183,11 +1215,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Finds exception list items + summary: Get exception list items tags: - Security Solution Exceptions API /api/exception_lists/summary: get: + description: Get a summary of the specified exception list. operationId: ReadExceptionListSummary parameters: - description: Exception list's identifier generated upon creation @@ -1266,11 +1299,24 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Retrieves an exception list summary + summary: Get an exception list summary tags: - Security Solution Exceptions API /api/exceptions/shared: post: + description: > + An exception list groups exception items and can be associated with + detection rules. A shared exception list can apply 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: CreateSharedExceptionList requestBody: content: @@ -1325,7 +1371,7 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Creates a shared exception list + summary: Create a shared exception list tags: - Security Solution Exceptions API components: 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 cd104baacda20..2a9bb3996a915 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 @@ -16,6 +16,7 @@ servers: paths: '/api/detection_engine/rules/{id}/exceptions': post: + description: Create exception items that apply to a single detection rule. operationId: CreateRuleExceptionListItems parameters: - description: Detection rule's identifier @@ -73,11 +74,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Creates rule exception list items + summary: Create rule exception list items tags: - Security Solution Exceptions API /api/exception_lists: delete: + description: Delete an exception list using the `id` or `list_id` field. operationId: DeleteExceptionList parameters: - description: Either `id` or `list_id` must be specified @@ -137,10 +139,11 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Deletes an exception list + summary: Delete an exception list tags: - Security Solution Exceptions API get: + 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 @@ -200,10 +203,23 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Retrieves an exception list using its `id` or `list_id` field + summary: Get exception list details tags: - Security Solution 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. + + > 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 requestBody: content: @@ -277,10 +293,11 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Creates an exception list + summary: Create an exception list tags: - Security Solution Exceptions API put: + description: Update an exception list using the `id` or `list_id` field. operationId: UpdateExceptionList requestBody: content: @@ -357,11 +374,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Updates an exception list + summary: Update an exception list tags: - Security Solution Exceptions API /api/exception_lists/_duplicate: post: + description: Duplicate an existing exception list. operationId: DuplicateExceptionList parameters: - description: Exception list's human identifier @@ -426,12 +444,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Duplicates an exception list + summary: Duplicate an exception list tags: - Security Solution Exceptions API /api/exception_lists/_export: post: - description: Exports an exception list and its associated items to an .ndjson file + description: Export an exception list and its associated items to an NDJSON file. operationId: ExportExceptionList parameters: - description: Exception list's identifier @@ -506,11 +524,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Exports an exception list + summary: Export an exception list tags: - Security Solution Exceptions API /api/exception_lists/_find: get: + description: Get a list of all exception lists. operationId: FindExceptionLists parameters: - description: > @@ -626,12 +645,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Finds exception lists + summary: Get exception lists tags: - Security Solution Exceptions API /api/exception_lists/_import: post: - description: Imports an exception list and associated items + description: Import an exception list and its associated items from an NDJSON file. operationId: ImportExceptionList parameters: - description: > @@ -742,11 +761,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Imports an exception list + summary: Import an exception list tags: - Security Solution Exceptions API /api/exception_lists/items: delete: + 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 @@ -806,10 +826,13 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Deletes an exception list item + summary: Delete an exception list item tags: - Security Solution Exceptions API get: + 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 @@ -869,10 +892,17 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Gets an exception list item + summary: Get an exception list item tags: - Security Solution Exceptions API post: + description: > + Create an exception item and associate it with the specified exception + list. + + > info + + > Before creating exception items, you must create an exception list. operationId: CreateExceptionListItem requestBody: content: @@ -956,10 +986,11 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Creates an exception list item + summary: Create an exception list item tags: - Security Solution Exceptions API put: + description: Update an exception list item using the `id` or `item_id` field. operationId: UpdateExceptionListItem requestBody: content: @@ -1047,11 +1078,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Updates an exception list item + summary: Update an exception list item tags: - Security Solution Exceptions API /api/exception_lists/items/_find: get: + description: Get a list of all exception list items in the specified list. operationId: FindExceptionListItems parameters: - description: List's id @@ -1183,11 +1215,12 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Finds exception list items + summary: Get exception list items tags: - Security Solution Exceptions API /api/exception_lists/summary: get: + description: Get a summary of the specified exception list. operationId: ReadExceptionListSummary parameters: - description: Exception list's identifier generated upon creation @@ -1266,11 +1299,24 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Retrieves an exception list summary + summary: Get an exception list summary tags: - Security Solution Exceptions API /api/exceptions/shared: post: + description: > + An exception list groups exception items and can be associated with + detection rules. A shared exception list can apply 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: CreateSharedExceptionList requestBody: content: @@ -1325,7 +1371,7 @@ paths: schema: $ref: '#/components/schemas/SiemErrorResponse' description: Internal server error response - summary: Creates a shared exception list + summary: Create a shared exception list tags: - Security Solution Exceptions API components: 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 e7426a737b39c..726f877898918 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 @@ -45,6 +45,12 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) const supertest = getService('supertest'); return { + /** + * An exception list groups exception items and can be associated with detection rules. You can assign detection rules with multiple exception lists. +> 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. + + */ createExceptionList(props: CreateExceptionListProps) { return supertest .post('/api/exception_lists') @@ -53,6 +59,12 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .send(props.body as object); }, + /** + * Create an exception item and associate it with the specified exception list. +> info +> Before creating exception items, you must create an exception list. + + */ createExceptionListItem(props: CreateExceptionListItemProps) { return supertest .post('/api/exception_lists/items') @@ -61,6 +73,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .send(props.body as object); }, + /** + * Create exception items that apply to a single detection rule. + */ createRuleExceptionListItems(props: CreateRuleExceptionListItemsProps) { return supertest .post(replaceParams('/api/detection_engine/rules/{id}/exceptions', props.params)) @@ -69,6 +84,12 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .send(props.body as object); }, + /** + * An exception list groups exception items and can be associated with detection rules. A shared exception list can apply 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. + + */ createSharedExceptionList(props: CreateSharedExceptionListProps) { return supertest .post('/api/exceptions/shared') @@ -77,6 +98,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .send(props.body as object); }, + /** + * Delete an exception list using the `id` or `list_id` field. + */ deleteExceptionList(props: DeleteExceptionListProps) { return supertest .delete('/api/exception_lists') @@ -85,6 +109,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .query(props.query); }, + /** + * Delete an exception list item using the `id` or `item_id` field. + */ deleteExceptionListItem(props: DeleteExceptionListItemProps) { return supertest .delete('/api/exception_lists/items') @@ -93,6 +120,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .query(props.query); }, + /** + * Duplicate an existing exception list. + */ duplicateExceptionList(props: DuplicateExceptionListProps) { return supertest .post('/api/exception_lists/_duplicate') @@ -102,7 +132,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .query(props.query); }, /** - * Exports an exception list and its associated items to an .ndjson file + * Export an exception list and its associated items to an NDJSON file. */ exportExceptionList(props: ExportExceptionListProps) { return supertest @@ -112,6 +142,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .query(props.query); }, + /** + * Get a list of all exception list items in the specified list. + */ findExceptionListItems(props: FindExceptionListItemsProps) { return supertest .get('/api/exception_lists/items/_find') @@ -120,6 +153,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .query(props.query); }, + /** + * Get a list of all exception lists. + */ findExceptionLists(props: FindExceptionListsProps) { return supertest .get('/api/exception_lists/_find') @@ -129,7 +165,7 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .query(props.query); }, /** - * Imports an exception list and associated items + * Import an exception list and its associated items from an NDJSON file. */ importExceptionList(props: ImportExceptionListProps) { return supertest @@ -139,6 +175,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .query(props.query); }, + /** + * Get the details of an exception list using the `id` or `list_id` field. + */ readExceptionList(props: ReadExceptionListProps) { return supertest .get('/api/exception_lists') @@ -147,6 +186,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .query(props.query); }, + /** + * Get the details of an exception list item using the `id` or `item_id` field. + */ readExceptionListItem(props: ReadExceptionListItemProps) { return supertest .get('/api/exception_lists/items') @@ -155,6 +197,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .query(props.query); }, + /** + * Get a summary of the specified exception list. + */ readExceptionListSummary(props: ReadExceptionListSummaryProps) { return supertest .get('/api/exception_lists/summary') @@ -163,6 +208,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .query(props.query); }, + /** + * Update an exception list using the `id` or `list_id` field. + */ updateExceptionList(props: UpdateExceptionListProps) { return supertest .put('/api/exception_lists') @@ -171,6 +219,9 @@ export function SecuritySolutionApiProvider({ getService }: FtrProviderContext) .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana') .send(props.body as object); }, + /** + * Update an exception list item using the `id` or `item_id` field. + */ updateExceptionListItem(props: UpdateExceptionListItemProps) { return supertest .put('/api/exception_lists/items')