Api key auth (http_api_key)
These APIs use key-based authentication. You must create an API key and use the encoded value in the request header. For example: Authorization: ApiKey base64AccessApiKey
Authentication
The API accepts 2 different authentication methods:
Basic auth (http)
Basic auth tokens are constructed with the Basic keyword, followed by a space, followed by a base64-encoded string of your username:password
(separated by a : colon).
Example: send a Authorization: Basic aGVsbG86aGVsbG8=
HTTP header with your requests to authenticate with the API.
Path parameters
-
id
string Required The identifier for the rule.
POST
/api/alerting/rule/{id}/_enable
curl \
--request POST 'https://localhost:5601/api/alerting/rule/{id}/_enable' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"Path parameters
-
id
string Required The identifier for the rule.
POST
/api/alerting/rule/{id}/_update_api_key
curl \
--request POST 'https://localhost:5601/api/alerting/rule/{id}/_update_api_key' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"Get a list of agent configurations
Headers
-
elastic-api-version
string Required The version of the API to use
Value is
2023-10-31. Default value is2023-10-31.
GET
/api/apm/settings/agent-configuration
curl \
--request GET 'https://localhost:5601/api/apm/settings/agent-configuration' \
--header "Authorization: $API_KEY" \
--header "elastic-api-version: 2023-10-31"APM agent keys
Configure APM agent keys to authorize requests from APM agents to the APM Server.
APM sourcemaps
Configure APM source maps.
Get all alerts for a case
Technical preview
You must have read privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on the owner of the cases you're seeking.
Path parameters
-
caseId
string Required The identifier for the case. To retrieve case IDs, use the find cases API. All non-ASCII characters must be URL encoded.
GET
/api/cases/{caseId}/alerts
curl \
--request GET 'https://localhost:5601/api/cases/9c235210-6834-11ea-a78c-6ffb38a34414/alerts' \
--header "Authorization: $API_KEY"
Response examples (200)
[
{
"id": "f6a7d0c3-d52d-432c-b2e6-447cd7fce04d",
"index": ".alerts-observability.logs.alerts-default",
"attached_at": "2022-07-25T20:09:40.963Z"
}
]Add case settings
Case settings include external connection details, custom fields, and templates. Connectors are used to interface with external systems. You must create a connector before you can use it in your cases. If you set a default connector, it is automatically selected when you create cases in Kibana. If you use the create case API, however, you must still specify all of the connector details. You must have all privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on where you are creating cases.
Body
-
closure_type
string Required Indicates whether a case is automatically closed when it is pushed to external systems (
close-by-pushing) or not automatically closed (close-by-user).Values are
close-by-pushingorclose-by-user. -
connector
object Required An object that contains the connector configuration.
-
customFields
array[object] Custom fields case configuration.
At least
0but not more than10elements. -
owner
string Required The application that owns the cases: Stack Management, Observability, or Elastic Security.
Values are
cases,observability, orsecuritySolution. -
templates
array[object] Technical preview
POST
/api/cases/configure
curl \
--request POST 'https://localhost:5601/api/cases/configure' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: string" \
--data '{"owner":"cases","connector":{"id":"5e656730-e1ca-11ec-be9b-9b1838238ee6","name":"my-jira-connector","type":".jira","fields":null},"templates":[{"key":"505932fe-ee3a-4960-a661-c781b5acdb05","name":"template-1","tags":["Template tag 1"],"caseFields":{"tags":["Default case tag"],"title":"Default case title","category":"Default-category","assignees":[{"uid":"u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"}],"description":"A default description for cases.","customFields":[{"key":"d312efda-ec2b-42ec-9e2c-84981795c581","type":"text","value":"A text field value for the template."}]},"description":"A description of the template."}],"closure_type":"close-by-user","customFields":[{"key":"d312efda-ec2b-42ec-9e2c-84981795c581","type":"text","label":"my-text-field","required":false,"defaultValue":"My custom field default value."}]}'
Request example
{
"owner": "cases",
"connector": {
"id": "5e656730-e1ca-11ec-be9b-9b1838238ee6",
"name": "my-jira-connector",
"type": ".jira",
"fields": null
},
"templates": [
{
"key": "505932fe-ee3a-4960-a661-c781b5acdb05",
"name": "template-1",
"tags": [
"Template tag 1"
],
"caseFields": {
"tags": [
"Default case tag"
],
"title": "Default case title",
"category": "Default-category",
"assignees": [
{
"uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
}
],
"description": "A default description for cases.",
"customFields": [
{
"key": "d312efda-ec2b-42ec-9e2c-84981795c581",
"type": "text",
"value": "A text field value for the template."
}
]
},
"description": "A description of the template."
}
],
"closure_type": "close-by-user",
"customFields": [
{
"key": "d312efda-ec2b-42ec-9e2c-84981795c581",
"type": "text",
"label": "my-text-field",
"required": false,
"defaultValue": "My custom field default value."
}
]
}
Response examples (200)
{
"id": "4a97a440-e1cd-11ec-be9b-9b1838238ee6",
"error": null,
"owner": "cases",
"version": "WzIwNzMsMV0=",
"mappings": [
{
"source": "title",
"target": "summary",
"action_type": "overwrite"
},
{
"source": "description",
"target": "description",
"action_type": "overwrite"
},
{
"source": "comments",
"target": "comments",
"action_type": "append"
},
{
"source": "tags",
"target": "labels",
"action_type": "overwrite"
}
],
"connector": {
"id": "5e656730-e1ca-11ec-be9b-9b1838238ee6",
"name": "my-jira-connector",
"type": ".jira",
"fields": null
},
"templates": [
{
"key": "505932fe-ee3a-4960-a661-c781b5acdb05",
"name": "template-1",
"tags": [
"Template tag 1"
],
"caseFields": {
"tags": [
"Default case tag"
],
"title": "Default case title",
"category": "Default-category",
"assignees": [
{
"uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
}
],
"description": "A default description for cases.",
"customFields": [
{
"key": "d312efda-ec2b-42ec-9e2c-84981795c581",
"type": "text",
"value": "A text field value for the template."
}
]
},
"description": "A description of the template."
}
],
"created_at": "2024-07-01T17:07:17.767Z",
"created_by": {
"email": "null,",
"username": "elastic",
"full_name": null,
"profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
},
"updated_at": null,
"updated_by": null,
"closure_type": "close-by-user",
"customFields": [
{
"key": "d312efda-ec2b-42ec-9e2c-84981795c581",
"type": "text",
"label": "my-text-field",
"required": false,
"defaultValue": "My custom field default value."
}
]
}Update case settings
Updates setting details such as the closure type, custom fields, templates, and the default connector for cases. Connectors are used to interface with external systems. You must create a connector before you can use it in your cases. You must have all privileges for the Cases feature in the Management, Observability, or Security section of the Kibana feature privileges, depending on where the case was created.
Path parameters
-
configurationId
string Required An identifier for the configuration.
Body
-
closure_type
string Indicates whether a case is automatically closed when it is pushed to external systems (
close-by-pushing) or not automatically closed (close-by-user).Values are
close-by-pushingorclose-by-user. -
connector
object An object that contains the connector configuration.
-
customFields
array[object] Custom fields case configuration.
-
templates
array[object] Technical preview -
version
string Required The version of the connector. To retrieve the version value, use the get configuration API.
PATCH
/api/cases/configure/{configurationId}
curl \
--request PATCH 'https://localhost:5601/api/cases/configure/3297a0f0-b5ec-11ec-b141-0fdb20a7f9a9' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: string" \
--data '{"version":"WzExOSw0XQ==","connector":{"id":"5e656730-e1ca-11ec-be9b-9b1838238ee6","name":"my-jira-connector","type":".jira","fields":null},"closure_type":"close-by-user","customFields":[{"key":"d312efda-ec2b-42ec-9e2c-84981795c581","type":"text","label":"my-text-field","required":true,"defaultValue":"A new default value."},{"key":"fcc6840d-eb14-42df-8aaf-232201a705ec","type":"toggle","label":"my-toggle","required":false}]}'
Request example
{
"version": "WzExOSw0XQ==",
"connector": {
"id": "5e656730-e1ca-11ec-be9b-9b1838238ee6",
"name": "my-jira-connector",
"type": ".jira",
"fields": null
},
"closure_type": "close-by-user",
"customFields": [
{
"key": "d312efda-ec2b-42ec-9e2c-84981795c581",
"type": "text",
"label": "my-text-field",
"required": true,
"defaultValue": "A new default value."
},
{
"key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
"type": "toggle",
"label": "my-toggle",
"required": false
}
]
}
Response examples (200)
{
"id": "4a97a440-e1cd-11ec-be9b-9b1838238ee6",
"error": null,
"owner": "cases",
"version": "WzI2LDNd",
"mappings": [
{
"source": "title",
"target": "summary",
"action_type": "overwrite"
},
{
"source": "description",
"target": "description",
"action_type": "overwrite"
},
{
"source": "tags",
"target": "labels",
"action_type": "overwrite"
},
{
"source": "comments",
"target": "comments",
"action_type": "append"
}
],
"connector": {
"id": "5e656730-e1ca-11ec-be9b-9b1838238ee6",
"name": "my-jira-connector",
"type": ".jira",
"fields": null
},
"templates": [],
"created_at": "2024-07-01T17:07:17.767Z",
"created_by": {
"email": null,
"username": "elastic",
"full_name": null,
"profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
},
"updated_at": "2024-07-19T00:52:42.401Z",
"updated_by": {
"email": null,
"username": "elastic",
"full_name": null,
"profile_uid": "u_mGBROF_q5bmFCATbLXAcCwKa0k8JvONAwSruelyKA5E_0"
},
"closure_type": "close-by-user",
"customFields": [
{
"key": "d312efda-ec2b-42ec-9e2c-84981795c581",
"type": "text",
"label": "my-text-field",
"required": true,
"defaultValue": "A new default value."
},
{
"key": "fcc6840d-eb14-42df-8aaf-232201a705ec",
"type": "toggle",
"label": "my-toggle",
"required": false
}
]
}Path parameters
-
id
string Required An identifier for the connector.
GET
/api/actions/action/{id}
curl \
--request GET 'https://localhost:5601/api/actions/action/{id}' \
--header "Authorization: $API_KEY"
Delete a connector
Deprecated
WARNING: When you delete a connector, it cannot be recovered.
Path parameters
-
id
string Required An identifier for the connector.
DELETE
/api/actions/action/{id}
curl \
--request DELETE 'https://localhost:5601/api/actions/action/{id}' \
--header "Authorization: $API_KEY" \
--header "kbn-xsrf: true"
GET
/api/actions/connectors
curl \
--request GET 'https://localhost:5601/api/actions/connectors' \
--header "Authorization: $API_KEY"
Response examples (200)
[
{
"id": "preconfigured-email-connector",
"name": "my-preconfigured-email-notification",
"is_deprecated": false,
"is_preconfigured": true,
"is_system_action": false,
"connector_type_id": ".email",
"referenced_by_count": 0
},
{
"id": "e07d0c80-8b8b-11ed-a780-3b746c987a81",
"name": "my-index-connector",
"config": {
"index": "test-index",
"refresh": false,
"executionTimeField": null
},
"is_deprecated": false,
"is_preconfigured": false,
"is_system_action": false,
"connector_type_id": ".index",
"is_missing_secrets": false,
"referenced_by_count": 2
}
]
GET
/api/data_views
curl \
--request GET 'https://localhost:5601/api/data_views' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"data_view": [
{
"id": "ff959d40-b880-11e8-a6d9-e546fe2bba5f",
"name": "Kibana Sample Data eCommerce",
"title": "kibana_sample_data_ecommerce",
"typeMeta": {},
"namespaces": [
"default"
]
},
{
"id": "d3d7af60-4c81-11e8-b3d7-01146121b73d",
"name": "Kibana Sample Data Flights",
"title": "kibana_sample_data_flights",
"namespaces": [
"default"
]
},
{
"id": "90943e30-9a47-11e8-b64d-95841ca0b247",
"name": "Kibana Sample Data Logs",
"title": "kibana_sample_data_logs",
"namespaces": [
"default"
]
}
]
}
POST
/api/data_views/data_view
curl \
--request POST 'https://localhost:5601/api/data_views/data_view' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--header "kbn-xsrf: string" \
--data '{"data_view":{"name":"My Logstash data view","title":"logstash-*","runtimeFieldMap":{"runtime_shape_name":{"type":"keyword","script":{"source":"emit(doc['shape_name'].value)"}}}}}'
Request example
{
"data_view": {
"name": "My Logstash data view",
"title": "logstash-*",
"runtimeFieldMap": {
"runtime_shape_name": {
"type": "keyword",
"script": {
"source": "emit(doc['shape_name'].value)"
}
}
}
}
}
Get a Logstash pipeline
Technical Preview
Get information for a centrally-managed Logstash pipeline.
To use this API, you must have either the logstash_admin built-in role or a customized Logstash reader role.
Path parameters
-
id
string Required An identifier for the pipeline.
GET
/api/logstash/pipeline/{id}
curl \
--request GET 'https://localhost:5601/api/logstash/pipeline/{id}' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"id": "hello-world",
"description": "Just a simple pipeline",
"username": "elastic",
"pipeline": "input { stdin {} } output { stdout {} }",
"settings": {
"queue.type": "persistent"
}
}
Delete a Logstash pipeline
Technical Preview
Delete a centrally-managed Logstash pipeline.
If your Elasticsearch cluster is protected with basic authentication, you must have either the logstash_admin built-in role or a customized Logstash writer role.
Path parameters
-
id
string Required An identifier for the pipeline.
DELETE
/api/logstash/pipeline/{id}
curl \
--request DELETE 'https://localhost:5601/api/logstash/pipeline/{id}' \
--header "Authorization: $API_KEY"Sync saved objects in the default space
Synchronizes Kibana saved objects for machine learning jobs and trained models in the default space. You must have all privileges for the Machine Learning feature in the Analytics section of the Kibana feature privileges. This API runs automatically when you start Kibana and periodically thereafter.
Query parameters
-
simulate
boolean When true, simulates the synchronization by returning only the list of actions that would be performed.
GET
/api/ml/saved_objects/sync
curl \
--request GET 'https://localhost:5601/api/ml/saved_objects/sync' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"datafeedsAdded": {},
"datafeedsRemoved": {},
"savedObjectsCreated": {
"anomaly-detector": {
"myjob1": {
"success": true
},
"myjob2": {
"success": true
}
}
},
"savedObjectsDeleted": {}
}Get a conversation
Get the details of an existing conversation using the conversation ID. This allows users to fetch the specific conversation data by its unique ID.
Path parameters
-
id
string(nonempty) Required The conversation's
idvalue, a unique identifier for the conversation.Minimum length is
1.
GET
/api/security_ai_assistant/current_user/conversations/{id}
curl \
--request GET 'https://localhost:5601/api/security_ai_assistant/current_user/conversations/abc123' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"id": "abc123",
"title": "Security Discussion",
"users": [
{
"id": "user1",
"name": "John Doe"
}
],
"category": "assistant",
"messages": [
{
"role": "system",
"content": "Hello, how can I assist you today?",
"timestamp": "2023-10-31T12:00:00Z"
}
],
"apiConfig": {
"connectorId": "12345",
"actionTypeId": "67890"
},
"createdAt": "2023-10-31T12:01:00Z",
"updatedAt": "2023-10-31T12:01:00Z",
"replacements": {},
"excludeFromLastConversationStorage": false
}Finds Knowledge Base Entries that match the given query.
Finds Knowledge Base Entries that match the given query.
Query parameters
-
fields
array[string] A list of fields to include in the response. If not provided, all fields will be included.
-
filter
string Search query to filter Knowledge Base Entries by specific criteria.
-
sort_field
string Field to sort the Knowledge Base Entries by.
Values are
created_at,is_default,title, orupdated_at. -
sort_order
string Sort order for the results, either asc or desc.
Values are
ascordesc. -
page
integer Page number for paginated results. Defaults to 1.
Minimum value is
1. Default value is1. -
per_page
integer Number of Knowledge Base Entries to return per page. Defaults to 20.
Minimum value is
0. Default value is20.
GET
/api/security_ai_assistant/knowledge_base/entries/_find
curl \
--request GET 'https://localhost:5601/api/security_ai_assistant/knowledge_base/entries/_find' \
--header "Authorization: $API_KEY"
POST
/api/detection_engine/index
curl \
--request POST 'https://localhost:5601/api/detection_engine/index' \
--header "Authorization: $API_KEY"Retrieve the status of prebuilt detection rules and Timelines
Retrieve the status of all Elastic prebuilt detection rules and Timelines.
This endpoint provides detailed information about the number of custom rules, installed prebuilt rules, available prebuilt rules that are not installed, outdated prebuilt rules, installed prebuilt timelines, available prebuilt timelines that are not installed, and outdated prebuilt timelines.
GET
/api/detection_engine/rules/prepackaged/_status
curl \
--request GET 'https://localhost:5601/api/detection_engine/rules/prepackaged/_status' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"rules_installed": 0,
"rules_not_updated": 0,
"rules_not_installed": 112,
"timelines_installed": 0,
"timelines_not_updated": 0,
"rules_custom_installed": 0,
"timelines_not_installed": 0
}
Clean up detection alert migrations
Deprecated
Migrations favor data integrity over shard size. Consequently, unused or orphaned indices are artifacts of the migration process. A successful migration will result in both the old and new indices being present. As such, the old, orphaned index can (and likely should) be deleted.
While you can delete these indices manually, the endpoint accomplishes this task by applying a deletion policy to the relevant index, causing it to be deleted after 30 days. It also deletes other artifacts specific to the migration implementation.
Body
Required
Array of migration_ids to cleanup
-
migration_ids
array[string] Required Array of
migration_ids to cleanup.At least
1element.
DELETE
/api/detection_engine/signals/migration
curl \
--request DELETE 'https://localhost:5601/api/detection_engine/signals/migration' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"migration_ids":["924f7c50-505f-11eb-ae0a-3fa2e626a51d"]}'
Request example
{
"migration_ids": [
"924f7c50-505f-11eb-ae0a-3fa2e626a51d"
]
}
Response examples (200)
{
"migrations": [
{
"id": "924f7c50-505f-11eb-ae0a-3fa2e626a51d",
"status": "success",
"updated": "2021-01-06T22:05:56.859Z",
"version": 16,
"sourceIndex": ".siem-signals-default-000002",
"destinationIndex": ".siem-signals-default-000002-r000016"
}
]
}Delete an endpoint exception list item
Delete an endpoint exception list item using the id or item_id field.
DELETE
/api/endpoint_list/items
curl \
--request DELETE 'https://localhost:5601/api/endpoint_list/items' \
--header "Authorization: $API_KEY"Security endpoint management
Interact with and manage endpoints running the Elastic Defend integration.
Get an action request log
Deprecated
Get an action request log for the specified agent ID.
Path parameters
-
agent_id
string Required Agent ID
Query parameters
-
query
object Required
GET
/api/endpoint/action_log/{agent_id}
curl \
--request GET 'https://localhost:5601/api/endpoint/action_log/{agent_id}?query=%7B%7D' \
--header "Authorization: $API_KEY"Get running processes
Get a list of all processes running on an endpoint.
Body
Required
-
agent_type
string List of agent types to retrieve. Defaults to
endpoint.Values are
endpoint,sentinel_one,crowdstrike, ormicrosoft_defender_endpoint. -
alert_ids
array[string(nonempty)] A list of alerts
ids.At least
1element. Minimum length of each is1. -
case_ids
array[string] Case IDs to be updated (cannot contain empty strings)
At least
1element. Minimum length of each is1. -
comment
string Optional comment
-
endpoint_ids
array[string] Required List of endpoint IDs (cannot contain empty strings)
At least
1element. Minimum length of each is1. -
parameters
object Optional parameters object
POST
/api/endpoint/action/running_procs
curl \
--request POST 'https://localhost:5601/api/endpoint/action/running_procs' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'
Request example
{
"endpoint_ids": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
]
}
Response examples (200)
{
"data": {
"id": "233db9ea-6733-4849-9226-5a7039c7161d",
"agents": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
],
"errors": [],
"command": "running-processes",
"comment": "",
"outputs": {
"ed518850-681a-4d60-bb98-e22640cae2a8": {
"type": "json",
"content": {
"key": "value"
}
}
},
"agentType": "endpoint",
"createdBy": "myuser",
"isExpired": false,
"startedAt": "2022-07-29T19:08:49.126Z",
"parameters": {},
"completedAt": "2022-07-29T19:09:44.961Z",
"isCompleted": true,
"wasSuccessful": true
}
}Suspend a process
Suspend a running process on an endpoint.
Body
Required
-
agent_type
string List of agent types to retrieve. Defaults to
endpoint.Values are
endpoint,sentinel_one,crowdstrike, ormicrosoft_defender_endpoint. -
alert_ids
array[string(nonempty)] A list of alerts
ids.At least
1element. Minimum length of each is1. -
case_ids
array[string] Case IDs to be updated (cannot contain empty strings)
At least
1element. Minimum length of each is1. -
comment
string Optional comment
-
endpoint_ids
array[string] Required List of endpoint IDs (cannot contain empty strings)
At least
1element. Minimum length of each is1. parameters
object Required -
parameters
object Optional parameters object
POST
/api/endpoint/action/suspend_process
curl \
--request POST 'https://localhost:5601/api/endpoint/action/suspend_process' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"comment":"suspend the process","parameters":{"entity_id":"abc123"},"endpoint_ids":["ed518850-681a-4d60-bb98-e22640cae2a8"]}'
Request example
{
"comment": "suspend the process",
"parameters": {
"entity_id": "abc123"
},
"endpoint_ids": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
]
}
Response examples (200)
{
"data": {
"id": "233db9ea-6733-4849-9226-5a7039c7161d",
"agents": [
"ed518850-681a-4d60-bb98-e22640cae2a8"
],
"errors": [],
"command": "suspend-process",
"comment": "suspend the process",
"outputs": {
"ed518850-681a-4d60-bb98-e22640cae2a8": {
"type": "json",
"content": {
"key": "value"
}
}
},
"agentType": "endpoint",
"createdBy": "myuser",
"isExpired": false,
"startedAt": "2022-07-29T19:08:49.126Z",
"parameters": {
"entity_id": "abc123"
},
"completedAt": "2022-07-29T19:09:44.961Z",
"isCompleted": true,
"wasSuccessful": true
}
}Query parameters
-
page
integer Page number
Minimum value is
1. Default value is1. -
pageSize
integer Number of items per page
Minimum value is
1, maximum value is100. Default value is10. -
kuery
string A KQL string.
-
hostStatuses
array[string] Required A set of agent health statuses to filter by.
Values are
healthy,offline,updating,inactive, orunenrolled. -
sortField
string Determines which field is used to sort the results.
Values are
enrolled_at,metadata.host.hostname,host_status,metadata.Endpoint.policy.applied.name,metadata.Endpoint.policy.applied.status,metadata.host.os.name,metadata.host.ip,metadata.agent.version, orlast_checkin. -
sortDirection
string Determines the sort order.
Values are
ascordesc.
GET
/api/endpoint/metadata
curl \
--request GET 'https://localhost:5601/api/endpoint/metadata?hostStatuses=healthy&hostStatuses=updating' \
--header "Authorization: $API_KEY"
Response examples (200)
{
"data": [
{
"metadata": {
"ecs": {
"version": "1.11.0"
},
"host": {
"id": "0cfead88e2024bd8a27476352b5ab264",
"ip": [
"127.0.0.1",
"::1",
"10.0.2.15",
"fe80::2ac7:8e15:b957:2fa1"
],
"os": {
"Ext": {
"variant": "Ubuntu"
},
"full": "Ubuntu 20.04.2",
"name": "Linux",
"type": "linux",
"family": "ubuntu",
"kernel": "5.8.0-59-generic #66~20.04.1-Ubuntu SMP Thu Jun 17 11:14:10 UTC 2021",
"version": "20.04.2",
"platform": "ubuntu"
},
"mac": [
"08:00:27:e6:78:8b"
],
"name": "david-Xubuntu",
"hostname": "david-Xubuntu",
"architecture": "x86_64"
},
"agent": {
"id": "285297c6-3bff-4b83-9a07-f3e749801123",
"type": "endpoint",
"build": {
"original": "version: 7.16.0, compiled: Tue Nov 16 16:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
},
"version": "7.16.0"
},
"event": {
"id": "MNtSXK/SkhEBnmgt++++++7S",
"kind": "metric",
"type": [
"info"
],
"action": "endpoint_metadata",
"module": "endpoint",
"created": "2023-07-04T15:47:57.432173535Z",
"dataset": "endpoint.metadata",
"category": [
"host"
],
"ingested": "2023-07-04T15:47:58Z",
"sequence": 400,
"agent_id_status": "verified"
},
"elastic": {
"agent": {
"id": "285297c6-3bff-4b83-9a07-f3e749801123"
}
},
"message": "Endpoint metadata",
"Endpoint": {
"state": {
"isolation": false
},
"policy": {
"applied": {
"id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
"name": "test",
"status": "success",
"version": "3",
"endpoint_policy_version": "2"
}
},
"status": "enrolled",
"capabilities": [
"isolation"
],
"configuration": {
"isolation": false
}
},
"@timestamp": "2023-07-04T15:47:57.432173535Z",
"data_stream": {
"type": "metrics",
"dataset": "endpoint.metadata",
"namespace": "default"
}
},
"host_status": "healthy",
"policy_info": {
"agent": {
"applied": {
"id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
"revision": 0
},
"configured": {
"id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
"revision": 3
}
},
"endpoint": {
"id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
"revision": 2
}
},
"last_checkin": "2023-07-04T15:47:57.432Z"
},
{
"metadata": {
"ecs": {
"version": "1.11.0"
},
"host": {
"id": "17d9cabc-7edd-43bc-bacb-8da5f5e6c0e5",
"ip": [
"10.0.2.15",
"fe80::21a6:63d3:d70e:e3ad",
"127.0.0.1",
"::1"
],
"os": {
"Ext": {
"variant": "Windows 10 Enterprise Evaluation"
},
"full": "Windows 10 Enterprise Evaluation 20H2 (10.0.19042.906)",
"name": "Windows",
"type": "windows",
"family": "windows",
"kernel": "20H2 (10.0.19042.906)",
"version": "20H2 (10.0.19042.906)",
"platform": "windows"
},
"mac": [
"08:00:27:b1:1d:5a"
],
"name": "WinDev2104Eval",
"hostname": "WinDev2104Eval",
"architecture": "x86_64"
},
"agent": {
"id": "abb8a826-6812-448c-a571-6d8269b51449",
"type": "endpoint",
"build": {
"original": "version: 7.16.0, compiled: Tue Nov 16 17:00:00 2021, branch: 7.16, commit: 73a51033db85e0fb3be1c934697ef6a2b08979ab"
},
"version": "7.16.0"
},
"event": {
"id": "MNtRc++KoKHXXwlj+++++/N9",
"kind": "metric",
"type": [
"info"
],
"action": "endpoint_metadata",
"module": "endpoint",
"created": "2023-07-04T15:44:31.4917849Z",
"dataset": "endpoint.metadata",
"category": [
"host"
],
"ingested": "2023-07-04T15:44:33Z",
"sequence": 5159,
"agent_id_status": "verified"
},
"elastic": {
"agent": {
"id": "abb8a826-6812-448c-a571-6d8269b51449"
}
},
"message": "Endpoint metadata",
"Endpoint": {
"state": {
"isolation": false
},
"policy": {
"applied": {
"id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
"name": "test",
"status": "success",
"version": "3",
"endpoint_policy_version": "2"
}
},
"status": "enrolled",
"capabilities": [
"isolation"
],
"configuration": {
"isolation": false
}
},
"@timestamp": "2023-07-04T15:44:31.4917849Z",
"data_stream": {
"type": "metrics",
"dataset": "endpoint.metadata",
"namespace": "default"
}
},
"host_status": "healthy",
"policy_info": {
"agent": {
"applied": {
"id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
"revision": 0
},
"configured": {
"id": "ed7e3720-4bad-11ec-a2a8-fb22e62a5753",
"revision": 3
}
},
"endpoint": {
"id": "d5371dcd-93b7-4627-af88-4084f7d6aa3e",
"revision": 2
}
},
"last_checkin": "2023-07-04T15:44:31.491Z"
}
],
"page": 0,
"total": 2,
"pageSize": 10,
"sortField": "enrolled_at",
"sortDirection": "desc"
}
Release an isolated endpoint
Deprecated
Release an isolated endpoint, allowing it to rejoin a network.
This URL will return a 308 permanent redirect to POST <kibana host>:<port>/api/endpoint/action/unisolate.
Body
Required
-
agent_type
string List of agent types to retrieve. Defaults to
endpoint.Values are
endpoint,sentinel_one,crowdstrike, ormicrosoft_defender_endpoint. -
alert_ids
array[string(nonempty)] A list of alerts
ids.At least
1element. Minimum length of each is1. -
case_ids
array[string] Case IDs to be updated (cannot contain empty strings)
At least
1element. Minimum length of each is1. -
comment
string Optional comment
-
endpoint_ids
array[string] Required List of endpoint IDs (cannot contain empty strings)
At least
1element. Minimum length of each is1. -
parameters
object Optional parameters object
POST
/api/endpoint/unisolate
curl \
--request POST 'https://localhost:5601/api/endpoint/unisolate' \
--header "Authorization: $API_KEY" \
--header "Content-Type: application/json" \
--data '{"agent_type":"endpoint","alert_ids":["string"],"case_ids":["case-id-1","case-id-2"],"comment":"This is a comment","endpoint_ids":["endpoint-id-1","endpoint-id-2"],"parameters":{}}'
GET
/api/entity_store/engines
curl \
--request GET 'https://localhost:5601/api/entity_store/engines' \
--header "Authorization: $API_KEY"Security exceptions
Exceptions are associated with detection and endpoint rules, and are used to prevent a rule from generating an alert from incoming events, even when the rule's other criteria are met. They can help reduce the number of false positives and prevent trusted processes and network activity from generating unnecessary alerts.
Exceptions are made up of:
- Exception containers: A container for related exceptions. Generally, a single exception container contains all the exception items relevant for a subset of rules. For example, a container can be used to group together network-related exceptions that are relevant for a large number of network rules. The container can then be associated with all the relevant rules.
- Exception items: The query (fields, values, and logic) used to prevent rules from generating alerts. When an exception item's query evaluates to
true, the rule does not generate an alert.
For detection rules, you can also use lists to define rule exceptions. A list holds multiple values of the same Elasticsearch data type, such as IP addresses. These values are used to determine when an exception prevents an alert from being generated.
You cannot use lists with endpoint rule exceptions.
Only exception containers can be associated with rules. You cannot directly associate an exception item or a list container with a rule. To use list exceptions, create an exception item that references the relevant list container.
Exceptions requirements
Before you can start working with exceptions that use value lists, you must create the .lists and .items data streams for the relevant Kibana space. To do this, use the Create list data streams endpoint. Once these data streams are created, your role needs privileges to manage rules. For a complete list of requirements, refer to Enable and access detections.