[Entity Analytics] Add missing OpenAPI descriptions and examples to p… (#264778)

Closes: elastic/security-team#16463

Adds operation-level descriptions and request/response examples to 19
OpenAPI schema files across the entity analytics public API surface to
improve documentation quality and developer experience.

- **risk_engine:** add response examples to CleanUpRiskEngine,
ScheduleRiskEngineNow; add request + response examples to
ConfigureRiskEngineSavedObject
- **monitoring/engine:** add descriptions and response examples to
InitMonitoringEngine, DisableMonitoringEngine, DeleteMonitoringEngine,
ScheduleMonitoringEngine
- **monitoring/health:** add description and response example to
PrivMonHealth
- **monitoring/users:** add descriptions, request examples, and response
examples to CreatePrivMonUser, DeletePrivMonUser, UpdatePrivMonUser,
ListPrivMonUsers; add description to PrivmonBulkUploadUsersCSV
- **monitoring/privileged_access_detection:** add descriptions and
response examples to InstallPrivilegedAccessDetectionPackage and
GetPrivilegedAccessDetectionPackageStatus
- **watchlists:** add descriptions to CreateWatchlist, GetWatchlist,
UpdateWatchlist, ListWatchlists

- [x] `CleanUpRiskEngine` — response example
- [x] `ConfigureRiskEngineSavedObject` — request example, response
example
- [x] `ScheduleRiskEngineNow` — response example

- [x] `InitMonitoringEngine` — description, response example
- [x] `DisableMonitoringEngine` — description, response example
- [x] `DeleteMonitoringEngine` — description, response example
- [x] `ScheduleMonitoringEngine` — description, response example
- [x] `PrivMonHealth` — description, response example
- [x] `CreatePrivMonUser` — description, request example, response
example
- [x] `DeletePrivMonUser` — description, response example
- [x] `UpdatePrivMonUser` — description, request example, response
example
- [x] `ListPrivMonUsers` — description, response example
- [x] `PrivmonBulkUploadUsersCSV` — description

- [x] `InstallPrivilegedAccessDetectionPackage` — description, response
example
- [x] `GetPrivilegedAccessDetectionPackageStatus` — description,
response example

- [x] `CreateWatchlist` — description
- [x] `GetWatchlist` — description
- [x] `UpdateWatchlist` — description
- [x] `ListWatchlists` — description

---------

Co-authored-by: Claude Sonnet 4.6 <noreply@anthropic.com>
Co-authored-by: kibanamachine <42973632+kibanamachine@users.noreply.github.com>
(cherry picked from commit fda4179)

Author: 3 people

x-pack/solutions/security/packages/test-api-clients/supertest/entity_analytics.gen.ts

@@ -236,6 +236,9 @@ If a record already exists for the specified entity, that record is overwritten
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .send(props.body as object);
   },
+  /**
+   * Creates a new privileged user to be monitored by the Privilege Monitoring Engine.
+   */
   createPrivMonUser(props: CreatePrivMonUserProps, kibanaSpace: string = 'default') {
     return supertest
       .post(getRouteUrlForSpace('/api/entity_analytics/monitoring/users', kibanaSpace))
@@ -244,6 +247,9 @@ If a record already exists for the specified entity, that record is overwritten
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .send(props.body as object);
   },
+  /**
+   * Creates a new entity analytics watchlist with an optional set of entity sources. Watchlists apply a risk score modifier to matched entities.
+   */
   createWatchlist(props: CreateWatchlistProps, kibanaSpace: string = 'default') {
     return supertest
       .post(getRouteUrlForSpace('/api/entity_analytics/watchlists', kibanaSpace))
@@ -318,6 +324,9 @@ If a record already exists for the specified entity, that record is overwritten
       .set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
   },
+  /**
+   * Deletes the Privilege Monitoring Engine and optionally removes all associated privileged user data.
+   */
   deleteMonitoringEngine(props: DeleteMonitoringEngineProps, kibanaSpace: string = 'default') {
     return supertest
       .delete(getRouteUrlForSpace('/api/entity_analytics/monitoring/engine/delete', kibanaSpace))
@@ -326,6 +335,9 @@ If a record already exists for the specified entity, that record is overwritten
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .query(props.query);
   },
+  /**
+   * Removes a privileged user from monitoring by their document ID.
+   */
   deletePrivMonUser(props: DeletePrivMonUserProps, kibanaSpace: string = 'default') {
     return supertest
       .delete(
@@ -388,6 +400,9 @@ The entity will be immediately deleted from the latest index.  It will remain av
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .send(props.body as object);
   },
+  /**
+   * Disables the Privilege Monitoring Engine, stopping all monitoring activity without removing data.
+   */
   disableMonitoringEngine(kibanaSpace: string = 'default') {
     return supertest
       .post(getRouteUrlForSpace('/api/entity_analytics/monitoring/engine/disable', kibanaSpace))
@@ -500,6 +515,9 @@ The entity will be immediately deleted from the latest index.  It will remain av
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .query(props.query);
   },
+  /**
+   * Returns the installation and ML module setup status of the privileged access detection package, along with the state of each associated ML job.
+   */
   getPrivilegedAccessDetectionPackageStatus(kibanaSpace: string = 'default') {
     return supertest
       .get(
@@ -522,6 +540,9 @@ The entity will be immediately deleted from the latest index.  It will remain av
       .set(ELASTIC_HTTP_VERSION_HEADER, '1')
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
   },
+  /**
+   * Retrieves the details of an entity analytics watchlist by its unique identifier.
+   */
   getWatchlist(props: GetWatchlistProps, kibanaSpace: string = 'default') {
     return supertest
       .get(
@@ -576,6 +597,9 @@ The entity will be immediately deleted from the latest index.  It will remain av
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .send(props.body as object);
   },
+  /**
+   * Initializes the Privilege Monitoring Engine, setting up the required resources and starting the engine.
+   */
   initMonitoringEngine(kibanaSpace: string = 'default') {
     return supertest
       .post(getRouteUrlForSpace('/api/entity_analytics/monitoring/engine/init', kibanaSpace))
@@ -593,6 +617,9 @@ The entity will be immediately deleted from the latest index.  It will remain av
       .set(ELASTIC_HTTP_VERSION_HEADER, '1')
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
   },
+  /**
+   * Installs the privileged access detection integration package and sets up the associated ML modules required for the Entity Analytics privileged user monitoring experience.
+   */
   installPrivilegedAccessDetectionPackage(kibanaSpace: string = 'default') {
     return supertest
       .post(
@@ -649,6 +676,9 @@ Each row will match up to 10,000 entities.
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .query(props.query);
   },
+  /**
+   * Returns a list of all privileged users currently being monitored. Supports optional KQL filtering.
+   */
   listPrivMonUsers(props: ListPrivMonUsersProps, kibanaSpace: string = 'default') {
     return supertest
       .get(getRouteUrlForSpace('/api/entity_analytics/monitoring/users/list', kibanaSpace))
@@ -676,6 +706,9 @@ Each row will match up to 10,000 entities.
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .query(props.query);
   },
+  /**
+   * Returns a list of all entity analytics watchlists.
+   */
   listWatchlists(kibanaSpace: string = 'default') {
     return supertest
       .get(getRouteUrlForSpace('/api/entity_analytics/watchlists/list', kibanaSpace))
@@ -694,13 +727,19 @@ Each row will match up to 10,000 entities.
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .send(props.body as object);
   },
+  /**
+   * Bulk upserts privileged users by uploading a CSV file. Returns per-row errors and aggregate upload statistics.
+   */
   privmonBulkUploadUsersCsv(kibanaSpace: string = 'default') {
     return supertest
       .post(getRouteUrlForSpace('/api/entity_analytics/monitoring/users/_csv', kibanaSpace))
       .set('kbn-xsrf', 'true')
       .set(ELASTIC_HTTP_VERSION_HEADER, '2023-10-31')
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
   },
+  /**
+   * Returns the current health status of the Privilege Monitoring Engine, including engine status, error details, and user count statistics.
+   */
   privMonHealth(kibanaSpace: string = 'default') {
     return supertest
       .get(getRouteUrlForSpace('/api/entity_analytics/monitoring/privileges/health', kibanaSpace))
@@ -741,6 +780,9 @@ Each row will match up to 10,000 entities.
       .set(ELASTIC_HTTP_VERSION_HEADER, '1')
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
   },
+  /**
+   * Schedules the Privilege Monitoring Engine to run as soon as possible, triggering an immediate monitoring cycle.
+   */
   scheduleMonitoringEngine(kibanaSpace: string = 'default') {
     return supertest
       .post(
@@ -863,6 +905,9 @@ remain on the watchlist.
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .send(props.body as object);
   },
+  /**
+   * Updates the details of an existing monitored privileged user by their document ID.
+   */
   updatePrivMonUser(props: UpdatePrivMonUserProps, kibanaSpace: string = 'default') {
     return supertest
       .put(
@@ -876,6 +921,9 @@ remain on the watchlist.
       .set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
       .send(props.body as object);
   },
+  /**
+   * Updates the name, description, risk modifier, or managed status of an existing entity analytics watchlist.
+   */
   updateWatchlist(props: UpdateWatchlistProps, kibanaSpace: string = 'default') {
     return supertest
       .put(

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/engine/delete.schema.yaml

@@ -10,6 +10,7 @@ paths:
       x-codegen-enabled: true
       operationId: DeleteMonitoringEngine
       summary: Delete the Privilege Monitoring Engine
+      description: Deletes the Privilege Monitoring Engine and optionally removes all associated privileged user data.
       parameters:
         - in: query
           name: data
@@ -31,3 +32,8 @@ paths:
                     type: boolean
                 required:
                   - deleted
+              examples:
+                DeleteMonitoringEngineResponse:
+                  summary: Engine deleted successfully
+                  value:
+                    deleted: true

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/engine/disable.schema.yaml

@@ -10,6 +10,7 @@ paths:
       x-codegen-enabled: true
       operationId: DisableMonitoringEngine
       summary: Disable the Privilege Monitoring Engine
+      description: Disables the Privilege Monitoring Engine, stopping all monitoring activity without removing data.
 
       responses:
         "200":
@@ -18,3 +19,8 @@ paths:
             application/json:
               schema:
                 $ref: "../common.schema.yaml#/components/schemas/MonitoringEngineDescriptor"
+              examples:
+                DisableMonitoringEngineResponse:
+                  summary: Engine disabled successfully
+                  value:
+                    status: disabled

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/engine/init.schema.yaml

@@ -10,6 +10,7 @@ paths:
       x-codegen-enabled: true
       operationId: InitMonitoringEngine
       summary: Initialize the Privilege Monitoring Engine
+      description: Initializes the Privilege Monitoring Engine, setting up the required resources and starting the engine.
 
       responses:
         "200":
@@ -18,6 +19,11 @@ paths:
             application/json:
               schema:
                 $ref: "../common.schema.yaml#/components/schemas/MonitoringEngineDescriptor"
+              examples:
+                InitMonitoringEngineResponse:
+                  summary: Engine initialized successfully
+                  value:
+                    status: started
         "500":
           description: Internal Server Error
           content:

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/engine/schedule_now.schema.yaml

@@ -10,6 +10,7 @@ paths:
       x-codegen-enabled: true
       operationId: ScheduleMonitoringEngine
       summary: Schedule the Privilege Monitoring Engine
+      description: Schedules the Privilege Monitoring Engine to run as soon as possible, triggering an immediate monitoring cycle.
 
       responses:
         "200":
@@ -22,6 +23,11 @@ paths:
                   success:
                     type: boolean
                     description: Indicates the scheduling was successful
+              examples:
+                ScheduleMonitoringEngineResponse:
+                  summary: Engine scheduled successfully
+                  value:
+                    success: true
         "409":
           description: Conflict - Monitoring engine is already running
           content:

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/health.schema.yaml

@@ -10,6 +10,7 @@ paths:
       x-codegen-enabled: true
       operationId: PrivMonHealth
       summary: Health check on Privilege Monitoring
+      description: Returns the current health status of the Privilege Monitoring Engine, including engine status, error details, and user count statistics.
 
       responses:
         "200":
@@ -44,3 +45,11 @@ paths:
 
                 required:
                   - status
+              examples:
+                PrivMonHealthResponse:
+                  summary: Healthy privilege monitoring engine
+                  value:
+                    status: started
+                    users:
+                      current_count: 42
+                      max_allowed: 1000

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/privileged_access_detection/install.schema.yaml

@@ -9,6 +9,7 @@ paths:
       x-codegen-enabled: true
       operationId: InstallPrivilegedAccessDetectionPackage
       summary: Installs the privileged access detection package for the Entity Analytics privileged user monitoring experience
+      description: Installs the privileged access detection integration package and sets up the associated ML modules required for the Entity Analytics privileged user monitoring experience.
 
       responses:
         "200":
@@ -22,3 +23,8 @@ paths:
                 properties:
                   message:
                     type: string
+              examples:
+                InstallPrivilegedAccessDetectionPackageResponse:
+                  summary: Package installed successfully
+                  value:
+                    message: Privileged access detection package installed successfully

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/privileged_access_detection/status.schema.yaml

@@ -9,6 +9,7 @@ paths:
       x-codegen-enabled: true
       operationId: GetPrivilegedAccessDetectionPackageStatus
       summary: Gets the status of the privileged access detection package for the Entity Analytics privileged user monitoring experience
+      description: Returns the installation and ML module setup status of the privileged access detection package, along with the state of each associated ML job.
 
       responses:
         "200":
@@ -43,3 +44,16 @@ paths:
                         state:
                           type: string
                           enum: [closing, closed, opened, failed, opening]
+              examples:
+                GetPrivilegedAccessDetectionPackageStatusResponse:
+                  summary: Package fully installed and running
+                  value:
+                    package_installation_status: complete
+                    ml_module_setup_status: complete
+                    jobs:
+                      - job_id: pad-high-risk-login
+                        description: Detects high-risk login patterns
+                        state: opened
+                      - job_id: pad-privilege-escalation
+                        description: Detects privilege escalation events
+                        state: opened

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/users/create.schema.yaml

@@ -10,12 +10,24 @@ paths:
       x-codegen-enabled: true
       operationId: CreatePrivMonUser
       summary: Create a new monitored user
+      description: Creates a new privileged user to be monitored by the Privilege Monitoring Engine.
       requestBody:
         required: true
         content:
           application/json:
             schema:
               $ref: "./common.schema.yaml#/components/schemas/UserName"
+            examples:
+              CreatePrivMonUserRequest:
+                summary: Create a monitored user
+                value:
+                  user:
+                    name: john.doe
+                  entity_analytics_monitoring:
+                    labels:
+                      - field: department
+                        value: IT
+                        source: api
 
       responses:
         "200":
@@ -24,3 +36,19 @@ paths:
             application/json:
               schema:
                 $ref: "./common.schema.yaml#/components/schemas/MonitoredUserDoc"
+              examples:
+                CreatePrivMonUserResponse:
+                  summary: Created monitored user
+                  value:
+                    id: user-abc-123
+                    user:
+                      name: john.doe
+                      is_privileged: true
+                    entity_analytics_monitoring:
+                      labels:
+                        - field: department
+                          value: IT
+                          source: api
+                    "@timestamp": "2026-01-28T12:00:00.000Z"
+                    event:
+                      ingested: "2026-01-28T12:00:00.000Z"

x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/monitoring/users/delete.schema.yaml

@@ -10,6 +10,7 @@ paths:
       x-codegen-enabled: true
       operationId: DeletePrivMonUser
       summary: Delete a monitored user
+      description: Removes a privileged user from monitoring by their document ID.
       parameters:
         - name: id
           in: path
@@ -32,3 +33,9 @@ paths:
                   message:
                     type: string
                     description: A message providing additional information about the deletion status
+              examples:
+                DeletePrivMonUserResponse:
+                  summary: User deleted successfully
+                  value:
+                    acknowledged: true
+                    message: User deleted successfully