diff --git a/docs/management/api/execute-api.asciidoc b/docs/management/api/execute-api.asciidoc new file mode 100644 index 0000000000..1e8bde57c8 --- /dev/null +++ b/docs/management/api/execute-api.asciidoc @@ -0,0 +1,96 @@ +[[execute-api]] +=== Execute a command on a host + +Execute a command on a host running {elastic-defend}. + +You must have the `Execute Operations` {kib} privilege in the Security feature as part of your role and at least an Enterprise license to perform this action. + +==== Request URL + +`POST :/api/endpoint/action/execute` + +==== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +|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` |String |How long the host should wait for the command to complete. Use `h` for hours, `m` for minutes, `s` for seconds (for example, `2s` is two seconds). If no timeout is specified, it defaults to four hours. |No +|============================================== + + +===== Example requests + +Runs the command `ls -al` on a host with an `endpoint_id` value of `ed518850-681a-4d60-bb98-e22640cae2a8` with a timeout of `5m` and comments `Get list of all files`: + +[source,sh] +-------------------------------------------------- +POST /api/endpoint/action/execute +{ + "endpoint_ids": ["ed518850-681a-4d60-bb98-e22640cae2a8"], + "parameters": { + "command": "ls -al", + "timeout": "5m" + }, + "comment": "Get list of all files" +} +-------------------------------------------------- + + +===== Response code + +`200`:: + Indicates a successful call. + +`403`:: + Indicates insufficient privileges, or unsupported license level (minimum Enterprise license required). + +==== Response payload + +A JSON object with the details of the response action created. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "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": 300 + } + } +} + +-------------------------------------------------- diff --git a/docs/management/api/get-file-api.asciidoc b/docs/management/api/get-file-api.asciidoc new file mode 100644 index 0000000000..f47f4ef034 --- /dev/null +++ b/docs/management/api/get-file-api.asciidoc @@ -0,0 +1,92 @@ +[[get-file-api]] +=== Get a file from a host + +Retrieve a file from a host running {elastic-defend}. + +You must have the `File Operations` {kib} privilege in the Security feature as part of your role and at least an Enterprise license to perform this action. + +==== Request URL + +`POST :/api/endpoint/action/get-file` + +==== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +|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.path` |String |The file’s full path (including the file name). |Yes +|============================================== + + +===== Example requests + +Retrieve a file `/usr/my-file.txt` on a host with an `endpoint_id` value of `ed518850-681a-4d60-bb98-e22640cae2a8` and comments `Get my file`: + +[source,sh] +-------------------------------------------------- +POST /api/endpoint/action/get-file +{ + "endpoint_ids": ["ed518850-681a-4d60-bb98-e22640cae2a8"], + "parameters": { + "path": "/usr/my-file.txt", + }, + "comment": "Get my file" +} +-------------------------------------------------- + + +===== Response code + +`200`:: + Indicates a successful call. + +`403`:: + Indicates insufficient privileges, or unsupported license level (minimum Enterprise license required). + +==== Response payload + +A JSON object with the details of the response action created. + +===== Example response + +[source,json] +-------------------------------------------------- +{ + "data": { + "id": "27ba1b42-7cc6-4e53-86ce-675c876092b2", + "agents": [ + "ed518850-681a-4d60-bb98-e22640cae2a8" + ], + "hosts": { + "ed518850-681a-4d60-bb98-e22640cae2a8": { + "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r" + } + }, + "command": "get-file", + "startedAt": "2023-07-28T19:00:03.911Z", + "isCompleted": false, + "wasSuccessful": false, + "isExpired": false, + "status": "pending", + "outputs": {}, + "agentState": { + "ed518850-681a-4d60-bb98-e22640cae2a8": { + "isCompleted": false, + "wasSuccessful": false + } + }, + "createdBy": "myuser", + "parameters": { + "path": "/usr/my-file.txt" + } + } +} + +-------------------------------------------------- diff --git a/docs/management/api/list-actions-api.asciidoc b/docs/management/api/list-actions-api.asciidoc index 26e8f5ff19..d6d04539ef 100644 --- a/docs/management/api/list-actions-api.asciidoc +++ b/docs/management/api/list-actions-api.asciidoc @@ -27,6 +27,9 @@ Accepted values are: * `kill-process` * `suspend-process` * `running-processes` +* `get-file` +* `execute` +* `upload` | |`agentIds` |string[] |A list of agent IDs. Max of 50. | diff --git a/docs/management/api/management-api-index.asciidoc b/docs/management/api/management-api-index.asciidoc index 6abe6cf486..925f376990 100644 --- a/docs/management/api/management-api-index.asciidoc +++ b/docs/management/api/management-api-index.asciidoc @@ -10,6 +10,8 @@ include::host-isolation-release-api.asciidoc[] include::kill-process-api.asciidoc[] include::suspend-process-api.asciidoc[] include::running-procs-api.asciidoc[] +include::get-file-api.asciidoc[] +include::execute-api.asciidoc[] include::upload-api.asciidoc[] include::trusted-apps-api.asciidoc[] include::event-filters-api.asciidoc[]