From 1e122558e6e180b90029ade0894b4d92b3f3a4d8 Mon Sep 17 00:00:00 2001 From: Maxim Palenov Date: Mon, 28 Jul 2025 23:33:13 +0200 Subject: [PATCH] [Security Solution] Improve bulk actions API reference docs (#228712) ## Summary This PR improves description on rule bulk action `ids` to make it clear rule's saved object ID is used. (cherry picked from commit 642f6b328be19a4e542a57c9cdfd6874e6c5978d) --- oas_docs/output/kibana.serverless.yaml | 34 +++++++--- oas_docs/output/kibana.yaml | 34 +++++++--- .../bulk_actions/bulk_actions_route.gen.ts | 8 ++- .../bulk_actions_route.schema.yaml | 11 +-- .../export_rules/export_rules_route.gen.ts | 2 +- .../export_rules_route.schema.yaml | 2 +- ...ections_api_2023_10_31.bundled.schema.yaml | 68 ++++++++++++------- ...ections_api_2023_10_31.bundled.schema.yaml | 68 ++++++++++++------- 8 files changed, 147 insertions(+), 80 deletions(-) diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml index d815a73b115b2..198f264465625 100644 --- a/oas_docs/output/kibana.serverless.yaml +++ b/oas_docs/output/kibana.serverless.yaml @@ -8376,7 +8376,7 @@ paths: type: object properties: objects: - description: Array of `rule_id` fields. Exports all rules when unspecified. + description: Array of objects with a rule's `rule_id` field. Do not use rule's `id` here. Exports all rules when unspecified. items: type: object properties: @@ -53422,7 +53422,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -53446,7 +53448,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -53483,7 +53487,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -53581,7 +53587,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -53610,7 +53618,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -53636,7 +53646,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -53677,7 +53689,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -53702,7 +53716,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index 95c46fdd25c50..5d68151298ebe 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -11351,7 +11351,7 @@ paths: type: object properties: objects: - description: Array of `rule_id` fields. Exports all rules when unspecified. + description: Array of objects with a rule's `rule_id` field. Do not use rule's `id` here. Exports all rules when unspecified. items: type: object properties: @@ -35897,7 +35897,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -35921,7 +35923,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -35958,7 +35962,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -36056,7 +36062,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -36085,7 +36093,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -36111,7 +36121,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -36152,7 +36164,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 @@ -36177,7 +36191,9 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. items: type: string minItems: 1 diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.gen.ts index 9f26cad0103ae..168c45e8f8e1a 100644 --- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.gen.ts +++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.gen.ts @@ -117,9 +117,11 @@ export const BulkActionBase = z.object({ * Query to filter rules. */ query: z.string().optional(), - /** - * Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. - */ + /** + * Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. +Only valid when query property is undefined. + + */ ids: z.array(z.string()).min(1).optional(), /** * Gaps range start, valid only when query is provided diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml index 8d8931f9a6e6c..3eacf345e0faf 100644 --- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml +++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml @@ -376,7 +376,7 @@ paths: duration: value: 1 unit: 'h' - missing_fields_strategy: 'suppress' + missing_fields_strategy: 'suppress' example28: summary: Edit - Set alert suppression to threshold rules (idempotent) description: The following request set alert suppression to threshold rules with the specified IDs. @@ -1060,7 +1060,7 @@ components: type: string enum: - RULE_NOT_MODIFIED - + BulkGapsFillingSkipReason: type: string enum: @@ -1206,7 +1206,9 @@ components: description: Query to filter rules. ids: type: array - description: Array of rule IDs. Array of rule IDs to which a bulk action will be applied. Only valid when query property is undefined. + description: | + Array of rule `id`s to which a bulk action will be applied. Do not use rule's `rule_id` here. + Only valid when query property is undefined. minItems: 1 items: type: string @@ -1309,7 +1311,7 @@ components: required: - action - run - + BulkManualRuleFillGaps: allOf: - $ref: '#/components/schemas/BulkActionBase' @@ -1603,7 +1605,6 @@ components: - $ref: '#/components/schemas/BulkActionEditPayloadSchedule' - $ref: '#/components/schemas/BulkActionEditPayloadAlertSuppression' - BulkEditRules: allOf: - $ref: '#/components/schemas/BulkActionBase' diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.gen.ts index dc14314d0707c..50d81f03aca2b 100644 --- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.gen.ts +++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.gen.ts @@ -39,7 +39,7 @@ export type ExportRulesRequestBody = z.infer; export const ExportRulesRequestBody = z .object({ /** - * Array of `rule_id` fields. Exports all rules when unspecified. + * Array of objects with a rule's `rule_id` field. Do not use rule's `id` here. Exports all rules when unspecified. */ objects: z.array( z.object({ diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml index 00ab724828599..f8f89f1bd3add 100644 --- a/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml +++ b/x-pack/solutions/security/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml @@ -72,7 +72,7 @@ paths: properties: rule_id: $ref: '../../model/rule_schema/common_attributes.schema.yaml#/components/schemas/RuleSignatureId' - description: Array of `rule_id` fields. Exports all rules when unspecified. + description: Array of objects with a rule's `rule_id` field. Do not use rule's `id` here. Exports all rules when unspecified. responses: 200: description: Indicates a successful call. diff --git a/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml index b40186e83d8f5..69854a75d8f8b 100644 --- a/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml @@ -3206,8 +3206,8 @@ paths: properties: objects: description: >- - Array of `rule_id` fields. Exports all rules when - unspecified. + Array of objects with a rule's `rule_id` field. Do not use + rule's `id` here. Exports all rules when unspecified. items: type: object properties: @@ -4822,9 +4822,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -4848,9 +4850,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -4887,9 +4891,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -4993,9 +4999,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -5024,9 +5032,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -5052,9 +5062,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -5097,9 +5109,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -5124,9 +5138,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 diff --git a/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml index 2bb2d3dd9c623..61da9ade1a1bc 100644 --- a/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml @@ -2733,8 +2733,8 @@ paths: properties: objects: description: >- - Array of `rule_id` fields. Exports all rules when - unspecified. + Array of objects with a rule's `rule_id` field. Do not use + rule's `id` here. Exports all rules when unspecified. items: type: object properties: @@ -3887,9 +3887,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -3913,9 +3915,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -3952,9 +3956,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -4058,9 +4064,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -4089,9 +4097,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -4117,9 +4127,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -4162,9 +4174,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1 @@ -4189,9 +4203,11 @@ components: description: Gaps range start, valid only when query is provided type: string ids: - description: >- - Array of rule IDs. Array of rule IDs to which a bulk action will be - applied. Only valid when query property is undefined. + description: > + Array of rule `id`s to which a bulk action will be applied. Do not + use rule's `rule_id` here. + + Only valid when query property is undefined. items: type: string minItems: 1