Kibana Security Endpoint Management API API
Interact with and manage endpoints running the Elastic Defend integration.
OpenAPI Specification
openapi: 3.0.3
info:
contact:
name: Kibana Team
description: 'The Kibana REST APIs enable you to manage resources such as connectors, data views, and saved objects.
The API calls are stateless.
Each request that you make happens in isolation from other calls and must include all of the necessary information for Kibana to fulfill the
request.
API requests return JSON output, which is a format that is machine-readable and works well for automation.
To interact with Kibana APIs, use the following operations:
- GET: Fetches the information.
- PATCH: Applies partial modifications to the existing information.
- POST: Adds new information.
- PUT: Updates the existing information.
- DELETE: Removes the information.
You can prepend any Kibana API endpoint with `kbn:` and run the request in **Dev Tools → Console**.
For example:
```
GET kbn:/api/data_views
```
For more information about the console, refer to [Run API requests](https://www.elastic.co/docs/explore-analyze/query-filter/tools/console).
NOTE: Access to internal Kibana API endpoints will be restricted in Kibana version 9.0. Please move any integrations to publicly documented APIs.
## Documentation source and versions
This documentation is derived from the `main` branch of the [kibana](https://github.com/elastic/kibana) repository.
It is provided under license [Attribution-NonCommercial-NoDerivatives 4.0 International](https://creativecommons.org/licenses/by-nc-nd/4.0/).
This documentation contains work-in-progress information for future Elastic Stack releases.
'
title: Kibana APIs Actions Security Endpoint Management API API
version: ''
x-doc-license:
name: Attribution-NonCommercial-NoDerivatives 4.0 International
url: https://creativecommons.org/licenses/by-nc-nd/4.0/
x-feedbackLink:
label: Feedback
url: https://github.com/elastic/docs-content/issues/new?assignees=&labels=feedback%2Ccommunity&projects=&template=api-feedback.yaml&title=%5BFeedback%5D%3A+
servers:
- url: https://{kibana_url}
variables:
kibana_url:
default: localhost:5601
security:
- apiKeyAuth: []
- basicAuth: []
tags:
- description: Interact with and manage endpoints running the Elastic Defend integration.
name: Security Endpoint Management API
x-displayName: Security endpoint management
paths:
/api/endpoint/action:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/endpoint/action</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get a list of all response actions.'
operationId: EndpointGetActionsList
parameters:
- in: query
name: page
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_Page'
- in: query
name: pageSize
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_PageSize'
- in: query
name: commands
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_Commands'
- in: query
name: agentIds
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_AgentIds'
- in: query
name: userIds
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_UserIds'
- in: query
name: startDate
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_StartDate'
- in: query
name: endDate
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_EndDate'
- in: query
name: agentTypes
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_AgentTypes'
- in: query
name: withOutputs
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_WithOutputs'
- in: query
name: types
required: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_Types'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_GetEndpointActionListResponse'
description: Indicates a successful call.
summary: Get response actions
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action_status:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/endpoint/action_status</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the status of response actions for the specified agent IDs.'
operationId: EndpointGetActionsStatus
parameters:
- description: A list of agent IDs to get the action status for.
in: query
name: agent_ids
required: true
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_AgentIds'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ActionStatusSuccessResponse'
description: Indicates a successful call.
summary: Get response actions status
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/{action_id}:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/{action_id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get the details of a response action using the action ID.'
operationId: EndpointGetActionsDetails
parameters:
- in: path
name: action_id
required: true
schema:
description: The ID of the action to retrieve.
example: fr518850-681a-4y60-aa98-e22640cae2b8
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ActionDetailsResponse'
description: OK
summary: Get action details
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/{action_id}/file/{file_id}:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/{action_id}/file/{file_id}</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get information for the specified response action file download.
'
operationId: EndpointFileInfo
parameters:
- description: The ID of the response action that generated the file.
in: path
name: action_id
required: true
schema:
type: string
- description: 'The file identifier is constructed in one of two ways:
- For Elastic Defend agents (`agentType` of `endpoint`): combine the `action_id` and `agent_id` values using a dot (`.`) separator:
`{file_id}` = `{action_id}.{agent_id}`
- For all other agent types: the `file_id` is the `agent_id` for which the response action was sent to.
'
in: path
name: file_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
properties:
data:
type: object
properties:
actionId:
description: The response action ID.
type: string
agentId:
description: The agent ID that generated the file.
type: string
agentType:
description: The type of agent that generated the file.
type: string
created:
description: The date and time the file was created.
format: date-time
type: string
id:
description: The unique file identifier.
type: string
mimeType:
description: The MIME type of the file.
type: string
name:
description: The file name.
type: string
size:
description: The file size in bytes.
type: number
status:
description: The file upload status.
enum:
- AWAITING_UPLOAD
- UPLOADING
- READY
- UPLOAD_ERROR
- DELETED
type: string
description: Indicates a successful call.
summary: Get file information
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/{action_id}/file/{file_id}/download:
get:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb get">get</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/{action_id}/file/{file_id}/download</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Download a file associated with a response action. Files are downloaded in a password-protected `.zip` archive to prevent the file from running. Use password `elastic` to open the `.zip` in a safe environment.
> info
> Files retrieved from third-party-protected hosts require a different password. Refer to [Third-party response actions](https://www.elastic.co/docs/solutions/security/endpoint-response-actions/third-party-response-actions) for your system''s password.
'
operationId: EndpointFileDownload
parameters:
- description: The ID of the response action that generated the file.
in: path
name: action_id
required: true
schema:
type: string
- description: 'The file identifier is constructed in one of two ways:
- For Elastic Defend agents (`agentType` of `endpoint`): combine the `action_id` and `agent_id` values using a dot (`.`) separator:
`{file_id}` = `{action_id}.{agent_id}`
- For all other agent types: the `file_id` is the `agent_id` for which the response action was sent to.
'
in: path
name: file_id
required: true
schema:
type: string
responses:
'200':
content:
application/octet-stream:
schema:
format: binary
type: string
description: Indicates a successful call.
summary: Download a file
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/cancel:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/cancel</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Cancel a running or pending response action (Applies only to some agent types).'
operationId: CancelAction
requestBody:
content:
application/json:
examples:
MicrosoftDefenderEndpoint:
summary: Cancel a response action on a Microsoft Defender for Endpoint host
value:
agent_type: microsoft_defender_endpoint
comment: Cancelling action due to change in requirements
endpoint_ids:
- ed518850-681a-4d60-bb98-e22640cae2a8
parameters:
id: 7f8c9b2a-4d3e-4f5a-8b1c-2e3f4a5b6c7d
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_CancelRouteRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
CancelSuccess:
summary: Cancel action successfully created
value:
data:
agents:
- ed518850-681a-4d60-bb98-e22640cae2a8
agentState:
ed518850-681a-4d60-bb98-e22640cae2a8:
isCompleted: false
wasSuccessful: false
agentType: microsoft_defender_endpoint
command: cancel
createdBy: elastic
hosts:
ed518850-681a-4d60-bb98-e22640cae2a8:
name: gke-node-1235412
id: 233db9ea-6733-4849-9226-5a7039c7161d
isCompleted: false
isExpired: false
outputs: {}
parameters:
id: 7f8c9b2a-4d3e-4f5a-8b1c-2e3f4a5b6c7d
startedAt: '2022-07-29T19:08:49.126Z'
status: pending
wasSuccessful: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ResponseActionCreateSuccessResponse'
description: Indicates a successful call.
summary: Cancel a response action
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/execute:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/execute</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Run a shell command on an endpoint.'
operationId: EndpointExecuteAction
requestBody:
content:
application/json:
examples:
executeCommand:
summary: Execute a shell command on an endpoint
value:
comment: Get list of all files
endpoint_ids:
- b3d6de74-36b0-4fa8-be46-c375bf1771bf
parameters:
command: ls -al
timeout: 600
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ExecuteRouteRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
ExecuteSuccess:
summary: Execute action successfully created
value:
data:
agents:
- ed518850-681a-4d60-bb98-e22640cae2a8
agentState:
ed518850-681a-4d60-bb98-e22640cae2a8:
isCompleted: false
wasSuccessful: false
agentType: endpoint
command: execute
createdBy: elastic
hosts:
ed518850-681a-4d60-bb98-e22640cae2a8:
name: gke-node-1235412
id: 9f934028-2300-4927-b531-b26376793dc4
isCompleted: false
isExpired: false
outputs: {}
parameters:
command: ls -al
timeout: 600
startedAt: '2023-07-28T18:43:27.362Z'
status: pending
wasSuccessful: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ResponseActionCreateSuccessResponse'
description: Indicates a successful call.
summary: Run a command
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/get_file:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/get_file</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get a file from an endpoint.'
operationId: EndpointGetFileAction
requestBody:
content:
application/json:
examples:
getFile:
summary: Get a specific file from an endpoint
value:
comment: Get my file
endpoint_ids:
- ed518850-681a-4d60-bb98-e22640cae2a8
parameters:
path: /usr/my-file.txt
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_GetFileRouteRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
GetFileSuccess:
summary: Get file action successfully created
value:
data:
agents:
- ed518850-681a-4d60-bb98-e22640cae2a8
agentState:
ed518850-681a-4d60-bb98-e22640cae2a8:
isCompleted: false
wasSuccessful: false
agentType: endpoint
command: get-file
createdBy: elastic
hosts:
ed518850-681a-4d60-bb98-e22640cae2a8:
name: gke-node-1235412
id: 27ba1b42-7cc6-4e53-86ce-675c876092b2
isCompleted: false
isExpired: false
outputs: {}
parameters:
path: /usr/my-file.txt
startedAt: '2023-07-28T19:00:03.911Z'
status: pending
wasSuccessful: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ResponseActionCreateSuccessResponse'
description: Indicates a successful call.
summary: Get a file
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/isolate:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/isolate</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Isolate an endpoint from the network. The endpoint remains isolated until it''s released.'
operationId: EndpointIsolateAction
requestBody:
content:
application/json:
examples:
multiple_endpoints:
summary: Isolates several hosts; includes a comment
value:
comment: Locked down, pending further investigation
endpoint_ids:
- 9972d10e-4b9e-41aa-a534-a85e2a28ea42
- bc0e4f0c-3bca-4633-9fee-156c0b505d16
- fa89271b-b9d4-43f2-a684-307cffddeb5a
single_endpoint:
summary: Isolates a single host with an endpoint_id value of ed518850-681a-4d60-bb98-e22640cae2a8
value:
endpoint_ids:
- ed518850-681a-4d60-bb98-e22640cae2a8
with_case_id:
summary: Isolates a single host with a case_id value of 1234
value:
case_ids:
- 4976be38-c134-4554-bd5e-0fd89ce63667
comment: Isolating as initial response
endpoint_ids:
- 1aa1f8fd-0fb0-4fe4-8c30-92068272d3f0
- b30a11bf-1395-4707-b508-fbb45ef9793e
schema:
type: object
properties:
agent_type:
$ref: '#/components/schemas/Security_Endpoint_Management_API_AgentTypes'
alert_ids:
description: If this action is associated with any alerts, they can be specified here. The action will be logged in any cases associated with the specified alerts. Max of 50.
example:
- alert-id-1
- alert-id-2
items:
minLength: 1
type: string
maxItems: 50
minItems: 1
type: array
case_ids:
description: The IDs of cases where the action taken will be logged. Max of 50.
example:
- case-id-1
- case-id-2
items:
minLength: 1
type: string
maxItems: 50
minItems: 1
type: array
comment:
$ref: '#/components/schemas/Security_Endpoint_Management_API_Comment'
endpoint_ids:
$ref: '#/components/schemas/Security_Endpoint_Management_API_EndpointIds'
parameters:
$ref: '#/components/schemas/Security_Endpoint_Management_API_Parameters'
required:
- endpoint_ids
required: true
responses:
'200':
content:
application/json:
examples:
IsolateSuccess:
summary: Isolate action successfully created
value:
action: 233db9ea-6733-4849-9226-5a7039c7161d
data:
agents:
- ed518850-681a-4d60-bb98-e22640cae2a8
agentState:
ed518850-681a-4d60-bb98-e22640cae2a8:
isCompleted: false
wasSuccessful: false
agentType: endpoint
command: isolate
createdBy: elastic
hosts:
ed518850-681a-4d60-bb98-e22640cae2a8:
name: gke-node-1235412
id: 233db9ea-6733-4849-9226-5a7039c7161d
isCompleted: false
isExpired: false
outputs: {}
startedAt: '2022-07-29T19:08:49.126Z'
status: pending
wasSuccessful: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_IsolateRouteResponse'
description: Indicates a successful call.
summary: Isolate an endpoint
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/kill_process:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/kill_process</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Terminate a running process on an endpoint.'
operationId: EndpointKillProcessAction
requestBody:
content:
application/json:
examples:
byEntityId:
summary: Terminate a process by entity ID
value:
comment: Terminating malicious process
endpoint_ids:
- ed518850-681a-4d60-bb98-e22640cae2a8
parameters:
entity_id: abc123
byPid:
summary: Terminate a process by PID
value:
endpoint_ids:
- ed518850-681a-4d60-bb98-e22640cae2a8
parameters:
pid: 1234
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_KillProcessRouteRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
KillProcessSuccess:
summary: Kill process action successfully created
value:
data:
agents:
- ed518850-681a-4d60-bb98-e22640cae2a8
agentState:
ed518850-681a-4d60-bb98-e22640cae2a8:
isCompleted: false
wasSuccessful: false
agentType: endpoint
command: kill-process
createdBy: elastic
hosts:
ed518850-681a-4d60-bb98-e22640cae2a8:
name: gke-node-1235412
id: 233db9ea-6733-4849-9226-5a7039c7161d
isCompleted: false
isExpired: false
outputs: {}
parameters:
entity_id: abc123
startedAt: '2022-07-29T19:08:49.126Z'
status: pending
wasSuccessful: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ResponseActionCreateSuccessResponse'
description: Indicates a successful call.
summary: Terminate a process
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/memory_dump:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/memory_dump</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Generates memory dumps on the targeted host.'
operationId: EndpointGenerateMemoryDump
requestBody:
content:
application/json:
examples:
ProcessMemoryDump:
summary: Generate a memory dump from the host machine
value:
agent_type: endpoint
comment: Generating memory dump for investigation
endpoint_ids:
- ed518850-681a-4d60-bb98-e22640cae2a8
parameters:
entity_id: abc123
type: process
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_MemoryDumpRouteRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
MemoryDumpSuccessResponse:
summary: Memory dump action successfully created
value:
data:
agents:
- ed518850-681a-4d60-bb98-e22640cae2a8
agentState:
ed518850-681a-4d60-bb98-e22640cae2a8:
isCompleted: false
wasSuccessful: false
agentType: endpoint
command: memory-dump
createdBy: elastic
hosts:
ed518850-681a-4d60-bb98-e22640cae2a8:
name: gke-node-1235412
id: 233db9ea-6733-4849-9226-5a7039c7161d
isCompleted: false
isExpired: false
outputs: {}
parameters:
entity_id: abc123
type: process
startedAt: '2022-07-29T19:08:49.126Z'
status: pending
wasSuccessful: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ResponseActionCreateSuccessResponse'
description: Indicates a successful call.
summary: Generate a memory dump from the host machine
tags:
- Security Endpoint Management API
x-metaTags:
- content: Kibana
name: product_name
/api/endpoint/action/running_procs:
post:
description: '**Spaces method and path for this operation:**
<div><span class="operation-verb post">post</span> <span class="operation-path">/s/{space_id}/api/endpoint/action/running_procs</span></div>
Refer to [Spaces](https://www.elastic.co/docs/deploy-manage/manage-spaces) for more information.
Get a list of all processes running on an endpoint.'
operationId: EndpointGetProcessesAction
requestBody:
content:
application/json:
examples:
singleEndpoint:
summary: Get running processes on a single endpoint
value:
endpoint_ids:
- ed518850-681a-4d60-bb98-e22640cae2a8
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_GetProcessesRouteRequestBody'
required: true
responses:
'200':
content:
application/json:
examples:
RunningProcsSuccess:
summary: Running processes action successfully created
value:
data:
agents:
- ed518850-681a-4d60-bb98-e22640cae2a8
agentState:
ed518850-681a-4d60-bb98-e22640cae2a8:
isCompleted: false
wasSuccessful: false
agentType: endpoint
command: running-processes
createdBy: elastic
hosts:
ed518850-681a-4d60-bb98-e22640cae2a8:
name: gke-node-1235412
id: 233db9ea-6733-4849-9226-5a7039c7161d
isCompleted: false
isExpired: false
outputs: {}
startedAt: '2022-07-29T19:08:49.126Z'
status: pending
wasSuccessful: false
schema:
$ref: '#/components/schemas/Security_Endpoint_Management_API_ResponseActionCreateSuccessResponse'
description: Indicates a successful call.
summary: Get running processes
tags:
- Security Endpoint Management A
# --- truncated at 32 KB (118 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/kibana/refs/heads/main/openapi/kibana-security-endpoint-management-api-api-openapi.yml