IMPORTANT: No additional bug fixes or documentation updates will be released for this version. For the latest information, see the current release documentation.

« Get a file from a host Upload file to host »

› › ›

Execute a command on a host

edit

Execute a command on a host

edit

Execute a command on a host running Elastic Defend.

You must have the Execute Operations Kibana privilege in the Security feature as part of your role and at least an Enterprise license to perform this action.

Request URL

edit

POST <kibana host>:<port>/api/endpoint/action/execute

Request body

edit

A JSON object with these fields:

Name	Type	Description	Required
`endpoint_ids`	Array (String)	The IDs of endpoints where you want to issue this action.	Yes
`alert_ids`	Array (String)	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.	No
`case_ids`	Array (String)	The IDs of cases where the action taken will be logged.	No
`comment`	String	Attach a comment to this action’s log. The comment text will appear in associated cases.	No
`parameters.command`	String	A shell command to run on the host. The command must be supported by `bash` for Linux and macOS hosts, and `cmd.exe` for Windows.	Yes
`parameters.timeout`	Integer	The duration, in seconds, that the host waits for the command to complete. If no timeout is specified, it defaults to four hours.	No

The execute action uploads a text file containing the results of the execution on the endpoint, which is rate-limited. If you are using the endpoint_ids field to task multiple endpoints, you should batch your calls in groups of 10 at a time.

Example requests

edit

Runs the command ls -al on a host with an endpoint_id value of ed518850-681a-4d60-bb98-e22640cae2a8 with a timeout of 600 seconds and comments Get list of all files:

POST /api/endpoint/action/execute
{
  "endpoint_ids": ["ed518850-681a-4d60-bb98-e22640cae2a8"],
  "parameters": {
    "command": "ls -al",
    "timeout": 600
  },
  "comment": "Get list of all files"
}

Response code

edit

200: Indicates a successful call.
403: Indicates insufficient privileges, or unsupported license level (minimum Enterprise license required).

Response payload

edit

A JSON object with the details of the response action created.

Example response

edit

{
  "data": {
    "id": "9f934028-2300-4927-b531-b26376793dc4",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
      }
    },
    "command": "execute",
    "startedAt": "2023-07-28T18:43:27.362Z",
    "isCompleted": false,
    "wasSuccessful": false,
    "isExpired": false,
    "status": "pending",
    "outputs": {},
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "createdBy": "myuser",
    "comment": "Get list of all files",
    "parameters": {
      "command": "ls -al",
      "timeout": 600
    }
  }
}

« Get a file from a host Upload file to host »