From 59e5cd928311fd70686c536d4451ec326dcf6edf Mon Sep 17 00:00:00 2001 From: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> Date: Thu, 19 Dec 2024 13:30:00 +0000 Subject: [PATCH] [8.17] Improves Entity Analytics API content (#193404) (#204914) # Backport This will backport the following commits from `main` to `8.17`: - [Improves Entity Analytics API content (#193404)](https://github.com/elastic/kibana/pull/193404) ### Questions ? Please refer to the [Backport tool documentation](https://github.com/sqren/backport) --------- Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com> --- oas_docs/output/kibana.yaml | 27 ++++++++----- .../bulk_upload_asset_criticality.schema.yaml | 7 +++- .../create_asset_criticality.schema.yaml | 7 +++- .../delete_asset_criticality.schema.yaml | 4 +- .../get_asset_criticality.schema.yaml | 4 +- .../list_asset_criticality.schema.yaml | 2 +- .../engine_schedule_now_route.schema.yaml | 3 +- .../common/api/quickstart_client.gen.ts | 21 +++++++--- ...alytics_api_2023_10_31.bundled.schema.yaml | 39 +++++++++++++------ ...alytics_api_2023_10_31.bundled.schema.yaml | 39 +++++++++++++------ .../services/security_solution_api.gen.ts | 21 +++++++--- 11 files changed, 118 insertions(+), 56 deletions(-) diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml index dacc4b3d10b33..54b0e0456f1c1 100644 --- a/oas_docs/output/kibana.yaml +++ b/oas_docs/output/kibana.yaml @@ -6436,7 +6436,7 @@ paths: - APM sourcemaps /api/asset_criticality: delete: - description: Delete the asset criticality record for a specific asset if it exists. + description: Delete the asset criticality record for a specific entity. operationId: DeleteAssetCriticalityRecord parameters: - description: The ID value of the asset. @@ -6478,11 +6478,11 @@ paths: description: Successful response '400': description: Invalid request - summary: Delete Criticality Record + summary: Delete an asset criticality record tags: - Security Entity Analytics API get: - description: Get the criticality record for a specific asset. + description: Get the asset criticality record for a specific entity. operationId: GetAssetCriticalityRecord parameters: - description: The ID value of the asset. @@ -6509,11 +6509,14 @@ paths: description: Invalid request '404': description: Criticality record not found - summary: Get Criticality Record + summary: Get an asset criticality record tags: - Security Entity Analytics API post: - description: Create or update a criticality record for a specific asset. + description: | + Create or update an asset criticality record for a specific entity. + + If a record already exists for the specified entity, that record is overwritten with the specified value. If a record doesn't exist for the specified entity, a new record is created. operationId: CreateAssetCriticalityRecord requestBody: content: @@ -6538,12 +6541,15 @@ paths: description: Successful response '400': description: Invalid request - summary: Upsert Criticality Record + summary: Upsert an asset criticality record tags: - Security Entity Analytics API /api/asset_criticality/bulk: post: - description: Bulk upsert up to 1000 asset criticality records, creating or updating them as needed. + description: | + Bulk upsert up to 1000 asset criticality records. + + If asset criticality records already exist for the specified entities, those records are overwritten with the specified values. If asset criticality records don't exist for the specified entities, new records are created. operationId: BulkUpsertAssetCriticalityRecords requestBody: content: @@ -6594,7 +6600,7 @@ paths: description: Bulk upload successful '413': description: File too large - summary: Bulk Upsert Asset Criticality Records + summary: Bulk upsert asset criticality records tags: - Security Entity Analytics API /api/asset_criticality/list: @@ -6670,7 +6676,7 @@ paths: - per_page - total description: Bulk upload successful - summary: List Asset Criticality Records + summary: List asset criticality records tags: - Security Entity Analytics API /api/cases: @@ -17953,6 +17959,7 @@ paths: - Security Entity Analytics API /api/risk_score/engine/schedule_now: post: + description: Schedule the risk scoring engine to run as soon as possible. You can use this to recalculate entity risk scores after updating their asset criticality. operationId: ScheduleRiskEngineNow requestBody: content: @@ -17976,7 +17983,7 @@ paths: schema: $ref: '#/components/schemas/Security_Entity_Analytics_API_RiskEngineScheduleNowErrorResponse' description: Unexpected error - summary: Schedule the risk engine to run as soon as possible + summary: Run the risk scoring engine tags: - Security Entity Analytics API /api/saved_objects/_bulk_create: diff --git a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/bulk_upload_asset_criticality.schema.yaml b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/bulk_upload_asset_criticality.schema.yaml index 1e7a9b6ca3372..1f372fb14adba 100644 --- a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/bulk_upload_asset_criticality.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/bulk_upload_asset_criticality.schema.yaml @@ -9,8 +9,11 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: BulkUpsertAssetCriticalityRecords - summary: Bulk Upsert Asset Criticality Records - description: Bulk upsert up to 1000 asset criticality records, creating or updating them as needed. + summary: Bulk upsert asset criticality records + description: | + Bulk upsert up to 1000 asset criticality records. + + If asset criticality records already exist for the specified entities, those records are overwritten with the specified values. If asset criticality records don't exist for the specified entities, new records are created. requestBody: content: application/json: diff --git a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/create_asset_criticality.schema.yaml b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/create_asset_criticality.schema.yaml index 13a9e831a2cd5..15e75c3caa080 100644 --- a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/create_asset_criticality.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/create_asset_criticality.schema.yaml @@ -9,8 +9,11 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: CreateAssetCriticalityRecord - summary: Upsert Criticality Record - description: Create or update a criticality record for a specific asset. + summary: Upsert an asset criticality record + description: | + Create or update an asset criticality record for a specific entity. + + If a record already exists for the specified entity, that record is overwritten with the specified value. If a record doesn't exist for the specified entity, a new record is created. requestBody: required: true content: diff --git a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.schema.yaml b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.schema.yaml index f74cf5791aa21..f393e7fbc6e01 100644 --- a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.schema.yaml @@ -9,8 +9,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: DeleteAssetCriticalityRecord - summary: Delete Criticality Record - description: Delete the asset criticality record for a specific asset if it exists. + summary: Delete an asset criticality record + description: Delete the asset criticality record for a specific entity. parameters: - name: id_value in: query diff --git a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/get_asset_criticality.schema.yaml b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/get_asset_criticality.schema.yaml index a162cf3944c69..a11ea07c6a270 100644 --- a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/get_asset_criticality.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/get_asset_criticality.schema.yaml @@ -9,8 +9,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: GetAssetCriticalityRecord - summary: Get Criticality Record - description: Get the criticality record for a specific asset. + summary: Get an asset criticality record + description: Get the asset criticality record for a specific entity. parameters: - name: id_value in: query diff --git a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/list_asset_criticality.schema.yaml b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/list_asset_criticality.schema.yaml index 020727c4638d7..f8b0a2caa2257 100644 --- a/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/list_asset_criticality.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/entity_analytics/asset_criticality/list_asset_criticality.schema.yaml @@ -9,7 +9,7 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: FindAssetCriticalityRecords - summary: List Asset Criticality Records + summary: List asset criticality records description: List asset criticality records, paging, sorting and filtering as needed. parameters: - name: sort_field diff --git a/x-pack/plugins/security_solution/common/api/entity_analytics/risk_engine/engine_schedule_now_route.schema.yaml b/x-pack/plugins/security_solution/common/api/entity_analytics/risk_engine/engine_schedule_now_route.schema.yaml index 4a09e8d08666f..b395ba2db967e 100644 --- a/x-pack/plugins/security_solution/common/api/entity_analytics/risk_engine/engine_schedule_now_route.schema.yaml +++ b/x-pack/plugins/security_solution/common/api/entity_analytics/risk_engine/engine_schedule_now_route.schema.yaml @@ -19,7 +19,8 @@ paths: x-labels: [ess, serverless] x-codegen-enabled: true operationId: ScheduleRiskEngineNow - summary: Schedule the risk engine to run as soon as possible + summary: Run the risk scoring engine + description: Schedule the risk scoring engine to run as soon as possible. You can use this to recalculate entity risk scores after updating their asset criticality. requestBody: content: application/json: {} diff --git a/x-pack/plugins/security_solution/common/api/quickstart_client.gen.ts b/x-pack/plugins/security_solution/common/api/quickstart_client.gen.ts index 2061354fc2db2..e9529dbfd782d 100644 --- a/x-pack/plugins/security_solution/common/api/quickstart_client.gen.ts +++ b/x-pack/plugins/security_solution/common/api/quickstart_client.gen.ts @@ -544,8 +544,11 @@ after 30 days. It also deletes other artifacts specific to the migration impleme .catch(catchAxiosErrorFormatAndThrow); } /** - * Bulk upsert up to 1000 asset criticality records, creating or updating them as needed. - */ + * Bulk upsert up to 1000 asset criticality records. + +If asset criticality records already exist for the specified entities, those records are overwritten with the specified values. If asset criticality records don't exist for the specified entities, new records are created. + + */ async bulkUpsertAssetCriticalityRecords(props: BulkUpsertAssetCriticalityRecordsProps) { this.log.info(`${new Date().toISOString()} Calling API BulkUpsertAssetCriticalityRecords`); return this.kbnClient @@ -641,8 +644,11 @@ Migrations are initiated per index. While the process is neither destructive nor .catch(catchAxiosErrorFormatAndThrow); } /** - * Create or update a criticality record for a specific asset. - */ + * Create or update an asset criticality record for a specific entity. + +If a record already exists for the specified entity, that record is overwritten with the specified value. If a record doesn't exist for the specified entity, a new record is created. + + */ async createAssetCriticalityRecord(props: CreateAssetCriticalityRecordProps) { this.log.info(`${new Date().toISOString()} Calling API CreateAssetCriticalityRecord`); return this.kbnClient @@ -733,7 +739,7 @@ Migrations are initiated per index. While the process is neither destructive nor .catch(catchAxiosErrorFormatAndThrow); } /** - * Delete the asset criticality record for a specific asset if it exists. + * Delete the asset criticality record for a specific entity. */ async deleteAssetCriticalityRecord(props: DeleteAssetCriticalityRecordProps) { this.log.info(`${new Date().toISOString()} Calling API DeleteAssetCriticalityRecord`); @@ -1265,7 +1271,7 @@ finalize it. .catch(catchAxiosErrorFormatAndThrow); } /** - * Get the criticality record for a specific asset. + * Get the asset criticality record for a specific entity. */ async getAssetCriticalityRecord(props: GetAssetCriticalityRecordProps) { this.log.info(`${new Date().toISOString()} Calling API GetAssetCriticalityRecord`); @@ -1937,6 +1943,9 @@ detection engine rules. }) .catch(catchAxiosErrorFormatAndThrow); } + /** + * Schedule the risk scoring engine to run as soon as possible. You can use this to recalculate entity risk scores after updating their asset criticality. + */ async scheduleRiskEngineNow() { this.log.info(`${new Date().toISOString()} Calling API ScheduleRiskEngineNow`); return this.kbnClient diff --git a/x-pack/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml b/x-pack/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml index 1dfa9becae7db..11b41a20ace93 100644 --- a/x-pack/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml @@ -13,7 +13,7 @@ servers: paths: /api/asset_criticality: delete: - description: Delete the asset criticality record for a specific asset if it exists. + description: Delete the asset criticality record for a specific entity. operationId: DeleteAssetCriticalityRecord parameters: - description: The ID value of the asset. @@ -57,11 +57,11 @@ paths: description: Successful response '400': description: Invalid request - summary: Delete Criticality Record + summary: Delete an asset criticality record tags: - Security Entity Analytics API get: - description: Get the criticality record for a specific asset. + description: Get the asset criticality record for a specific entity. operationId: GetAssetCriticalityRecord parameters: - description: The ID value of the asset. @@ -88,11 +88,17 @@ paths: description: Invalid request '404': description: Criticality record not found - summary: Get Criticality Record + summary: Get an asset criticality record tags: - Security Entity Analytics API post: - description: Create or update a criticality record for a specific asset. + description: > + Create or update an asset criticality record for a specific entity. + + + If a record already exists for the specified entity, that record is + overwritten with the specified value. If a record doesn't exist for the + specified entity, a new record is created. operationId: CreateAssetCriticalityRecord requestBody: content: @@ -119,14 +125,19 @@ paths: description: Successful response '400': description: Invalid request - summary: Upsert Criticality Record + summary: Upsert an asset criticality record tags: - Security Entity Analytics API /api/asset_criticality/bulk: post: - description: >- - Bulk upsert up to 1000 asset criticality records, creating or updating - them as needed. + description: > + Bulk upsert up to 1000 asset criticality records. + + + If asset criticality records already exist for the specified entities, + those records are overwritten with the specified values. If asset + criticality records don't exist for the specified entities, new records + are created. operationId: BulkUpsertAssetCriticalityRecords requestBody: content: @@ -177,7 +188,7 @@ paths: description: Bulk upload successful '413': description: File too large - summary: Bulk Upsert Asset Criticality Records + summary: Bulk upsert asset criticality records tags: - Security Entity Analytics API /api/asset_criticality/list: @@ -253,7 +264,7 @@ paths: - per_page - total description: Bulk upload successful - summary: List Asset Criticality Records + summary: List asset criticality records tags: - Security Entity Analytics API /api/entity_store/engines: @@ -598,6 +609,10 @@ paths: - Security Entity Analytics API /api/risk_score/engine/schedule_now: post: + description: >- + Schedule the risk scoring engine to run as soon as possible. You can use + this to recalculate entity risk scores after updating their asset + criticality. operationId: ScheduleRiskEngineNow requestBody: content: @@ -621,7 +636,7 @@ paths: schema: $ref: '#/components/schemas/RiskEngineScheduleNowErrorResponse' description: Unexpected error - summary: Schedule the risk engine to run as soon as possible + summary: Run the risk scoring engine tags: - Security Entity Analytics API components: diff --git a/x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml b/x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml index a941f7215a972..b8a48cfa2d26c 100644 --- a/x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml +++ b/x-pack/plugins/security_solution/docs/openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml @@ -13,7 +13,7 @@ servers: paths: /api/asset_criticality: delete: - description: Delete the asset criticality record for a specific asset if it exists. + description: Delete the asset criticality record for a specific entity. operationId: DeleteAssetCriticalityRecord parameters: - description: The ID value of the asset. @@ -57,11 +57,11 @@ paths: description: Successful response '400': description: Invalid request - summary: Delete Criticality Record + summary: Delete an asset criticality record tags: - Security Entity Analytics API get: - description: Get the criticality record for a specific asset. + description: Get the asset criticality record for a specific entity. operationId: GetAssetCriticalityRecord parameters: - description: The ID value of the asset. @@ -88,11 +88,17 @@ paths: description: Invalid request '404': description: Criticality record not found - summary: Get Criticality Record + summary: Get an asset criticality record tags: - Security Entity Analytics API post: - description: Create or update a criticality record for a specific asset. + description: > + Create or update an asset criticality record for a specific entity. + + + If a record already exists for the specified entity, that record is + overwritten with the specified value. If a record doesn't exist for the + specified entity, a new record is created. operationId: CreateAssetCriticalityRecord requestBody: content: @@ -119,14 +125,19 @@ paths: description: Successful response '400': description: Invalid request - summary: Upsert Criticality Record + summary: Upsert an asset criticality record tags: - Security Entity Analytics API /api/asset_criticality/bulk: post: - description: >- - Bulk upsert up to 1000 asset criticality records, creating or updating - them as needed. + description: > + Bulk upsert up to 1000 asset criticality records. + + + If asset criticality records already exist for the specified entities, + those records are overwritten with the specified values. If asset + criticality records don't exist for the specified entities, new records + are created. operationId: BulkUpsertAssetCriticalityRecords requestBody: content: @@ -177,7 +188,7 @@ paths: description: Bulk upload successful '413': description: File too large - summary: Bulk Upsert Asset Criticality Records + summary: Bulk upsert asset criticality records tags: - Security Entity Analytics API /api/asset_criticality/list: @@ -253,7 +264,7 @@ paths: - per_page - total description: Bulk upload successful - summary: List Asset Criticality Records + summary: List asset criticality records tags: - Security Entity Analytics API /api/entity_store/engines: @@ -598,6 +609,10 @@ paths: - Security Entity Analytics API /api/risk_score/engine/schedule_now: post: + description: >- + Schedule the risk scoring engine to run as soon as possible. You can use + this to recalculate entity risk scores after updating their asset + criticality. operationId: ScheduleRiskEngineNow requestBody: content: @@ -621,7 +636,7 @@ paths: schema: $ref: '#/components/schemas/RiskEngineScheduleNowErrorResponse' description: Unexpected error - summary: Schedule the risk engine to run as soon as possible + summary: Run the risk scoring engine tags: - Security Entity Analytics API components: diff --git a/x-pack/test/api_integration/services/security_solution_api.gen.ts b/x-pack/test/api_integration/services/security_solution_api.gen.ts index 2f4ccd8ef15a2..0655515ce70a5 100644 --- a/x-pack/test/api_integration/services/security_solution_api.gen.ts +++ b/x-pack/test/api_integration/services/security_solution_api.gen.ts @@ -257,8 +257,11 @@ after 30 days. It also deletes other artifacts specific to the migration impleme .send(props.body as object); }, /** - * Bulk upsert up to 1000 asset criticality records, creating or updating them as needed. - */ + * Bulk upsert up to 1000 asset criticality records. + +If asset criticality records already exist for the specified entities, those records are overwritten with the specified values. If asset criticality records don't exist for the specified entities, new records are created. + + */ bulkUpsertAssetCriticalityRecords( props: BulkUpsertAssetCriticalityRecordsProps, kibanaSpace: string = 'default' @@ -327,8 +330,11 @@ Migrations are initiated per index. While the process is neither destructive nor .send(props.body as object); }, /** - * Create or update a criticality record for a specific asset. - */ + * Create or update an asset criticality record for a specific entity. + +If a record already exists for the specified entity, that record is overwritten with the specified value. If a record doesn't exist for the specified entity, a new record is created. + + */ createAssetCriticalityRecord( props: CreateAssetCriticalityRecordProps, kibanaSpace: string = 'default' @@ -400,7 +406,7 @@ Migrations are initiated per index. While the process is neither destructive nor .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana'); }, /** - * Delete the asset criticality record for a specific asset if it exists. + * Delete the asset criticality record for a specific entity. */ deleteAssetCriticalityRecord( props: DeleteAssetCriticalityRecordProps, @@ -803,7 +809,7 @@ finalize it. .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana'); }, /** - * Get the criticality record for a specific asset. + * Get the asset criticality record for a specific entity. */ getAssetCriticalityRecord( props: GetAssetCriticalityRecordProps, @@ -1301,6 +1307,9 @@ detection engine rules. .send(props.body as object) .query(props.query); }, + /** + * Schedule the risk scoring engine to run as soon as possible. You can use this to recalculate entity risk scores after updating their asset criticality. + */ scheduleRiskEngineNow(kibanaSpace: string = 'default') { return supertest .post(routeWithNamespace('/api/risk_score/engine/schedule_now', kibanaSpace))