diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
index f8927c2d5a939..dd2716374680d 100644
--- a/oas_docs/output/kibana.yaml
+++ b/oas_docs/output/kibana.yaml
@@ -14815,6 +14815,14 @@ paths:
- Security Endpoint Management API
/api/entity_store/enable:
post:
+ description: |-
+ **Spaces method and path for this operation:**
+
+ post /s/{space_id}/api/entity_store/enable
+
+ Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
+
+ Initialize the entire Entity Store, creating engines for all or specified entity types.
operationId: InitEntityStore
requestBody:
content:
@@ -14863,20 +14871,47 @@ paths:
default: '@timestamp'
description: The field to use as the timestamp.
type: string
- description: Schema for the entity store initialization
+ description: Configuration for the entity store initialization.
required: true
responses:
'200':
content:
application/json:
+ examples:
+ initEntityStoreExample:
+ description: The Entity Store was successfully initialized, creating host and user engines in the installing state.
+ summary: Entity Store initialized with host and user engines
+ value:
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
+ succeeded: true
schema:
type: object
properties:
engines:
+ description: The engine descriptors created during initialization.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
type: array
succeeded:
+ description: Whether the Entity Store was initialized successfully.
type: boolean
description: Successful response
'400':
@@ -14884,25 +14919,54 @@ paths:
summary: Initialize the Entity Store
tags:
- Security Entity Analytics API
+ /api/entity_store/engines:
+ get:
description: |-
**Spaces method and path for this operation:**
- post /s/{space_id}/api/entity_store/enable
+ get /s/{space_id}/api/entity_store/engines
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- /api/entity_store/engines:
- get:
+
+ Get a list of all installed entity engines and their current status.
operationId: ListEntityEngines
responses:
'200':
content:
application/json:
+ examples:
+ listEntityEnginesExample:
+ description: Returns a list with one running host engine and one stopped user engine.
+ summary: Two engines installed
+ value:
+ count: 2
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: stopped
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
schema:
type: object
properties:
count:
+ description: The total number of entity engines.
type: integer
engines:
+ description: An array of engine descriptors.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
type: array
@@ -14910,12 +14974,6 @@ paths:
summary: List the Entity Engines
tags:
- Security Entity Analytics API
- description: |-
- **Spaces method and path for this operation:**
-
- get /s/{space_id}/api/entity_store/engines
-
- Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/api/entity_store/engines/{entityType}:
delete:
operationId: DeleteEntityEngine
@@ -14940,6 +14998,7 @@ paths:
type: object
properties:
deleted:
+ description: Whether the engine was successfully deleted.
type: boolean
description: Successful response
summary: Delete the Entity Engine
@@ -14952,9 +15011,18 @@ paths:
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
get:
+ description: |-
+ **Spaces method and path for this operation:**
+
+ get /s/{space_id}/api/entity_store/engines/{entityType}
+
+ Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
+
+ Get the engine descriptor for a specific entity type, including its configuration and current status.
operationId: GetEntityEngine
parameters:
- - description: The entity type of the engine (either 'user' or 'host').
+ - description: The entity type of the engine.
+ example: host
in: path
name: entityType
required: true
@@ -14964,20 +15032,36 @@ paths:
'200':
content:
application/json:
+ examples:
+ getEntityEngineExample:
+ description: Returns the engine descriptor for a host engine that is currently running with default settings.
+ summary: A running host engine
+ value:
+ delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
description: Successful response
summary: Get an Entity Engine
tags:
- Security Entity Analytics API
+ /api/entity_store/engines/{entityType}/init:
+ post:
description: |-
**Spaces method and path for this operation:**
- get /s/{space_id}/api/entity_store/engines/{entityType}
+ post /s/{space_id}/api/entity_store/engines/{entityType}/init
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- /api/entity_store/engines/{entityType}/init:
- post:
+
+ Initialize a single entity engine for the specified entity type.
operationId: InitEntityEngine
parameters:
- description: The entity type of the engine (either 'user' or 'host').
@@ -15035,6 +15119,20 @@ paths:
'200':
content:
application/json:
+ examples:
+ initEntityEngineExample:
+ description: A host engine was successfully initialized and is now in the installing state.
+ summary: Host engine initialized
+ value:
+ delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 3h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
description: Successful response
@@ -15043,17 +15141,20 @@ paths:
summary: Initialize an Entity Engine
tags:
- Security Entity Analytics API
+ /api/entity_store/engines/{entityType}/start:
+ post:
description: |-
**Spaces method and path for this operation:**
- post /s/{space_id}/api/entity_store/engines/{entityType}/init
+ post /s/{space_id}/api/entity_store/engines/{entityType}/start
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- /api/entity_store/engines/{entityType}/start:
- post:
+
+ Start a previously stopped entity engine, resuming transform processing for the given entity type.
operationId: StartEntityEngine
parameters:
- - description: The entity type of the engine
+ - description: The entity type of the engine to start.
+ example: host
in: path
name: entityType
required: true
@@ -15063,26 +15164,36 @@ paths:
'200':
content:
application/json:
+ examples:
+ startEntityEngineExample:
+ description: The engine was successfully started and is now processing data.
+ summary: Engine started successfully
+ value:
+ started: true
schema:
type: object
properties:
started:
+ description: Whether the engine was successfully started.
type: boolean
description: Successful response
summary: Start an Entity Engine
tags:
- Security Entity Analytics API
+ /api/entity_store/engines/{entityType}/stop:
+ post:
description: |-
**Spaces method and path for this operation:**
- post /s/{space_id}/api/entity_store/engines/{entityType}/start
+ post /s/{space_id}/api/entity_store/engines/{entityType}/stop
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- /api/entity_store/engines/{entityType}/stop:
- post:
+
+ Stop a running entity engine, pausing transform processing for the given entity type.
operationId: StopEntityEngine
parameters:
- - description: The entity type of the engine (either 'user' or 'host').
+ - description: The entity type of the engine to stop.
+ example: host
in: path
name: entityType
required: true
@@ -15092,75 +15203,125 @@ paths:
'200':
content:
application/json:
+ examples:
+ stopEntityEngineExample:
+ description: The engine was successfully stopped and is no longer processing data.
+ summary: Engine stopped successfully
+ value:
+ stopped: true
schema:
type: object
properties:
stopped:
+ description: Whether the engine was successfully stopped.
type: boolean
description: Successful response
summary: Stop an Entity Engine
tags:
- Security Entity Analytics API
+ /api/entity_store/engines/apply_dataview_indices:
+ post:
description: |-
**Spaces method and path for this operation:**
- post /s/{space_id}/api/entity_store/engines/{entityType}/stop
+ post /s/{space_id}/api/entity_store/engines/apply_dataview_indices
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
- /api/entity_store/engines/apply_dataview_indices:
- post:
+
+ Synchronize data view index patterns to all running entity engines so that newly added indices are picked up by the transforms.
operationId: ApplyEntityEngineDataviewIndices
responses:
'200':
content:
application/json:
+ examples:
+ applyDataviewIndicesExample:
+ description: All running engines were successfully updated with the current data view index patterns.
+ summary: All engines updated
+ value:
+ result:
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ - auditbeat-*
+ type: host
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ - auditbeat-*
+ type: user
+ success: true
schema:
type: object
properties:
result:
+ description: Per-engine update results.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDataviewUpdateResult'
type: array
success:
+ description: Whether all engines updated successfully.
type: boolean
description: Successful response
'207':
content:
application/json:
+ examples:
+ partialSuccessExample:
+ description: The host engine was updated but the user engine failed due to insufficient privileges.
+ summary: One engine failed
+ value:
+ errors:
+ - 'Failed to update user engine: insufficient privileges'
+ result:
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ type: host
+ success: false
schema:
type: object
properties:
errors:
+ description: Error messages for engines that failed to update.
items:
type: string
type: array
result:
+ description: Per-engine update results for engines that succeeded.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDataviewUpdateResult'
type: array
success:
+ description: Always `false` for a partial success.
type: boolean
description: Partial successful response
'500':
content:
application/json:
+ examples:
+ serverErrorExample:
+ description: An unexpected error occurred while applying data view indices.
+ summary: Internal server error
+ value:
+ body: An internal error occurred while updating engine indices
+ statusCode: 500
schema:
type: object
properties:
body:
+ description: Error message.
type: string
statusCode:
+ description: HTTP status code.
type: number
description: Error response
summary: Apply DataView indices to all installed engines
tags:
- Security Entity Analytics API
- description: |-
- **Spaces method and path for this operation:**
-
- post /s/{space_id}/api/entity_store/engines/apply_dataview_indices
-
- Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/api/entity_store/entities/list:
get:
description: |-
@@ -15173,12 +15334,15 @@ paths:
List entities records, paging, sorting and filtering as needed.
operationId: ListEntities
parameters:
- - in: query
+ - description: Field to sort results by.
+ example: entity.name
+ in: query
name: sort_field
required: false
schema:
type: string
- - in: query
+ - description: Sort order.
+ in: query
name: sort_order
required: false
schema:
@@ -15186,13 +15350,17 @@ paths:
- asc
- desc
type: string
- - in: query
+ - description: Page number to return (1-indexed).
+ example: 1
+ in: query
name: page
required: false
schema:
minimum: 1
type: integer
- - in: query
+ - description: Number of entities per page.
+ example: 10
+ in: query
name: per_page
required: false
schema:
@@ -15205,7 +15373,8 @@ paths:
required: false
schema:
type: string
- - in: query
+ - description: Entity types to include in the results.
+ in: query
name: entity_types
required: true
schema:
@@ -15222,17 +15391,21 @@ paths:
inspect:
$ref: '#/components/schemas/Security_Entity_Analytics_API_InspectQuery'
page:
+ description: Current page number.
minimum: 1
type: integer
per_page:
+ description: Number of entities per page.
maximum: 1000
minimum: 1
type: integer
records:
+ description: The entity records for this page.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Entity'
type: array
total:
+ description: Total number of entities matching the query.
minimum: 0
type: integer
required:
@@ -15246,9 +15419,18 @@ paths:
- Security Entity Analytics API
/api/entity_store/status:
get:
+ description: |-
+ **Spaces method and path for this operation:**
+
+ get /s/{space_id}/api/entity_store/status
+
+ Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
+
+ Get the overall Entity Store status and per-engine statuses, optionally including component-level health details.
operationId: GetEntityStoreStatus
parameters:
- - description: If true returns a detailed status of the engine including all it's components
+ - description: If true, returns a detailed status of each engine including all its components.
+ example: true
in: query
name: include_components
schema:
@@ -15257,22 +15439,50 @@ paths:
'200':
content:
application/json:
+ examples:
+ entityStoreRunning:
+ description: The Entity Store is running with both host and user engines started and using default settings.
+ summary: Entity Store running with two engines
+ value:
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
+ status: running
schema:
type: object
properties:
engines:
+ description: Per-engine status information.
items:
allOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_EngineDescriptor'
- type: object
properties:
components:
+ description: Detailed component-level status. Only included when include_components is true.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineComponentStatus'
type: array
type: array
status:
$ref: '#/components/schemas/Security_Entity_Analytics_API_StoreStatus'
+ description: The overall status of the Entity Store.
required:
- status
- engines
@@ -15280,12 +15490,6 @@ paths:
summary: Get the status of the Entity Store
tags:
- Security Entity Analytics API
- description: |-
- **Spaces method and path for this operation:**
-
- get /s/{space_id}/api/entity_store/status
-
- Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/api/exception_lists:
delete:
description: |-
@@ -52147,6 +52351,7 @@ components:
required:
- criticality_level
Security_Entity_Analytics_API_EngineComponentResource:
+ description: The type of Elasticsearch or Kibana resource backing an engine component.
enum:
- entity_engine
- entity_definition
@@ -52159,18 +52364,23 @@ components:
- transform
type: string
Security_Entity_Analytics_API_EngineComponentStatus:
+ description: Status of an individual Elasticsearch or Kibana resource backing an engine.
type: object
properties:
errors:
+ description: Errors reported by this component, if any.
items:
type: object
properties:
message:
+ description: Detailed error message.
type: string
title:
+ description: Short error title.
type: string
type: array
health:
+ description: The health status of the component.
enum:
- green
- yellow
@@ -52179,8 +52389,10 @@ components:
- unknown
type: string
id:
+ description: Unique identifier for the component.
type: string
installed:
+ description: Whether the component is currently installed.
type: boolean
resource:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineComponentResource'
@@ -52189,61 +52401,84 @@ components:
- installed
- resource
Security_Entity_Analytics_API_EngineDataviewUpdateResult:
+ description: The result of applying data view index changes to a single engine.
type: object
properties:
changes:
+ description: The changes applied to the engine.
type: object
properties:
indexPatterns:
+ description: The updated list of index patterns now used by the engine.
items:
type: string
type: array
type:
+ description: The entity type of the engine that was updated.
type: string
required:
- type
Security_Entity_Analytics_API_EngineDescriptor:
+ description: Describes a single entity engine, including its configuration and current status.
type: object
properties:
delay:
default: 1m
+ description: The delay before the transform processes new data, allowing late-arriving documents to be included.
+ example: 1m
pattern: '[smdh]$'
type: string
docsPerSecond:
+ description: Throttle value for the number of documents processed per second. Use -1 for no throttle.
type: integer
error:
+ description: Present when the engine status is `error`. Describes the failure.
type: object
properties:
action:
+ description: The lifecycle action that caused the error.
enum:
- init
type: string
message:
+ description: A human-readable error message.
type: string
required:
- message
- action
fieldHistoryLength:
+ description: The number of historical values retained per field.
+ example: 10
type: integer
filter:
+ description: An optional Kibana Query Language (KQL) filter applied to source documents before aggregation.
+ example: 'host.name: "my-host"'
type: string
frequency:
default: 1m
+ description: How often the transform runs.
+ example: 1m
pattern: '[smdh]$'
type: string
indexPattern:
$ref: '#/components/schemas/Security_Entity_Analytics_API_IndexPattern'
lookbackPeriod:
default: 24h
+ description: How far back the transform looks when calculating aggregations.
+ example: 24h
pattern: '[smdh]$'
type: string
status:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineStatus'
timeout:
default: 180s
+ description: The timeout for initializing the aggregating transform.
+ example: 180s
pattern: '[smdh]$'
type: string
timestampField:
+ description: The field used as the timestamp for source documents.
+ example: '@timestamp'
type: string
type:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
@@ -52253,6 +52488,7 @@ components:
- status
- fieldHistoryLength
Security_Entity_Analytics_API_EngineStatus:
+ description: The current operational status of an entity engine.
enum:
- installing
- started
@@ -52261,6 +52497,7 @@ components:
- error
type: string
Security_Entity_Analytics_API_Entity:
+ description: An entity record from the Entity Store. The `entity` namespace is a root-level field in the latest index, unlike source logs where it is nested under `host`, `user`, or `service`.
oneOf:
- $ref: '#/components/schemas/Security_Entity_Analytics_API_UserEntity'
- $ref: '#/components/schemas/Security_Entity_Analytics_API_HostEntity'
@@ -52341,15 +52578,18 @@ components:
- inputs
- notes
Security_Entity_Analytics_API_EntityType:
+ description: The type of entity.
enum:
- user
- host
- service
type: string
Security_Entity_Analytics_API_HostEntity:
+ description: An entity record representing a host, stored in the Entity Store latest index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -52373,40 +52613,50 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
host:
+ description: Elastic Common Schema (ECS) host fields collected on the entity.
type: object
properties:
architecture:
+ description: Observed CPU architectures.
items:
type: string
type: array
domain:
+ description: Observed host domains.
items:
type: string
type: array
hostname:
+ description: Observed hostnames.
items:
type: string
type: array
id:
+ description: Observed host IDs.
items:
type: string
type: array
ip:
+ description: Observed IP addresses.
items:
type: string
type: array
mac:
+ description: Observed MAC addresses.
items:
type: string
type: array
name:
+ description: Primary host name.
type: string
risk:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskScoreRecord'
type:
+ description: Observed host types.
items:
type: string
type: array
@@ -52422,15 +52672,20 @@ components:
- service.name
type: string
Security_Entity_Analytics_API_IndexPattern:
+ description: An additional Elasticsearch index pattern to include as a source for entity data. Merged with the default data view indices when the engine runs.
+ example: logs-*
type: string
Security_Entity_Analytics_API_InspectQuery:
+ description: Debug information about the Elasticsearch query executed.
type: object
properties:
dsl:
+ description: Elasticsearch query DSL that was executed.
items:
type: string
type: array
response:
+ description: Raw Elasticsearch responses.
items:
type: string
type: array
@@ -52496,9 +52751,11 @@ components:
- description
- category
Security_Entity_Analytics_API_ServiceEntity:
+ description: An entity record representing a service, stored in the Entity Store latest index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -52522,12 +52779,15 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
service:
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
type: object
properties:
name:
+ description: Primary service name.
type: string
risk:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskScoreRecord'
@@ -52537,6 +52797,7 @@ components:
- service
- entity
Security_Entity_Analytics_API_StoreStatus:
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -52557,9 +52818,11 @@ components:
- status_code
- message
Security_Entity_Analytics_API_UserEntity:
+ description: An entity record representing a user, stored in the Entity Store latest index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -52583,36 +52846,45 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
user:
+ description: Elastic Common Schema (ECS) user fields collected on the entity.
type: object
properties:
domain:
+ description: Observed user domains.
items:
type: string
type: array
email:
+ description: Observed email addresses.
items:
type: string
type: array
full_name:
+ description: Observed full names of the user.
items:
type: string
type: array
hash:
+ description: Observed user hashes.
items:
type: string
type: array
id:
+ description: Observed user IDs.
items:
type: string
type: array
name:
+ description: Primary user name.
type: string
risk:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskScoreRecord'
roles:
+ description: Observed roles assigned to the user.
items:
type: string
type: array
diff --git a/x-pack/solutions/security/packages/test-api-clients/supertest/entity_analytics.gen.ts b/x-pack/solutions/security/packages/test-api-clients/supertest/entity_analytics.gen.ts
index fc8af5add0be5..555f8de100fa8 100644
--- a/x-pack/solutions/security/packages/test-api-clients/supertest/entity_analytics.gen.ts
+++ b/x-pack/solutions/security/packages/test-api-clients/supertest/entity_analytics.gen.ts
@@ -53,6 +53,9 @@ import type { FtrProviderContext } from '@kbn/ftr-common-functional-services';
import { getRouteUrlForSpace } from '@kbn/spaces-plugin/common';
const securitySolutionApiServiceFactory = (supertest: SuperTest.Agent) => ({
+ /**
+ * Synchronize data view index patterns to all running entity engines so that newly added indices are picked up by the transforms.
+ */
applyEntityEngineDataviewIndices(kibanaSpace: string = 'default') {
return supertest
.post(getRouteUrlForSpace('/api/entity_store/engines/apply_dataview_indices', kibanaSpace))
@@ -180,6 +183,9 @@ If a record already exists for the specified entity, that record is overwritten
.set(ELASTIC_HTTP_VERSION_HEADER, '1')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
+ /**
+ * Check whether the current user has the required Elasticsearch and Kibana privileges to use the Entity Store.
+ */
entityStoreGetPrivileges(kibanaSpace: string = 'default') {
return supertest
.get(getRouteUrlForSpace('/internal/entity_store/privileges', kibanaSpace))
@@ -222,6 +228,9 @@ If a record already exists for the specified entity, that record is overwritten
.set(ELASTIC_HTTP_VERSION_HEADER, '1')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
+ /**
+ * Get the engine descriptor for a specific entity type, including its configuration and current status.
+ */
getEntityEngine(props: GetEntityEngineProps, kibanaSpace: string = 'default') {
return supertest
.get(
@@ -234,6 +243,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');
},
+ /**
+ * Get the overall Entity Store status and per-engine statuses, optionally including component-level health details.
+ */
getEntityStoreStatus(props: GetEntityStoreStatusProps, kibanaSpace: string = 'default') {
return supertest
.get(getRouteUrlForSpace('/api/entity_store/status', kibanaSpace))
@@ -252,6 +264,9 @@ If a record already exists for the specified entity, that record is overwritten
.set(ELASTIC_HTTP_VERSION_HEADER, '1')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
+ /**
+ * Initialize a single entity engine for the specified entity type.
+ */
initEntityEngine(props: InitEntityEngineProps, kibanaSpace: string = 'default') {
return supertest
.post(
@@ -265,6 +280,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);
},
+ /**
+ * Initialize the entire Entity Store, creating engines for all or specified entity types.
+ */
initEntityStore(props: InitEntityStoreProps, kibanaSpace: string = 'default') {
return supertest
.post(getRouteUrlForSpace('/api/entity_store/enable', kibanaSpace))
@@ -301,6 +319,9 @@ If a record already exists for the specified entity, that record is overwritten
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
+ /**
+ * Get a list of all installed entity engines and their current status.
+ */
listEntityEngines(kibanaSpace: string = 'default') {
return supertest
.get(getRouteUrlForSpace('/api/entity_store/engines', kibanaSpace))
@@ -350,6 +371,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');
},
+ /**
+ * Start a previously stopped entity engine, resuming transform processing for the given entity type.
+ */
startEntityEngine(props: StartEntityEngineProps, kibanaSpace: string = 'default') {
return supertest
.post(
@@ -362,6 +386,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');
},
+ /**
+ * Stop a running entity engine, pausing transform processing for the given entity type.
+ */
stopEntityEngine(props: StopEntityEngineProps, kibanaSpace: string = 'default') {
return supertest
.post(
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/common.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/common.gen.ts
index f5af870b38951..00e573d877a3c 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/common.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/common.gen.ts
@@ -16,56 +16,104 @@
import { z } from '@kbn/zod';
+/**
+ * The type of entity.
+ */
export type EntityType = z.infer;
export const EntityType = z.enum(['user', 'host', 'service']);
export type EntityTypeEnum = typeof EntityType.enum;
export const EntityTypeEnum = EntityType.enum;
+/**
+ * An additional Elasticsearch index pattern to include as a source for entity data. Merged with the default data view indices when the engine runs.
+ */
export type IndexPattern = z.infer;
export const IndexPattern = z.string();
+/**
+ * The current operational status of an entity engine.
+ */
export type EngineStatus = z.infer;
export const EngineStatus = z.enum(['installing', 'started', 'stopped', 'updating', 'error']);
export type EngineStatusEnum = typeof EngineStatus.enum;
export const EngineStatusEnum = EngineStatus.enum;
+/**
+ * Describes a single entity engine, including its configuration and current status.
+ */
export type EngineDescriptor = z.infer;
export const EngineDescriptor = z.object({
type: EntityType,
indexPattern: IndexPattern,
status: EngineStatus,
+ /**
+ * An optional Kibana Query Language (KQL) filter applied to source documents before aggregation.
+ */
filter: z.string().optional(),
+ /**
+ * The number of historical values retained per field.
+ */
fieldHistoryLength: z.number().int(),
+ /**
+ * How far back the transform looks when calculating aggregations.
+ */
lookbackPeriod: z
.string()
.regex(/[smdh]$/)
.optional()
.default('24h'),
+ /**
+ * The field used as the timestamp for source documents.
+ */
timestampField: z.string().optional(),
+ /**
+ * The timeout for initializing the aggregating transform.
+ */
timeout: z
.string()
.regex(/[smdh]$/)
.optional()
.default('180s'),
+ /**
+ * How often the transform runs.
+ */
frequency: z
.string()
.regex(/[smdh]$/)
.optional()
.default('1m'),
+ /**
+ * The delay before the transform processes new data, allowing late-arriving documents to be included.
+ */
delay: z
.string()
.regex(/[smdh]$/)
.optional()
.default('1m'),
+ /**
+ * Throttle value for the number of documents processed per second. Use -1 for no throttle.
+ */
docsPerSecond: z.number().int().optional(),
+ /**
+ * Present when the engine status is `error`. Describes the failure.
+ */
error: z
.object({
+ /**
+ * A human-readable error message.
+ */
message: z.string(),
+ /**
+ * The lifecycle action that caused the error.
+ */
action: z.literal('init'),
})
.optional(),
});
+/**
+ * The type of Elasticsearch or Kibana resource backing an engine component.
+ */
export type EngineComponentResource = z.infer;
export const EngineComponentResource = z.enum([
'entity_engine',
@@ -81,30 +129,63 @@ export const EngineComponentResource = z.enum([
export type EngineComponentResourceEnum = typeof EngineComponentResource.enum;
export const EngineComponentResourceEnum = EngineComponentResource.enum;
+/**
+ * Status of an individual Elasticsearch or Kibana resource backing an engine.
+ */
export type EngineComponentStatus = z.infer;
export const EngineComponentStatus = z.object({
+ /**
+ * Unique identifier for the component.
+ */
id: z.string(),
+ /**
+ * Whether the component is currently installed.
+ */
installed: z.boolean(),
resource: EngineComponentResource,
+ /**
+ * The health status of the component.
+ */
health: z.enum(['green', 'yellow', 'red', 'unavailable', 'unknown']).optional(),
+ /**
+ * Errors reported by this component, if any.
+ */
errors: z
.array(
z.object({
+ /**
+ * Short error title.
+ */
title: z.string().optional(),
+ /**
+ * Detailed error message.
+ */
message: z.string().optional(),
})
)
.optional(),
});
+/**
+ * The overall operational status of the Entity Store.
+ */
export type StoreStatus = z.infer;
export const StoreStatus = z.enum(['not_installed', 'installing', 'running', 'stopped', 'error']);
export type StoreStatusEnum = typeof StoreStatus.enum;
export const StoreStatusEnum = StoreStatus.enum;
+/**
+ * Debug information about the Elasticsearch query executed.
+ */
export type InspectQuery = z.infer;
export const InspectQuery = z.object({
+ /**
+ * Raw Elasticsearch responses.
+ */
response: z.array(z.string()),
+ /**
+ * Elasticsearch query DSL that was executed.
+ */
dsl: z.array(z.string()),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/common.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/common.schema.yaml
index 50dcf0430f59d..8fc57236b45a3 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/common.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/common.schema.yaml
@@ -8,13 +8,16 @@ components:
schemas:
EntityType:
type: string
+ description: The type of entity.
enum:
- user
- host
- service
+
EngineDescriptor:
type: object
+ description: Describes a single entity engine, including its configuration and current status.
required:
- type
- indexPattern
@@ -29,43 +32,62 @@ components:
$ref: '#/components/schemas/EngineStatus'
filter:
type: string
+ description: An optional Kibana Query Language (KQL) filter applied to source documents before aggregation.
+ example: 'host.name: "my-host"'
fieldHistoryLength:
type: integer
+ description: The number of historical values retained per field.
+ example: 10
lookbackPeriod:
type: string
default: 24h
pattern: '[smdh]$'
+ description: How far back the transform looks when calculating aggregations.
+ example: '24h'
timestampField:
type: string
+ description: The field used as the timestamp for source documents.
+ example: '@timestamp'
timeout:
type: string
default: 180s
pattern: '[smdh]$'
+ description: The timeout for initializing the aggregating transform.
+ example: '180s'
frequency:
type: string
default: 1m
pattern: '[smdh]$'
+ description: How often the transform runs.
+ example: '1m'
delay:
type: string
default: 1m
pattern: '[smdh]$'
+ description: The delay before the transform processes new data, allowing late-arriving documents to be included.
+ example: '1m'
docsPerSecond:
type: integer
+ description: Throttle value for the number of documents processed per second. Use -1 for no throttle.
error:
type: object
+ description: Present when the engine status is `error`. Describes the failure.
required:
- message
- action
properties:
message:
type: string
+ description: A human-readable error message.
action:
type: string
+ description: The lifecycle action that caused the error.
enum:
- init
EngineStatus:
type: string
+ description: The current operational status of an entity engine.
enum:
- installing
- started
@@ -75,6 +97,7 @@ components:
EngineComponentStatus:
type: object
+ description: Status of an individual Elasticsearch or Kibana resource backing an engine.
required:
- id
- installed
@@ -82,12 +105,15 @@ components:
properties:
id:
type: string
+ description: Unique identifier for the component.
installed:
type: boolean
+ description: Whether the component is currently installed.
resource:
$ref: '#/components/schemas/EngineComponentResource'
health:
type: string
+ description: The health status of the component.
enum:
- green
- yellow
@@ -96,16 +122,20 @@ components:
- unknown
errors:
type: array
+ description: Errors reported by this component, if any.
items:
type: object
properties:
title:
type: string
+ description: Short error title.
message:
type: string
+ description: Detailed error message.
EngineComponentResource:
type: string
+ description: The type of Elasticsearch or Kibana resource backing an engine component.
enum:
- entity_engine
- entity_definition
@@ -119,6 +149,7 @@ components:
StoreStatus:
type: string
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -128,16 +159,21 @@ components:
IndexPattern:
type: string
+ description: An additional Elasticsearch index pattern to include as a source for entity data. Merged with the default data view indices when the engine runs.
+ example: 'logs-*'
InspectQuery:
type: object
+ description: Debug information about the Elasticsearch query executed.
properties:
response:
type: array
+ description: Raw Elasticsearch responses.
items:
type: string
dsl:
type: array
+ description: Elasticsearch query DSL that was executed.
items:
type: string
required:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/enable.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/enable.gen.ts
index 3f738851fb6fd..3e7d7aed5175f 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/enable.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/enable.gen.ts
@@ -73,6 +73,12 @@ export type InitEntityStoreRequestBodyInput = z.input;
export const InitEntityStoreResponse = z.object({
+ /**
+ * Whether the Entity Store was initialized successfully.
+ */
succeeded: z.boolean().optional(),
+ /**
+ * The engine descriptors created during initialization.
+ */
engines: z.array(EngineDescriptor).optional(),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/enable.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/enable.schema.yaml
index dfa21d4797160..6aa3a2918c100 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/enable.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/enable.schema.yaml
@@ -10,9 +10,10 @@ paths:
x-codegen-enabled: true
operationId: InitEntityStore
summary: Initialize the Entity Store
+ description: Initialize the entire Entity Store, creating engines for all or specified entity types.
requestBody:
- description: Schema for the entity store initialization
+ description: Configuration for the entity store initialization.
required: true
content:
application/json:
@@ -70,9 +71,36 @@ paths:
properties:
succeeded:
type: boolean
+ description: Whether the Entity Store was initialized successfully.
engines:
type: array
+ description: The engine descriptors created during initialization.
items:
$ref: './common.schema.yaml#/components/schemas/EngineDescriptor'
+ examples:
+ initEntityStoreExample:
+ summary: Entity Store initialized with host and user engines
+ description: The Entity Store was successfully initialized, creating host and user engines in the installing state.
+ value:
+ succeeded: true
+ engines:
+ - type: host
+ indexPattern: ''
+ status: installing
+ fieldHistoryLength: 10
+ lookbackPeriod: '24h'
+ timestampField: '@timestamp'
+ timeout: '180s'
+ frequency: '1m'
+ delay: '1m'
+ - type: user
+ indexPattern: ''
+ status: installing
+ fieldHistoryLength: 10
+ lookbackPeriod: '24h'
+ timestampField: '@timestamp'
+ timeout: '180s'
+ frequency: '1m'
+ delay: '1m'
'400':
description: Invalid request
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/apply_dataview_indices.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/apply_dataview_indices.gen.ts
index c3492ad88f754..16f23c714a27e 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/apply_dataview_indices.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/apply_dataview_indices.gen.ts
@@ -16,11 +16,23 @@
import { z } from '@kbn/zod';
+/**
+ * The result of applying data view index changes to a single engine.
+ */
export type EngineDataviewUpdateResult = z.infer;
export const EngineDataviewUpdateResult = z.object({
+ /**
+ * The entity type of the engine that was updated.
+ */
type: z.string(),
+ /**
+ * The changes applied to the engine.
+ */
changes: z
.object({
+ /**
+ * The updated list of index patterns now used by the engine.
+ */
indexPatterns: z.array(z.string()).optional(),
})
.optional(),
@@ -30,6 +42,12 @@ export type ApplyEntityEngineDataviewIndicesResponse = z.infer<
typeof ApplyEntityEngineDataviewIndicesResponse
>;
export const ApplyEntityEngineDataviewIndicesResponse = z.object({
+ /**
+ * Whether all engines updated successfully.
+ */
success: z.boolean().optional(),
+ /**
+ * Per-engine update results.
+ */
result: z.array(EngineDataviewUpdateResult).optional(),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/apply_dataview_indices.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/apply_dataview_indices.schema.yaml
index 20afc96cd54e3..937a6e1cb2e69 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/apply_dataview_indices.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/apply_dataview_indices.schema.yaml
@@ -10,6 +10,7 @@ paths:
x-codegen-enabled: true
operationId: ApplyEntityEngineDataviewIndices
summary: Apply DataView indices to all installed engines
+ description: Synchronize data view index patterns to all running entity engines so that newly added indices are picked up by the transforms.
responses:
'200':
description: Successful response
@@ -20,10 +21,31 @@ paths:
properties:
success:
type: boolean
+ description: Whether all engines updated successfully.
result:
type: array
+ description: Per-engine update results.
items:
$ref: '#/components/schemas/EngineDataviewUpdateResult'
+ examples:
+ applyDataviewIndicesExample:
+ summary: All engines updated
+ description: All running engines were successfully updated with the current data view index patterns.
+ value:
+ success: true
+ result:
+ - type: host
+ changes:
+ indexPatterns:
+ - 'logs-*'
+ - 'filebeat-*'
+ - 'auditbeat-*'
+ - type: user
+ changes:
+ indexPatterns:
+ - 'logs-*'
+ - 'filebeat-*'
+ - 'auditbeat-*'
'207':
description: Partial successful response
@@ -34,14 +56,31 @@ paths:
properties:
success:
type: boolean
+ description: Always `false` for a partial success.
result:
type: array
+ description: Per-engine update results for engines that succeeded.
items:
$ref: '#/components/schemas/EngineDataviewUpdateResult'
errors:
type: array
+ description: Error messages for engines that failed to update.
items:
type: string
+ examples:
+ partialSuccessExample:
+ summary: One engine failed
+ description: The host engine was updated but the user engine failed due to insufficient privileges.
+ value:
+ success: false
+ result:
+ - type: host
+ changes:
+ indexPatterns:
+ - 'logs-*'
+ - 'filebeat-*'
+ errors:
+ - 'Failed to update user engine: insufficient privileges'
'500':
description: Error response
content:
@@ -51,20 +90,33 @@ paths:
properties:
body:
type: string
+ description: Error message.
statusCode:
type: number
+ description: HTTP status code.
+ examples:
+ serverErrorExample:
+ summary: Internal server error
+ description: An unexpected error occurred while applying data view indices.
+ value:
+ body: 'An internal error occurred while updating engine indices'
+ statusCode: 500
components:
schemas:
EngineDataviewUpdateResult:
type: object
+ description: The result of applying data view index changes to a single engine.
properties:
type:
type: string
+ description: The entity type of the engine that was updated.
changes:
type: object
+ description: The changes applied to the engine.
properties:
indexPatterns:
type: array
+ description: The updated list of index patterns now used by the engine.
items:
type: string
required:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/delete.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/delete.gen.ts
index af147e63d05fc..74b98c13794e0 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/delete.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/delete.gen.ts
@@ -39,5 +39,8 @@ export type DeleteEntityEngineRequestParamsInput = z.input;
export const DeleteEntityEngineResponse = z.object({
+ /**
+ * Whether the engine was successfully deleted.
+ */
deleted: z.boolean().optional(),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/delete.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/delete.schema.yaml
index 4de339ea14e1c..b237e0eb31067 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/delete.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/delete.schema.yaml
@@ -31,7 +31,8 @@ paths:
application/json:
schema:
type: object
- properties:
+ properties:
deleted:
type: boolean
+ description: Whether the engine was successfully deleted.
\ No newline at end of file
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get.gen.ts
index c5ebbb1aebb99..ef7b0b21cb299 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get.gen.ts
@@ -21,7 +21,7 @@ import { EntityType, EngineDescriptor } from '../common.gen';
export type GetEntityEngineRequestParams = z.infer;
export const GetEntityEngineRequestParams = z.object({
/**
- * The entity type of the engine (either 'user' or 'host').
+ * The entity type of the engine.
*/
entityType: EntityType,
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get.schema.yaml
index 4108f3f4594ae..9935b3e9e2579 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get.schema.yaml
@@ -9,13 +9,15 @@ paths:
x-codegen-enabled: true
operationId: GetEntityEngine
summary: Get an Entity Engine
+ description: Get the engine descriptor for a specific entity type, including its configuration and current status.
parameters:
- name: entityType
in: path
required: true
schema:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
- description: The entity type of the engine (either 'user' or 'host').
+ description: The entity type of the engine.
+ example: host
responses:
'200':
description: Successful response
@@ -23,3 +25,17 @@ paths:
application/json:
schema:
$ref: '../common.schema.yaml#/components/schemas/EngineDescriptor'
+ examples:
+ getEntityEngineExample:
+ summary: A running host engine
+ description: Returns the engine descriptor for a host engine that is currently running with default settings.
+ value:
+ type: host
+ indexPattern: ''
+ status: started
+ fieldHistoryLength: 10
+ lookbackPeriod: '24h'
+ timestampField: '@timestamp'
+ timeout: '180s'
+ frequency: '1m'
+ delay: '1m'
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get_privileges.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get_privileges.schema.yaml
index f1db3b3f93a5a..418c658ab404d 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get_privileges.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/get_privileges.schema.yaml
@@ -10,10 +10,31 @@ paths:
x-codegen-enabled: true
operationId: EntityStoreGetPrivileges
summary: Get Entity Store Privileges
+ description: Check whether the current user has the required Elasticsearch and Kibana privileges to use the Entity Store.
responses:
'200':
description: Successful response
content:
application/json:
- schema:
+ schema:
$ref: '../../common/common.schema.yaml#/components/schemas/EntityAnalyticsPrivileges'
+ examples:
+ allPrivilegesGranted:
+ summary: User has all required privileges
+ description: The current user has all Elasticsearch cluster and index privileges required to operate the Entity Store.
+ value:
+ has_all_required: true
+ has_read_permissions: true
+ has_write_permissions: true
+ privileges:
+ elasticsearch:
+ cluster:
+ manage_enrich: true
+ manage_transform: true
+ manage_ingest_pipelines: true
+ manage_index_templates: true
+ index:
+ '.entities.v1.latest.*':
+ read: true
+ write: true
+ kibana: {}
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/init.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/init.schema.yaml
index 117d68fb563db..1875c1e8edea4 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/init.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/init.schema.yaml
@@ -10,6 +10,7 @@ paths:
x-codegen-enabled: true
operationId: InitEntityEngine
summary: Initialize an Entity Engine
+ description: Initialize a single entity engine for the specified entity type.
parameters:
- name: entityType
in: path
@@ -69,5 +70,19 @@ paths:
application/json:
schema:
$ref: '../common.schema.yaml#/components/schemas/EngineDescriptor'
+ examples:
+ initEntityEngineExample:
+ summary: Host engine initialized
+ description: A host engine was successfully initialized and is now in the installing state.
+ value:
+ type: host
+ indexPattern: ''
+ status: installing
+ fieldHistoryLength: 10
+ lookbackPeriod: '3h'
+ timestampField: '@timestamp'
+ timeout: '180s'
+ frequency: '1m'
+ delay: '1m'
'400':
description: Invalid request
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/list.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/list.gen.ts
index 0a35fa49f6b33..a4f888da8a928 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/list.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/list.gen.ts
@@ -20,6 +20,12 @@ import { EngineDescriptor } from '../common.gen';
export type ListEntityEnginesResponse = z.infer;
export const ListEntityEnginesResponse = z.object({
+ /**
+ * The total number of entity engines.
+ */
count: z.number().int().optional(),
+ /**
+ * An array of engine descriptors.
+ */
engines: z.array(EngineDescriptor).optional(),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/list.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/list.schema.yaml
index deee32a8b2bb7..7d254ad458a21 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/list.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/list.schema.yaml
@@ -9,6 +9,7 @@ paths:
x-codegen-enabled: true
operationId: ListEntityEngines
summary: List the Entity Engines
+ description: Get a list of all installed entity engines and their current status.
responses:
'200':
description: Successful response
@@ -19,7 +20,34 @@ paths:
properties:
count:
type: integer
+ description: The total number of entity engines.
engines:
type: array
+ description: An array of engine descriptors.
items:
- $ref: '../common.schema.yaml#/components/schemas/EngineDescriptor'
\ No newline at end of file
+ $ref: '../common.schema.yaml#/components/schemas/EngineDescriptor'
+ examples:
+ listEntityEnginesExample:
+ summary: Two engines installed
+ description: Returns a list with one running host engine and one stopped user engine.
+ value:
+ count: 2
+ engines:
+ - type: host
+ indexPattern: ''
+ status: started
+ fieldHistoryLength: 10
+ lookbackPeriod: '24h'
+ timestampField: '@timestamp'
+ timeout: '180s'
+ frequency: '1m'
+ delay: '1m'
+ - type: user
+ indexPattern: ''
+ status: stopped
+ fieldHistoryLength: 10
+ lookbackPeriod: '24h'
+ timestampField: '@timestamp'
+ timeout: '180s'
+ frequency: '1m'
+ delay: '1m'
\ No newline at end of file
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/start.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/start.gen.ts
index e78c6d812bb10..a67333c7875da 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/start.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/start.gen.ts
@@ -21,7 +21,7 @@ import { EntityType } from '../common.gen';
export type StartEntityEngineRequestParams = z.infer;
export const StartEntityEngineRequestParams = z.object({
/**
- * The entity type of the engine
+ * The entity type of the engine to start.
*/
entityType: EntityType,
});
@@ -29,5 +29,8 @@ export type StartEntityEngineRequestParamsInput = z.input;
export const StartEntityEngineResponse = z.object({
+ /**
+ * Whether the engine was successfully started.
+ */
started: z.boolean().optional(),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/start.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/start.schema.yaml
index 188254a67df1a..b8738f1808828 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/start.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/start.schema.yaml
@@ -10,13 +10,15 @@ paths:
x-codegen-enabled: true
operationId: StartEntityEngine
summary: Start an Entity Engine
+ description: Start a previously stopped entity engine, resuming transform processing for the given entity type.
parameters:
- name: entityType
in: path
required: true
schema:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
- description: The entity type of the engine
+ description: The entity type of the engine to start.
+ example: host
responses:
'200':
description: Successful response
@@ -24,8 +26,13 @@ paths:
application/json:
schema:
type: object
- properties:
+ properties:
started:
type: boolean
-
-
\ No newline at end of file
+ description: Whether the engine was successfully started.
+ examples:
+ startEntityEngineExample:
+ summary: Engine started successfully
+ description: The engine was successfully started and is now processing data.
+ value:
+ started: true
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/stop.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/stop.gen.ts
index c2bb1bcc834be..96d3deec427bd 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/stop.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/stop.gen.ts
@@ -21,7 +21,7 @@ import { EntityType } from '../common.gen';
export type StopEntityEngineRequestParams = z.infer;
export const StopEntityEngineRequestParams = z.object({
/**
- * The entity type of the engine (either 'user' or 'host').
+ * The entity type of the engine to stop.
*/
entityType: EntityType,
});
@@ -29,5 +29,8 @@ export type StopEntityEngineRequestParamsInput = z.input;
export const StopEntityEngineResponse = z.object({
+ /**
+ * Whether the engine was successfully stopped.
+ */
stopped: z.boolean().optional(),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/stop.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/stop.schema.yaml
index 7c2c16c94fcc8..31c095f0bf8b7 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/stop.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/engine/stop.schema.yaml
@@ -10,13 +10,15 @@ paths:
x-codegen-enabled: true
operationId: StopEntityEngine
summary: Stop an Entity Engine
+ description: Stop a running entity engine, pausing transform processing for the given entity type.
parameters:
- name: entityType
in: path
required: true
schema:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
- description: The entity type of the engine (either 'user' or 'host').
+ description: The entity type of the engine to stop.
+ example: host
responses:
'200':
description: Successful response
@@ -24,7 +26,13 @@ paths:
application/json:
schema:
type: object
- properties:
+ properties:
stopped:
type: boolean
-
+ description: Whether the engine was successfully stopped.
+ examples:
+ stopEntityEngineExample:
+ summary: Engine stopped successfully
+ description: The engine was successfully stopped and is no longer processing data.
+ value:
+ stopped: true
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/common.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/common.gen.ts
index 6efd6e4be02b9..5e02c0680341c 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/common.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/common.gen.ts
@@ -19,20 +19,50 @@ import { z } from '@kbn/zod';
import { EntityRiskScoreRecord } from '../../common/common.gen';
import { AssetCriticalityLevel } from '../../asset_criticality/common.gen';
+/**
+ * An entity record representing a user, stored in the Entity Store latest index.
+ */
export type UserEntity = z.infer;
export const UserEntity = z.object({
+ /**
+ * The time the entity record was last updated.
+ */
'@timestamp': z.string().datetime().optional(),
entity: z.object({
name: z.string(),
source: z.string(),
}),
+ /**
+ * Elastic Common Schema (ECS) user fields collected on the entity.
+ */
user: z.object({
+ /**
+ * Observed full names of the user.
+ */
full_name: z.array(z.string()).optional(),
+ /**
+ * Observed user domains.
+ */
domain: z.array(z.string()).optional(),
+ /**
+ * Observed roles assigned to the user.
+ */
roles: z.array(z.string()).optional(),
+ /**
+ * Primary user name.
+ */
name: z.string(),
+ /**
+ * Observed user IDs.
+ */
id: z.array(z.string()).optional(),
+ /**
+ * Observed email addresses.
+ */
email: z.array(z.string()).optional(),
+ /**
+ * Observed user hashes.
+ */
hash: z.array(z.string()).optional(),
risk: EntityRiskScoreRecord.optional(),
}),
@@ -43,26 +73,62 @@ export const UserEntity = z.object({
.optional(),
event: z
.object({
+ /**
+ * When the event was ingested into Elasticsearch.
+ */
ingested: z.string().datetime().optional(),
})
.optional(),
});
+/**
+ * An entity record representing a host, stored in the Entity Store latest index.
+ */
export type HostEntity = z.infer;
export const HostEntity = z.object({
+ /**
+ * The time the entity record was last updated.
+ */
'@timestamp': z.string().datetime().optional(),
entity: z.object({
name: z.string(),
source: z.string(),
}),
+ /**
+ * Elastic Common Schema (ECS) host fields collected on the entity.
+ */
host: z.object({
+ /**
+ * Observed hostnames.
+ */
hostname: z.array(z.string()).optional(),
+ /**
+ * Observed host domains.
+ */
domain: z.array(z.string()).optional(),
+ /**
+ * Observed IP addresses.
+ */
ip: z.array(z.string()).optional(),
+ /**
+ * Primary host name.
+ */
name: z.string(),
+ /**
+ * Observed host IDs.
+ */
id: z.array(z.string()).optional(),
+ /**
+ * Observed host types.
+ */
type: z.array(z.string()).optional(),
+ /**
+ * Observed MAC addresses.
+ */
mac: z.array(z.string()).optional(),
+ /**
+ * Observed CPU architectures.
+ */
architecture: z.array(z.string()).optional(),
risk: EntityRiskScoreRecord.optional(),
}),
@@ -73,19 +139,34 @@ export const HostEntity = z.object({
.optional(),
event: z
.object({
+ /**
+ * When the event was ingested into Elasticsearch.
+ */
ingested: z.string().datetime().optional(),
})
.optional(),
});
+/**
+ * An entity record representing a service, stored in the Entity Store latest index.
+ */
export type ServiceEntity = z.infer;
export const ServiceEntity = z.object({
+ /**
+ * The time the entity record was last updated.
+ */
'@timestamp': z.string().datetime().optional(),
entity: z.object({
name: z.string(),
source: z.string(),
}),
+ /**
+ * Elastic Common Schema (ECS) service fields collected on the entity.
+ */
service: z.object({
+ /**
+ * Primary service name.
+ */
name: z.string(),
risk: EntityRiskScoreRecord.optional(),
}),
@@ -96,11 +177,17 @@ export const ServiceEntity = z.object({
.optional(),
event: z
.object({
+ /**
+ * When the event was ingested into Elasticsearch.
+ */
ingested: z.string().datetime().optional(),
})
.optional(),
});
+/**
+ * An entity record from the Entity Store. The `entity` namespace is a root-level field in the latest index, unlike source logs where it is nested under `host`, `user`, or `service`.
+ */
export const EntityInternal = z.union([UserEntity, HostEntity, ServiceEntity]);
export type Entity = z.infer;
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/common.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/common.schema.yaml
index d2b2f46ff5e34..b50510f42b274 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/common.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/common.schema.yaml
@@ -8,6 +8,7 @@ components:
schemas:
UserEntity:
type: object
+ description: An entity record representing a user, stored in the Entity Store latest index.
required:
- user
- entity
@@ -15,6 +16,7 @@ components:
"@timestamp":
type: string
format: date-time
+ description: The time the entity record was last updated.
entity:
type: object
required:
@@ -27,31 +29,39 @@ components:
type: string
user:
type: object
+ description: Elastic Common Schema (ECS) user fields collected on the entity.
properties:
full_name:
type: array
+ description: Observed full names of the user.
items:
type: string
domain:
type: array
+ description: Observed user domains.
items:
type: string
roles:
type: array
+ description: Observed roles assigned to the user.
items:
type: string
name:
type: string
+ description: Primary user name.
id:
type: array
+ description: Observed user IDs.
items:
type: string
email:
type: array
+ description: Observed email addresses.
items:
type: string
hash:
type: array
+ description: Observed user hashes.
items:
type: string
risk:
@@ -71,8 +81,10 @@ components:
ingested:
type: string
format: date-time
+ description: When the event was ingested into Elasticsearch.
HostEntity:
type: object
+ description: An entity record representing a host, stored in the Entity Store latest index.
required:
- host
- entity
@@ -80,6 +92,7 @@ components:
"@timestamp":
type: string
format: date-time
+ description: The time the entity record was last updated.
entity:
type: object
required:
@@ -92,35 +105,44 @@ components:
type: string
host:
type: object
+ description: Elastic Common Schema (ECS) host fields collected on the entity.
properties:
hostname:
type: array
+ description: Observed hostnames.
items:
type: string
domain:
type: array
+ description: Observed host domains.
items:
type: string
ip:
type: array
+ description: Observed IP addresses.
items:
type: string
name:
type: string
+ description: Primary host name.
id:
type: array
+ description: Observed host IDs.
items:
type: string
type:
type: array
+ description: Observed host types.
items:
type: string
mac:
type: array
+ description: Observed MAC addresses.
items:
type: string
architecture:
type: array
+ description: Observed CPU architectures.
items:
type: string
risk:
@@ -140,8 +162,10 @@ components:
ingested:
type: string
format: date-time
+ description: When the event was ingested into Elasticsearch.
ServiceEntity:
type: object
+ description: An entity record representing a service, stored in the Entity Store latest index.
required:
- service
- entity
@@ -149,6 +173,7 @@ components:
"@timestamp":
type: string
format: date-time
+ description: The time the entity record was last updated.
entity:
type: object
required:
@@ -161,9 +186,11 @@ components:
type: string
service:
type: object
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
properties:
name:
type: string
+ description: Primary service name.
risk:
$ref: '../../common/common.schema.yaml#/components/schemas/EntityRiskScoreRecord'
required:
@@ -181,7 +208,10 @@ components:
ingested:
type: string
format: date-time
+ description: When the event was ingested into Elasticsearch.
+
Entity:
+ description: An entity record from the Entity Store. The `entity` namespace is a root-level field in the latest index, unlike source logs where it is nested under `host`, `user`, or `service`.
oneOf:
- $ref: '#/components/schemas/UserEntity'
- $ref: '#/components/schemas/HostEntity'
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/list_entities.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/list_entities.gen.ts
index daf6c003194b8..23ff2684b978b 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/list_entities.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/list_entities.gen.ts
@@ -22,23 +22,50 @@ import { Entity } from './common.gen';
export type ListEntitiesRequestQuery = z.infer;
export const ListEntitiesRequestQuery = z.object({
+ /**
+ * Field to sort results by.
+ */
sort_field: z.string().optional(),
+ /**
+ * Sort order.
+ */
sort_order: z.enum(['asc', 'desc']).optional(),
+ /**
+ * Page number to return (1-indexed).
+ */
page: z.coerce.number().int().min(1).optional(),
+ /**
+ * Number of entities per page.
+ */
per_page: z.coerce.number().int().min(1).max(10000).optional(),
/**
* An ES query to filter by.
*/
filterQuery: z.string().optional(),
+ /**
+ * Entity types to include in the results.
+ */
entity_types: ArrayFromString(EntityType),
});
export type ListEntitiesRequestQueryInput = z.input;
export type ListEntitiesResponse = z.infer;
export const ListEntitiesResponse = z.object({
+ /**
+ * The entity records for this page.
+ */
records: z.array(Entity),
+ /**
+ * Current page number.
+ */
page: z.number().int().min(1),
+ /**
+ * Number of entities per page.
+ */
per_page: z.number().int().min(1).max(1000),
+ /**
+ * Total number of entities matching the query.
+ */
total: z.number().int().min(0),
inspect: InspectQuery.optional(),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/list_entities.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/list_entities.schema.yaml
index 8063542001c29..3e81b0e2300b6 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/list_entities.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/list_entities.schema.yaml
@@ -17,6 +17,8 @@ paths:
required: false
schema:
type: string
+ description: Field to sort results by.
+ example: 'entity.name'
- name: sort_order
in: query
required: false
@@ -25,12 +27,15 @@ paths:
enum:
- asc
- desc
+ description: Sort order.
- name: page
in: query
required: false
schema:
type: integer
minimum: 1
+ description: Page number to return (1-indexed).
+ example: 1
- name: per_page
in: query
required: false
@@ -38,6 +43,8 @@ paths:
type: integer
minimum: 1
maximum: 10000
+ description: Number of entities per page.
+ example: 10
- name: filterQuery
in: query
required: false
@@ -51,6 +58,7 @@ paths:
type: array
items:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
+ description: Entity types to include in the results.
responses:
'200':
description: Entities returned successfully
@@ -61,18 +69,22 @@ paths:
properties:
records:
type: array
+ description: The entity records for this page.
items:
$ref: './common.schema.yaml#/components/schemas/Entity'
page:
type: integer
minimum: 1
+ description: Current page number.
per_page:
type: integer
minimum: 1
maximum: 1000
+ description: Number of entities per page.
total:
type: integer
minimum: 0
+ description: Total number of entities matching the query.
inspect:
$ref: '../common.schema.yaml#/components/schemas/InspectQuery'
required:
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/status.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/status.gen.ts
index 76249a787a43b..ef33f27edbc49 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/status.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/status.gen.ts
@@ -10,7 +10,7 @@
* This file is automatically generated by the OpenAPI Generator, @kbn/openapi-generator.
*
* info:
- * title: Enable Entity Store
+ * title: Get Entity Store Status
* version: 2023-10-31
*/
@@ -22,7 +22,7 @@ import { StoreStatus, EngineDescriptor, EngineComponentStatus } from './common.g
export type GetEntityStoreStatusRequestQuery = z.infer;
export const GetEntityStoreStatusRequestQuery = z.object({
/**
- * If true returns a detailed status of the engine including all it's components
+ * If true, returns a detailed status of each engine including all its components.
*/
include_components: BooleanFromString.optional(),
});
@@ -32,10 +32,19 @@ export type GetEntityStoreStatusRequestQueryInput = z.input<
export type GetEntityStoreStatusResponse = z.infer;
export const GetEntityStoreStatusResponse = z.object({
+ /**
+ * The overall status of the Entity Store.
+ */
status: StoreStatus,
+ /**
+ * Per-engine status information.
+ */
engines: z.array(
EngineDescriptor.merge(
z.object({
+ /**
+ * Detailed component-level status. Only included when include_components is true.
+ */
components: z.array(EngineComponentStatus).optional(),
})
)
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/status.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/status.schema.yaml
index a1be66282328e..a7f7be3c123b0 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/status.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/status.schema.yaml
@@ -1,7 +1,7 @@
openapi: 3.0.0
info:
- title: Enable Entity Store
+ title: Get Entity Store Status
version: '2023-10-31'
paths:
/api/entity_store/status:
@@ -10,13 +10,15 @@ paths:
x-codegen-enabled: true
operationId: GetEntityStoreStatus
summary: Get the status of the Entity Store
-
+ description: Get the overall Entity Store status and per-engine statuses, optionally including component-level health details.
+
parameters:
- name: include_components
- in: query
+ in: query
schema:
type: boolean
- description: If true returns a detailed status of the engine including all it's components
+ description: If true, returns a detailed status of each engine including all its components.
+ example: true
responses:
'200':
@@ -29,10 +31,12 @@ paths:
- status
- engines
properties:
- status:
+ status:
$ref: './common.schema.yaml#/components/schemas/StoreStatus'
+ description: The overall status of the Entity Store.
engines:
type: array
+ description: Per-engine status information.
items:
allOf:
- $ref: './common.schema.yaml#/components/schemas/EngineDescriptor'
@@ -40,5 +44,31 @@ paths:
properties:
components:
type: array
+ description: Detailed component-level status. Only included when include_components is true.
items:
$ref: './common.schema.yaml#/components/schemas/EngineComponentStatus'
+ examples:
+ entityStoreRunning:
+ summary: Entity Store running with two engines
+ description: The Entity Store is running with both host and user engines started and using default settings.
+ value:
+ status: running
+ engines:
+ - type: host
+ indexPattern: ''
+ status: started
+ fieldHistoryLength: 10
+ lookbackPeriod: '24h'
+ timestampField: '@timestamp'
+ timeout: '180s'
+ frequency: '1m'
+ delay: '1m'
+ - type: user
+ indexPattern: ''
+ status: started
+ fieldHistoryLength: 10
+ lookbackPeriod: '24h'
+ timestampField: '@timestamp'
+ timeout: '180s'
+ frequency: '1m'
+ delay: '1m'
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts
index 76efaabb9f0a6..473fb75462460 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/quickstart_client.gen.ts
@@ -459,6 +459,9 @@ after 30 days. It also deletes other artifacts specific to the migration impleme
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Synchronize data view index patterns to all running entity engines so that newly added indices are picked up by the transforms.
+ */
async applyEntityEngineDataviewIndices() {
this.log.info(`${new Date().toISOString()} Calling API ApplyEntityEngineDataviewIndices`);
return this.kbnClient
@@ -1319,6 +1322,9 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Check whether the current user has the required Elasticsearch and Kibana privileges to use the Entity Store.
+ */
async entityStoreGetPrivileges() {
this.log.info(`${new Date().toISOString()} Calling API EntityStoreGetPrivileges`);
return this.kbnClient
@@ -1529,6 +1535,9 @@ finalize it.
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Get the engine descriptor for a specific entity type, including its configuration and current status.
+ */
async getEntityEngine(props: GetEntityEngineProps) {
this.log.info(`${new Date().toISOString()} Calling API GetEntityEngine`);
return this.kbnClient
@@ -1541,6 +1550,9 @@ finalize it.
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Get the overall Entity Store status and per-engine statuses, optionally including component-level health details.
+ */
async getEntityStoreStatus(props: GetEntityStoreStatusProps) {
this.log.info(`${new Date().toISOString()} Calling API GetEntityStoreStatus`);
return this.kbnClient
@@ -1913,6 +1925,9 @@ finalize it.
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Initialize a single entity engine for the specified entity type.
+ */
async initEntityEngine(props: InitEntityEngineProps) {
this.log.info(`${new Date().toISOString()} Calling API InitEntityEngine`);
return this.kbnClient
@@ -1926,6 +1941,9 @@ finalize it.
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Initialize the entire Entity Store, creating engines for all or specified entity types.
+ */
async initEntityStore(props: InitEntityStoreProps) {
this.log.info(`${new Date().toISOString()} Calling API InitEntityStore`);
return this.kbnClient
@@ -2042,6 +2060,9 @@ providing you with the most current and effective threat detection capabilities.
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Get a list of all installed entity engines and their current status.
+ */
async listEntityEngines() {
this.log.info(`${new Date().toISOString()} Calling API ListEntityEngines`);
return this.kbnClient
@@ -2453,6 +2474,9 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Start a previously stopped entity engine, resuming transform processing for the given entity type.
+ */
async startEntityEngine(props: StartEntityEngineProps) {
this.log.info(`${new Date().toISOString()} Calling API StartEntityEngine`);
return this.kbnClient
@@ -2481,6 +2505,9 @@ The difference between the `id` and `rule_id` is that the `id` is a unique rule
})
.catch(catchAxiosErrorFormatAndThrow);
}
+ /**
+ * Stop a running entity engine, pausing transform processing for the given entity type.
+ */
async stopEntityEngine(props: StopEntityEngineProps) {
this.log.info(`${new Date().toISOString()} Calling API StopEntityEngine`);
return this.kbnClient
diff --git a/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml
index b06a91ff4cb6c..923b87d28a923 100644
--- a/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/docs/openapi/ess/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml
@@ -1,6 +1,6 @@
openapi: 3.0.3
info:
- description: ''
+ description: Manage entity risk scores, asset criticality, and the Entity Store.
title: Security Entity Analytics API (Elastic Cloud and self-hosted)
version: '2023-10-31'
servers:
@@ -300,6 +300,9 @@ paths:
- Security Entity Analytics API
/api/entity_store/enable:
post:
+ description: >-
+ Initialize the entire Entity Store, creating engines for all or
+ specified entity types.
operationId: InitEntityStore
requestBody:
content:
@@ -350,20 +353,49 @@ paths:
default: '@timestamp'
description: The field to use as the timestamp.
type: string
- description: Schema for the entity store initialization
+ description: Configuration for the entity store initialization.
required: true
responses:
'200':
content:
application/json:
+ examples:
+ initEntityStoreExample:
+ description: >-
+ The Entity Store was successfully initialized, creating host
+ and user engines in the installing state.
+ summary: Entity Store initialized with host and user engines
+ value:
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
+ succeeded: true
schema:
type: object
properties:
engines:
+ description: The engine descriptors created during initialization.
items:
$ref: '#/components/schemas/EngineDescriptor'
type: array
succeeded:
+ description: Whether the Entity Store was initialized successfully.
type: boolean
description: Successful response
'400':
@@ -373,17 +405,47 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines:
get:
+ description: Get a list of all installed entity engines and their current status.
operationId: ListEntityEngines
responses:
'200':
content:
application/json:
+ examples:
+ listEntityEnginesExample:
+ description: >-
+ Returns a list with one running host engine and one stopped
+ user engine.
+ summary: Two engines installed
+ value:
+ count: 2
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: stopped
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
schema:
type: object
properties:
count:
+ description: The total number of entity engines.
type: integer
engines:
+ description: An array of engine descriptors.
items:
$ref: '#/components/schemas/EngineDescriptor'
type: array
@@ -415,15 +477,20 @@ paths:
type: object
properties:
deleted:
+ description: Whether the engine was successfully deleted.
type: boolean
description: Successful response
summary: Delete the Entity Engine
tags:
- Security Entity Analytics API
get:
+ description: >-
+ Get the engine descriptor for a specific entity type, including its
+ configuration and current status.
operationId: GetEntityEngine
parameters:
- - description: The entity type of the engine (either 'user' or 'host').
+ - description: The entity type of the engine.
+ example: host
in: path
name: entityType
required: true
@@ -433,6 +500,22 @@ paths:
'200':
content:
application/json:
+ examples:
+ getEntityEngineExample:
+ description: >-
+ Returns the engine descriptor for a host engine that is
+ currently running with default settings.
+ summary: A running host engine
+ value:
+ delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
schema:
$ref: '#/components/schemas/EngineDescriptor'
description: Successful response
@@ -441,6 +524,7 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines/{entityType}/init:
post:
+ description: Initialize a single entity engine for the specified entity type.
operationId: InitEntityEngine
parameters:
- description: The entity type of the engine (either 'user' or 'host').
@@ -500,6 +584,22 @@ paths:
'200':
content:
application/json:
+ examples:
+ initEntityEngineExample:
+ description: >-
+ A host engine was successfully initialized and is now in the
+ installing state.
+ summary: Host engine initialized
+ value:
+ delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 3h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
schema:
$ref: '#/components/schemas/EngineDescriptor'
description: Successful response
@@ -510,9 +610,13 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines/{entityType}/start:
post:
+ description: >-
+ Start a previously stopped entity engine, resuming transform processing
+ for the given entity type.
operationId: StartEntityEngine
parameters:
- - description: The entity type of the engine
+ - description: The entity type of the engine to start.
+ example: host
in: path
name: entityType
required: true
@@ -522,10 +626,19 @@ paths:
'200':
content:
application/json:
+ examples:
+ startEntityEngineExample:
+ description: >-
+ The engine was successfully started and is now processing
+ data.
+ summary: Engine started successfully
+ value:
+ started: true
schema:
type: object
properties:
started:
+ description: Whether the engine was successfully started.
type: boolean
description: Successful response
summary: Start an Entity Engine
@@ -533,9 +646,13 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines/{entityType}/stop:
post:
+ description: >-
+ Stop a running entity engine, pausing transform processing for the given
+ entity type.
operationId: StopEntityEngine
parameters:
- - description: The entity type of the engine (either 'user' or 'host').
+ - description: The entity type of the engine to stop.
+ example: host
in: path
name: entityType
required: true
@@ -545,10 +662,19 @@ paths:
'200':
content:
application/json:
+ examples:
+ stopEntityEngineExample:
+ description: >-
+ The engine was successfully stopped and is no longer
+ processing data.
+ summary: Engine stopped successfully
+ value:
+ stopped: true
schema:
type: object
properties:
stopped:
+ description: Whether the engine was successfully stopped.
type: boolean
description: Successful response
summary: Stop an Entity Engine
@@ -556,47 +682,103 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines/apply_dataview_indices:
post:
+ description: >-
+ Synchronize data view index patterns to all running entity engines so
+ that newly added indices are picked up by the transforms.
operationId: ApplyEntityEngineDataviewIndices
responses:
'200':
content:
application/json:
+ examples:
+ applyDataviewIndicesExample:
+ description: >-
+ All running engines were successfully updated with the
+ current data view index patterns.
+ summary: All engines updated
+ value:
+ result:
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ - auditbeat-*
+ type: host
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ - auditbeat-*
+ type: user
+ success: true
schema:
type: object
properties:
result:
+ description: Per-engine update results.
items:
$ref: '#/components/schemas/EngineDataviewUpdateResult'
type: array
success:
+ description: Whether all engines updated successfully.
type: boolean
description: Successful response
'207':
content:
application/json:
+ examples:
+ partialSuccessExample:
+ description: >-
+ The host engine was updated but the user engine failed due
+ to insufficient privileges.
+ summary: One engine failed
+ value:
+ errors:
+ - 'Failed to update user engine: insufficient privileges'
+ result:
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ type: host
+ success: false
schema:
type: object
properties:
errors:
+ description: Error messages for engines that failed to update.
items:
type: string
type: array
result:
+ description: Per-engine update results for engines that succeeded.
items:
$ref: '#/components/schemas/EngineDataviewUpdateResult'
type: array
success:
+ description: Always `false` for a partial success.
type: boolean
description: Partial successful response
'500':
content:
application/json:
+ examples:
+ serverErrorExample:
+ description: >-
+ An unexpected error occurred while applying data view
+ indices.
+ summary: Internal server error
+ value:
+ body: An internal error occurred while updating engine indices
+ statusCode: 500
schema:
type: object
properties:
body:
+ description: Error message.
type: string
statusCode:
+ description: HTTP status code.
type: number
description: Error response
summary: Apply DataView indices to all installed engines
@@ -607,12 +789,15 @@ paths:
description: List entities records, paging, sorting and filtering as needed.
operationId: ListEntities
parameters:
- - in: query
+ - description: Field to sort results by.
+ example: entity.name
+ in: query
name: sort_field
required: false
schema:
type: string
- - in: query
+ - description: Sort order.
+ in: query
name: sort_order
required: false
schema:
@@ -620,13 +805,17 @@ paths:
- asc
- desc
type: string
- - in: query
+ - description: Page number to return (1-indexed).
+ example: 1
+ in: query
name: page
required: false
schema:
minimum: 1
type: integer
- - in: query
+ - description: Number of entities per page.
+ example: 10
+ in: query
name: per_page
required: false
schema:
@@ -639,7 +828,8 @@ paths:
required: false
schema:
type: string
- - in: query
+ - description: Entity types to include in the results.
+ in: query
name: entity_types
required: true
schema:
@@ -656,17 +846,21 @@ paths:
inspect:
$ref: '#/components/schemas/InspectQuery'
page:
+ description: Current page number.
minimum: 1
type: integer
per_page:
+ description: Number of entities per page.
maximum: 1000
minimum: 1
type: integer
records:
+ description: The entity records for this page.
items:
$ref: '#/components/schemas/Entity'
type: array
total:
+ description: Total number of entities matching the query.
minimum: 0
type: integer
required:
@@ -680,11 +874,15 @@ paths:
- Security Entity Analytics API
/api/entity_store/status:
get:
+ description: >-
+ Get the overall Entity Store status and per-engine statuses, optionally
+ including component-level health details.
operationId: GetEntityStoreStatus
parameters:
- description: >-
- If true returns a detailed status of the engine including all it's
- components
+ If true, returns a detailed status of each engine including all its
+ components.
+ example: true
in: query
name: include_components
schema:
@@ -693,22 +891,54 @@ paths:
'200':
content:
application/json:
+ examples:
+ entityStoreRunning:
+ description: >-
+ The Entity Store is running with both host and user engines
+ started and using default settings.
+ summary: Entity Store running with two engines
+ value:
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
+ status: running
schema:
type: object
properties:
engines:
+ description: Per-engine status information.
items:
allOf:
- $ref: '#/components/schemas/EngineDescriptor'
- type: object
properties:
components:
+ description: >-
+ Detailed component-level status. Only included
+ when include_components is true.
items:
$ref: '#/components/schemas/EngineComponentStatus'
type: array
type: array
status:
$ref: '#/components/schemas/StoreStatus'
+ description: The overall status of the Entity Store.
required:
- status
- engines
@@ -1007,6 +1237,9 @@ components:
required:
- criticality_level
EngineComponentResource:
+ description: >-
+ The type of Elasticsearch or Kibana resource backing an engine
+ component.
enum:
- entity_engine
- entity_definition
@@ -1019,18 +1252,25 @@ components:
- transform
type: string
EngineComponentStatus:
+ description: >-
+ Status of an individual Elasticsearch or Kibana resource backing an
+ engine.
type: object
properties:
errors:
+ description: Errors reported by this component, if any.
items:
type: object
properties:
message:
+ description: Detailed error message.
type: string
title:
+ description: Short error title.
type: string
type: array
health:
+ description: The health status of the component.
enum:
- green
- yellow
@@ -1039,8 +1279,10 @@ components:
- unknown
type: string
id:
+ description: Unique identifier for the component.
type: string
installed:
+ description: Whether the component is currently installed.
type: boolean
resource:
$ref: '#/components/schemas/EngineComponentResource'
@@ -1049,61 +1291,92 @@ components:
- installed
- resource
EngineDataviewUpdateResult:
+ description: The result of applying data view index changes to a single engine.
type: object
properties:
changes:
+ description: The changes applied to the engine.
type: object
properties:
indexPatterns:
+ description: The updated list of index patterns now used by the engine.
items:
type: string
type: array
type:
+ description: The entity type of the engine that was updated.
type: string
required:
- type
EngineDescriptor:
+ description: >-
+ Describes a single entity engine, including its configuration and
+ current status.
type: object
properties:
delay:
default: 1m
+ description: >-
+ The delay before the transform processes new data, allowing
+ late-arriving documents to be included.
+ example: 1m
pattern: '[smdh]$'
type: string
docsPerSecond:
+ description: >-
+ Throttle value for the number of documents processed per second. Use
+ -1 for no throttle.
type: integer
error:
+ description: Present when the engine status is `error`. Describes the failure.
type: object
properties:
action:
+ description: The lifecycle action that caused the error.
enum:
- init
type: string
message:
+ description: A human-readable error message.
type: string
required:
- message
- action
fieldHistoryLength:
+ description: The number of historical values retained per field.
+ example: 10
type: integer
filter:
+ description: >-
+ An optional Kibana Query Language (KQL) filter applied to source
+ documents before aggregation.
+ example: 'host.name: "my-host"'
type: string
frequency:
default: 1m
+ description: How often the transform runs.
+ example: 1m
pattern: '[smdh]$'
type: string
indexPattern:
$ref: '#/components/schemas/IndexPattern'
lookbackPeriod:
default: 24h
+ description: How far back the transform looks when calculating aggregations.
+ example: 24h
pattern: '[smdh]$'
type: string
status:
$ref: '#/components/schemas/EngineStatus'
timeout:
default: 180s
+ description: The timeout for initializing the aggregating transform.
+ example: 180s
pattern: '[smdh]$'
type: string
timestampField:
+ description: The field used as the timestamp for source documents.
+ example: '@timestamp'
type: string
type:
$ref: '#/components/schemas/EntityType'
@@ -1113,6 +1386,7 @@ components:
- status
- fieldHistoryLength
EngineStatus:
+ description: The current operational status of an entity engine.
enum:
- installing
- started
@@ -1121,6 +1395,10 @@ components:
- error
type: string
Entity:
+ description: >-
+ An entity record from the Entity Store. The `entity` namespace is a
+ root-level field in the latest index, unlike source logs where it is
+ nested under `host`, `user`, or `service`.
oneOf:
- $ref: '#/components/schemas/UserEntity'
- $ref: '#/components/schemas/HostEntity'
@@ -1213,15 +1491,20 @@ components:
- inputs
- notes
EntityType:
+ description: The type of entity.
enum:
- user
- host
- service
type: string
HostEntity:
+ description: >-
+ An entity record representing a host, stored in the Entity Store latest
+ index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -1245,40 +1528,50 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
host:
+ description: Elastic Common Schema (ECS) host fields collected on the entity.
type: object
properties:
architecture:
+ description: Observed CPU architectures.
items:
type: string
type: array
domain:
+ description: Observed host domains.
items:
type: string
type: array
hostname:
+ description: Observed hostnames.
items:
type: string
type: array
id:
+ description: Observed host IDs.
items:
type: string
type: array
ip:
+ description: Observed IP addresses.
items:
type: string
type: array
mac:
+ description: Observed MAC addresses.
items:
type: string
type: array
name:
+ description: Primary host name.
type: string
risk:
$ref: '#/components/schemas/EntityRiskScoreRecord'
type:
+ description: Observed host types.
items:
type: string
type: array
@@ -1294,15 +1587,23 @@ components:
- service.name
type: string
IndexPattern:
+ description: >-
+ An additional Elasticsearch index pattern to include as a source for
+ entity data. Merged with the default data view indices when the engine
+ runs.
+ example: logs-*
type: string
InspectQuery:
+ description: Debug information about the Elasticsearch query executed.
type: object
properties:
dsl:
+ description: Elasticsearch query DSL that was executed.
items:
type: string
type: array
response:
+ description: Raw Elasticsearch responses.
items:
type: string
type: array
@@ -1371,9 +1672,13 @@ components:
- description
- category
ServiceEntity:
+ description: >-
+ An entity record representing a service, stored in the Entity Store
+ latest index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -1397,12 +1702,15 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
service:
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
type: object
properties:
name:
+ description: Primary service name.
type: string
risk:
$ref: '#/components/schemas/EntityRiskScoreRecord'
@@ -1412,6 +1720,7 @@ components:
- service
- entity
StoreStatus:
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -1432,9 +1741,13 @@ components:
- status_code
- message
UserEntity:
+ description: >-
+ An entity record representing a user, stored in the Entity Store latest
+ index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -1458,36 +1771,45 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
user:
+ description: Elastic Common Schema (ECS) user fields collected on the entity.
type: object
properties:
domain:
+ description: Observed user domains.
items:
type: string
type: array
email:
+ description: Observed email addresses.
items:
type: string
type: array
full_name:
+ description: Observed full names of the user.
items:
type: string
type: array
hash:
+ description: Observed user hashes.
items:
type: string
type: array
id:
+ description: Observed user IDs.
items:
type: string
type: array
name:
+ description: Primary user name.
type: string
risk:
$ref: '#/components/schemas/EntityRiskScoreRecord'
roles:
+ description: Observed roles assigned to the user.
items:
type: string
type: array
diff --git a/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml b/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml
index db449c167ea17..0c887c15537a6 100644
--- a/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/docs/openapi/serverless/security_solution_entity_analytics_api_2023_10_31.bundled.schema.yaml
@@ -1,6 +1,6 @@
openapi: 3.0.3
info:
- description: ''
+ description: Manage entity risk scores, asset criticality, and the Entity Store.
title: Security Entity Analytics API (Elastic Cloud Serverless)
version: '2023-10-31'
servers:
@@ -300,6 +300,9 @@ paths:
- Security Entity Analytics API
/api/entity_store/enable:
post:
+ description: >-
+ Initialize the entire Entity Store, creating engines for all or
+ specified entity types.
operationId: InitEntityStore
requestBody:
content:
@@ -350,20 +353,49 @@ paths:
default: '@timestamp'
description: The field to use as the timestamp.
type: string
- description: Schema for the entity store initialization
+ description: Configuration for the entity store initialization.
required: true
responses:
'200':
content:
application/json:
+ examples:
+ initEntityStoreExample:
+ description: >-
+ The Entity Store was successfully initialized, creating host
+ and user engines in the installing state.
+ summary: Entity Store initialized with host and user engines
+ value:
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
+ succeeded: true
schema:
type: object
properties:
engines:
+ description: The engine descriptors created during initialization.
items:
$ref: '#/components/schemas/EngineDescriptor'
type: array
succeeded:
+ description: Whether the Entity Store was initialized successfully.
type: boolean
description: Successful response
'400':
@@ -373,17 +405,47 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines:
get:
+ description: Get a list of all installed entity engines and their current status.
operationId: ListEntityEngines
responses:
'200':
content:
application/json:
+ examples:
+ listEntityEnginesExample:
+ description: >-
+ Returns a list with one running host engine and one stopped
+ user engine.
+ summary: Two engines installed
+ value:
+ count: 2
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: stopped
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
schema:
type: object
properties:
count:
+ description: The total number of entity engines.
type: integer
engines:
+ description: An array of engine descriptors.
items:
$ref: '#/components/schemas/EngineDescriptor'
type: array
@@ -415,15 +477,20 @@ paths:
type: object
properties:
deleted:
+ description: Whether the engine was successfully deleted.
type: boolean
description: Successful response
summary: Delete the Entity Engine
tags:
- Security Entity Analytics API
get:
+ description: >-
+ Get the engine descriptor for a specific entity type, including its
+ configuration and current status.
operationId: GetEntityEngine
parameters:
- - description: The entity type of the engine (either 'user' or 'host').
+ - description: The entity type of the engine.
+ example: host
in: path
name: entityType
required: true
@@ -433,6 +500,22 @@ paths:
'200':
content:
application/json:
+ examples:
+ getEntityEngineExample:
+ description: >-
+ Returns the engine descriptor for a host engine that is
+ currently running with default settings.
+ summary: A running host engine
+ value:
+ delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
schema:
$ref: '#/components/schemas/EngineDescriptor'
description: Successful response
@@ -441,6 +524,7 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines/{entityType}/init:
post:
+ description: Initialize a single entity engine for the specified entity type.
operationId: InitEntityEngine
parameters:
- description: The entity type of the engine (either 'user' or 'host').
@@ -500,6 +584,22 @@ paths:
'200':
content:
application/json:
+ examples:
+ initEntityEngineExample:
+ description: >-
+ A host engine was successfully initialized and is now in the
+ installing state.
+ summary: Host engine initialized
+ value:
+ delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 3h
+ status: installing
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
schema:
$ref: '#/components/schemas/EngineDescriptor'
description: Successful response
@@ -510,9 +610,13 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines/{entityType}/start:
post:
+ description: >-
+ Start a previously stopped entity engine, resuming transform processing
+ for the given entity type.
operationId: StartEntityEngine
parameters:
- - description: The entity type of the engine
+ - description: The entity type of the engine to start.
+ example: host
in: path
name: entityType
required: true
@@ -522,10 +626,19 @@ paths:
'200':
content:
application/json:
+ examples:
+ startEntityEngineExample:
+ description: >-
+ The engine was successfully started and is now processing
+ data.
+ summary: Engine started successfully
+ value:
+ started: true
schema:
type: object
properties:
started:
+ description: Whether the engine was successfully started.
type: boolean
description: Successful response
summary: Start an Entity Engine
@@ -533,9 +646,13 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines/{entityType}/stop:
post:
+ description: >-
+ Stop a running entity engine, pausing transform processing for the given
+ entity type.
operationId: StopEntityEngine
parameters:
- - description: The entity type of the engine (either 'user' or 'host').
+ - description: The entity type of the engine to stop.
+ example: host
in: path
name: entityType
required: true
@@ -545,10 +662,19 @@ paths:
'200':
content:
application/json:
+ examples:
+ stopEntityEngineExample:
+ description: >-
+ The engine was successfully stopped and is no longer
+ processing data.
+ summary: Engine stopped successfully
+ value:
+ stopped: true
schema:
type: object
properties:
stopped:
+ description: Whether the engine was successfully stopped.
type: boolean
description: Successful response
summary: Stop an Entity Engine
@@ -556,47 +682,103 @@ paths:
- Security Entity Analytics API
/api/entity_store/engines/apply_dataview_indices:
post:
+ description: >-
+ Synchronize data view index patterns to all running entity engines so
+ that newly added indices are picked up by the transforms.
operationId: ApplyEntityEngineDataviewIndices
responses:
'200':
content:
application/json:
+ examples:
+ applyDataviewIndicesExample:
+ description: >-
+ All running engines were successfully updated with the
+ current data view index patterns.
+ summary: All engines updated
+ value:
+ result:
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ - auditbeat-*
+ type: host
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ - auditbeat-*
+ type: user
+ success: true
schema:
type: object
properties:
result:
+ description: Per-engine update results.
items:
$ref: '#/components/schemas/EngineDataviewUpdateResult'
type: array
success:
+ description: Whether all engines updated successfully.
type: boolean
description: Successful response
'207':
content:
application/json:
+ examples:
+ partialSuccessExample:
+ description: >-
+ The host engine was updated but the user engine failed due
+ to insufficient privileges.
+ summary: One engine failed
+ value:
+ errors:
+ - 'Failed to update user engine: insufficient privileges'
+ result:
+ - changes:
+ indexPatterns:
+ - logs-*
+ - filebeat-*
+ type: host
+ success: false
schema:
type: object
properties:
errors:
+ description: Error messages for engines that failed to update.
items:
type: string
type: array
result:
+ description: Per-engine update results for engines that succeeded.
items:
$ref: '#/components/schemas/EngineDataviewUpdateResult'
type: array
success:
+ description: Always `false` for a partial success.
type: boolean
description: Partial successful response
'500':
content:
application/json:
+ examples:
+ serverErrorExample:
+ description: >-
+ An unexpected error occurred while applying data view
+ indices.
+ summary: Internal server error
+ value:
+ body: An internal error occurred while updating engine indices
+ statusCode: 500
schema:
type: object
properties:
body:
+ description: Error message.
type: string
statusCode:
+ description: HTTP status code.
type: number
description: Error response
summary: Apply DataView indices to all installed engines
@@ -607,12 +789,15 @@ paths:
description: List entities records, paging, sorting and filtering as needed.
operationId: ListEntities
parameters:
- - in: query
+ - description: Field to sort results by.
+ example: entity.name
+ in: query
name: sort_field
required: false
schema:
type: string
- - in: query
+ - description: Sort order.
+ in: query
name: sort_order
required: false
schema:
@@ -620,13 +805,17 @@ paths:
- asc
- desc
type: string
- - in: query
+ - description: Page number to return (1-indexed).
+ example: 1
+ in: query
name: page
required: false
schema:
minimum: 1
type: integer
- - in: query
+ - description: Number of entities per page.
+ example: 10
+ in: query
name: per_page
required: false
schema:
@@ -639,7 +828,8 @@ paths:
required: false
schema:
type: string
- - in: query
+ - description: Entity types to include in the results.
+ in: query
name: entity_types
required: true
schema:
@@ -656,17 +846,21 @@ paths:
inspect:
$ref: '#/components/schemas/InspectQuery'
page:
+ description: Current page number.
minimum: 1
type: integer
per_page:
+ description: Number of entities per page.
maximum: 1000
minimum: 1
type: integer
records:
+ description: The entity records for this page.
items:
$ref: '#/components/schemas/Entity'
type: array
total:
+ description: Total number of entities matching the query.
minimum: 0
type: integer
required:
@@ -680,11 +874,15 @@ paths:
- Security Entity Analytics API
/api/entity_store/status:
get:
+ description: >-
+ Get the overall Entity Store status and per-engine statuses, optionally
+ including component-level health details.
operationId: GetEntityStoreStatus
parameters:
- description: >-
- If true returns a detailed status of the engine including all it's
- components
+ If true, returns a detailed status of each engine including all its
+ components.
+ example: true
in: query
name: include_components
schema:
@@ -693,22 +891,54 @@ paths:
'200':
content:
application/json:
+ examples:
+ entityStoreRunning:
+ description: >-
+ The Entity Store is running with both host and user engines
+ started and using default settings.
+ summary: Entity Store running with two engines
+ value:
+ engines:
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: host
+ - delay: 1m
+ fieldHistoryLength: 10
+ frequency: 1m
+ indexPattern: ''
+ lookbackPeriod: 24h
+ status: started
+ timeout: 180s
+ timestampField: '@timestamp'
+ type: user
+ status: running
schema:
type: object
properties:
engines:
+ description: Per-engine status information.
items:
allOf:
- $ref: '#/components/schemas/EngineDescriptor'
- type: object
properties:
components:
+ description: >-
+ Detailed component-level status. Only included
+ when include_components is true.
items:
$ref: '#/components/schemas/EngineComponentStatus'
type: array
type: array
status:
$ref: '#/components/schemas/StoreStatus'
+ description: The overall status of the Entity Store.
required:
- status
- engines
@@ -1007,6 +1237,9 @@ components:
required:
- criticality_level
EngineComponentResource:
+ description: >-
+ The type of Elasticsearch or Kibana resource backing an engine
+ component.
enum:
- entity_engine
- entity_definition
@@ -1019,18 +1252,25 @@ components:
- transform
type: string
EngineComponentStatus:
+ description: >-
+ Status of an individual Elasticsearch or Kibana resource backing an
+ engine.
type: object
properties:
errors:
+ description: Errors reported by this component, if any.
items:
type: object
properties:
message:
+ description: Detailed error message.
type: string
title:
+ description: Short error title.
type: string
type: array
health:
+ description: The health status of the component.
enum:
- green
- yellow
@@ -1039,8 +1279,10 @@ components:
- unknown
type: string
id:
+ description: Unique identifier for the component.
type: string
installed:
+ description: Whether the component is currently installed.
type: boolean
resource:
$ref: '#/components/schemas/EngineComponentResource'
@@ -1049,61 +1291,92 @@ components:
- installed
- resource
EngineDataviewUpdateResult:
+ description: The result of applying data view index changes to a single engine.
type: object
properties:
changes:
+ description: The changes applied to the engine.
type: object
properties:
indexPatterns:
+ description: The updated list of index patterns now used by the engine.
items:
type: string
type: array
type:
+ description: The entity type of the engine that was updated.
type: string
required:
- type
EngineDescriptor:
+ description: >-
+ Describes a single entity engine, including its configuration and
+ current status.
type: object
properties:
delay:
default: 1m
+ description: >-
+ The delay before the transform processes new data, allowing
+ late-arriving documents to be included.
+ example: 1m
pattern: '[smdh]$'
type: string
docsPerSecond:
+ description: >-
+ Throttle value for the number of documents processed per second. Use
+ -1 for no throttle.
type: integer
error:
+ description: Present when the engine status is `error`. Describes the failure.
type: object
properties:
action:
+ description: The lifecycle action that caused the error.
enum:
- init
type: string
message:
+ description: A human-readable error message.
type: string
required:
- message
- action
fieldHistoryLength:
+ description: The number of historical values retained per field.
+ example: 10
type: integer
filter:
+ description: >-
+ An optional Kibana Query Language (KQL) filter applied to source
+ documents before aggregation.
+ example: 'host.name: "my-host"'
type: string
frequency:
default: 1m
+ description: How often the transform runs.
+ example: 1m
pattern: '[smdh]$'
type: string
indexPattern:
$ref: '#/components/schemas/IndexPattern'
lookbackPeriod:
default: 24h
+ description: How far back the transform looks when calculating aggregations.
+ example: 24h
pattern: '[smdh]$'
type: string
status:
$ref: '#/components/schemas/EngineStatus'
timeout:
default: 180s
+ description: The timeout for initializing the aggregating transform.
+ example: 180s
pattern: '[smdh]$'
type: string
timestampField:
+ description: The field used as the timestamp for source documents.
+ example: '@timestamp'
type: string
type:
$ref: '#/components/schemas/EntityType'
@@ -1113,6 +1386,7 @@ components:
- status
- fieldHistoryLength
EngineStatus:
+ description: The current operational status of an entity engine.
enum:
- installing
- started
@@ -1121,6 +1395,10 @@ components:
- error
type: string
Entity:
+ description: >-
+ An entity record from the Entity Store. The `entity` namespace is a
+ root-level field in the latest index, unlike source logs where it is
+ nested under `host`, `user`, or `service`.
oneOf:
- $ref: '#/components/schemas/UserEntity'
- $ref: '#/components/schemas/HostEntity'
@@ -1213,15 +1491,20 @@ components:
- inputs
- notes
EntityType:
+ description: The type of entity.
enum:
- user
- host
- service
type: string
HostEntity:
+ description: >-
+ An entity record representing a host, stored in the Entity Store latest
+ index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -1245,40 +1528,50 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
host:
+ description: Elastic Common Schema (ECS) host fields collected on the entity.
type: object
properties:
architecture:
+ description: Observed CPU architectures.
items:
type: string
type: array
domain:
+ description: Observed host domains.
items:
type: string
type: array
hostname:
+ description: Observed hostnames.
items:
type: string
type: array
id:
+ description: Observed host IDs.
items:
type: string
type: array
ip:
+ description: Observed IP addresses.
items:
type: string
type: array
mac:
+ description: Observed MAC addresses.
items:
type: string
type: array
name:
+ description: Primary host name.
type: string
risk:
$ref: '#/components/schemas/EntityRiskScoreRecord'
type:
+ description: Observed host types.
items:
type: string
type: array
@@ -1294,15 +1587,23 @@ components:
- service.name
type: string
IndexPattern:
+ description: >-
+ An additional Elasticsearch index pattern to include as a source for
+ entity data. Merged with the default data view indices when the engine
+ runs.
+ example: logs-*
type: string
InspectQuery:
+ description: Debug information about the Elasticsearch query executed.
type: object
properties:
dsl:
+ description: Elasticsearch query DSL that was executed.
items:
type: string
type: array
response:
+ description: Raw Elasticsearch responses.
items:
type: string
type: array
@@ -1371,9 +1672,13 @@ components:
- description
- category
ServiceEntity:
+ description: >-
+ An entity record representing a service, stored in the Entity Store
+ latest index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -1397,12 +1702,15 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
service:
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
type: object
properties:
name:
+ description: Primary service name.
type: string
risk:
$ref: '#/components/schemas/EntityRiskScoreRecord'
@@ -1412,6 +1720,7 @@ components:
- service
- entity
StoreStatus:
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -1432,9 +1741,13 @@ components:
- status_code
- message
UserEntity:
+ description: >-
+ An entity record representing a user, stored in the Entity Store latest
+ index.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -1458,36 +1771,45 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
user:
+ description: Elastic Common Schema (ECS) user fields collected on the entity.
type: object
properties:
domain:
+ description: Observed user domains.
items:
type: string
type: array
email:
+ description: Observed email addresses.
items:
type: string
type: array
full_name:
+ description: Observed full names of the user.
items:
type: string
type: array
hash:
+ description: Observed user hashes.
items:
type: string
type: array
id:
+ description: Observed user IDs.
items:
type: string
type: array
name:
+ description: Primary user name.
type: string
risk:
$ref: '#/components/schemas/EntityRiskScoreRecord'
roles:
+ description: Observed roles assigned to the user.
items:
type: string
type: array
diff --git a/x-pack/solutions/security/plugins/security_solution/scripts/openapi/bundle_entity_analytics.js b/x-pack/solutions/security/plugins/security_solution/scripts/openapi/bundle_entity_analytics.js
index 195e8a7fae2bd..2d9f064c0db02 100644
--- a/x-pack/solutions/security/plugins/security_solution/scripts/openapi/bundle_entity_analytics.js
+++ b/x-pack/solutions/security/plugins/security_solution/scripts/openapi/bundle_entity_analytics.js
@@ -23,7 +23,7 @@ const ROOT = resolve(__dirname, '../..');
prototypeDocument: {
info: {
title: 'Security Entity Analytics API (Elastic Cloud Serverless)',
- description: '',
+ description: 'Manage entity risk scores, asset criticality, and the Entity Store.',
},
tags: [
{
@@ -47,7 +47,7 @@ const ROOT = resolve(__dirname, '../..');
prototypeDocument: {
info: {
title: 'Security Entity Analytics API (Elastic Cloud and self-hosted)',
- description: '',
+ description: 'Manage entity risk scores, asset criticality, and the Entity Store.',
},
tags: [
{