Create an entity

Base URL: https://{kibana_url}

POST /api/security/entity_store/entities/{entityType}
POST /s/{space_id}/api/security/entity_store/entities/{entityType}

Auth

Create a new entity record in the Entity Store for the specified entity type.

Required privileges

Privileges securitySolution

Path parameters

space_id string optional: An identifier for the space. If space_id is not provided in the URL, the default space is used. Refer to Spaces for more information.
entityType enum required: The entity type to create.; Values: user host service generic

Header parameters

kbn-xsrf string required: A required header to protect against CSRF attacks

Request body

Any of:

@timestamp string · format: date-time · max length: 64: The time the entity record was last updated.
asset object
entity object
event object
labels map string to object: Custom key-value labels attached to the entity.
tags string[]: Tags attached to the entity.
user object: Elastic Common Schema (ECS) user fields collected on the entity.

@timestamp string · format: date-time · max length: 64: The time the entity record was last updated.
asset object
entity object
event object
host object: Elastic Common Schema (ECS) host fields collected on the entity.
labels map string to object: Custom key-value labels attached to the entity.
tags string[]: Tags attached to the entity.

@timestamp string · format: date-time · max length: 64: The time the entity record was last updated.
asset object
entity object
event object
labels map string to object: Custom key-value labels attached to the entity.
service object: Elastic Common Schema (ECS) service fields collected on the entity.
tags string[]: Tags attached to the entity.

@timestamp string · format: date-time · max length: 64: The time the entity record was last updated.
asset object
cloud object: Elastic Common Schema (ECS) cloud fields for cloud-hosted entities.
entity object
event object
labels map string to object
orchestrator object: Elastic Common Schema (ECS) orchestrator fields for container-orchestrated entities.
tags string[]

Responses

200

Indicates the entity was successfully created.

application/json

400

Bad request.

application/json

409

Conflict.

application/json

Base URL: https://{kibana_url}

Examples

Request Console 1 / 2 languages

Console Kibana Dev Tools

POST kbn://api/security/entity_store/entities/host
{
  "entity": {
    "id": "host:web-server-prod-01",
    "name": "web-server-prod-01",
    "type": "host",
    "source": ["manual"],
    "attributes": { "asset": true }
  },
  "host": {
    "name": "web-server-prod-01",
    "ip": ["10.0.1.42"]
  }
}

curl Shell

curl -X POST -H "kbn-xsrf: true" -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{"entity":{"id":"host:web-server-prod-01","name":"web-server-prod-01","type":"host","source":["manual"],"attributes":{"asset":true}},"host":{"name":"web-server-prod-01","ip":["10.0.1.42"]}}' \
  "${KIBANA_URL}/api/security/entity_store/entities/host"

Response

No example

{
  "error": "Bad Request",
  "message": "Bad request: Supplied ID my-custom-id does not match generated EUID host:web-server-prod-01",
  "statusCode": 400
}

{
  "error": "Conflict",
  "message": "Entity ID \u0027host:web-server-prod-01\u0027 already exists",
  "statusCode": 409
}

Request Console 1 / 2 languages

Create a new host entity record with basic host and entity fields. The entity identifier must match the auto-generated format for the entity type.

Console Kibana Dev Tools

POST kbn:/api/security/entity_store/entities/ENTITY_TYPE
{
  "asset": {
    "business_unit": "Engineering",
    "criticality": "high_impact",
    "environment": "production"
  },
  "entity": {
    "attributes": {
      "asset": true,
      "managed": true
    },
    "id": "host:web-server-prod-01",
    "name": "web-server-prod-01",
    "source": [
      "manual"
    ],
    "type": "host"
  },
  "host": {
    "hostname": [
      "web-server-prod-01.example.com"
    ],
    "ip": [
      "10.0.1.42"
    ],
    "name": "web-server-prod-01"
  }
}

Generated from the API spec

curl Shell

curl -X POST -H "kbn-xsrf: true" -H "Authorization: ApiKey ${API_KEY}" \
  -H "Content-Type: application/json" \
  -d '{
    "asset": {
      "business_unit": "Engineering",
      "criticality": "high_impact",
      "environment": "production"
    },
    "entity": {
      "attributes": {
        "asset": true,
        "managed": true
      },
      "id": "host:web-server-prod-01",
      "name": "web-server-prod-01",
      "source": [
        "manual"
      ],
      "type": "host"
    },
    "host": {
      "hostname": [
        "web-server-prod-01.example.com"
      ],
      "ip": [
        "10.0.1.42"
      ],
      "name": "web-server-prod-01"
    }
  }' \
  "${KIBANA_URL}/api/security/entity_store/entities/${ENTITY_TYPE}"

Generated from the API spec

Response

The entity record was successfully created in the Entity Store.

{
  "ok": true
}

{
  "error": "Bad Request",
  "message": "Bad request: Supplied ID my-custom-id does not match generated EUID host:web-server-prod-01",
  "statusCode": 400
}

{
  "error": "Conflict",
  "message": "Entity ID \u0027host:web-server-prod-01\u0027 already exists",
  "statusCode": 409
}