Update the Entity Store

PUT /api/security/entity_store

Spaces method and path for this operation:

put /s/{space_id}/api/security/entity_store

Refer to Spaces for more information.

Update the Entity Store configuration without reinstalling. Send logExtraction to change log extraction settings. Omitting a log extraction field leaves it unchanged. Sending null for a log extraction field clears that override and reverts to the entity type default (for frequency: 1m for host and user, 10m for service, 30m for generic). Send historySnapshot.frequency to change the snapshot interval (at least 1 hour) and historySnapshot.retentionDays to change how long snapshots are kept. Omitting either history snapshot field leaves it unchanged. At least one of logExtraction, excludedUserNames or historySnapshot is required.

[Required authorization] Route required privileges: securitySolution.

Headers

kbn-xsrf string Required

A required header to protect against CSRF attacks

application/json

Body

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 a successful response.
400 application/json

Bad request.
404 application/json

Entity Store not found.

PUT /api/security/entity_store

curl -X PUT -H "kbn-xsrf: true" -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"logExtraction":{"lookbackPeriod":"6h","frequency":"10m","fieldHistoryLength":15}}' \
  "${KIBANA_URL}/api/security/entity_store"

PUT kbn://api/security/entity_store
{
  "logExtraction": {
    "lookbackPeriod": "6h",
    "frequency": "10m",
    "fieldHistoryLength": 15
  }
}

curl -X PUT -H "kbn-xsrf: true" -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"historySnapshot":{"frequency":"12h","retentionDays":90}}' \
  "${KIBANA_URL}/api/security/entity_store"

PUT kbn://api/security/entity_store
{
  "historySnapshot": {
    "frequency": "12h",
    "retentionDays": 90
  }
}

Request examples

Send null for any field to clear that override and revert it to the entity type default. For frequency, that is 1m for host and user, 10m for service and 30m for generic.

{
  "logExtraction": {
    "delay": null,
    "frequency": null
  }
}

Update the history snapshot interval and retention. Omit a field to leave it unchanged.

{
  "historySnapshot": {
    "frequency": "12h",
    "retentionDays": 90
  }
}

Update the log extraction configuration with a new lookback period and frequency.

{
  "logExtraction": {
    "fieldHistoryLength": 15,
    "frequency": "10m",
    "lookbackPeriod": "6h"
  }
}

Response examples (200)

The Entity Store configuration was successfully updated.

{
  "ok": true
}

Response examples (400)

A log extraction parameter has an invalid duration format.

{
  "error": "Bad Request",
  "message": "[request body]: logExtraction.frequency: must be a valid duration of at least 30 seconds (e.g. 1m, 30s)",
  "statusCode": 400
}

The history snapshot interval must be at least 1 hour.

{
  "error": "Bad Request",
  "message": "[request body]: historySnapshot.frequency: must be a valid duration of at least 1 hour (e.g. 1h, 24h)",
  "statusCode": 400
}

Response examples (404)

The Entity Store has not been installed yet.

{
  "error": "Not Found",
  "message": "Entity store is not installed",
  "statusCode": 404
}