diff --git a/docs/management/api/execute-api.asciidoc b/docs/management/api/execute-api.asciidoc index 771c2ec897..5679491581 100644 --- a/docs/management/api/execute-api.asciidoc +++ b/docs/management/api/execute-api.asciidoc @@ -3,7 +3,7 @@ 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. +You must have the `Execute Operations` {kib} privilege in the Security feature as part of your role and an Enterprise license to perform this action. ==== Request URL @@ -49,7 +49,7 @@ POST /api/endpoint/action/execute Indicates a successful call. `403`:: - Indicates insufficient privileges, or unsupported license level (minimum Enterprise license required). + Indicates insufficient user privilege (*Execute Operations* required), or unsupported license level (Enterprise license required). ==== Response payload diff --git a/docs/management/api/get-file-api.asciidoc b/docs/management/api/get-file-api.asciidoc index 8b5a4152f6..4909c554ff 100644 --- a/docs/management/api/get-file-api.asciidoc +++ b/docs/management/api/get-file-api.asciidoc @@ -3,7 +3,7 @@ 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. +You must have the `File Operations` {kib} privilege in the Security feature as part of your role and an Enterprise license to perform this action. ==== Request URL @@ -44,7 +44,7 @@ POST /api/endpoint/action/get_file Indicates a successful call. `403`:: - Indicates insufficient privileges, or unsupported license level (minimum Enterprise license required). + Indicates insufficient user privilege (*File Operations* required), or unsupported license level (Enterprise license required). ==== Response payload diff --git a/docs/management/api/kill-process-api.asciidoc b/docs/management/api/kill-process-api.asciidoc index b2e40bc4e8..7709162a04 100644 --- a/docs/management/api/kill-process-api.asciidoc +++ b/docs/management/api/kill-process-api.asciidoc @@ -3,7 +3,7 @@ Terminates a process on a host running {elastic-defend}. -You must have the *Process Operations* <> and at least an Enterprise license to perform this action. +You must have the *Process Operations* <> and an Enterprise license to perform this action. ==== Request URL @@ -46,7 +46,7 @@ POST /api/endpoint/action/kill_process Indicates a successful call. `403`:: - Indicates insufficient user privilege (*Process Operations* required), or unsupported license level (minimum Enterprise license required). + Indicates insufficient user privilege (*Process Operations* required), or unsupported license level (Enterprise license required). `500`:: General error. A response message will provide additional details. diff --git a/docs/management/api/list-actions-api.asciidoc b/docs/management/api/list-actions-api.asciidoc index cdad22957e..50b0f329fa 100644 --- a/docs/management/api/list-actions-api.asciidoc +++ b/docs/management/api/list-actions-api.asciidoc @@ -30,6 +30,7 @@ Accepted values are: * `get-file` * `execute` * `upload` +* `scan` | |`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 925f376990..f4d6e81d6c 100644 --- a/docs/management/api/management-api-index.asciidoc +++ b/docs/management/api/management-api-index.asciidoc @@ -13,6 +13,7 @@ include::running-procs-api.asciidoc[] include::get-file-api.asciidoc[] include::execute-api.asciidoc[] include::upload-api.asciidoc[] +include::scan-api.asciidoc[] include::trusted-apps-api.asciidoc[] include::event-filters-api.asciidoc[] include::host-isolation-exceptions-api.asciidoc[] diff --git a/docs/management/api/running-procs-api.asciidoc b/docs/management/api/running-procs-api.asciidoc index a360157d1e..0f351b7d1c 100644 --- a/docs/management/api/running-procs-api.asciidoc +++ b/docs/management/api/running-procs-api.asciidoc @@ -3,7 +3,7 @@ Get processes on a host running {elastic-defend}. -You must have the *Process Operations* <> and at least an Enterprise license to perform this action. +You must have the *Process Operations* <> and an Enterprise license to perform this action. ==== Request URL @@ -37,7 +37,7 @@ POST /api/endpoint/action/running_procs Indicates a successful call. `403`:: - Indicates insufficient user privilege (*Process Operations* required), or unsupported license level (minimum Enterprise license required). + Indicates insufficient user privilege (*Process Operations* required), or unsupported license level (Enterprise license required). `500`:: General error. A response message will provide additional details. diff --git a/docs/management/api/scan-api.asciidoc b/docs/management/api/scan-api.asciidoc new file mode 100644 index 0000000000..49f522bfb5 --- /dev/null +++ b/docs/management/api/scan-api.asciidoc @@ -0,0 +1,89 @@ +[[scan-api]] +=== Scan a file or folder + +Scan a file or folder for malware on a host running {elastic-defend}. + +You must have the `Scan Operations` {kib} privilege in the Security feature as part of your role and an Enterprise license to perform this action. + +==== Request URL + +`POST :/api/endpoint/action/scan` + +==== Request body + +A JSON object with these fields: + +[width="100%",options="header"] +|============================================== +include::_response-actions-api-reusable-content.asciidoc[tags=create-response-actions-api-common-body-options-row-content] + +|`parameters.path` |String |The folder or file’s full path (including the file name). |Yes +|============================================== + + +===== Example requests + +Scan a file `/usr/my-file.txt` on a host with an `endpoint_id` value of `ed518850-681a-4d60-bb98-e22640cae2a8` and comment `Scan the file for malware`: + +[source,sh] +-------------------------------------------------- +POST /api/endpoint/action/scan +{ + "endpoint_ids": ["ed518850-681a-4d60-bb98-e22640cae2a8"], + "parameters": { + "path": "/usr/my-file.txt", + }, + "comment": "Scan the file for malware" +} +-------------------------------------------------- + + +===== Response code + +`200`:: + Indicates a successful call. + +`403`:: + Indicates insufficient user privilege (*Scan Operations* required), or unsupported license level (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" + } + }, + "agentType": "endpoint", + "command": "scan", + "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/suspend-process-api.asciidoc b/docs/management/api/suspend-process-api.asciidoc index cada0ba3cd..a3084360fa 100644 --- a/docs/management/api/suspend-process-api.asciidoc +++ b/docs/management/api/suspend-process-api.asciidoc @@ -3,7 +3,7 @@ Suspend a process on a host running {elastic-defend}. -You must have the *Process Operations* <> and at least an Enterprise license to perform this action. +You must have the *Process Operations* <> and an Enterprise license to perform this action. ==== Request URL @@ -46,7 +46,7 @@ POST /api/endpoint/action/suspend_process Indicates a successful call. `403`:: - Indicates insufficient user privilege (*Process Operations* required), or unsupported license level (minimum Enterprise license required). + Indicates insufficient user privilege (*Process Operations* required), or unsupported license level (Enterprise license required). `500`:: General error. A response message will provide additional details. diff --git a/docs/management/api/upload-api.asciidoc b/docs/management/api/upload-api.asciidoc index 11add1a8bf..ec1a0b4995 100644 --- a/docs/management/api/upload-api.asciidoc +++ b/docs/management/api/upload-api.asciidoc @@ -3,7 +3,7 @@ Upload a file to 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. +You must have the `File Operations` {kib} privilege in the Security feature as part of your role and an Enterprise license to perform this action. ==== Request URL @@ -47,7 +47,7 @@ curl -X POST "api/endpoint/action/upload" \ Indicates a successful call. `403`:: - Indicates insufficient privileges, or unsupported license level (minimum Enterprise license required). + Indicates insufficient user privilege (*File Operations* required), or unsupported license level (Enterprise license required). ==== Response payload