diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml index 739386d637ab..d6dc83592e6c 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/alert_assignees/set_alert_assignees_route.schema.yaml @@ -4,12 +4,15 @@ info: version: '2023-10-31' paths: /api/detection_engine/signals/assignees: - summary: Assigns users to alerts post: x-labels: [ess, serverless] x-codegen-enabled: true operationId: SetAlertAssignees - description: Assigns users to alerts. + summary: Assign and unassign users from detection alerts + description: | + Assign users to detection alerts, and unassign them from alerts. + > info + > You cannot add and remove the same assignee. requestBody: required: true content: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml index ca2c93b88b25..b6a07e04f89b 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/alert_tags/set_alert_tags/set_alert_tags.schema.yaml @@ -8,7 +8,11 @@ paths: x-labels: [serverless, ess] operationId: ManageAlertTags x-codegen-enabled: true - summary: Manage alert tags for a one or more alerts + summary: Add and remove detection alert tags + description: | + And tags to detection alerts, and remove them from alerts. + > info + > You cannot add and remove the same alert tag. tags: - Alerts API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_response_actions/response_actions.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_response_actions/response_actions.schema.yaml index 751a1efee8fa..3666b9e4e063 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_response_actions/response_actions.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_response_actions/response_actions.schema.yaml @@ -34,7 +34,7 @@ components: description: Query ID query: type: string - description: Query to execute + description: Query to run ecs_mapping: $ref: '#/components/schemas/EcsMapping' version: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_schema/common_attributes.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_schema/common_attributes.schema.yaml index cd5e238723f6..b5765d77a1f8 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_schema/common_attributes.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_schema/common_attributes.schema.yaml @@ -92,7 +92,7 @@ components: RuleIntervalFrom: type: string - description: Time from which data is analyzed each time the rule executes, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time). + description: Time from which data is analyzed each time the rule runs, using a date math range. For example, now-4200s means the rule analyzes data from 70 minutes before its start time. Defaults to now-6m (analyzes data from 6 minutes before the start time). format: date-math RuleIntervalTo: @@ -406,7 +406,7 @@ components: - field_names RuleActionThrottle: - description: Defines the interval on which a rule's actions are executed. + description: Defines how often rule actions are taken. oneOf: - type: string enum: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_schema/specific_attributes/threat_match_attributes.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_schema/specific_attributes/threat_match_attributes.schema.yaml index de43ecfeb073..6b9f8805d578 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_schema/specific_attributes/threat_match_attributes.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/model/rule_schema/specific_attributes/threat_match_attributes.schema.yaml @@ -8,7 +8,7 @@ components: schemas: ThreatQuery: type: string - description: Query to execute + description: Query to run ThreatMapping: type: array diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/prebuilt_rules/get_prebuilt_rules_and_timelines_status/get_prebuilt_rules_and_timelines_status_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/prebuilt_rules/get_prebuilt_rules_and_timelines_status/get_prebuilt_rules_and_timelines_status_route.schema.yaml index 92b82e9d1e84..bc44026806f6 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/prebuilt_rules/get_prebuilt_rules_and_timelines_status/get_prebuilt_rules_and_timelines_status_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/prebuilt_rules/get_prebuilt_rules_and_timelines_status/get_prebuilt_rules_and_timelines_status_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [ess] x-codegen-enabled: true operationId: GetPrebuiltRulesAndTimelinesStatus - summary: Get the status of Elastic prebuilt rules + summary: Retrieve the status of prebuilt detection rules and Timelines + description: Retrieve the status of all Elastic prebuilt detection rules and Timelines. tags: - Prebuilt Rules API responses: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/prebuilt_rules/install_prebuilt_rules_and_timelines/install_prebuilt_rules_and_timelines_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/prebuilt_rules/install_prebuilt_rules_and_timelines/install_prebuilt_rules_and_timelines_route.schema.yaml index ab27c71c4ef3..171070aa5e2d 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/prebuilt_rules/install_prebuilt_rules_and_timelines/install_prebuilt_rules_and_timelines_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/prebuilt_rules/install_prebuilt_rules_and_timelines/install_prebuilt_rules_and_timelines_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [ess] x-codegen-enabled: true operationId: InstallPrebuiltRulesAndTimelines - summary: Installs all Elastic prebuilt rules and timelines + summary: Install prebuilt detection rules and Timelines + description: Install and update all Elastic prebuilt detection rules and Timelines. tags: - Prebuilt Rules API responses: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml index a2e75b8ae4fb..022646dda04c 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_actions/bulk_actions_route.schema.yaml @@ -8,8 +8,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: PerformBulkAction - summary: Applies a bulk action to multiple rules - description: The bulk action is applied to all rules that match the filter or to the list of rules by their IDs. + summary: Apply a bulk action to detection rules + description: Apply a bulk action, such as bulk edit, duplicate, or delete, to multiple detection rules. The bulk action is applied to all rules that match the query or to the rules listed by their IDs. tags: - Bulk API parameters: @@ -339,7 +339,7 @@ components: properties: interval: type: string - description: Interval in which the rule is executed + description: Interval in which the rule runs. For example, `"1h"` means the rule runs every hour. pattern: '^[1-9]\d*[smh]$' # any number except zero followed by one of the suffixes 's', 'm', 'h' example: '1h' lookback: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_create_rules/bulk_create_rules_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_create_rules/bulk_create_rules_route.schema.yaml index 127ad9784988..8b024946bc22 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_create_rules/bulk_create_rules_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_create_rules/bulk_create_rules_route.schema.yaml @@ -9,7 +9,8 @@ paths: x-codegen-enabled: true operationId: BulkCreateRules deprecated: true - description: Creates new detection rules in bulk. + summary: Create multiple detection rules + description: Create new detection rules in bulk. tags: - Bulk API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_delete_rules/bulk_delete_rules_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_delete_rules/bulk_delete_rules_route.schema.yaml index 02f78a65fee7..2ccc3cee7180 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_delete_rules/bulk_delete_rules_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_delete_rules/bulk_delete_rules_route.schema.yaml @@ -9,7 +9,8 @@ paths: x-codegen-enabled: true operationId: BulkDeleteRules deprecated: true - description: Deletes multiple rules. + summary: Delete multiple detection rules + description: Delete detection rules in bulk. tags: - Bulk API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_patch_rules/bulk_patch_rules_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_patch_rules/bulk_patch_rules_route.schema.yaml index 65bd0e1a4ac3..8c414965385f 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_patch_rules/bulk_patch_rules_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_patch_rules/bulk_patch_rules_route.schema.yaml @@ -7,9 +7,10 @@ paths: patch: x-labels: [ess] x-codegen-enabled: true + summary: Patch multiple detection rules operationId: BulkPatchRules deprecated: true - description: Updates multiple rules using the `PATCH` method. + description: Update specific fields of existing detection rules using the `rule_id` or `id` field. tags: - Bulk API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_update_rules/bulk_update_rules_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_update_rules/bulk_update_rules_route.schema.yaml index 37241035439d..841abbaea8fc 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_update_rules/bulk_update_rules_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/bulk_crud/bulk_update_rules/bulk_update_rules_route.schema.yaml @@ -9,7 +9,11 @@ paths: x-codegen-enabled: true operationId: BulkUpdateRules deprecated: true - description: Updates multiple rules using the `PUT` method. + summary: Update multiple detection rules + description: | + Update multiple detection rules using the `rule_id` or `id` field. The original rules are replaced, and all unspecified fields are deleted. + > info + > You cannot modify the `id` or `rule_id` values. tags: - Bulk API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/create_rule/create_rule_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/create_rule/create_rule_route.schema.yaml index a5071837af2c..d3e3dca94d00 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/create_rule/create_rule_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/create_rule/create_rule_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: CreateRule - description: Create a single detection rule + summary: Create a detection rule + description: Create a new detection rule. tags: - Rules API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml index b6ef8a444eb5..78d34bc2c569 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/delete_rule/delete_rule_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: DeleteRule - description: Deletes a single rule using the `rule_id` or `id` field. + summary: Delete a detection rule + description: Delete a detection rule using the `rule_id` or `id` field. tags: - Rules API parameters: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/patch_rule/patch_rule_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/patch_rule/patch_rule_route.schema.yaml index aec02102bcca..1ef40635f330 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/patch_rule/patch_rule_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/patch_rule/patch_rule_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: PatchRule - description: Patch a single rule + summary: Patch a detection rule + description: Update specific fields of an existing detection rule using the `rule_id` or `id` field. tags: - Rules API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/read_rule/read_rule_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/read_rule/read_rule_route.schema.yaml index 817579eb8c27..b22de6af6a9b 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/read_rule/read_rule_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/read_rule/read_rule_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: ReadRule - description: Read a single rule + summary: Retrieve a detection rule + description: Retrieve a detection rule using the `rule_id` or `id` field. tags: - Rules API parameters: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/update_rule/update_rule_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/update_rule/update_rule_route.schema.yaml index de82265ca337..4450b0ec1f7d 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/update_rule/update_rule_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/crud/update_rule/update_rule_route.schema.yaml @@ -8,7 +8,11 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: UpdateRule - description: Update a single rule + summary: Update a detection rule + description: | + Update a detection rule using the `rule_id` or `id` field. The original rule is replaced, and all unspecified fields are deleted. + > info + > You cannot modify the `id` or `rule_id` values. tags: - Rules API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml index 0a88075abb15..cae20f30e2c7 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/export_rules/export_rules_route.schema.yaml @@ -4,13 +4,17 @@ info: version: '2023-10-31' paths: /api/detection_engine/rules/_export: - summary: Exports rules to an `.ndjson` file post: x-labels: [ess, serverless] x-codegen-enabled: true operationId: ExportRules - summary: Export rules - description: Exports rules to an `.ndjson` file. The following configuration items are also included in the `.ndjson` file - Actions, Exception lists. Prebuilt rules cannot be exported. + summary: Export detection rules + description: | + Export detection rules to an `.ndjson` file. The following configuration items are also included in the `.ndjson` file: + - Actions + - Exception lists + > info + > You cannot export prebuilt rules. tags: - Import/Export API parameters: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml index 4f27662e37bf..3be5404bae74 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/find_rules/find_rules_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: FindRules - description: Finds rules that match the given query. + summary: List all detection rules + description: Retrieve a paginated list of detection rules. By default, the first page is returned, with 20 results per page. tags: - Rules API parameters: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml index 9056fcea04bc..5d0b0c9d857b 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/import_rules/import_rules_route.schema.yaml @@ -4,13 +4,15 @@ info: version: '2023-10-31' paths: /api/detection_engine/rules/_import: - summary: Imports rules from an `.ndjson` file post: x-labels: [ess, serverless] x-codegen-enabled: true operationId: ImportRules - summary: Import rules - description: Imports rules from an `.ndjson` file, including actions and exception lists. + summary: Import detection rules + description: | + Import detection rules from an `.ndjson` file, including actions and exception lists. The request must include: + - The `Content-Type: multipart/form-data` HTTP header. + - A link to the `.ndjson` file containing the rules. tags: - Import/Export API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/read_tags/read_tags_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/read_tags/read_tags_route.schema.yaml index 0a9d622dd2d4..84ebd0605205 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/read_tags/read_tags_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_management/read_tags/read_tags_route.schema.yaml @@ -4,12 +4,12 @@ info: version: '2023-10-31' paths: /api/detection_engine/tags: - summary: Aggregates and returns rule tags get: x-labels: [ess, serverless] x-codegen-enabled: true operationId: ReadTags - summary: Aggregates and returns all unique tags from all rules + summary: List all detection rule tags + description: List all unique tags from all detection rules. tags: - Tags API responses: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml index cd70e4b0c407..00061cf50c60 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/signals/query_signals/query_signals_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: SearchAlerts x-codegen-enabled: true - summary: Find and/or aggregate detection alerts that match the given query + summary: Find and/or aggregate detection alerts + description: Find and/or aggregate detection alerts that match the given query. tags: - Alerts API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml index 29ee065c77e6..fe514c4dafe2 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/signals/set_signal_status/set_signals_status_route.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [serverless, ess] operationId: SetAlertsStatus x-codegen-enabled: true - summary: Sets the status of one or more alerts + summary: Set a detection alert status + description: Set the status of one or more detection alerts. tags: - Alerts API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml index 26204ea0d619..52178537d636 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/create_signals_migration/create_signals_migration.schema.yaml @@ -8,7 +8,10 @@ paths: x-labels: [ess] operationId: CreateAlertsMigration x-codegen-enabled: true - summary: Initiates an alerts migration + summary: Initiate a detection alert migration + description: | + Initiate a migration of detection alerts. + Migrations are initiated per index. While the process is neither destructive nor interferes with existing data, it may be resource-intensive. As such, it is recommended that you plan your migrations accordingly. tags: - Alerts migration API requestBody: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml index 7b8136f3702c..8aa36d8496d0 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/delete_signals_migration/delete_signals_migration.schema.yaml @@ -8,11 +8,13 @@ paths: x-labels: [ess] operationId: AlertsMigrationCleanup x-codegen-enabled: true - summary: Performs alerts migration(s) cleanup + summary: Clean up detection alert migrations description: | Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of the migration process. A successful migration will result in both the old and new indices being present. - As such, the old, orphaned index can (and likely should) be deleted. While you can delete these indices manually, + As such, the old, orphaned index can (and likely should) be deleted. + + While you can delete these indices manually, the endpoint accomplishes this task by applying a deletion policy to the relevant index, causing it to be deleted after 30 days. It also deletes other artifacts specific to the migration implementation. tags: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml index 3654973f9de7..d36df7383253 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/finalize_signals_migration/finalize_signals_migration.schema.yaml @@ -8,9 +8,9 @@ paths: x-labels: [ess] operationId: FinalizeAlertsMigration x-codegen-enabled: true - summary: Finalizes alerts migration(s) + summary: Finalize detection alert migrations description: | - The finalization endpoint replaces the original index's alias with the successfully migrated index's alias. + Finalize successful migrations of detection alerts. This replaces the original index's alias with the successfully migrated index's alias. The endpoint is idempotent; therefore, it can safely be used to poll a given migration and, upon completion, finalize it. tags: diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/get_signals_migration_status/get_signals_migration_status.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/get_signals_migration_status/get_signals_migration_status.schema.yaml index b480b4374498..64eafd09f65d 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/get_signals_migration_status/get_signals_migration_status.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/signals_migration/get_signals_migration_status/get_signals_migration_status.schema.yaml @@ -8,7 +8,8 @@ paths: x-labels: [ess] operationId: GetAlertsMigrationStatus x-codegen-enabled: true - summary: Returns an alerts migration status + summary: Retrieve the status of detection alert migrations + description: Retrieve indices that contain detection alerts of a particular age, along with migration information for each of those indices. tags: - Alerts migration API parameters: diff --git a/x-pack/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml b/x-pack/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml index ca8bae8f42f0..b62836910bc4 100644 --- a/x-pack/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/plugins/security_solution/docs/openapi/ess/security_solution_detections_api_2023_10_31.bundled.schema.yaml @@ -16,7 +16,7 @@ servers: paths: /api/detection_engine/rules: delete: - description: Deletes a single rule using the `rule_id` or `id` field. + description: Delete a detection rule using the `rule_id` or `id` field. operationId: DeleteRule parameters: - description: The rule's `id` value. @@ -38,10 +38,11 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Delete a detection rule tags: - Rules API get: - description: Read a single rule + description: Retrieve a detection rule using the `rule_id` or `id` field. operationId: ReadRule parameters: - description: The rule's `id` value. @@ -63,10 +64,13 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Retrieve a detection rule tags: - Rules API patch: - description: Patch a single rule + description: >- + Update specific fields of an existing detection rule using the `rule_id` + or `id` field. operationId: PatchRule requestBody: content: @@ -81,10 +85,11 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Patch a detection rule tags: - Rules API post: - description: Create a single detection rule + description: Create a new detection rule. operationId: CreateRule requestBody: content: @@ -99,10 +104,17 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Create a detection rule tags: - Rules API put: - description: Update a single rule + description: > + Update a detection rule using the `rule_id` or `id` field. The original + rule is replaced, and all unspecified fields are deleted. + + > info + + > You cannot modify the `id` or `rule_id` values. operationId: UpdateRule requestBody: content: @@ -117,13 +129,15 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Update a detection rule tags: - Rules API /api/detection_engine/rules/_bulk_action: post: description: >- - The bulk action is applied to all rules that match the filter or to the - list of rules by their IDs. + Apply a bulk action, such as bulk edit, duplicate, or delete, to + multiple detection rules. The bulk action is applied to all rules that + match the query or to the rules listed by their IDs. operationId: PerformBulkAction parameters: - description: Enables dry run mode for the request call. @@ -152,13 +166,13 @@ paths: - $ref: '#/components/schemas/BulkEditActionResponse' - $ref: '#/components/schemas/BulkExportActionResponse' description: OK - summary: Applies a bulk action to multiple rules + summary: Apply a bulk action to detection rules tags: - Bulk API /api/detection_engine/rules/_bulk_create: post: deprecated: true - description: Creates new detection rules in bulk. + description: Create new detection rules in bulk. operationId: BulkCreateRules requestBody: content: @@ -176,12 +190,13 @@ paths: schema: $ref: '#/components/schemas/BulkCrudRulesResponse' description: Indicates a successful call. + summary: Create multiple detection rules tags: - Bulk API /api/detection_engine/rules/_bulk_delete: delete: deprecated: true - description: Deletes multiple rules. + description: Delete detection rules in bulk. operationId: BulkDeleteRules requestBody: content: @@ -206,12 +221,15 @@ paths: schema: $ref: '#/components/schemas/BulkCrudRulesResponse' description: Indicates a successful call. + summary: Delete multiple detection rules tags: - Bulk API /api/detection_engine/rules/_bulk_update: patch: deprecated: true - description: Updates multiple rules using the `PATCH` method. + description: >- + Update specific fields of existing detection rules using the `rule_id` + or `id` field. operationId: BulkPatchRules requestBody: content: @@ -229,11 +247,18 @@ paths: schema: $ref: '#/components/schemas/BulkCrudRulesResponse' description: Indicates a successful call. + summary: Patch multiple detection rules tags: - Bulk API put: deprecated: true - description: Updates multiple rules using the `PUT` method. + description: > + Update multiple detection rules using the `rule_id` or `id` field. The + original rules are replaced, and all unspecified fields are deleted. + + > info + + > You cannot modify the `id` or `rule_id` values. operationId: BulkUpdateRules requestBody: content: @@ -253,14 +278,22 @@ paths: schema: $ref: '#/components/schemas/BulkCrudRulesResponse' description: Indicates a successful call. + summary: Update multiple detection rules tags: - Bulk API /api/detection_engine/rules/_export: post: - description: >- - Exports rules to an `.ndjson` file. The following configuration items - are also included in the `.ndjson` file - Actions, Exception lists. - Prebuilt rules cannot be exported. + description: > + Export detection rules to an `.ndjson` file. The following configuration + items are also included in the `.ndjson` file: + + - Actions + + - Exception lists + + > info + + > You cannot export prebuilt rules. operationId: ExportRules parameters: - description: Determines whether a summary of the exported rules is returned. @@ -308,13 +341,14 @@ paths: format: binary type: string description: Indicates a successful call. - summary: Export rules + summary: Export detection rules tags: - Import/Export API - summary: Exports rules to an `.ndjson` file /api/detection_engine/rules/_find: get: - description: Finds rules that match the given query. + description: >- + Retrieve a paginated list of detection rules. By default, the first page + is returned, with 20 results per page. operationId: FindRules parameters: - in: query @@ -381,13 +415,18 @@ paths: - total - data description: Successful response + summary: List all detection rules tags: - Rules API /api/detection_engine/rules/_import: post: - description: >- - Imports rules from an `.ndjson` file, including actions and exception - lists. + description: > + Import detection rules from an `.ndjson` file, including actions and + exception lists. The request must include: + + - The `Content-Type: multipart/form-data` HTTP header. + + - A link to the `.ndjson` file containing the rules. operationId: ImportRules parameters: - description: >- @@ -490,12 +529,12 @@ paths: - action_connectors_success - action_connectors_success_count description: Indicates a successful call. - summary: Import rules + summary: Import detection rules tags: - Import/Export API - summary: Imports rules from an `.ndjson` file /api/detection_engine/rules/prepackaged: put: + description: Install and update all Elastic prebuilt detection rules and Timelines. operationId: InstallPrebuiltRulesAndTimelines responses: '200': @@ -527,11 +566,14 @@ paths: - timelines_installed - timelines_updated description: Indicates a successful call - summary: Installs all Elastic prebuilt rules and timelines + summary: Install prebuilt detection rules and Timelines tags: - Prebuilt Rules API /api/detection_engine/rules/prepackaged/_status: get: + description: >- + Retrieve the status of all Elastic prebuilt detection rules and + Timelines. operationId: GetPrebuiltRulesAndTimelinesStatus responses: '200': @@ -582,12 +624,15 @@ paths: - timelines_not_installed - timelines_not_updated description: Indicates a successful call - summary: Get the status of Elastic prebuilt rules + summary: Retrieve the status of prebuilt detection rules and Timelines tags: - Prebuilt Rules API /api/detection_engine/signals/assignees: post: - description: Assigns users to alerts. + description: | + Assign users to detection alerts, and unassign them from alerts. + > info + > You cannot add and remove the same assignee. operationId: SetAlertAssignees requestBody: content: @@ -610,9 +655,433 @@ paths: description: Indicates a successful call. '400': description: Invalid request. - summary: Assigns users to alerts + summary: Assign and unassign users from detection alerts + /api/detection_engine/signals/finalize_migration: + post: + description: > + Finalize successful migrations of detection alerts. This replaces the + original index's alias with the successfully migrated index's alias. + + The endpoint is idempotent; therefore, it can safely be used to poll a + given migration and, upon completion, + + finalize it. + operationId: FinalizeAlertsMigration + requestBody: + content: + application/json: + schema: + type: object + properties: + migration_ids: + items: + type: string + minItems: 1 + type: array + required: + - migration_ids + description: Array of `migration_id`s to finalize + required: true + responses: + '200': + content: + application/json: + schema: + items: + $ref: '#/components/schemas/MigrationFinalizationResult' + type: array + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Finalize detection alert migrations + tags: + - Alerts migration API + /api/detection_engine/signals/migration: + delete: + description: > + Migrations favor data integrity over shard size. Consequently, unused or + orphaned indices are artifacts of + + the migration process. A successful migration will result in both the + old and new indices being present. + + As such, the old, orphaned index can (and likely should) be deleted. + + + While you can delete these indices manually, + + the endpoint accomplishes this task by applying a deletion policy to the + relevant index, causing it to be deleted + + after 30 days. It also deletes other artifacts specific to the migration + implementation. + operationId: AlertsMigrationCleanup + requestBody: + content: + application/json: + schema: + type: object + properties: + migration_ids: + items: + type: string + minItems: 1 + type: array + required: + - migration_ids + description: Array of `migration_id`s to cleanup + required: true + responses: + '200': + content: + application/json: + schema: + items: + $ref: '#/components/schemas/MigrationCleanupResult' + type: array + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Clean up detection alert migrations + tags: + - Alerts migration API + post: + description: > + Initiate a migration of detection alerts. + + Migrations are initiated per index. While the process is neither + destructive nor interferes with existing data, it may be + resource-intensive. As such, it is recommended that you plan your + migrations accordingly. + operationId: CreateAlertsMigration + requestBody: + content: + application/json: + schema: + allOf: + - type: object + properties: + index: + items: + $ref: '#/components/schemas/NonEmptyString' + minItems: 1 + type: array + required: + - index + - $ref: '#/components/schemas/AlertsReindexOptions' + description: Alerts migration parameters + required: true + responses: + '200': + content: + application/json: + schema: + type: object + properties: + indices: + items: + oneOf: + - $ref: '#/components/schemas/AlertsIndexMigrationSuccess' + - $ref: '#/components/schemas/AlertsIndexMigrationError' + - $ref: '#/components/schemas/SkippedAlertsIndexMigration' + type: array + required: + - indices + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Initiate a detection alert migration + tags: + - Alerts migration API + /api/detection_engine/signals/migration_status: + post: + description: >- + Retrieve indices that contain detection alerts of a particular age, + along with migration information for each of those indices. + operationId: GetAlertsMigrationStatus + parameters: + - description: Maximum age of qualifying detection alerts + in: query + name: from + required: true + schema: + description: > + Time from which data is analyzed. For example, now-4200s means the + rule analyzes data from 70 minutes + + before its start time. Defaults to now-6m (analyzes data from 6 + minutes before the start time). + format: date-math + type: string + responses: + '200': + content: + application/json: + schema: + type: object + properties: + indices: + items: + $ref: '#/components/schemas/IndexMigrationStatus' + type: array + required: + - indices + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Retrieve the status of detection alert migrations + tags: + - Alerts migration API + /api/detection_engine/signals/search: + post: + description: Find and/or aggregate detection alerts that match the given query. + operationId: SearchAlerts + requestBody: + content: + application/json: + schema: + description: Elasticsearch query and aggregation request + type: object + properties: + _source: + oneOf: + - type: boolean + - type: string + - items: + type: string + type: array + aggs: + additionalProperties: true + type: object + fields: + items: + type: string + type: array + query: + additionalProperties: true + type: object + runtime_mappings: + additionalProperties: true + type: object + size: + minimum: 0 + type: integer + sort: + $ref: '#/components/schemas/AlertsSort' + track_total_hits: + type: boolean + description: Search and/or aggregation query + required: true + responses: + '200': + content: + application/json: + schema: + additionalProperties: true + description: Elasticsearch search response + type: object + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Find and/or aggregate detection alerts + tags: + - Alerts API + /api/detection_engine/signals/status: + post: + description: Set the status of one or more detection alerts. + operationId: SetAlertsStatus + requestBody: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/SetAlertsStatusByIds' + - $ref: '#/components/schemas/SetAlertsStatusByQuery' + description: >- + An object containing desired status and explicit alert ids or a query + to select alerts + required: true + responses: + '200': + content: + application/json: + schema: + additionalProperties: true + description: Elasticsearch update by query response + type: object + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Set a detection alert status + tags: + - Alerts API + /api/detection_engine/signals/tags: + post: + description: | + And tags to detection alerts, and remove them from alerts. + > info + > You cannot add and remove the same alert tag. + operationId: ManageAlertTags + requestBody: + content: + application/json: + schema: + type: object + properties: + ids: + $ref: '#/components/schemas/AlertIds' + tags: + $ref: '#/components/schemas/ManageAlertTags' + required: + - ids + - tags + description: >- + An object containing tags to add or remove and alert ids the changes + will be applied + required: true + responses: + '200': + content: + application/json: + schema: + additionalProperties: true + description: Elasticsearch update by query response + type: object + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Add and remove detection alert tags + tags: + - Alerts API /api/detection_engine/tags: get: + description: List all unique tags from all detection rules. operationId: ReadTags responses: '200': @@ -621,10 +1090,9 @@ paths: schema: $ref: '#/components/schemas/RuleTagArray' description: Indicates a successful call - summary: Aggregates and returns all unique tags from all rules + summary: List all detection rule tags tags: - Tags API - summary: Aggregates and returns rule tags components: schemas: AlertAssignees: @@ -653,9 +1121,70 @@ components: deprecated: true description: (deprecated) Has no effect. type: string + AlertsIndexMigrationError: + type: object + properties: + error: + type: object + properties: + message: + type: string + status_code: + type: string + required: + - message + - status_code + index: + type: string + required: + - index + - error + AlertsIndexMigrationSuccess: + type: object + properties: + index: + type: string + migration_id: + type: string + migration_index: + type: string + required: + - index + - migration_id + - migration_index AlertsIndexNamespace: description: Has no effect. type: string + AlertsReindexOptions: + type: object + properties: + requests_per_second: + minimum: 1 + type: integer + size: + minimum: 1 + type: integer + slices: + minimum: 1 + type: integer + AlertsSort: + oneOf: + - $ref: '#/components/schemas/AlertsSortCombinations' + - items: + $ref: '#/components/schemas/AlertsSortCombinations' + type: array + AlertsSortCombinations: + anyOf: + - type: string + - additionalProperties: true + type: object + AlertStatus: + enum: + - open + - closed + - acknowledged + - in-progress + type: string AlertSuppression: type: object properties: @@ -700,6 +1229,22 @@ components: - doNotSuppress - suppress type: string + AlertTag: + $ref: '#/components/schemas/NonEmptyString' + AlertTags: + items: + $ref: '#/components/schemas/AlertTag' + type: array + AlertVersion: + type: object + properties: + count: + type: integer + version: + type: integer + required: + - version + - count AnomalyThreshold: description: Anomaly threshold minimum: 0 @@ -782,7 +1327,9 @@ components: type: object properties: interval: - description: Interval in which the rule is executed + description: >- + Interval in which the rule runs. For example, `"1h"` means the + rule runs every hour. example: 1h pattern: '^[1-9]\d*[smh]$' type: string @@ -2065,6 +2612,29 @@ components: type: string HistoryWindowStart: $ref: '#/components/schemas/NonEmptyString' + IndexMigrationStatus: + type: object + properties: + index: + $ref: '#/components/schemas/NonEmptyString' + is_outdated: + type: boolean + migrations: + items: + $ref: '#/components/schemas/MigrationStatus' + type: array + signal_versions: + items: + $ref: '#/components/schemas/AlertVersion' + type: array + version: + type: integer + required: + - index + - version + - signal_versions + - migrations + - is_outdated IndexPatternArray: items: type: string @@ -2549,9 +3119,117 @@ components: - risk_score - severity - $ref: '#/components/schemas/MachineLearningRuleCreateFields' + ManageAlertTags: + type: object + properties: + tags_to_add: + $ref: '#/components/schemas/AlertTags' + tags_to_remove: + $ref: '#/components/schemas/AlertTags' + required: + - tags_to_add + - tags_to_remove MaxSignals: minimum: 1 type: integer + MigrationCleanupResult: + type: object + properties: + destinationIndex: + type: string + error: + type: object + properties: + message: + type: string + status_code: + type: integer + required: + - message + - status_code + id: + type: string + sourceIndex: + type: string + status: + enum: + - success + - failure + - pending + type: string + updated: + format: date-time + type: string + version: + type: string + required: + - id + - destinationIndex + - status + - sourceIndex + - version + - updated + MigrationFinalizationResult: + type: object + properties: + completed: + type: boolean + destinationIndex: + type: string + error: + type: object + properties: + message: + type: string + status_code: + type: integer + required: + - message + - status_code + id: + type: string + sourceIndex: + type: string + status: + enum: + - success + - failure + - pending + type: string + updated: + format: date-time + type: string + version: + type: string + required: + - id + - completed + - destinationIndex + - status + - sourceIndex + - version + - updated + MigrationStatus: + type: object + properties: + id: + $ref: '#/components/schemas/NonEmptyString' + status: + enum: + - success + - failure + - pending + type: string + updated: + format: date-time + type: string + version: + type: integer + required: + - id + - status + - version + - updated NewTermsFields: items: type: string @@ -3085,7 +3763,7 @@ components: platform: type: string query: - description: Query to execute + description: Query to run type: string removed: type: boolean @@ -3109,6 +3787,19 @@ components: required: - action_type_id - params + PlatformErrorResponse: + type: object + properties: + error: + type: string + message: + type: string + statusCode: + type: integer + required: + - statusCode + - error + - message ProcessesParams: type: object properties: @@ -3782,7 +4473,7 @@ components: to the connector type. type: object RuleActionThrottle: - description: Defines the interval on which a rule's actions are executed. + description: Defines how often rule actions are taken. oneOf: - enum: - no_actions @@ -3944,10 +4635,10 @@ components: type: string RuleIntervalFrom: description: >- - Time from which data is analyzed each time the rule executes, using a - date math range. For example, now-4200s means the rule analyzes data - from 70 minutes before its start time. Defaults to now-6m (analyzes data - from 6 minutes before the start time). + Time from which data is analyzed each time the rule runs, using a date + math range. For example, now-4200s means the rule analyzes data from 70 + minutes before its start time. Defaults to now-6m (analyzes data from 6 + minutes before the start time). format: date-math type: string RuleIntervalTo: @@ -4500,6 +5191,36 @@ components: - risk_score - severity - $ref: '#/components/schemas/SavedQueryRuleCreateFields' + SetAlertsStatusByIds: + type: object + properties: + signal_ids: + items: + $ref: '#/components/schemas/NonEmptyString' + minItems: 1 + type: array + status: + $ref: '#/components/schemas/AlertStatus' + required: + - signal_ids + - status + SetAlertsStatusByQuery: + type: object + properties: + conflicts: + default: abort + enum: + - abort + - proceed + type: string + query: + additionalProperties: true + type: object + status: + $ref: '#/components/schemas/AlertStatus' + required: + - query + - status SetupGuide: type: string Severity: @@ -4531,6 +5252,23 @@ components: - severity - value type: array + SiemErrorResponse: + type: object + properties: + message: + type: string + status_code: + type: integer + required: + - status_code + - message + SkippedAlertsIndexMigration: + type: object + properties: + index: + type: string + required: + - index SortOrder: enum: - asc @@ -5073,7 +5811,7 @@ components: - severity - $ref: '#/components/schemas/ThreatMatchRuleCreateFields' ThreatQuery: - description: Query to execute + description: Query to run type: string ThreatSubtechnique: type: object diff --git a/x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml b/x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml index 94682a8e1b8f..218c488100a5 100644 --- a/x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_detections_api_2023_10_31.bundled.schema.yaml @@ -16,7 +16,7 @@ servers: paths: /api/detection_engine/rules: delete: - description: Deletes a single rule using the `rule_id` or `id` field. + description: Delete a detection rule using the `rule_id` or `id` field. operationId: DeleteRule parameters: - description: The rule's `id` value. @@ -38,10 +38,11 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Delete a detection rule tags: - Rules API get: - description: Read a single rule + description: Retrieve a detection rule using the `rule_id` or `id` field. operationId: ReadRule parameters: - description: The rule's `id` value. @@ -63,10 +64,13 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Retrieve a detection rule tags: - Rules API patch: - description: Patch a single rule + description: >- + Update specific fields of an existing detection rule using the `rule_id` + or `id` field. operationId: PatchRule requestBody: content: @@ -81,10 +85,11 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Patch a detection rule tags: - Rules API post: - description: Create a single detection rule + description: Create a new detection rule. operationId: CreateRule requestBody: content: @@ -99,10 +104,17 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Create a detection rule tags: - Rules API put: - description: Update a single rule + description: > + Update a detection rule using the `rule_id` or `id` field. The original + rule is replaced, and all unspecified fields are deleted. + + > info + + > You cannot modify the `id` or `rule_id` values. operationId: UpdateRule requestBody: content: @@ -117,13 +129,15 @@ paths: schema: $ref: '#/components/schemas/RuleResponse' description: Indicates a successful call. + summary: Update a detection rule tags: - Rules API /api/detection_engine/rules/_bulk_action: post: description: >- - The bulk action is applied to all rules that match the filter or to the - list of rules by their IDs. + Apply a bulk action, such as bulk edit, duplicate, or delete, to + multiple detection rules. The bulk action is applied to all rules that + match the query or to the rules listed by their IDs. operationId: PerformBulkAction parameters: - description: Enables dry run mode for the request call. @@ -152,15 +166,22 @@ paths: - $ref: '#/components/schemas/BulkEditActionResponse' - $ref: '#/components/schemas/BulkExportActionResponse' description: OK - summary: Applies a bulk action to multiple rules + summary: Apply a bulk action to detection rules tags: - Bulk API /api/detection_engine/rules/_export: post: - description: >- - Exports rules to an `.ndjson` file. The following configuration items - are also included in the `.ndjson` file - Actions, Exception lists. - Prebuilt rules cannot be exported. + description: > + Export detection rules to an `.ndjson` file. The following configuration + items are also included in the `.ndjson` file: + + - Actions + + - Exception lists + + > info + + > You cannot export prebuilt rules. operationId: ExportRules parameters: - description: Determines whether a summary of the exported rules is returned. @@ -208,13 +229,14 @@ paths: format: binary type: string description: Indicates a successful call. - summary: Export rules + summary: Export detection rules tags: - Import/Export API - summary: Exports rules to an `.ndjson` file /api/detection_engine/rules/_find: get: - description: Finds rules that match the given query. + description: >- + Retrieve a paginated list of detection rules. By default, the first page + is returned, with 20 results per page. operationId: FindRules parameters: - in: query @@ -281,13 +303,18 @@ paths: - total - data description: Successful response + summary: List all detection rules tags: - Rules API /api/detection_engine/rules/_import: post: - description: >- - Imports rules from an `.ndjson` file, including actions and exception - lists. + description: > + Import detection rules from an `.ndjson` file, including actions and + exception lists. The request must include: + + - The `Content-Type: multipart/form-data` HTTP header. + + - A link to the `.ndjson` file containing the rules. operationId: ImportRules parameters: - description: >- @@ -390,13 +417,15 @@ paths: - action_connectors_success - action_connectors_success_count description: Indicates a successful call. - summary: Import rules + summary: Import detection rules tags: - Import/Export API - summary: Imports rules from an `.ndjson` file /api/detection_engine/signals/assignees: post: - description: Assigns users to alerts. + description: | + Assign users to detection alerts, and unassign them from alerts. + > info + > You cannot add and remove the same assignee. operationId: SetAlertAssignees requestBody: content: @@ -419,9 +448,185 @@ paths: description: Indicates a successful call. '400': description: Invalid request. - summary: Assigns users to alerts + summary: Assign and unassign users from detection alerts + /api/detection_engine/signals/search: + post: + description: Find and/or aggregate detection alerts that match the given query. + operationId: SearchAlerts + requestBody: + content: + application/json: + schema: + description: Elasticsearch query and aggregation request + type: object + properties: + _source: + oneOf: + - type: boolean + - type: string + - items: + type: string + type: array + aggs: + additionalProperties: true + type: object + fields: + items: + type: string + type: array + query: + additionalProperties: true + type: object + runtime_mappings: + additionalProperties: true + type: object + size: + minimum: 0 + type: integer + sort: + $ref: '#/components/schemas/AlertsSort' + track_total_hits: + type: boolean + description: Search and/or aggregation query + required: true + responses: + '200': + content: + application/json: + schema: + additionalProperties: true + description: Elasticsearch search response + type: object + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Find and/or aggregate detection alerts + tags: + - Alerts API + /api/detection_engine/signals/status: + post: + description: Set the status of one or more detection alerts. + operationId: SetAlertsStatus + requestBody: + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/SetAlertsStatusByIds' + - $ref: '#/components/schemas/SetAlertsStatusByQuery' + description: >- + An object containing desired status and explicit alert ids or a query + to select alerts + required: true + responses: + '200': + content: + application/json: + schema: + additionalProperties: true + description: Elasticsearch update by query response + type: object + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Set a detection alert status + tags: + - Alerts API + /api/detection_engine/signals/tags: + post: + description: | + And tags to detection alerts, and remove them from alerts. + > info + > You cannot add and remove the same alert tag. + operationId: ManageAlertTags + requestBody: + content: + application/json: + schema: + type: object + properties: + ids: + $ref: '#/components/schemas/AlertIds' + tags: + $ref: '#/components/schemas/ManageAlertTags' + required: + - ids + - tags + description: >- + An object containing tags to add or remove and alert ids the changes + will be applied + required: true + responses: + '200': + content: + application/json: + schema: + additionalProperties: true + description: Elasticsearch update by query response + type: object + description: Successful response + '400': + content: + application/json: + schema: + oneOf: + - $ref: '#/components/schemas/PlatformErrorResponse' + - $ref: '#/components/schemas/SiemErrorResponse' + description: Invalid input data response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Add and remove detection alert tags + tags: + - Alerts API /api/detection_engine/tags: get: + description: List all unique tags from all detection rules. operationId: ReadTags responses: '200': @@ -430,10 +635,9 @@ paths: schema: $ref: '#/components/schemas/RuleTagArray' description: Indicates a successful call - summary: Aggregates and returns all unique tags from all rules + summary: List all detection rule tags tags: - Tags API - summary: Aggregates and returns rule tags components: schemas: AlertAssignees: @@ -465,6 +669,24 @@ components: AlertsIndexNamespace: description: Has no effect. type: string + AlertsSort: + oneOf: + - $ref: '#/components/schemas/AlertsSortCombinations' + - items: + $ref: '#/components/schemas/AlertsSortCombinations' + type: array + AlertsSortCombinations: + anyOf: + - type: string + - additionalProperties: true + type: object + AlertStatus: + enum: + - open + - closed + - acknowledged + - in-progress + type: string AlertSuppression: type: object properties: @@ -509,6 +731,12 @@ components: - doNotSuppress - suppress type: string + AlertTag: + $ref: '#/components/schemas/NonEmptyString' + AlertTags: + items: + $ref: '#/components/schemas/AlertTag' + type: array AnomalyThreshold: description: Anomaly threshold minimum: 0 @@ -591,7 +819,9 @@ components: type: object properties: interval: - description: Interval in which the rule is executed + description: >- + Interval in which the rule runs. For example, `"1h"` means the + rule runs every hour. example: 1h pattern: '^[1-9]\d*[smh]$' type: string @@ -2352,6 +2582,16 @@ components: - risk_score - severity - $ref: '#/components/schemas/MachineLearningRuleCreateFields' + ManageAlertTags: + type: object + properties: + tags_to_add: + $ref: '#/components/schemas/AlertTags' + tags_to_remove: + $ref: '#/components/schemas/AlertTags' + required: + - tags_to_add + - tags_to_remove MaxSignals: minimum: 1 type: integer @@ -2888,7 +3128,7 @@ components: platform: type: string query: - description: Query to execute + description: Query to run type: string removed: type: boolean @@ -2912,6 +3152,19 @@ components: required: - action_type_id - params + PlatformErrorResponse: + type: object + properties: + error: + type: string + message: + type: string + statusCode: + type: integer + required: + - statusCode + - error + - message ProcessesParams: type: object properties: @@ -3585,7 +3838,7 @@ components: to the connector type. type: object RuleActionThrottle: - description: Defines the interval on which a rule's actions are executed. + description: Defines how often rule actions are taken. oneOf: - enum: - no_actions @@ -3747,10 +4000,10 @@ components: type: string RuleIntervalFrom: description: >- - Time from which data is analyzed each time the rule executes, using a - date math range. For example, now-4200s means the rule analyzes data - from 70 minutes before its start time. Defaults to now-6m (analyzes data - from 6 minutes before the start time). + Time from which data is analyzed each time the rule runs, using a date + math range. For example, now-4200s means the rule analyzes data from 70 + minutes before its start time. Defaults to now-6m (analyzes data from 6 + minutes before the start time). format: date-math type: string RuleIntervalTo: @@ -4303,6 +4556,36 @@ components: - risk_score - severity - $ref: '#/components/schemas/SavedQueryRuleCreateFields' + SetAlertsStatusByIds: + type: object + properties: + signal_ids: + items: + $ref: '#/components/schemas/NonEmptyString' + minItems: 1 + type: array + status: + $ref: '#/components/schemas/AlertStatus' + required: + - signal_ids + - status + SetAlertsStatusByQuery: + type: object + properties: + conflicts: + default: abort + enum: + - abort + - proceed + type: string + query: + additionalProperties: true + type: object + status: + $ref: '#/components/schemas/AlertStatus' + required: + - query + - status SetupGuide: type: string Severity: @@ -4334,6 +4617,16 @@ components: - severity - value type: array + SiemErrorResponse: + type: object + properties: + message: + type: string + status_code: + type: integer + required: + - status_code + - message SortOrder: enum: - asc @@ -4876,7 +5169,7 @@ components: - severity - $ref: '#/components/schemas/ThreatMatchRuleCreateFields' ThreatQuery: - description: Query to execute + description: Query to run type: string ThreatSubtechnique: type: object