Install the Entity Store

POST /api/security/entity_store/install

Spaces method and path for this operation:

post /s/{space_id}/api/security/entity_store/install

Refer to Spaces for more information.

Install the Entity Store and create engines for the specified entity types. logExtraction sets overrides that apply to all entity types, on top of built-in defaults per entity type. The default frequency is 1m for host and user, 10m for service and 30m for generic. Supply it once at install to customize settings; omit it (or send an empty object) to use defaults on first install or preserve the existing configuration on re-install. Omitting a field leaves it unchanged. Sending null for a field clears that override and reverts to the entity type default. To change settings after install, use the update endpoint.

[Required authorization] Route required privileges: securitySolution.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

entityTypes array[string]

Values are user, host, service, or generic. Default value is ["user", "host", "service", "generic"].
excludedUserNames array[string]

Not more than 200 elements.
historySnapshot object

Additional properties are NOT allowed.
Hide historySnapshot attributes Show historySnapshot attributes object
- frequency string
  
  Maximum length is 32. Format should match the following pattern: [smdh]$.
- retentionDays integer
  
  Minimum value is 1, maximum value is 3650.
logExtraction object

Additional properties are NOT allowed.
Hide logExtraction attributes Show logExtraction attributes object
- additionalIndexPatterns array[string] | null
  
  Not more than 1000 elements. Maximum length of each is 2048.
- delay string | null
  
  Maximum length is 32. Format should match the following pattern: [smdh]$.
- docsLimit integer | null
  
  Minimum value is 1, maximum value is 9007199254740991.
- excludedIndexPatterns array[string] | null
  
  Not more than 1000 elements. Maximum length of each is 2048.
- fieldHistoryLength integer | null
  
  Minimum value is -9007199254740991, maximum value is 9007199254740991.
- frequency string | null
  
  Maximum length is 32. Format should match the following pattern: [smdh]$.
- lookbackPeriod string | null
  
  Maximum length is 32. Format should match the following pattern: [smdh]$.
- maxLogsPerPage integer | null
  
  Minimum value is 1, maximum value is 9007199254740991.
- maxLogsPerWindow integer | null
  
  Minimum value is 0, maximum value is 9007199254740991.
- maxLogsPerWindowCapBehavior string | null
  
  Values are defer or drop.
- maxTimeWindowSize string | null
  
  Maximum length is 32. Format should match the following pattern: [smdh]$.

Responses

200 application/json

Indicates all requested entity types are already installed.
201 application/json

Indicates the Entity Store was successfully installed.
403 application/json

Insufficient privileges.

POST /api/security/entity_store/install

curl -X POST -H "kbn-xsrf: true" -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"entityTypes":["user","host","service","generic"],"logExtraction":{}}' \
  "${KIBANA_URL}/api/security/entity_store/install"

POST kbn://api/security/entity_store/install
{
  "entityTypes": ["user", "host", "service", "generic"],
  "logExtraction": {}
}

Request examples

Install the Entity Store for all entity types with default log extraction settings.

{
  "entityTypes": [
    "user",
    "host",
    "service",
    "generic"
  ],
  "logExtraction": {}
}

Install the Entity Store for host entities only with a custom lookback period and field history length.

{
  "entityTypes": [
    "host"
  ],
  "logExtraction": {
    "delay": "2m",
    "fieldHistoryLength": 20,
    "frequency": "5m",
    "lookbackPeriod": "12h"
  }
}

Response examples (200)

All requested entity types were already installed.

{
  "ok": true
}

Response examples (201)

The Entity Store was installed and engines are being created.

{
  "ok": true
}

Response examples (403)

The user does not have the required Elasticsearch privileges.

{
  "error": "Forbidden",
  "message": "User 'analyst' has insufficient privileges",
  "statusCode": 403
}