diff --git a/oas_docs/output/kibana.serverless.yaml b/oas_docs/output/kibana.serverless.yaml
index 3907d18519d16..d71d4897b5ab1 100644
--- a/oas_docs/output/kibana.serverless.yaml
+++ b/oas_docs/output/kibana.serverless.yaml
@@ -17951,6 +17951,14 @@ paths:
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/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:
@@ -18004,20 +18012,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':
@@ -18028,12 +18063,6 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
- 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.
/api/entity_store/engines:
delete:
operationId: DeleteEntityEngines
@@ -18074,10 +18103,12 @@ paths:
type: object
properties:
deleted:
+ description: Entity types whose engines were successfully deleted.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
still_running:
+ description: Entity types whose engines are still running.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
@@ -18095,17 +18126,52 @@ 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
+
+ Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
+
+ 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
@@ -18116,12 +18182,6 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
- 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
@@ -18161,6 +18221,7 @@ paths:
type: object
properties:
deleted:
+ description: Whether the engine was successfully deleted.
type: boolean
description: Successful response
summary: Delete the Entity Engine
@@ -18176,9 +18237,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
@@ -18188,6 +18258,20 @@ 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
@@ -18197,14 +18281,16 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
+ /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.
@@ -18267,6 +18353,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
@@ -18278,17 +18378,20 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
+ /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
@@ -18298,10 +18401,17 @@ 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
@@ -18310,17 +18420,20 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
+ /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
@@ -18330,10 +18443,17 @@ 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
@@ -18342,55 +18462,104 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
+ /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
@@ -18399,12 +18568,6 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
- 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/{entityType}:
delete:
description: |
@@ -18418,7 +18581,8 @@ paths:
The entity will be immediately deleted from the latest index. It will remain available in historical snapshots if it has been snapshotted. The delete operation does not prevent the entity from being recreated if it is observed again in the future.
operationId: DeleteSingleEntity
parameters:
- - in: path
+ - example: user
+ in: path
name: entityType
required: true
schema:
@@ -18431,6 +18595,7 @@ paths:
properties:
id:
description: Identifier of the entity to be deleted, commonly entity.id value.
+ example: arn:aws:iam::123456789012:user/jane.doe
type: string
required:
- id
@@ -18440,10 +18605,17 @@ paths:
'200':
content:
application/json:
+ examples:
+ deleteEntityExample:
+ description: The entity was found and successfully removed from the latest index.
+ summary: Entity deleted
+ value:
+ deleted: true
schema:
type: object
properties:
deleted:
+ description: Whether the entity was successfully deleted.
type: boolean
description: Successful response. Entity deleted.
'404':
@@ -18470,12 +18642,14 @@ paths:
> Due to technical limitations, create is an async operation. The time for a document to be present in the > final index depends on the entity store transform and usually takes more than 1 minute.
operationId: UpsertEntity
parameters:
- - in: path
+ - example: user
+ in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
- - in: query
+ - description: When true, allows updating protected fields.
+ in: query
name: force
required: false
schema:
@@ -18521,7 +18695,8 @@ paths:
The creation is asynchronous. The time for a document to be present in the final index depends on the entity store transform and usually takes more than 1 minute.
operationId: UpsertEntitiesBulk
parameters:
- - in: query
+ - description: When true, allows updating protected fields.
+ in: query
name: force
required: false
schema:
@@ -18559,12 +18734,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:
@@ -18572,13 +18750,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:
@@ -18591,7 +18773,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:
@@ -18608,17 +18791,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:
@@ -18635,9 +18822,18 @@ paths:
name: product_name
/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:
@@ -18646,22 +18842,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
@@ -18672,12 +18896,6 @@ paths:
x-metaTags:
- content: Kibana, Elastic Cloud Serverless
name: product_name
- 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: |-
@@ -102291,25 +102509,35 @@ components:
type: string
Security_Entity_Analytics_API_Asset:
additionalProperties: false
+ description: Asset metadata associated with the entity.
type: object
properties:
business_unit:
+ description: Business unit the asset belongs to.
type: string
criticality:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
+ description: The criticality level assigned to this asset.
environment:
+ description: Deployment environment (for example, production, staging).
type: string
id:
+ description: Unique identifier for the asset.
type: string
model:
+ description: Model name or number.
type: string
name:
+ description: Human-readable asset name.
type: string
owner:
+ description: The owner of the asset.
type: string
serial_number:
+ description: Serial number of the asset.
type: string
vendor:
+ description: Vendor or manufacturer.
type: string
Security_Entity_Analytics_API_AssetCriticalityBulkUploadErrorItem:
type: object
@@ -102508,6 +102736,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
@@ -102522,18 +102751,23 @@ components:
- ilm_policy
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
@@ -102542,8 +102776,10 @@ components:
- unknown
type: string
id:
+ description: Unique identifier for the component.
type: string
installed:
+ description: Whether the component is currently installed.
type: boolean
metadata:
$ref: '#/components/schemas/Security_Entity_Analytics_API_TransformStatsMetadata'
@@ -102554,61 +102790,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'
@@ -102619,13 +102878,16 @@ components:
- fieldHistoryLength
Security_Entity_Analytics_API_EngineMetadata:
additionalProperties: false
+ description: Internal metadata attached to an entity by the engine that produced it.
type: object
properties:
Type:
+ description: The engine type that produced this entity record.
type: string
required:
- Type
Security_Entity_Analytics_API_EngineStatus:
+ description: The current operational status of an entity engine.
enum:
- installing
- started
@@ -102634,15 +102896,18 @@ components:
- error
type: string
Security_Entity_Analytics_API_EntitiesContainer:
+ description: A collection of entities to upsert in bulk.
type: object
properties:
entities:
+ description: The entities to create or update.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityContainer'
type: array
required:
- entities
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'
@@ -102683,99 +102948,130 @@ components:
- has_all_required
- privileges
Security_Entity_Analytics_API_EntityContainer:
+ description: A wrapper that pairs an entity type with the entity record to upsert.
type: object
properties:
record:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Entity'
+ description: The entity record to create or update.
type:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
+ description: The entity type of the record.
required:
- type
- record
Security_Entity_Analytics_API_EntityField:
additionalProperties: false
+ description: Core entity fields shared across all entity types. The `entity` namespace is a root-level field in the Entity Store latest index.
type: object
properties:
attributes:
additionalProperties: false
+ description: Boolean flags describing characteristics of the entity.
type: object
properties:
asset:
+ description: Whether the entity is classified as an asset.
type: boolean
managed:
+ description: Whether the entity is managed (for example, via a directory service).
type: boolean
mfa_enabled:
+ description: Whether multi-factor authentication is enabled for the entity.
type: boolean
privileged:
+ description: Whether the entity has elevated privileges.
type: boolean
behaviors:
additionalProperties: false
+ description: Boolean flags indicating observed behavioral signals.
type: object
properties:
brute_force_victim:
+ description: Whether the entity has been targeted by brute-force attacks.
type: boolean
new_country_login:
+ description: Whether the entity has logged in from a new country.
type: boolean
used_usb_device:
+ description: Whether the entity has used a USB device.
type: boolean
EngineMetadata:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineMetadata'
id:
+ description: Unique identifier for this entity.
+ example: arn:aws:iam::123456789012:user/jane.doe
type: string
lifecycle:
additionalProperties: false
+ description: Timestamps tracking the entity lifecycle.
type: object
properties:
first_seen:
+ description: When the entity was first observed.
format: date-time
type: string
last_activity:
+ description: When the entity last generated activity.
format: date-time
type: string
name:
+ description: Human-readable name of the entity.
+ example: jane.doe
type: string
relationships:
additionalProperties: false
+ description: Connections between this entity and other entities.
type: object
properties:
accessed_frequently_by:
+ description: Entity IDs that frequently access this entity.
items:
type: string
type: array
accesses_frequently:
+ description: Entity IDs this entity accesses frequently.
items:
type: string
type: array
communicates_with:
+ description: Entity IDs this entity communicates with.
items:
type: string
type: array
dependent_of:
+ description: Entity IDs that depend on this entity.
items:
type: string
type: array
depends_on:
+ description: Entity IDs this entity depends on.
items:
type: string
type: array
owned_by:
+ description: Entity IDs that own this entity.
items:
type: string
type: array
owns:
+ description: Entity IDs owned by this entity.
items:
type: string
type: array
supervised_by:
+ description: Entity IDs that supervise this entity.
items:
type: string
type: array
supervises:
+ description: Entity IDs supervised by this entity.
items:
type: string
type: array
risk:
additionalProperties: false
+ description: Risk scoring information for the entity.
type: object
properties:
calculated_level:
@@ -102793,10 +103089,14 @@ components:
minimum: 0
type: number
source:
+ description: The source that produced this entity record.
type: string
sub_type:
+ description: Optional sub-type classification for the entity.
type: string
type:
+ description: The entity type.
+ example: user
type: string
required:
- id
@@ -102898,6 +103198,7 @@ components:
- inputs
- notes
Security_Entity_Analytics_API_EntityType:
+ description: The type of entity.
enum:
- user
- host
@@ -102906,9 +103207,11 @@ components:
type: string
Security_Entity_Analytics_API_GenericEntity:
additionalProperties: false
+ description: A generic entity record. Maps only the `entity` and `asset` namespaces. Add additional field mappings here as needed.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -102920,9 +103223,11 @@ components:
- entity
Security_Entity_Analytics_API_HostEntity:
additionalProperties: false
+ 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:
@@ -102935,43 +103240,53 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
host:
additionalProperties: false
+ 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
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
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
@@ -102987,15 +103302,20 @@ components:
- entity.id
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
@@ -103201,9 +103521,11 @@ components:
- category
Security_Entity_Analytics_API_ServiceEntity:
additionalProperties: false
+ 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:
@@ -103216,15 +103538,18 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
service:
additionalProperties: false
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
type: object
properties:
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
name:
+ description: Primary service name.
type: string
risk:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskScoreRecord'
@@ -103233,6 +103558,7 @@ components:
required:
- entity
Security_Entity_Analytics_API_StoreStatus:
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -103253,41 +103579,59 @@ components:
- status_code
- message
Security_Entity_Analytics_API_TransformStatsMetadata:
+ description: Statistics from the underlying Elasticsearch transform.
type: object
properties:
delete_time_in_ms:
+ description: Total time spent deleting documents, in milliseconds.
type: integer
documents_deleted:
+ description: Total number of documents deleted from the destination index.
type: integer
documents_indexed:
+ description: Total number of documents written to the destination index.
type: integer
documents_processed:
+ description: Total number of source documents processed.
type: integer
exponential_avg_checkpoint_duration_ms:
+ description: Exponential moving average of checkpoint duration, in milliseconds.
type: integer
exponential_avg_documents_indexed:
+ description: Exponential moving average of documents indexed per checkpoint.
type: integer
exponential_avg_documents_processed:
+ description: Exponential moving average of documents processed per checkpoint.
type: integer
index_failures:
+ description: Total number of failed index operations.
type: integer
index_time_in_ms:
+ description: Total time spent indexing documents, in milliseconds.
type: integer
index_total:
+ description: Total number of index operations.
type: integer
pages_processed:
+ description: Number of composite aggregation pages processed.
type: integer
processing_time_in_ms:
+ description: Total time spent processing results, in milliseconds.
type: integer
processing_total:
+ description: Total number of processing operations.
type: integer
search_failures:
+ description: Total number of failed search operations.
type: integer
search_time_in_ms:
+ description: Total time spent on search queries, in milliseconds.
type: integer
search_total:
+ description: Total number of search operations.
type: integer
trigger_count:
+ description: Number of times the transform has been triggered.
type: integer
required:
- pages_processed
@@ -103307,9 +103651,11 @@ components:
- exponential_avg_documents_processed
Security_Entity_Analytics_API_UserEntity:
additionalProperties: false
+ 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:
@@ -103322,38 +103668,47 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
user:
additionalProperties: false
+ 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'
additionalProperties: false
roles:
+ description: Observed roles assigned to the user.
items:
type: string
type: array
diff --git a/oas_docs/output/kibana.yaml b/oas_docs/output/kibana.yaml
index 70cfffe3f495f..4a1436a8806e5 100644
--- a/oas_docs/output/kibana.yaml
+++ b/oas_docs/output/kibana.yaml
@@ -20118,6 +20118,14 @@ paths:
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
/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:
@@ -20171,20 +20179,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':
@@ -20195,12 +20230,6 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
- 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.
/api/entity_store/engines:
delete:
operationId: DeleteEntityEngines
@@ -20241,10 +20270,12 @@ paths:
type: object
properties:
deleted:
+ description: Entity types whose engines were successfully deleted.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
still_running:
+ description: Entity types whose engines are still running.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
type: array
@@ -20262,17 +20293,52 @@ 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
+
+ Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
+
+ 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
@@ -20283,12 +20349,6 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
- 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
@@ -20328,6 +20388,7 @@ paths:
type: object
properties:
deleted:
+ description: Whether the engine was successfully deleted.
type: boolean
description: Successful response
summary: Delete the Entity Engine
@@ -20343,9 +20404,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
@@ -20355,6 +20425,20 @@ 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
@@ -20364,14 +20448,16 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
+ /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.
@@ -20434,6 +20520,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
@@ -20445,17 +20545,20 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
+ /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
@@ -20465,10 +20568,17 @@ 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
@@ -20477,17 +20587,20 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
+ /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
@@ -20497,10 +20610,17 @@ 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
@@ -20509,55 +20629,104 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
+ /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
@@ -20566,12 +20735,6 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
- 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/{entityType}:
delete:
description: |
@@ -20585,7 +20748,8 @@ paths:
The entity will be immediately deleted from the latest index. It will remain available in historical snapshots if it has been snapshotted. The delete operation does not prevent the entity from being recreated if it is observed again in the future.
operationId: DeleteSingleEntity
parameters:
- - in: path
+ - example: user
+ in: path
name: entityType
required: true
schema:
@@ -20598,6 +20762,7 @@ paths:
properties:
id:
description: Identifier of the entity to be deleted, commonly entity.id value.
+ example: arn:aws:iam::123456789012:user/jane.doe
type: string
required:
- id
@@ -20607,10 +20772,17 @@ paths:
'200':
content:
application/json:
+ examples:
+ deleteEntityExample:
+ description: The entity was found and successfully removed from the latest index.
+ summary: Entity deleted
+ value:
+ deleted: true
schema:
type: object
properties:
deleted:
+ description: Whether the entity was successfully deleted.
type: boolean
description: Successful response. Entity deleted.
'404':
@@ -20637,12 +20809,14 @@ paths:
> Due to technical limitations, create is an async operation. The time for a document to be present in the > final index depends on the entity store transform and usually takes more than 1 minute.
operationId: UpsertEntity
parameters:
- - in: path
+ - example: user
+ in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
- - in: query
+ - description: When true, allows updating protected fields.
+ in: query
name: force
required: false
schema:
@@ -20688,7 +20862,8 @@ paths:
The creation is asynchronous. The time for a document to be present in the final index depends on the entity store transform and usually takes more than 1 minute.
operationId: UpsertEntitiesBulk
parameters:
- - in: query
+ - description: When true, allows updating protected fields.
+ in: query
name: force
required: false
schema:
@@ -20726,12 +20901,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:
@@ -20739,13 +20917,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:
@@ -20758,7 +20940,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:
@@ -20775,17 +20958,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:
@@ -20802,9 +20989,18 @@ paths:
name: product_name
/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:
@@ -20813,22 +21009,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
@@ -20839,12 +21063,6 @@ paths:
x-metaTags:
- content: Kibana
name: product_name
- 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: |-
@@ -105845,25 +106063,35 @@ components:
type: string
Security_Entity_Analytics_API_Asset:
additionalProperties: false
+ description: Asset metadata associated with the entity.
type: object
properties:
business_unit:
+ description: Business unit the asset belongs to.
type: string
criticality:
$ref: '#/components/schemas/Security_Entity_Analytics_API_AssetCriticalityLevel'
+ description: The criticality level assigned to this asset.
environment:
+ description: Deployment environment (for example, production, staging).
type: string
id:
+ description: Unique identifier for the asset.
type: string
model:
+ description: Model name or number.
type: string
name:
+ description: Human-readable asset name.
type: string
owner:
+ description: The owner of the asset.
type: string
serial_number:
+ description: Serial number of the asset.
type: string
vendor:
+ description: Vendor or manufacturer.
type: string
Security_Entity_Analytics_API_AssetCriticalityBulkUploadErrorItem:
type: object
@@ -106062,6 +106290,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
@@ -106076,18 +106305,23 @@ components:
- ilm_policy
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
@@ -106096,8 +106330,10 @@ components:
- unknown
type: string
id:
+ description: Unique identifier for the component.
type: string
installed:
+ description: Whether the component is currently installed.
type: boolean
metadata:
$ref: '#/components/schemas/Security_Entity_Analytics_API_TransformStatsMetadata'
@@ -106108,61 +106344,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'
@@ -106173,13 +106432,16 @@ components:
- fieldHistoryLength
Security_Entity_Analytics_API_EngineMetadata:
additionalProperties: false
+ description: Internal metadata attached to an entity by the engine that produced it.
type: object
properties:
Type:
+ description: The engine type that produced this entity record.
type: string
required:
- Type
Security_Entity_Analytics_API_EngineStatus:
+ description: The current operational status of an entity engine.
enum:
- installing
- started
@@ -106188,15 +106450,18 @@ components:
- error
type: string
Security_Entity_Analytics_API_EntitiesContainer:
+ description: A collection of entities to upsert in bulk.
type: object
properties:
entities:
+ description: The entities to create or update.
items:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityContainer'
type: array
required:
- entities
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'
@@ -106237,99 +106502,130 @@ components:
- has_all_required
- privileges
Security_Entity_Analytics_API_EntityContainer:
+ description: A wrapper that pairs an entity type with the entity record to upsert.
type: object
properties:
record:
$ref: '#/components/schemas/Security_Entity_Analytics_API_Entity'
+ description: The entity record to create or update.
type:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityType'
+ description: The entity type of the record.
required:
- type
- record
Security_Entity_Analytics_API_EntityField:
additionalProperties: false
+ description: Core entity fields shared across all entity types. The `entity` namespace is a root-level field in the Entity Store latest index.
type: object
properties:
attributes:
additionalProperties: false
+ description: Boolean flags describing characteristics of the entity.
type: object
properties:
asset:
+ description: Whether the entity is classified as an asset.
type: boolean
managed:
+ description: Whether the entity is managed (for example, via a directory service).
type: boolean
mfa_enabled:
+ description: Whether multi-factor authentication is enabled for the entity.
type: boolean
privileged:
+ description: Whether the entity has elevated privileges.
type: boolean
behaviors:
additionalProperties: false
+ description: Boolean flags indicating observed behavioral signals.
type: object
properties:
brute_force_victim:
+ description: Whether the entity has been targeted by brute-force attacks.
type: boolean
new_country_login:
+ description: Whether the entity has logged in from a new country.
type: boolean
used_usb_device:
+ description: Whether the entity has used a USB device.
type: boolean
EngineMetadata:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EngineMetadata'
id:
+ description: Unique identifier for this entity.
+ example: arn:aws:iam::123456789012:user/jane.doe
type: string
lifecycle:
additionalProperties: false
+ description: Timestamps tracking the entity lifecycle.
type: object
properties:
first_seen:
+ description: When the entity was first observed.
format: date-time
type: string
last_activity:
+ description: When the entity last generated activity.
format: date-time
type: string
name:
+ description: Human-readable name of the entity.
+ example: jane.doe
type: string
relationships:
additionalProperties: false
+ description: Connections between this entity and other entities.
type: object
properties:
accessed_frequently_by:
+ description: Entity IDs that frequently access this entity.
items:
type: string
type: array
accesses_frequently:
+ description: Entity IDs this entity accesses frequently.
items:
type: string
type: array
communicates_with:
+ description: Entity IDs this entity communicates with.
items:
type: string
type: array
dependent_of:
+ description: Entity IDs that depend on this entity.
items:
type: string
type: array
depends_on:
+ description: Entity IDs this entity depends on.
items:
type: string
type: array
owned_by:
+ description: Entity IDs that own this entity.
items:
type: string
type: array
owns:
+ description: Entity IDs owned by this entity.
items:
type: string
type: array
supervised_by:
+ description: Entity IDs that supervise this entity.
items:
type: string
type: array
supervises:
+ description: Entity IDs supervised by this entity.
items:
type: string
type: array
risk:
additionalProperties: false
+ description: Risk scoring information for the entity.
type: object
properties:
calculated_level:
@@ -106347,10 +106643,14 @@ components:
minimum: 0
type: number
source:
+ description: The source that produced this entity record.
type: string
sub_type:
+ description: Optional sub-type classification for the entity.
type: string
type:
+ description: The entity type.
+ example: user
type: string
required:
- id
@@ -106452,6 +106752,7 @@ components:
- inputs
- notes
Security_Entity_Analytics_API_EntityType:
+ description: The type of entity.
enum:
- user
- host
@@ -106460,9 +106761,11 @@ components:
type: string
Security_Entity_Analytics_API_GenericEntity:
additionalProperties: false
+ description: A generic entity record. Maps only the `entity` and `asset` namespaces. Add additional field mappings here as needed.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -106474,9 +106777,11 @@ components:
- entity
Security_Entity_Analytics_API_HostEntity:
additionalProperties: false
+ 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:
@@ -106489,43 +106794,53 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
host:
additionalProperties: false
+ 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
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
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
@@ -106541,15 +106856,20 @@ components:
- entity.id
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
@@ -106755,9 +107075,11 @@ components:
- category
Security_Entity_Analytics_API_ServiceEntity:
additionalProperties: false
+ 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:
@@ -106770,15 +107092,18 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
service:
additionalProperties: false
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
type: object
properties:
entity:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityField'
name:
+ description: Primary service name.
type: string
risk:
$ref: '#/components/schemas/Security_Entity_Analytics_API_EntityRiskScoreRecord'
@@ -106787,6 +107112,7 @@ components:
required:
- entity
Security_Entity_Analytics_API_StoreStatus:
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -106807,41 +107133,59 @@ components:
- status_code
- message
Security_Entity_Analytics_API_TransformStatsMetadata:
+ description: Statistics from the underlying Elasticsearch transform.
type: object
properties:
delete_time_in_ms:
+ description: Total time spent deleting documents, in milliseconds.
type: integer
documents_deleted:
+ description: Total number of documents deleted from the destination index.
type: integer
documents_indexed:
+ description: Total number of documents written to the destination index.
type: integer
documents_processed:
+ description: Total number of source documents processed.
type: integer
exponential_avg_checkpoint_duration_ms:
+ description: Exponential moving average of checkpoint duration, in milliseconds.
type: integer
exponential_avg_documents_indexed:
+ description: Exponential moving average of documents indexed per checkpoint.
type: integer
exponential_avg_documents_processed:
+ description: Exponential moving average of documents processed per checkpoint.
type: integer
index_failures:
+ description: Total number of failed index operations.
type: integer
index_time_in_ms:
+ description: Total time spent indexing documents, in milliseconds.
type: integer
index_total:
+ description: Total number of index operations.
type: integer
pages_processed:
+ description: Number of composite aggregation pages processed.
type: integer
processing_time_in_ms:
+ description: Total time spent processing results, in milliseconds.
type: integer
processing_total:
+ description: Total number of processing operations.
type: integer
search_failures:
+ description: Total number of failed search operations.
type: integer
search_time_in_ms:
+ description: Total time spent on search queries, in milliseconds.
type: integer
search_total:
+ description: Total number of search operations.
type: integer
trigger_count:
+ description: Number of times the transform has been triggered.
type: integer
required:
- pages_processed
@@ -106861,9 +107205,11 @@ components:
- exponential_avg_documents_processed
Security_Entity_Analytics_API_UserEntity:
additionalProperties: false
+ 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:
@@ -106876,38 +107222,47 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
user:
additionalProperties: false
+ 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'
additionalProperties: false
roles:
+ description: Observed roles assigned to the user.
items:
type: string
type: array
diff --git a/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json b/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json
index c4a1be435303a..b41cba49207c4 100644
--- a/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json
+++ b/src/platform/packages/private/kbn-validate-oas/src/oas_error_baseline.json
@@ -1,4 +1,4 @@
{
- "./oas_docs/output/kibana.yaml": 1242,
- "./oas_docs/output/kibana.serverless.yaml": 1128
+ "./oas_docs/output/kibana.yaml": 1224,
+ "./oas_docs/output/kibana.serverless.yaml": 1110
}
\ No newline at end of file
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 9d7646917e7c1..97e91f8efd6bb 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
@@ -86,6 +86,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))
@@ -313,6 +316,9 @@ The entity will be immediately deleted from the latest index. It will remain av
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.send(props.body as object);
},
+ /**
+ * 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))
@@ -355,6 +361,9 @@ The entity will be immediately deleted from the latest index. It will remain av
.set(ELASTIC_HTTP_VERSION_HEADER, '1')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
+ /**
+ * Get the engine descriptor for a specific entity type, including its configuration and current status.
+ */
getEntityEngine(props: GetEntityEngineProps, kibanaSpace: string = 'default') {
return supertest
.get(
@@ -379,6 +388,9 @@ The entity will be immediately deleted from the latest index. It will remain av
.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))
@@ -409,6 +421,9 @@ The entity will be immediately deleted from the latest index. It will remain av
.set(ELASTIC_HTTP_VERSION_HEADER, '1')
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana');
},
+ /**
+ * Initialize a single entity engine for the specified entity type.
+ */
initEntityEngine(props: InitEntityEngineProps, kibanaSpace: string = 'default') {
return supertest
.post(
@@ -422,6 +437,9 @@ The entity will be immediately deleted from the latest index. It will remain av
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.send(props.body as object);
},
+ /**
+ * 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))
@@ -477,6 +495,9 @@ The entity will be immediately deleted from the latest index. It will remain av
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
+ /**
+ * 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))
@@ -585,6 +606,9 @@ The entity will be immediately deleted from the latest index. It will remain av
.set(X_ELASTIC_INTERNAL_ORIGIN_REQUEST, 'kibana')
.query(props.query);
},
+ /**
+ * Start a previously stopped entity engine, resuming transform processing for the given entity type.
+ */
startEntityEngine(props: StartEntityEngineProps, kibanaSpace: string = 'default') {
return supertest
.post(
@@ -597,6 +621,9 @@ The entity will be immediately deleted from the latest index. It will remain av
.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 6965dacbf7422..13634a9bb8671 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,85 +16,190 @@
import { z } from '@kbn/zod';
+/**
+ * The type of entity.
+ */
export type EntityType = z.infer;
export const EntityType = z.enum(['user', 'host', 'service', 'generic']);
export type EntityTypeEnum = typeof EntityType.enum;
export const EntityTypeEnum = EntityType.enum;
+/**
+ * The top-level Elastic Common Schema (ECS) field group that the entity maps to.
+ */
export type BaseECSEntityField = z.infer;
export const BaseECSEntityField = z.enum(['user', 'host', 'service', 'entity']);
export type BaseECSEntityFieldEnum = typeof BaseECSEntityField.enum;
export const BaseECSEntityFieldEnum = BaseECSEntityField.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(),
});
+/**
+ * Statistics from the underlying Elasticsearch transform.
+ */
export type TransformStatsMetadata = z.infer;
export const TransformStatsMetadata = z.object({
+ /**
+ * Number of composite aggregation pages processed.
+ */
pages_processed: z.number().int(),
+ /**
+ * Total number of source documents processed.
+ */
documents_processed: z.number().int(),
+ /**
+ * Total number of documents written to the destination index.
+ */
documents_indexed: z.number().int(),
+ /**
+ * Total number of documents deleted from the destination index.
+ */
documents_deleted: z.number().int().optional(),
+ /**
+ * Number of times the transform has been triggered.
+ */
trigger_count: z.number().int(),
+ /**
+ * Total time spent indexing documents, in milliseconds.
+ */
index_time_in_ms: z.number().int(),
+ /**
+ * Total number of index operations.
+ */
index_total: z.number().int(),
+ /**
+ * Total number of failed index operations.
+ */
index_failures: z.number().int(),
+ /**
+ * Total time spent on search queries, in milliseconds.
+ */
search_time_in_ms: z.number().int(),
+ /**
+ * Total number of search operations.
+ */
search_total: z.number().int(),
+ /**
+ * Total number of failed search operations.
+ */
search_failures: z.number().int(),
+ /**
+ * Total time spent processing results, in milliseconds.
+ */
processing_time_in_ms: z.number().int(),
+ /**
+ * Total number of processing operations.
+ */
processing_total: z.number().int(),
+ /**
+ * Total time spent deleting documents, in milliseconds.
+ */
delete_time_in_ms: z.number().int().optional(),
+ /**
+ * Exponential moving average of checkpoint duration, in milliseconds.
+ */
exponential_avg_checkpoint_duration_ms: z.number().int(),
+ /**
+ * Exponential moving average of documents indexed per checkpoint.
+ */
exponential_avg_documents_indexed: z.number().int(),
+ /**
+ * Exponential moving average of documents processed per checkpoint.
+ */
exponential_avg_documents_processed: z.number().int(),
});
export type Metadata = z.infer;
export const Metadata = TransformStatsMetadata;
+/**
+ * The type of Elasticsearch or Kibana resource backing an engine component.
+ */
export type EngineComponentResource = z.infer;
export const EngineComponentResource = z.enum([
'entity_engine',
@@ -112,31 +217,64 @@ 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(),
metadata: Metadata.optional(),
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 bd582e3cf5409..682190cc7c157 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,6 +8,7 @@ components:
schemas:
EntityType:
type: string
+ description: The type of entity.
enum:
- user
- host
@@ -15,6 +16,7 @@ components:
- generic
BaseECSEntityField:
type: string
+ description: The top-level Elastic Common Schema (ECS) field group that the entity maps to.
enum:
- user
- host
@@ -22,6 +24,7 @@ components:
- entity
EngineDescriptor:
type: object
+ description: Describes a single entity engine, including its configuration and current status.
required:
- type
- indexPattern
@@ -36,43 +39,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
@@ -82,6 +104,7 @@ components:
EngineComponentStatus:
type: object
+ description: Status of an individual Elasticsearch or Kibana resource backing an engine.
required:
- id
- installed
@@ -89,14 +112,17 @@ components:
properties:
id:
type: string
+ description: Unique identifier for the component.
installed:
type: boolean
+ description: Whether the component is currently installed.
metadata:
$ref: '#/components/schemas/Metadata'
resource:
$ref: '#/components/schemas/EngineComponentResource'
health:
type: string
+ description: The health status of the component.
enum:
- green
- yellow
@@ -105,13 +131,16 @@ 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.
Metadata:
allOf:
@@ -119,6 +148,7 @@ components:
TransformStatsMetadata:
type: object
+ description: Statistics from the underlying Elasticsearch transform.
required:
- pages_processed
- documents_processed
@@ -138,41 +168,59 @@ components:
properties:
pages_processed:
type: integer
+ description: Number of composite aggregation pages processed.
documents_processed:
type: integer
+ description: Total number of source documents processed.
documents_indexed:
type: integer
+ description: Total number of documents written to the destination index.
documents_deleted:
type: integer
+ description: Total number of documents deleted from the destination index.
trigger_count:
type: integer
+ description: Number of times the transform has been triggered.
index_time_in_ms:
type: integer
+ description: Total time spent indexing documents, in milliseconds.
index_total:
type: integer
+ description: Total number of index operations.
index_failures:
type: integer
+ description: Total number of failed index operations.
search_time_in_ms:
type: integer
+ description: Total time spent on search queries, in milliseconds.
search_total:
type: integer
+ description: Total number of search operations.
search_failures:
type: integer
+ description: Total number of failed search operations.
processing_time_in_ms:
type: integer
+ description: Total time spent processing results, in milliseconds.
processing_total:
type: integer
+ description: Total number of processing operations.
delete_time_in_ms:
type: integer
+ description: Total time spent deleting documents, in milliseconds.
exponential_avg_checkpoint_duration_ms:
type: integer
+ description: Exponential moving average of checkpoint duration, in milliseconds.
exponential_avg_documents_indexed:
type: integer
+ description: Exponential moving average of documents indexed per checkpoint.
exponential_avg_documents_processed:
type: integer
+ description: Exponential moving average of documents processed per checkpoint.
EngineComponentResource:
type: string
+ description: The type of Elasticsearch or Kibana resource backing an engine component.
enum:
- entity_engine
- entity_definition
@@ -188,6 +236,7 @@ components:
StoreStatus:
type: string
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -197,16 +246,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 0bf9ed8438277..c5288be9fa16a 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
@@ -77,6 +77,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 2a06c5c89cc90..fc1796dfd185f 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:
@@ -75,9 +76,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 57f79f307693d..422da519a8907 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
@@ -43,6 +43,9 @@ export type DeleteEntityEngineRequestParamsInput = z.input;
export const DeleteEntityEngineResponse = z.object({
+ /**
+ * Whether the engine was successfully deleted.
+ */
deleted: z.boolean().optional(),
});
export type DeleteEntityEnginesRequestQuery = z.infer;
@@ -60,6 +63,12 @@ export type DeleteEntityEnginesRequestQueryInput = z.input;
export const DeleteEntityEnginesResponse = z.object({
+ /**
+ * Entity types whose engines were successfully deleted.
+ */
deleted: z.array(EntityType).optional(),
+ /**
+ * Entity types whose engines are still running.
+ */
still_running: z.array(EntityType).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 7a09e81a2575d..f70d4d7e5df7d 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
@@ -42,13 +42,15 @@ paths:
still_running: ['generic', 'user', 'service']
schema:
type: object
- properties:
+ properties:
deleted:
type: array
+ description: Entity types whose engines were successfully deleted.
items:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
still_running:
type: array
+ description: Entity types whose engines are still running.
items:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
@@ -93,7 +95,8 @@ paths:
deleted: true
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 50fbb01ea443d..c795af01e5702 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
@@ -74,5 +75,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 6db7ef762c36f..c159dd085601b 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,60 +19,153 @@ import { z } from '@kbn/zod';
import { EntityRiskLevels, EntityRiskScoreRecord } from '../../common/common.gen';
import { AssetCriticalityLevel } from '../../asset_criticality/common.gen';
+/**
+ * Internal metadata attached to an entity by the engine that produced it.
+ */
export type EngineMetadata = z.infer;
export const EngineMetadata = z
.object({
+ /**
+ * The engine type that produced this entity record.
+ */
Type: z.string(),
})
.strict();
+/**
+ * Core entity fields shared across all entity types. The `entity` namespace is a root-level field in the Entity Store latest index.
+ */
export type EntityField = z.infer;
export const EntityField = z
.object({
+ /**
+ * Unique identifier for this entity.
+ */
id: z.string(),
+ /**
+ * Human-readable name of the entity.
+ */
name: z.string().optional(),
+ /**
+ * The entity type.
+ */
type: z.string().optional(),
+ /**
+ * Optional sub-type classification for the entity.
+ */
sub_type: z.string().optional(),
+ /**
+ * The source that produced this entity record.
+ */
source: z.string().optional(),
EngineMetadata: EngineMetadata.optional(),
+ /**
+ * Boolean flags describing characteristics of the entity.
+ */
attributes: z
.object({
+ /**
+ * Whether the entity has elevated privileges.
+ */
privileged: z.boolean().optional(),
+ /**
+ * Whether the entity is classified as an asset.
+ */
asset: z.boolean().optional(),
+ /**
+ * Whether the entity is managed (for example, via a directory service).
+ */
managed: z.boolean().optional(),
+ /**
+ * Whether multi-factor authentication is enabled for the entity.
+ */
mfa_enabled: z.boolean().optional(),
})
.strict()
.optional(),
+ /**
+ * Boolean flags indicating observed behavioral signals.
+ */
behaviors: z
.object({
+ /**
+ * Whether the entity has been targeted by brute-force attacks.
+ */
brute_force_victim: z.boolean().optional(),
+ /**
+ * Whether the entity has logged in from a new country.
+ */
new_country_login: z.boolean().optional(),
+ /**
+ * Whether the entity has used a USB device.
+ */
used_usb_device: z.boolean().optional(),
})
.strict()
.optional(),
+ /**
+ * Timestamps tracking the entity lifecycle.
+ */
lifecycle: z
.object({
+ /**
+ * When the entity was first observed.
+ */
first_seen: z.string().datetime().optional(),
+ /**
+ * When the entity last generated activity.
+ */
last_activity: z.string().datetime().optional(),
})
.strict()
.optional(),
+ /**
+ * Connections between this entity and other entities.
+ */
relationships: z
.object({
+ /**
+ * Entity IDs this entity communicates with.
+ */
communicates_with: z.array(z.string()).optional(),
+ /**
+ * Entity IDs this entity depends on.
+ */
depends_on: z.array(z.string()).optional(),
+ /**
+ * Entity IDs that depend on this entity.
+ */
dependent_of: z.array(z.string()).optional(),
+ /**
+ * Entity IDs owned by this entity.
+ */
owns: z.array(z.string()).optional(),
+ /**
+ * Entity IDs that own this entity.
+ */
owned_by: z.array(z.string()).optional(),
+ /**
+ * Entity IDs this entity accesses frequently.
+ */
accesses_frequently: z.array(z.string()).optional(),
+ /**
+ * Entity IDs that frequently access this entity.
+ */
accessed_frequently_by: z.array(z.string()).optional(),
+ /**
+ * Entity IDs supervised by this entity.
+ */
supervises: z.array(z.string()).optional(),
+ /**
+ * Entity IDs that supervise this entity.
+ */
supervised_by: z.array(z.string()).optional(),
})
.strict()
.optional(),
+ /**
+ * Risk scoring information for the entity.
+ */
risk: z
.object({
/**
@@ -93,34 +186,94 @@ export const EntityField = z
})
.strict();
+/**
+ * Asset metadata associated with the entity.
+ */
export type Asset = z.infer;
export const Asset = z
.object({
+ /**
+ * Unique identifier for the asset.
+ */
id: z.string().optional(),
+ /**
+ * Human-readable asset name.
+ */
name: z.string().optional(),
+ /**
+ * The owner of the asset.
+ */
owner: z.string().optional(),
+ /**
+ * Serial number of the asset.
+ */
serial_number: z.string().optional(),
+ /**
+ * Model name or number.
+ */
model: z.string().optional(),
+ /**
+ * Vendor or manufacturer.
+ */
vendor: z.string().optional(),
+ /**
+ * Deployment environment (for example, production, staging).
+ */
environment: z.string().optional(),
+ /**
+ * The criticality level assigned to this asset.
+ */
criticality: AssetCriticalityLevel.optional(),
+ /**
+ * Business unit the asset belongs to.
+ */
business_unit: z.string().optional(),
})
.strict();
+/**
+ * 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: EntityField,
+ /**
+ * 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(),
})
@@ -129,6 +282,9 @@ export const UserEntity = z
asset: Asset.optional(),
event: z
.object({
+ /**
+ * When the event was ingested into Elasticsearch.
+ */
ingested: z.string().datetime().optional(),
})
.strict()
@@ -136,20 +292,53 @@ export const UserEntity = z
})
.strict();
+/**
+ * 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: EntityField,
+ /**
+ * 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(),
entity: EntityField.optional(),
@@ -159,6 +348,9 @@ export const HostEntity = z
asset: Asset.optional(),
event: z
.object({
+ /**
+ * When the event was ingested into Elasticsearch.
+ */
ingested: z.string().datetime().optional(),
})
.strict()
@@ -166,13 +358,25 @@ export const HostEntity = z
})
.strict();
+/**
+ * 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: EntityField,
+ /**
+ * Elastic Common Schema (ECS) service fields collected on the entity.
+ */
service: z
.object({
+ /**
+ * Primary service name.
+ */
name: z.string(),
risk: EntityRiskScoreRecord.optional(),
entity: EntityField.optional(),
@@ -182,6 +386,9 @@ export const ServiceEntity = z
asset: Asset.optional(),
event: z
.object({
+ /**
+ * When the event was ingested into Elasticsearch.
+ */
ingested: z.string().datetime().optional(),
})
.strict()
@@ -189,15 +396,24 @@ export const ServiceEntity = z
})
.strict();
+/**
+ * A generic entity record. Maps only the `entity` and `asset` namespaces. Add additional field mappings here as needed.
+ */
export type GenericEntity = z.infer;
export const GenericEntity = z
.object({
+ /**
+ * The time the entity record was last updated.
+ */
'@timestamp': z.string().datetime().optional(),
entity: EntityField,
asset: Asset.optional(),
})
.strict();
+/**
+ * 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, GenericEntity]);
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 32af53a9113c6..3798b082130ef 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,105 +8,139 @@ components:
schemas:
EngineMetadata:
type: object
+ description: Internal metadata attached to an entity by the engine that produced it.
additionalProperties: false
required:
- Type
properties:
Type:
type: string
+ description: The engine type that produced this entity record.
EntityField:
type: object
+ description: Core entity fields shared across all entity types. The `entity` namespace is a root-level field in the Entity Store latest index.
additionalProperties: false
required:
- id
properties:
id:
type: string
+ description: Unique identifier for this entity.
+ example: 'arn:aws:iam::123456789012:user/jane.doe'
name:
type: string
+ description: Human-readable name of the entity.
+ example: 'jane.doe'
type:
type: string
+ description: The entity type.
+ example: 'user'
sub_type:
type: string
+ description: Optional sub-type classification for the entity.
source:
type: string
+ description: The source that produced this entity record.
EngineMetadata:
$ref: '#/components/schemas/EngineMetadata'
attributes:
type: object
+ description: Boolean flags describing characteristics of the entity.
additionalProperties: false
properties:
privileged:
type: boolean
+ description: Whether the entity has elevated privileges.
asset:
type: boolean
+ description: Whether the entity is classified as an asset.
managed:
type: boolean
+ description: Whether the entity is managed (for example, via a directory service).
mfa_enabled:
type: boolean
- behaviors:
+ description: Whether multi-factor authentication is enabled for the entity.
+ behaviors:
type: object
+ description: Boolean flags indicating observed behavioral signals.
additionalProperties: false
properties:
brute_force_victim:
type: boolean
+ description: Whether the entity has been targeted by brute-force attacks.
new_country_login:
type: boolean
+ description: Whether the entity has logged in from a new country.
used_usb_device:
type: boolean
+ description: Whether the entity has used a USB device.
lifecycle:
type: object
+ description: Timestamps tracking the entity lifecycle.
additionalProperties: false
properties:
first_seen:
type: string
format: date-time
+ description: When the entity was first observed.
last_activity:
type: string
format: date-time
+ description: When the entity last generated activity.
relationships:
type: object
+ description: Connections between this entity and other entities.
additionalProperties: false
properties:
communicates_with:
type: array
+ description: Entity IDs this entity communicates with.
items:
type: string
depends_on:
type: array
+ description: Entity IDs this entity depends on.
items:
type: string
dependent_of:
type: array
+ description: Entity IDs that depend on this entity.
items:
type: string
owns:
type: array
+ description: Entity IDs owned by this entity.
items:
type: string
owned_by:
type: array
+ description: Entity IDs that own this entity.
items:
type: string
accesses_frequently:
type: array
+ description: Entity IDs this entity accesses frequently.
items:
type: string
accessed_frequently_by:
type: array
+ description: Entity IDs that frequently access this entity.
items:
type: string
supervises:
type: array
+ description: Entity IDs supervised by this entity.
items:
type: string
supervised_by:
type: array
+ description: Entity IDs that supervise this entity.
items:
type: string
risk:
type: object
+ description: Risk scoring information for the entity.
additionalProperties: false
properties:
calculated_level:
@@ -126,29 +160,40 @@ components:
Asset:
type: object
+ description: Asset metadata associated with the entity.
additionalProperties: false
properties:
id:
type: string
+ description: Unique identifier for the asset.
name:
type: string
+ description: Human-readable asset name.
owner:
type: string
+ description: The owner of the asset.
serial_number:
type: string
+ description: Serial number of the asset.
model:
type: string
+ description: Model name or number.
vendor:
type: string
+ description: Vendor or manufacturer.
environment:
type: string
+ description: Deployment environment (for example, production, staging).
criticality:
$ref: '../../asset_criticality/common.schema.yaml#/components/schemas/AssetCriticalityLevel'
+ description: The criticality level assigned to this asset.
business_unit:
type: string
+ description: Business unit the asset belongs to.
UserEntity:
type: object
+ description: An entity record representing a user, stored in the Entity Store latest index.
additionalProperties: false
required:
- entity
@@ -156,36 +201,45 @@ components:
"@timestamp":
type: string
format: date-time
+ description: The time the entity record was last updated.
entity:
$ref: '#/components/schemas/EntityField'
user:
type: object
+ description: Elastic Common Schema (ECS) user fields collected on the entity.
additionalProperties: false
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:
@@ -203,9 +257,11 @@ 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.
additionalProperties: false
required:
- entity
@@ -213,40 +269,50 @@ components:
"@timestamp":
type: string
format: date-time
+ description: The time the entity record was last updated.
entity:
$ref: '#/components/schemas/EntityField'
host:
type: object
+ description: Elastic Common Schema (ECS) host fields collected on the entity.
additionalProperties: false
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:
@@ -265,9 +331,11 @@ 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.
additionalProperties: false
required:
- entity
@@ -275,14 +343,17 @@ components:
"@timestamp":
type: string
format: date-time
+ description: The time the entity record was last updated.
entity:
$ref: '#/components/schemas/EntityField'
service:
type: object
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
additionalProperties: false
properties:
name:
type: string
+ description: Primary service name.
risk:
$ref: '../../common/common.schema.yaml#/components/schemas/EntityRiskScoreRecord'
entity:
@@ -299,15 +370,11 @@ components:
ingested:
type: string
format: date-time
+ description: When the event was ingested into Elasticsearch.
- # The Generic Entity definition maps more than just entity.
- # however I don't see a reason to duplicate the definition
- # of all the fields just for the sake of doing.
- # Thus the current mapping maps entity and asset only
- # (used in code). If you end up needing the fields mapped
- # in the schema just add it.
GenericEntity:
type: object
+ description: A generic entity record. Maps only the `entity` and `asset` namespaces. Add additional field mappings here as needed.
additionalProperties: false
required:
- entity
@@ -315,18 +382,16 @@ components:
"@timestamp":
type: string
format: date-time
+ description: The time the entity record was last updated.
entity:
$ref: '#/components/schemas/EntityField'
asset:
$ref: '#/components/schemas/Asset'
additionalProperties: false
-
- # These entities represent the API of Entity Store
- # where entity is a root field, as it's in the final
- # index for entities. Note that this is different from the
- # source logs mapping where `entity` will be nested under
- # `host`, `user` and `service`
+
+
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/delete_entity.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/delete_entity.gen.ts
index 24e6d744c79e8..a978b95ebda94 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/delete_entity.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/delete_entity.gen.ts
@@ -35,5 +35,8 @@ export type DeleteSingleEntityRequestBodyInput = z.input;
export const DeleteSingleEntityResponse = z.object({
+ /**
+ * Whether the entity was successfully deleted.
+ */
deleted: z.boolean().optional(),
});
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/delete_entity.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/delete_entity.schema.yaml
index 8a1dfa2212c3a..ddeceb0b215d1 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/delete_entity.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/delete_entity.schema.yaml
@@ -21,6 +21,7 @@ paths:
required: true
schema:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
+ example: user
requestBody:
description: Schema for the deleting entity
required: true
@@ -32,9 +33,11 @@ paths:
id:
type: string
description: Identifier of the entity to be deleted, commonly entity.id value.
+ example: 'arn:aws:iam::123456789012:user/jane.doe'
required: ["id"]
responses:
'200':
+ description: Successful response. Entity deleted.
content:
application/json:
schema:
@@ -42,7 +45,13 @@ paths:
properties:
deleted:
type: boolean
- description: Successful response. Entity deleted.
+ description: Whether the entity was successfully deleted.
+ examples:
+ deleteEntityExample:
+ summary: Entity deleted
+ description: The entity was found and successfully removed from the latest index.
+ value:
+ deleted: true
'404':
description: Entity Not Found. No entity with this ID and Type exists.
'503':
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/entities/upsert_entities_bulk.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entities_bulk.gen.ts
index 98dc8bfe8e441..26c55e7be5afb 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entities_bulk.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entities_bulk.gen.ts
@@ -20,19 +20,37 @@ import { BooleanFromString } from '@kbn/zod-helpers';
import { EntityType } from '../common.gen';
import { Entity } from './common.gen';
+/**
+ * A wrapper that pairs an entity type with the entity record to upsert.
+ */
export type EntityContainer = z.infer;
export const EntityContainer = z.object({
+ /**
+ * The entity type of the record.
+ */
type: EntityType,
+ /**
+ * The entity record to create or update.
+ */
record: Entity,
});
+/**
+ * A collection of entities to upsert in bulk.
+ */
export type EntitiesContainer = z.infer;
export const EntitiesContainer = z.object({
+ /**
+ * The entities to create or update.
+ */
entities: z.array(EntityContainer),
});
export type UpsertEntitiesBulkRequestQuery = z.infer;
export const UpsertEntitiesBulkRequestQuery = z.object({
+ /**
+ * When true, allows updating protected fields.
+ */
force: BooleanFromString.optional().default(false),
});
export type UpsertEntitiesBulkRequestQueryInput = z.input;
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entities_bulk.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entities_bulk.schema.yaml
index 218908041998e..f0b681ab236fe 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entities_bulk.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entities_bulk.schema.yaml
@@ -24,6 +24,7 @@ paths:
schema:
type: boolean
default: false
+ description: When true, allows updating protected fields.
requestBody:
description: Schema for the updating many entities
required: true
@@ -44,20 +45,25 @@ components:
schemas:
EntityContainer:
type: object
+ description: A wrapper that pairs an entity type with the entity record to upsert.
required:
- type
- record
properties:
- type:
+ type:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
+ description: The entity type of the record.
record:
$ref: './common.schema.yaml#/components/schemas/Entity'
+ description: The entity record to create or update.
EntitiesContainer:
type: object
+ description: A collection of entities to upsert in bulk.
required:
- entities
properties:
entities:
type: array
+ description: The entities to create or update.
items:
$ref: '#/components/schemas/EntityContainer'
\ No newline at end of file
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entity.gen.ts b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entity.gen.ts
index f4b4c766d7532..082b016e50d8e 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entity.gen.ts
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entity.gen.ts
@@ -22,6 +22,9 @@ import { Entity } from './common.gen';
export type UpsertEntityRequestQuery = z.infer;
export const UpsertEntityRequestQuery = z.object({
+ /**
+ * When true, allows updating protected fields.
+ */
force: BooleanFromString.optional().default(false),
});
export type UpsertEntityRequestQueryInput = z.input;
diff --git a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entity.schema.yaml b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entity.schema.yaml
index 9aa60c81c72ca..157fb5f88f317 100644
--- a/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entity.schema.yaml
+++ b/x-pack/solutions/security/plugins/security_solution/common/api/entity_analytics/entity_store/entities/upsert_entity.schema.yaml
@@ -32,12 +32,14 @@ paths:
required: true
schema:
$ref: '../common.schema.yaml#/components/schemas/EntityType'
+ example: user
- name: force
in: query
required: false
schema:
type: boolean
default: false
+ description: When true, allows updating protected fields.
requestBody:
description: Schema for the updating a single entity
required: true
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 0b58134825a24..eca224938364b 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
@@ -537,6 +537,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
@@ -1447,6 +1450,9 @@ The entity will be immediately deleted from the latest index. It will remain av
})
.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
@@ -1771,6 +1777,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
@@ -1795,6 +1804,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
@@ -2181,6 +2193,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
@@ -2194,6 +2209,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
@@ -2355,6 +2373,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
@@ -2914,6 +2935,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
@@ -2960,6 +2984,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 9e9e656c08169..fe997b8880cb8 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:
@@ -668,6 +668,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:
@@ -725,20 +728,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':
@@ -790,10 +822,12 @@ paths:
type: object
properties:
deleted:
+ description: Entity types whose engines were successfully deleted.
items:
$ref: '#/components/schemas/EntityType'
type: array
still_running:
+ description: Entity types whose engines are still running.
items:
$ref: '#/components/schemas/EntityType'
type: array
@@ -802,17 +836,47 @@ paths:
tags:
- Security Entity Analytics API
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
@@ -859,15 +923,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
@@ -877,6 +946,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
@@ -885,6 +970,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.
@@ -951,6 +1037,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
@@ -961,9 +1063,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
@@ -973,10 +1079,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
@@ -984,9 +1099,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
@@ -996,10 +1115,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
@@ -1007,47 +1135,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
@@ -1064,7 +1248,8 @@ paths:
it is observed again in the future.
operationId: DeleteSingleEntity
parameters:
- - in: path
+ - example: user
+ in: path
name: entityType
required: true
schema:
@@ -1079,6 +1264,7 @@ paths:
description: >-
Identifier of the entity to be deleted, commonly entity.id
value.
+ example: arn:aws:iam::123456789012:user/jane.doe
type: string
required:
- id
@@ -1088,10 +1274,19 @@ paths:
'200':
content:
application/json:
+ examples:
+ deleteEntityExample:
+ description: >-
+ The entity was found and successfully removed from the
+ latest index.
+ summary: Entity deleted
+ value:
+ deleted: true
schema:
type: object
properties:
deleted:
+ description: Whether the entity was successfully deleted.
type: boolean
description: Successful response. Entity deleted.
'404':
@@ -1123,12 +1318,14 @@ paths:
store transform and usually takes more than 1 minute.
operationId: UpsertEntity
parameters:
- - in: path
+ - example: user
+ in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/EntityType'
- - in: query
+ - description: When true, allows updating protected fields.
+ in: query
name: force
required: false
schema:
@@ -1174,7 +1371,8 @@ paths:
more than 1 minute.
operationId: UpsertEntitiesBulk
parameters:
- - in: query
+ - description: When true, allows updating protected fields.
+ in: query
name: force
required: false
schema:
@@ -1204,12 +1402,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:
@@ -1217,13 +1418,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:
@@ -1236,7 +1441,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:
@@ -1253,17 +1459,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:
@@ -1277,11 +1487,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:
@@ -1290,22 +1504,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
@@ -1453,25 +1699,35 @@ components:
schemas:
Asset:
additionalProperties: false
+ description: Asset metadata associated with the entity.
type: object
properties:
business_unit:
+ description: Business unit the asset belongs to.
type: string
criticality:
$ref: '#/components/schemas/AssetCriticalityLevel'
+ description: The criticality level assigned to this asset.
environment:
+ description: Deployment environment (for example, production, staging).
type: string
id:
+ description: Unique identifier for the asset.
type: string
model:
+ description: Model name or number.
type: string
name:
+ description: Human-readable asset name.
type: string
owner:
+ description: The owner of the asset.
type: string
serial_number:
+ description: Serial number of the asset.
type: string
vendor:
+ description: Vendor or manufacturer.
type: string
AssetCriticalityBulkUploadErrorItem:
type: object
@@ -1673,6 +1929,9 @@ components:
required:
- criticality_level
EngineComponentResource:
+ description: >-
+ The type of Elasticsearch or Kibana resource backing an engine
+ component.
enum:
- entity_engine
- entity_definition
@@ -1687,18 +1946,25 @@ components:
- ilm_policy
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
@@ -1707,8 +1973,10 @@ components:
- unknown
type: string
id:
+ description: Unique identifier for the component.
type: string
installed:
+ description: Whether the component is currently installed.
type: boolean
metadata:
$ref: '#/components/schemas/Metadata'
@@ -1719,61 +1987,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'
@@ -1784,13 +2083,16 @@ components:
- fieldHistoryLength
EngineMetadata:
additionalProperties: false
+ description: Internal metadata attached to an entity by the engine that produced it.
type: object
properties:
Type:
+ description: The engine type that produced this entity record.
type: string
required:
- Type
EngineStatus:
+ description: The current operational status of an entity engine.
enum:
- installing
- started
@@ -1799,15 +2101,21 @@ components:
- error
type: string
EntitiesContainer:
+ description: A collection of entities to upsert in bulk.
type: object
properties:
entities:
+ description: The entities to create or update.
items:
$ref: '#/components/schemas/EntityContainer'
type: array
required:
- entities
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'
@@ -1848,99 +2156,134 @@ components:
- has_all_required
- privileges
EntityContainer:
+ description: A wrapper that pairs an entity type with the entity record to upsert.
type: object
properties:
record:
$ref: '#/components/schemas/Entity'
+ description: The entity record to create or update.
type:
$ref: '#/components/schemas/EntityType'
+ description: The entity type of the record.
required:
- type
- record
EntityField:
additionalProperties: false
+ description: >-
+ Core entity fields shared across all entity types. The `entity`
+ namespace is a root-level field in the Entity Store latest index.
type: object
properties:
attributes:
additionalProperties: false
+ description: Boolean flags describing characteristics of the entity.
type: object
properties:
asset:
+ description: Whether the entity is classified as an asset.
type: boolean
managed:
+ description: >-
+ Whether the entity is managed (for example, via a directory
+ service).
type: boolean
mfa_enabled:
+ description: Whether multi-factor authentication is enabled for the entity.
type: boolean
privileged:
+ description: Whether the entity has elevated privileges.
type: boolean
behaviors:
additionalProperties: false
+ description: Boolean flags indicating observed behavioral signals.
type: object
properties:
brute_force_victim:
+ description: Whether the entity has been targeted by brute-force attacks.
type: boolean
new_country_login:
+ description: Whether the entity has logged in from a new country.
type: boolean
used_usb_device:
+ description: Whether the entity has used a USB device.
type: boolean
EngineMetadata:
$ref: '#/components/schemas/EngineMetadata'
id:
+ description: Unique identifier for this entity.
+ example: arn:aws:iam::123456789012:user/jane.doe
type: string
lifecycle:
additionalProperties: false
+ description: Timestamps tracking the entity lifecycle.
type: object
properties:
first_seen:
+ description: When the entity was first observed.
format: date-time
type: string
last_activity:
+ description: When the entity last generated activity.
format: date-time
type: string
name:
+ description: Human-readable name of the entity.
+ example: jane.doe
type: string
relationships:
additionalProperties: false
+ description: Connections between this entity and other entities.
type: object
properties:
accessed_frequently_by:
+ description: Entity IDs that frequently access this entity.
items:
type: string
type: array
accesses_frequently:
+ description: Entity IDs this entity accesses frequently.
items:
type: string
type: array
communicates_with:
+ description: Entity IDs this entity communicates with.
items:
type: string
type: array
dependent_of:
+ description: Entity IDs that depend on this entity.
items:
type: string
type: array
depends_on:
+ description: Entity IDs this entity depends on.
items:
type: string
type: array
owned_by:
+ description: Entity IDs that own this entity.
items:
type: string
type: array
owns:
+ description: Entity IDs owned by this entity.
items:
type: string
type: array
supervised_by:
+ description: Entity IDs that supervise this entity.
items:
type: string
type: array
supervises:
+ description: Entity IDs supervised by this entity.
items:
type: string
type: array
risk:
additionalProperties: false
+ description: Risk scoring information for the entity.
type: object
properties:
calculated_level:
@@ -1960,10 +2303,14 @@ components:
minimum: 0
type: number
source:
+ description: The source that produced this entity record.
type: string
sub_type:
+ description: Optional sub-type classification for the entity.
type: string
type:
+ description: The entity type.
+ example: user
type: string
required:
- id
@@ -2077,6 +2424,7 @@ components:
- inputs
- notes
EntityType:
+ description: The type of entity.
enum:
- user
- host
@@ -2085,9 +2433,13 @@ components:
type: string
GenericEntity:
additionalProperties: false
+ description: >-
+ A generic entity record. Maps only the `entity` and `asset` namespaces.
+ Add additional field mappings here as needed.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -2099,9 +2451,13 @@ components:
- entity
HostEntity:
additionalProperties: false
+ 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:
@@ -2114,43 +2470,53 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
host:
additionalProperties: false
+ 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
entity:
$ref: '#/components/schemas/EntityField'
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
@@ -2166,15 +2532,23 @@ components:
- entity.id
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
@@ -2385,9 +2759,13 @@ components:
- category
ServiceEntity:
additionalProperties: false
+ 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:
@@ -2400,15 +2778,18 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
service:
additionalProperties: false
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
type: object
properties:
entity:
$ref: '#/components/schemas/EntityField'
name:
+ description: Primary service name.
type: string
risk:
$ref: '#/components/schemas/EntityRiskScoreRecord'
@@ -2417,6 +2798,7 @@ components:
required:
- entity
StoreStatus:
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -2437,41 +2819,59 @@ components:
- status_code
- message
TransformStatsMetadata:
+ description: Statistics from the underlying Elasticsearch transform.
type: object
properties:
delete_time_in_ms:
+ description: Total time spent deleting documents, in milliseconds.
type: integer
documents_deleted:
+ description: Total number of documents deleted from the destination index.
type: integer
documents_indexed:
+ description: Total number of documents written to the destination index.
type: integer
documents_processed:
+ description: Total number of source documents processed.
type: integer
exponential_avg_checkpoint_duration_ms:
+ description: Exponential moving average of checkpoint duration, in milliseconds.
type: integer
exponential_avg_documents_indexed:
+ description: Exponential moving average of documents indexed per checkpoint.
type: integer
exponential_avg_documents_processed:
+ description: Exponential moving average of documents processed per checkpoint.
type: integer
index_failures:
+ description: Total number of failed index operations.
type: integer
index_time_in_ms:
+ description: Total time spent indexing documents, in milliseconds.
type: integer
index_total:
+ description: Total number of index operations.
type: integer
pages_processed:
+ description: Number of composite aggregation pages processed.
type: integer
processing_time_in_ms:
+ description: Total time spent processing results, in milliseconds.
type: integer
processing_total:
+ description: Total number of processing operations.
type: integer
search_failures:
+ description: Total number of failed search operations.
type: integer
search_time_in_ms:
+ description: Total time spent on search queries, in milliseconds.
type: integer
search_total:
+ description: Total number of search operations.
type: integer
trigger_count:
+ description: Number of times the transform has been triggered.
type: integer
required:
- pages_processed
@@ -2491,9 +2891,13 @@ components:
- exponential_avg_documents_processed
UserEntity:
additionalProperties: false
+ 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:
@@ -2506,38 +2910,47 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
user:
additionalProperties: false
+ 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'
additionalProperties: false
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 51b4132b9afaa..57677d7d01565 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:
@@ -668,6 +668,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:
@@ -725,20 +728,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':
@@ -790,10 +822,12 @@ paths:
type: object
properties:
deleted:
+ description: Entity types whose engines were successfully deleted.
items:
$ref: '#/components/schemas/EntityType'
type: array
still_running:
+ description: Entity types whose engines are still running.
items:
$ref: '#/components/schemas/EntityType'
type: array
@@ -802,17 +836,47 @@ paths:
tags:
- Security Entity Analytics API
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
@@ -859,15 +923,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
@@ -877,6 +946,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
@@ -885,6 +970,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.
@@ -951,6 +1037,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
@@ -961,9 +1063,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
@@ -973,10 +1079,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
@@ -984,9 +1099,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
@@ -996,10 +1115,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
@@ -1007,47 +1135,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
@@ -1064,7 +1248,8 @@ paths:
it is observed again in the future.
operationId: DeleteSingleEntity
parameters:
- - in: path
+ - example: user
+ in: path
name: entityType
required: true
schema:
@@ -1079,6 +1264,7 @@ paths:
description: >-
Identifier of the entity to be deleted, commonly entity.id
value.
+ example: arn:aws:iam::123456789012:user/jane.doe
type: string
required:
- id
@@ -1088,10 +1274,19 @@ paths:
'200':
content:
application/json:
+ examples:
+ deleteEntityExample:
+ description: >-
+ The entity was found and successfully removed from the
+ latest index.
+ summary: Entity deleted
+ value:
+ deleted: true
schema:
type: object
properties:
deleted:
+ description: Whether the entity was successfully deleted.
type: boolean
description: Successful response. Entity deleted.
'404':
@@ -1123,12 +1318,14 @@ paths:
store transform and usually takes more than 1 minute.
operationId: UpsertEntity
parameters:
- - in: path
+ - example: user
+ in: path
name: entityType
required: true
schema:
$ref: '#/components/schemas/EntityType'
- - in: query
+ - description: When true, allows updating protected fields.
+ in: query
name: force
required: false
schema:
@@ -1174,7 +1371,8 @@ paths:
more than 1 minute.
operationId: UpsertEntitiesBulk
parameters:
- - in: query
+ - description: When true, allows updating protected fields.
+ in: query
name: force
required: false
schema:
@@ -1204,12 +1402,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:
@@ -1217,13 +1418,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:
@@ -1236,7 +1441,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:
@@ -1253,17 +1459,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:
@@ -1277,11 +1487,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:
@@ -1290,22 +1504,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
@@ -1453,25 +1699,35 @@ components:
schemas:
Asset:
additionalProperties: false
+ description: Asset metadata associated with the entity.
type: object
properties:
business_unit:
+ description: Business unit the asset belongs to.
type: string
criticality:
$ref: '#/components/schemas/AssetCriticalityLevel'
+ description: The criticality level assigned to this asset.
environment:
+ description: Deployment environment (for example, production, staging).
type: string
id:
+ description: Unique identifier for the asset.
type: string
model:
+ description: Model name or number.
type: string
name:
+ description: Human-readable asset name.
type: string
owner:
+ description: The owner of the asset.
type: string
serial_number:
+ description: Serial number of the asset.
type: string
vendor:
+ description: Vendor or manufacturer.
type: string
AssetCriticalityBulkUploadErrorItem:
type: object
@@ -1673,6 +1929,9 @@ components:
required:
- criticality_level
EngineComponentResource:
+ description: >-
+ The type of Elasticsearch or Kibana resource backing an engine
+ component.
enum:
- entity_engine
- entity_definition
@@ -1687,18 +1946,25 @@ components:
- ilm_policy
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
@@ -1707,8 +1973,10 @@ components:
- unknown
type: string
id:
+ description: Unique identifier for the component.
type: string
installed:
+ description: Whether the component is currently installed.
type: boolean
metadata:
$ref: '#/components/schemas/Metadata'
@@ -1719,61 +1987,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'
@@ -1784,13 +2083,16 @@ components:
- fieldHistoryLength
EngineMetadata:
additionalProperties: false
+ description: Internal metadata attached to an entity by the engine that produced it.
type: object
properties:
Type:
+ description: The engine type that produced this entity record.
type: string
required:
- Type
EngineStatus:
+ description: The current operational status of an entity engine.
enum:
- installing
- started
@@ -1799,15 +2101,21 @@ components:
- error
type: string
EntitiesContainer:
+ description: A collection of entities to upsert in bulk.
type: object
properties:
entities:
+ description: The entities to create or update.
items:
$ref: '#/components/schemas/EntityContainer'
type: array
required:
- entities
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'
@@ -1848,99 +2156,134 @@ components:
- has_all_required
- privileges
EntityContainer:
+ description: A wrapper that pairs an entity type with the entity record to upsert.
type: object
properties:
record:
$ref: '#/components/schemas/Entity'
+ description: The entity record to create or update.
type:
$ref: '#/components/schemas/EntityType'
+ description: The entity type of the record.
required:
- type
- record
EntityField:
additionalProperties: false
+ description: >-
+ Core entity fields shared across all entity types. The `entity`
+ namespace is a root-level field in the Entity Store latest index.
type: object
properties:
attributes:
additionalProperties: false
+ description: Boolean flags describing characteristics of the entity.
type: object
properties:
asset:
+ description: Whether the entity is classified as an asset.
type: boolean
managed:
+ description: >-
+ Whether the entity is managed (for example, via a directory
+ service).
type: boolean
mfa_enabled:
+ description: Whether multi-factor authentication is enabled for the entity.
type: boolean
privileged:
+ description: Whether the entity has elevated privileges.
type: boolean
behaviors:
additionalProperties: false
+ description: Boolean flags indicating observed behavioral signals.
type: object
properties:
brute_force_victim:
+ description: Whether the entity has been targeted by brute-force attacks.
type: boolean
new_country_login:
+ description: Whether the entity has logged in from a new country.
type: boolean
used_usb_device:
+ description: Whether the entity has used a USB device.
type: boolean
EngineMetadata:
$ref: '#/components/schemas/EngineMetadata'
id:
+ description: Unique identifier for this entity.
+ example: arn:aws:iam::123456789012:user/jane.doe
type: string
lifecycle:
additionalProperties: false
+ description: Timestamps tracking the entity lifecycle.
type: object
properties:
first_seen:
+ description: When the entity was first observed.
format: date-time
type: string
last_activity:
+ description: When the entity last generated activity.
format: date-time
type: string
name:
+ description: Human-readable name of the entity.
+ example: jane.doe
type: string
relationships:
additionalProperties: false
+ description: Connections between this entity and other entities.
type: object
properties:
accessed_frequently_by:
+ description: Entity IDs that frequently access this entity.
items:
type: string
type: array
accesses_frequently:
+ description: Entity IDs this entity accesses frequently.
items:
type: string
type: array
communicates_with:
+ description: Entity IDs this entity communicates with.
items:
type: string
type: array
dependent_of:
+ description: Entity IDs that depend on this entity.
items:
type: string
type: array
depends_on:
+ description: Entity IDs this entity depends on.
items:
type: string
type: array
owned_by:
+ description: Entity IDs that own this entity.
items:
type: string
type: array
owns:
+ description: Entity IDs owned by this entity.
items:
type: string
type: array
supervised_by:
+ description: Entity IDs that supervise this entity.
items:
type: string
type: array
supervises:
+ description: Entity IDs supervised by this entity.
items:
type: string
type: array
risk:
additionalProperties: false
+ description: Risk scoring information for the entity.
type: object
properties:
calculated_level:
@@ -1960,10 +2303,14 @@ components:
minimum: 0
type: number
source:
+ description: The source that produced this entity record.
type: string
sub_type:
+ description: Optional sub-type classification for the entity.
type: string
type:
+ description: The entity type.
+ example: user
type: string
required:
- id
@@ -2077,6 +2424,7 @@ components:
- inputs
- notes
EntityType:
+ description: The type of entity.
enum:
- user
- host
@@ -2085,9 +2433,13 @@ components:
type: string
GenericEntity:
additionalProperties: false
+ description: >-
+ A generic entity record. Maps only the `entity` and `asset` namespaces.
+ Add additional field mappings here as needed.
type: object
properties:
'@timestamp':
+ description: The time the entity record was last updated.
format: date-time
type: string
asset:
@@ -2099,9 +2451,13 @@ components:
- entity
HostEntity:
additionalProperties: false
+ 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:
@@ -2114,43 +2470,53 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
host:
additionalProperties: false
+ 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
entity:
$ref: '#/components/schemas/EntityField'
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
@@ -2166,15 +2532,23 @@ components:
- entity.id
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
@@ -2385,9 +2759,13 @@ components:
- category
ServiceEntity:
additionalProperties: false
+ 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:
@@ -2400,15 +2778,18 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
service:
additionalProperties: false
+ description: Elastic Common Schema (ECS) service fields collected on the entity.
type: object
properties:
entity:
$ref: '#/components/schemas/EntityField'
name:
+ description: Primary service name.
type: string
risk:
$ref: '#/components/schemas/EntityRiskScoreRecord'
@@ -2417,6 +2798,7 @@ components:
required:
- entity
StoreStatus:
+ description: The overall operational status of the Entity Store.
enum:
- not_installed
- installing
@@ -2437,41 +2819,59 @@ components:
- status_code
- message
TransformStatsMetadata:
+ description: Statistics from the underlying Elasticsearch transform.
type: object
properties:
delete_time_in_ms:
+ description: Total time spent deleting documents, in milliseconds.
type: integer
documents_deleted:
+ description: Total number of documents deleted from the destination index.
type: integer
documents_indexed:
+ description: Total number of documents written to the destination index.
type: integer
documents_processed:
+ description: Total number of source documents processed.
type: integer
exponential_avg_checkpoint_duration_ms:
+ description: Exponential moving average of checkpoint duration, in milliseconds.
type: integer
exponential_avg_documents_indexed:
+ description: Exponential moving average of documents indexed per checkpoint.
type: integer
exponential_avg_documents_processed:
+ description: Exponential moving average of documents processed per checkpoint.
type: integer
index_failures:
+ description: Total number of failed index operations.
type: integer
index_time_in_ms:
+ description: Total time spent indexing documents, in milliseconds.
type: integer
index_total:
+ description: Total number of index operations.
type: integer
pages_processed:
+ description: Number of composite aggregation pages processed.
type: integer
processing_time_in_ms:
+ description: Total time spent processing results, in milliseconds.
type: integer
processing_total:
+ description: Total number of processing operations.
type: integer
search_failures:
+ description: Total number of failed search operations.
type: integer
search_time_in_ms:
+ description: Total time spent on search queries, in milliseconds.
type: integer
search_total:
+ description: Total number of search operations.
type: integer
trigger_count:
+ description: Number of times the transform has been triggered.
type: integer
required:
- pages_processed
@@ -2491,9 +2891,13 @@ components:
- exponential_avg_documents_processed
UserEntity:
additionalProperties: false
+ 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:
@@ -2506,38 +2910,47 @@ components:
type: object
properties:
ingested:
+ description: When the event was ingested into Elasticsearch.
format: date-time
type: string
user:
additionalProperties: false
+ 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'
additionalProperties: false
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: [
{