diff --git a/.buildkite/scripts/steps/checks.sh b/.buildkite/scripts/steps/checks.sh index 2844d8eee212f..dd7c0c0e6d69c 100755 --- a/.buildkite/scripts/steps/checks.sh +++ b/.buildkite/scripts/steps/checks.sh @@ -13,4 +13,5 @@ fi .buildkite/scripts/steps/capture_oas_snapshot.sh .buildkite/scripts/steps/code_generation/elastic_assistant_codegen.sh .buildkite/scripts/steps/code_generation/security_solution_codegen.sh +.buildkite/scripts/steps/openapi_bundling/security_solution_openapi_bundling.sh .buildkite/scripts/steps/code_generation/osquery_codegen.sh diff --git a/.buildkite/scripts/steps/openapi_bundling/security_solution_openapi_bundling.sh b/.buildkite/scripts/steps/openapi_bundling/security_solution_openapi_bundling.sh old mode 100644 new mode 100755 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 0229f28a0941d..fd441941d52e7 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 @@ -39,20 +39,20 @@ paths: application/json: schema: oneOf: - - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + - $ref: '../../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + - $ref: '../../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' 401: description: Unsuccessful authentication response content: application/json: schema: - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + $ref: '../../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' 500: description: Internal server error response content: application/json: schema: - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + $ref: '../../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' post: x-labels: [ess] @@ -89,17 +89,17 @@ paths: application/json: schema: oneOf: - - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + - $ref: '../../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + - $ref: '../../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' 401: description: Unsuccessful authentication response content: application/json: schema: - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + $ref: '../../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' 500: description: Internal server error response content: application/json: schema: - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + $ref: '../../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' diff --git a/x-pack/plugins/security_solution/common/api/detection_engine/rule_preview/rule_preview.schema.yaml b/x-pack/plugins/security_solution/common/api/detection_engine/rule_preview/rule_preview.schema.yaml index 933dccc0b8d65..1d65d6b4e037e 100644 --- a/x-pack/plugins/security_solution/common/api/detection_engine/rule_preview/rule_preview.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/detection_engine/rule_preview/rule_preview.schema.yaml @@ -67,20 +67,20 @@ paths: application/json: schema: oneOf: - - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' - - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + - $ref: '../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + - $ref: '../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' 401: description: Unsuccessful authentication response content: application/json: schema: - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' + $ref: '../../model/error_responses.schema.yaml#/components/schemas/PlatformErrorResponse' 500: description: Internal server error response content: application/json: schema: - $ref: '../../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' + $ref: '../../model/error_responses.schema.yaml#/components/schemas/SiemErrorResponse' components: schemas: 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 ca8bae8f42f0f..2a239497d896e 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 @@ -14,6 +14,174 @@ servers: port: default: '5601' paths: + /api/detection_engine/index: + delete: + operationId: DeleteAlertsIndex + responses: + '200': + content: + application/json: + schema: + type: object + properties: + acknowledged: + type: boolean + required: + - acknowledged + description: Successful response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Not enough permissions response + '404': + content: + application/json: + schema: + type: string + description: Index does not exist response + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Delete an alerts index + tags: + - Alert index API + get: + operationId: GetAlertsIndex + responses: + '200': + content: + application/json: + schema: + type: object + properties: + index_mapping_outdated: + nullable: true + type: boolean + name: + type: string + required: + - name + - index_mapping_outdated + description: Successful response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Not enough permissions response + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Gets the alert index name if it exists + tags: + - Alert index API + post: + operationId: CreateAlertsIndex + responses: + '200': + content: + application/json: + schema: + type: object + properties: + acknowledged: + type: boolean + required: + - acknowledged + description: Successful response + '401': + content: + application/json: + schema: + $ref: '#/components/schemas/PlatformErrorResponse' + description: Unsuccessful authentication response + '403': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Not enough permissions response + '404': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + '500': + content: + application/json: + schema: + $ref: '#/components/schemas/SiemErrorResponse' + description: Internal server error response + summary: Create an alerts index + tags: + - Alert index API + /api/detection_engine/privileges: + get: + description: > + Retrieves whether or not the user is authenticated, and the user's + Kibana + + space and index privileges, which determine if the user can create an + + index for the Elastic Security alerts generated by + + detection engine rules. + operationId: GetPrivileges + responses: + '200': + content: + application/json: + schema: + type: object + properties: + has_encryption_key: + type: boolean + is_authenticated: + type: boolean + required: + - is_authenticated + - has_encryption_key + description: Successful 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: Returns user privileges for the Kibana space + tags: + - Privileges API /api/detection_engine/rules: delete: description: Deletes a single rule using the `rule_id` or `id` field. @@ -142,6 +310,7 @@ paths: - $ref: '#/components/schemas/BulkEnableRules' - $ref: '#/components/schemas/BulkExportRules' - $ref: '#/components/schemas/BulkDuplicateRules' + - $ref: '#/components/schemas/BulkManualRuleRun' - $ref: '#/components/schemas/BulkEditRules' responses: '200': @@ -206,6 +375,75 @@ paths: schema: $ref: '#/components/schemas/BulkCrudRulesResponse' description: Indicates a successful call. + '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 + tags: + - Bulk API + post: + deprecated: true + description: Deletes multiple rules. + operationId: BulkDeleteRulesPost + requestBody: + content: + application/json: + schema: + items: + type: object + properties: + id: + $ref: '#/components/schemas/RuleObjectId' + rule_id: + $ref: '#/components/schemas/RuleSignatureId' + type: array + description: >- + A JSON array of `id` or `rule_id` fields of the rules you want to + delete. + required: true + responses: + '200': + content: + application/json: + schema: + $ref: '#/components/schemas/BulkCrudRulesResponse' + description: Indicates a successful call. + '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 tags: - Bulk API /api/detection_engine/rules/_bulk_update: @@ -585,6 +823,85 @@ paths: summary: Get the status of Elastic prebuilt rules tags: - Prebuilt Rules API + /api/detection_engine/rules/preview: + post: + operationId: RulePreview + requestBody: + content: + application/json: + schema: + anyOf: + - allOf: + - $ref: '#/components/schemas/EqlRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/QueryRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/SavedQueryRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/ThresholdRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/ThreatMatchRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/MachineLearningRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/NewTermsRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/EsqlRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + discriminator: + propertyName: type + 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: + type: object + properties: + isAborted: + type: boolean + logs: + items: + $ref: '#/components/schemas/RulePreviewLogs' + type: array + previewId: + $ref: '#/components/schemas/NonEmptyString' + required: + - logs + 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: Preview rule alerts generated on specified time range + tags: + - Rule preview API /api/detection_engine/signals/assignees: post: description: Assigns users to alerts. @@ -611,6 +928,411 @@ paths: '400': description: Invalid request. summary: Assigns users to alerts + /api/detection_engine/signals/finalize_migration: + post: + description: > + The finalization endpoint 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: Finalizes alerts migration(s) + 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: Performs alerts migration(s) cleanup + tags: + - Alerts migration API + post: + 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: Initiates an alerts migration + tags: + - Alerts migration API + /api/detection_engine/signals/migration_status: + post: + 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: Returns an alerts migration status + tags: + - Alerts migration API + /api/detection_engine/signals/search: + post: + 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 that match the given query + tags: + - Alerts API + /api/detection_engine/signals/status: + post: + 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: Sets the status of one or more alerts + tags: + - Alerts API + /api/detection_engine/signals/tags: + post: + 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: Manage alert tags for a one or more alerts + tags: + - Alerts API /api/detection_engine/tags: get: operationId: ReadTags @@ -653,9 +1375,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 +1483,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 @@ -838,6 +1637,8 @@ components: - MACHINE_LEARNING_INDEX_PATTERN - ESQL_INDEX_PATTERN - INVESTIGATION_FIELDS_FEATURE + - MANUAL_RULE_RUN_FEATURE + - MANUAL_RULE_RUN_DISABLED_RULE type: string BulkActionSkipResult: type: object @@ -1057,6 +1858,36 @@ components: type: string required: - action + BulkManualRuleRun: + type: object + properties: + action: + enum: + - run + type: string + ids: + description: Array of rule IDs + items: + type: string + minItems: 1 + type: array + query: + description: Query to filter rules + type: string + run: + type: object + properties: + end_date: + description: End date of the manual rule run + type: string + start_date: + description: Start date of the manual rule run + type: string + required: + - start_date + required: + - action + - run ConcurrentSearches: minimum: 1 type: integer @@ -2065,6 +2896,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 @@ -2082,6 +2936,34 @@ components: required: - type InvestigationFields: + description: > + Schema for fields relating to investigation fields. These are user + defined fields we use to highlight + + in various features in the UI such as alert details flyout and + exceptions auto-population from alert. + + Added in PR #163235 + + Right now we only have a single field but anticipate adding more related + fields to store various + + configuration states such as `override` - where a user might say if they + want only these fields to + + display, or if they want these fields + the fields we select. When + expanding this field, it may look + + something like: + + ```typescript + + const investigationFields = z.object({ + field_names: NonEmptyArray(NonEmptyString), + override: z.boolean().optional(), + }); + + ``` type: object properties: field_names: @@ -2237,7 +3119,9 @@ components: - $ref: '#/components/schemas/ResponseFields' - $ref: '#/components/schemas/MachineLearningRuleResponseFields' MachineLearningRuleCreateFields: - $ref: '#/components/schemas/MachineLearningRuleRequiredFields' + allOf: + - $ref: '#/components/schemas/MachineLearningRuleRequiredFields' + - $ref: '#/components/schemas/MachineLearningRuleOptionalFields' MachineLearningRuleCreateProps: allOf: - type: object @@ -2332,18 +3216,25 @@ components: - risk_score - severity - $ref: '#/components/schemas/MachineLearningRuleCreateFields' - MachineLearningRulePatchFields: + MachineLearningRuleOptionalFields: type: object properties: - anomaly_threshold: - $ref: '#/components/schemas/AnomalyThreshold' - machine_learning_job_id: - $ref: '#/components/schemas/MachineLearningJobId' - type: - description: Rule type - enum: - - machine_learning - type: string + alert_suppression: + $ref: '#/components/schemas/AlertSuppression' + MachineLearningRulePatchFields: + allOf: + - type: object + properties: + anomaly_threshold: + $ref: '#/components/schemas/AnomalyThreshold' + machine_learning_job_id: + $ref: '#/components/schemas/MachineLearningJobId' + type: + description: Rule type + enum: + - machine_learning + type: string + - $ref: '#/components/schemas/MachineLearningRuleOptionalFields' MachineLearningRulePatchProps: allOf: - type: object @@ -2452,7 +3343,9 @@ components: - machine_learning_job_id - anomaly_threshold MachineLearningRuleResponseFields: - $ref: '#/components/schemas/MachineLearningRuleRequiredFields' + allOf: + - $ref: '#/components/schemas/MachineLearningRuleRequiredFields' + - $ref: '#/components/schemas/MachineLearningRuleOptionalFields' MachineLearningRuleUpdateProps: allOf: - type: object @@ -2549,9 +3442,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 @@ -3109,6 +4110,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: @@ -3590,6 +4604,63 @@ components: - severity - $ref: '#/components/schemas/QueryRuleCreateFields' RelatedIntegration: + description: > + Related integration is a potential dependency of a rule. It's assumed + that if the user installs + + one of the related integrations of a rule, the rule might start to work + properly because it will + + have source events (generated by this integration) potentially matching + the rule's query. + + + NOTE: Proper work is not guaranteed, because a related integration, if + installed, can be + + configured differently or generate data that is not necessarily relevant + for this rule. + + + Related integration is a combination of a Fleet package and (optionally) + one of the + + package's "integrations" that this package contains. It is represented + by 3 properties: + + + - `package`: name of the package (required, unique id) + + - `version`: version of the package (required, semver-compatible) + + - `integration`: name of the integration of this package (optional, id + within the package) + + + There are Fleet packages like `windows` that contain only one + integration; in this case, + + `integration` should be unspecified. There are also packages like `aws` + and `azure` that contain + + several integrations; in this case, `integration` should be specified. + + + @example + + const x: RelatedIntegration = { + package: 'windows', + version: '1.5.x', + }; + + + @example + + const x: RelatedIntegration = { + package: 'azure', + version: '~1.1.6', + integration: 'activitylogs', + }; type: object properties: integration: @@ -3606,7 +4677,40 @@ components: $ref: '#/components/schemas/RelatedIntegration' type: array RequiredField: - description: Describes an Elasticsearch field that is needed for the rule to function + description: > + Describes an Elasticsearch field that is needed for the rule to + function. + + + Almost all types of Security rules check source event documents for a + match to some kind of + + query or filter. If a document has certain field with certain values, + then it's a match and + + the rule will generate an alert. + + + Required field is an event field that must be present in the source + indices of a given rule. + + + @example + + const standardEcsField: RequiredField = { + name: 'event.action', + type: 'keyword', + ecs: true, + }; + + + @example + + const nonEcsField: RequiredField = { + name: 'winlog.event_data.AttributeLDAPDisplayName', + type: 'keyword', + ecs: false, + }; type: object properties: ecs: @@ -3976,6 +5080,37 @@ components: - $ref: '#/components/schemas/MachineLearningRulePatchProps' - $ref: '#/components/schemas/NewTermsRulePatchProps' - $ref: '#/components/schemas/EsqlRulePatchProps' + RulePreviewLogs: + type: object + properties: + duration: + description: Execution duration in milliseconds + type: integer + errors: + items: + $ref: '#/components/schemas/NonEmptyString' + type: array + startedAt: + $ref: '#/components/schemas/NonEmptyString' + warnings: + items: + $ref: '#/components/schemas/NonEmptyString' + type: array + required: + - errors + - warnings + - duration + RulePreviewParams: + type: object + properties: + invocationCount: + type: integer + timeframeEnd: + format: date-time + type: string + required: + - invocationCount + - timeframeEnd RuleQuery: type: string RuleReferenceArray: @@ -4500,6 +5635,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 +5696,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 @@ -5680,3 +6862,4 @@ components: type: http security: - BasicAuth: [] +tags: ! '' 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 94682a8e1b8f9..e39ba6065675a 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 @@ -14,6 +14,48 @@ servers: port: default: '5601' paths: + /api/detection_engine/privileges: + get: + description: > + Retrieves whether or not the user is authenticated, and the user's + Kibana + + space and index privileges, which determine if the user can create an + + index for the Elastic Security alerts generated by + + detection engine rules. + operationId: GetPrivileges + responses: + '200': + content: + application/json: + schema: + type: object + properties: + has_encryption_key: + type: boolean + is_authenticated: + type: boolean + required: + - is_authenticated + - has_encryption_key + description: Successful 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: Returns user privileges for the Kibana space + tags: + - Privileges API /api/detection_engine/rules: delete: description: Deletes a single rule using the `rule_id` or `id` field. @@ -142,6 +184,7 @@ paths: - $ref: '#/components/schemas/BulkEnableRules' - $ref: '#/components/schemas/BulkExportRules' - $ref: '#/components/schemas/BulkDuplicateRules' + - $ref: '#/components/schemas/BulkManualRuleRun' - $ref: '#/components/schemas/BulkEditRules' responses: '200': @@ -394,6 +437,85 @@ paths: tags: - Import/Export API summary: Imports rules from an `.ndjson` file + /api/detection_engine/rules/preview: + post: + operationId: RulePreview + requestBody: + content: + application/json: + schema: + anyOf: + - allOf: + - $ref: '#/components/schemas/EqlRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/QueryRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/SavedQueryRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/ThresholdRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/ThreatMatchRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/MachineLearningRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/NewTermsRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + - allOf: + - $ref: '#/components/schemas/EsqlRuleCreateProps' + - $ref: '#/components/schemas/RulePreviewParams' + discriminator: + propertyName: type + 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: + type: object + properties: + isAborted: + type: boolean + logs: + items: + $ref: '#/components/schemas/RulePreviewLogs' + type: array + previewId: + $ref: '#/components/schemas/NonEmptyString' + required: + - logs + 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: Preview rule alerts generated on specified time range + tags: + - Rule preview API /api/detection_engine/signals/assignees: post: description: Assigns users to alerts. @@ -420,6 +542,175 @@ paths: '400': description: Invalid request. summary: Assigns users to alerts + /api/detection_engine/signals/search: + post: + 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 that match the given query + tags: + - Alerts API + /api/detection_engine/signals/status: + post: + 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: Sets the status of one or more alerts + tags: + - Alerts API + /api/detection_engine/signals/tags: + post: + 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: Manage alert tags for a one or more alerts + tags: + - Alerts API /api/detection_engine/tags: get: operationId: ReadTags @@ -465,6 +756,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 +818,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 @@ -647,6 +962,8 @@ components: - MACHINE_LEARNING_INDEX_PATTERN - ESQL_INDEX_PATTERN - INVESTIGATION_FIELDS_FEATURE + - MANUAL_RULE_RUN_FEATURE + - MANUAL_RULE_RUN_DISABLED_RULE type: string BulkActionSkipResult: type: object @@ -860,6 +1177,36 @@ components: type: string required: - action + BulkManualRuleRun: + type: object + properties: + action: + enum: + - run + type: string + ids: + description: Array of rule IDs + items: + type: string + minItems: 1 + type: array + query: + description: Query to filter rules + type: string + run: + type: object + properties: + end_date: + description: End date of the manual rule run + type: string + start_date: + description: Start date of the manual rule run + type: string + required: + - start_date + required: + - action + - run ConcurrentSearches: minimum: 1 type: integer @@ -1885,6 +2232,34 @@ components: required: - type InvestigationFields: + description: > + Schema for fields relating to investigation fields. These are user + defined fields we use to highlight + + in various features in the UI such as alert details flyout and + exceptions auto-population from alert. + + Added in PR #163235 + + Right now we only have a single field but anticipate adding more related + fields to store various + + configuration states such as `override` - where a user might say if they + want only these fields to + + display, or if they want these fields + the fields we select. When + expanding this field, it may look + + something like: + + ```typescript + + const investigationFields = z.object({ + field_names: NonEmptyArray(NonEmptyString), + override: z.boolean().optional(), + }); + + ``` type: object properties: field_names: @@ -2040,7 +2415,9 @@ components: - $ref: '#/components/schemas/ResponseFields' - $ref: '#/components/schemas/MachineLearningRuleResponseFields' MachineLearningRuleCreateFields: - $ref: '#/components/schemas/MachineLearningRuleRequiredFields' + allOf: + - $ref: '#/components/schemas/MachineLearningRuleRequiredFields' + - $ref: '#/components/schemas/MachineLearningRuleOptionalFields' MachineLearningRuleCreateProps: allOf: - type: object @@ -2135,18 +2512,25 @@ components: - risk_score - severity - $ref: '#/components/schemas/MachineLearningRuleCreateFields' - MachineLearningRulePatchFields: + MachineLearningRuleOptionalFields: type: object properties: - anomaly_threshold: - $ref: '#/components/schemas/AnomalyThreshold' - machine_learning_job_id: - $ref: '#/components/schemas/MachineLearningJobId' - type: - description: Rule type - enum: - - machine_learning - type: string + alert_suppression: + $ref: '#/components/schemas/AlertSuppression' + MachineLearningRulePatchFields: + allOf: + - type: object + properties: + anomaly_threshold: + $ref: '#/components/schemas/AnomalyThreshold' + machine_learning_job_id: + $ref: '#/components/schemas/MachineLearningJobId' + type: + description: Rule type + enum: + - machine_learning + type: string + - $ref: '#/components/schemas/MachineLearningRuleOptionalFields' MachineLearningRulePatchProps: allOf: - type: object @@ -2255,7 +2639,9 @@ components: - machine_learning_job_id - anomaly_threshold MachineLearningRuleResponseFields: - $ref: '#/components/schemas/MachineLearningRuleRequiredFields' + allOf: + - $ref: '#/components/schemas/MachineLearningRuleRequiredFields' + - $ref: '#/components/schemas/MachineLearningRuleOptionalFields' MachineLearningRuleUpdateProps: allOf: - type: object @@ -2352,6 +2738,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 @@ -2912,6 +3308,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: @@ -3393,6 +3802,63 @@ components: - severity - $ref: '#/components/schemas/QueryRuleCreateFields' RelatedIntegration: + description: > + Related integration is a potential dependency of a rule. It's assumed + that if the user installs + + one of the related integrations of a rule, the rule might start to work + properly because it will + + have source events (generated by this integration) potentially matching + the rule's query. + + + NOTE: Proper work is not guaranteed, because a related integration, if + installed, can be + + configured differently or generate data that is not necessarily relevant + for this rule. + + + Related integration is a combination of a Fleet package and (optionally) + one of the + + package's "integrations" that this package contains. It is represented + by 3 properties: + + + - `package`: name of the package (required, unique id) + + - `version`: version of the package (required, semver-compatible) + + - `integration`: name of the integration of this package (optional, id + within the package) + + + There are Fleet packages like `windows` that contain only one + integration; in this case, + + `integration` should be unspecified. There are also packages like `aws` + and `azure` that contain + + several integrations; in this case, `integration` should be specified. + + + @example + + const x: RelatedIntegration = { + package: 'windows', + version: '1.5.x', + }; + + + @example + + const x: RelatedIntegration = { + package: 'azure', + version: '~1.1.6', + integration: 'activitylogs', + }; type: object properties: integration: @@ -3409,7 +3875,40 @@ components: $ref: '#/components/schemas/RelatedIntegration' type: array RequiredField: - description: Describes an Elasticsearch field that is needed for the rule to function + description: > + Describes an Elasticsearch field that is needed for the rule to + function. + + + Almost all types of Security rules check source event documents for a + match to some kind of + + query or filter. If a document has certain field with certain values, + then it's a match and + + the rule will generate an alert. + + + Required field is an event field that must be present in the source + indices of a given rule. + + + @example + + const standardEcsField: RequiredField = { + name: 'event.action', + type: 'keyword', + ecs: true, + }; + + + @example + + const nonEcsField: RequiredField = { + name: 'winlog.event_data.AttributeLDAPDisplayName', + type: 'keyword', + ecs: false, + }; type: object properties: ecs: @@ -3779,6 +4278,37 @@ components: - $ref: '#/components/schemas/MachineLearningRulePatchProps' - $ref: '#/components/schemas/NewTermsRulePatchProps' - $ref: '#/components/schemas/EsqlRulePatchProps' + RulePreviewLogs: + type: object + properties: + duration: + description: Execution duration in milliseconds + type: integer + errors: + items: + $ref: '#/components/schemas/NonEmptyString' + type: array + startedAt: + $ref: '#/components/schemas/NonEmptyString' + warnings: + items: + $ref: '#/components/schemas/NonEmptyString' + type: array + required: + - errors + - warnings + - duration + RulePreviewParams: + type: object + properties: + invocationCount: + type: integer + timeframeEnd: + format: date-time + type: string + required: + - invocationCount + - timeframeEnd RuleQuery: type: string RuleReferenceArray: @@ -4303,6 +4833,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 +4894,16 @@ components: - severity - value type: array + SiemErrorResponse: + type: object + properties: + message: + type: string + status_code: + type: integer + required: + - status_code + - message SortOrder: enum: - asc @@ -5483,3 +6053,4 @@ components: type: http security: - BasicAuth: [] +tags: ! ''