Improves Entity Analytics API content (elastic#193404)

## Summary Resolves elastic/security-docs-internal#39 by improving the Entity Analytics API docs content. Adds missing and improves existing operation summaries and operation descriptions to adhere to our [OAS standards](https://elasticco.atlassian.net/wiki/spaces/DOC/pages/450494532/API+reference+docs). --------- Co-authored-by: kibanamachine <[email protected]> (cherry picked from commit d49f7e4) # Conflicts: # x-pack/test/api_integration/services/security_solution_api.gen.ts
natasha-moore-elastic · Dec 19, 2024 · c4374fe · c4374fe
1 parent eccf163
commit c4374fe
Show file tree

Hide file tree

Showing 10 changed files with 101 additions and 46 deletions.
diff --git a/...n/common/api/entity_analytics/asset_criticality/bulk_upload_asset_criticality.schema.yaml b/...n/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/...lution/common/api/entity_analytics/asset_criticality/create_asset_criticality.schema.yaml b/...lution/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/...lution/common/api/entity_analytics/asset_criticality/delete_asset_criticality.schema.yaml b/...lution/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/..._solution/common/api/entity_analytics/asset_criticality/get_asset_criticality.schema.yaml b/..._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/...solution/common/api/entity_analytics/asset_criticality/list_asset_criticality.schema.yaml b/...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/...ty_solution/common/api/entity_analytics/risk_engine/engine_schedule_now_route.schema.yaml b/...ty_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
@@ -521,8 +521,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
@@ -616,8 +619,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
@@ -689,7 +695,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`);
@@ -1185,7 +1191,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`);
@@ -1783,6 +1789,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/...on/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml b/...on/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/.../openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml b/.../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
@@ -240,8 +240,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'
@@ -308,8 +311,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'
@@ -367,7 +373,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,
@@ -744,7 +750,7 @@ finalize it.
         .query(props.query);
     },
     /**
-     * Get the criticality record for a specific asset.
+     * Get the asset criticality record for a specific entity.
      */
     getAssetCriticalityRecord(
       props: GetAssetCriticalityRecordProps,
@@ -1169,6 +1175,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))