From 75ae27651b930a22c54ac10de7476c9c69e4b66d Mon Sep 17 00:00:00 2001 From: Ashokaditya Date: Tue, 25 Jun 2024 11:47:24 +0200 Subject: [PATCH 1/8] Add `scan` response action API doc for 8.15 closes elastic/security-team/issues/9232 --- .../api/management-api-index.asciidoc | 1 + docs/management/api/scan-api.asciidoc | 89 +++++++++++++++++++ 2 files changed, 90 insertions(+) create mode 100644 docs/management/api/scan-api.asciidoc 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/scan-api.asciidoc b/docs/management/api/scan-api.asciidoc new file mode 100644 index 0000000000..7dc49cb3bc --- /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 on a host running {elastic-defend} for malware. + +You must have the `Scan 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/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 comments `Get my file`: + +[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 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" + } + }, + "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" + } + } +} + +-------------------------------------------------- From 0c9f039a7cc1531cec71283b92eb1fc1fc8d4366 Mon Sep 17 00:00:00 2001 From: Ashokaditya Date: Tue, 25 Jun 2024 11:54:14 +0200 Subject: [PATCH 2/8] Update list-actions-api.asciidoc --- docs/management/api/list-actions-api.asciidoc | 1 + 1 file changed, 1 insertion(+) 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. | From 082e6195458d3dd46f501d4f4b05db47186c946d Mon Sep 17 00:00:00 2001 From: Ashokaditya Date: Tue, 25 Jun 2024 14:15:16 +0200 Subject: [PATCH 3/8] Update scan-api.asciidoc --- docs/management/api/scan-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/management/api/scan-api.asciidoc b/docs/management/api/scan-api.asciidoc index 7dc49cb3bc..5556022e61 100644 --- a/docs/management/api/scan-api.asciidoc +++ b/docs/management/api/scan-api.asciidoc @@ -23,7 +23,7 @@ include::_response-actions-api-reusable-content.asciidoc[tags=create-response-ac ===== Example requests -Scan 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`: +Scan a file `/usr/my-file.txt` on a host with an `endpoint_id` value of `ed518850-681a-4d60-bb98-e22640cae2a8` and comments `Scan the file for malware`: [source,sh] -------------------------------------------------- From d48f7883bfcd5facae8c638c2da4ad62de495e1b Mon Sep 17 00:00:00 2001 From: Ashokaditya Date: Tue, 25 Jun 2024 21:04:48 +0200 Subject: [PATCH 4/8] update license info review changes --- docs/management/api/execute-api.asciidoc | 2 +- docs/management/api/get-file-api.asciidoc | 2 +- docs/management/api/kill-process-api.asciidoc | 2 +- docs/management/api/running-procs-api.asciidoc | 2 +- docs/management/api/scan-api.asciidoc | 2 +- docs/management/api/suspend-process-api.asciidoc | 2 +- docs/management/api/upload-api.asciidoc | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/management/api/execute-api.asciidoc b/docs/management/api/execute-api.asciidoc index 771c2ec897..122c394688 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 diff --git a/docs/management/api/get-file-api.asciidoc b/docs/management/api/get-file-api.asciidoc index 8b5a4152f6..de0cb9a97f 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 diff --git a/docs/management/api/kill-process-api.asciidoc b/docs/management/api/kill-process-api.asciidoc index b2e40bc4e8..cd3131475f 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 diff --git a/docs/management/api/running-procs-api.asciidoc b/docs/management/api/running-procs-api.asciidoc index a360157d1e..9335c97d91 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 diff --git a/docs/management/api/scan-api.asciidoc b/docs/management/api/scan-api.asciidoc index 5556022e61..c895da2cb3 100644 --- a/docs/management/api/scan-api.asciidoc +++ b/docs/management/api/scan-api.asciidoc @@ -3,7 +3,7 @@ Scan a file or folder on a host running {elastic-defend} for malware. -You must have the `Scan 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 `Scan Operations` {kib} privilege in the Security feature as part of your role and an Enterprise license to perform this action. ==== Request URL diff --git a/docs/management/api/suspend-process-api.asciidoc b/docs/management/api/suspend-process-api.asciidoc index cada0ba3cd..e0bbf38f8b 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 diff --git a/docs/management/api/upload-api.asciidoc b/docs/management/api/upload-api.asciidoc index 11add1a8bf..bc302ceb33 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 From 04e4f304206deb1a429400ecb154910c5a11c9ca Mon Sep 17 00:00:00 2001 From: Ash <1849116+ashokaditya@users.noreply.github.com> Date: Thu, 27 Jun 2024 16:23:12 +0200 Subject: [PATCH 5/8] Update docs/management/api/scan-api.asciidoc Co-authored-by: Joe Peeples --- docs/management/api/scan-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/management/api/scan-api.asciidoc b/docs/management/api/scan-api.asciidoc index c895da2cb3..3b6b55a343 100644 --- a/docs/management/api/scan-api.asciidoc +++ b/docs/management/api/scan-api.asciidoc @@ -1,7 +1,7 @@ [[scan-api]] === Scan a file or folder -Scan a file or folder on a host running {elastic-defend} for malware. +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. From 948b1a3597b78f8812658901e533d3830c3c1c2f Mon Sep 17 00:00:00 2001 From: Ash <1849116+ashokaditya@users.noreply.github.com> Date: Thu, 27 Jun 2024 16:23:21 +0200 Subject: [PATCH 6/8] Update docs/management/api/scan-api.asciidoc Co-authored-by: Joe Peeples --- docs/management/api/scan-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/management/api/scan-api.asciidoc b/docs/management/api/scan-api.asciidoc index 3b6b55a343..cb460ae2b3 100644 --- a/docs/management/api/scan-api.asciidoc +++ b/docs/management/api/scan-api.asciidoc @@ -23,7 +23,7 @@ include::_response-actions-api-reusable-content.asciidoc[tags=create-response-ac ===== Example requests -Scan a file `/usr/my-file.txt` on a host with an `endpoint_id` value of `ed518850-681a-4d60-bb98-e22640cae2a8` and comments `Scan the file for malware`: +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] -------------------------------------------------- From 101d357217324e529531cbdd5a78f00aa8b8b4bf Mon Sep 17 00:00:00 2001 From: Ash <1849116+ashokaditya@users.noreply.github.com> Date: Thu, 27 Jun 2024 16:23:42 +0200 Subject: [PATCH 7/8] Update docs/management/api/scan-api.asciidoc Co-authored-by: Joe Peeples --- docs/management/api/scan-api.asciidoc | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/management/api/scan-api.asciidoc b/docs/management/api/scan-api.asciidoc index cb460ae2b3..8a44d90586 100644 --- a/docs/management/api/scan-api.asciidoc +++ b/docs/management/api/scan-api.asciidoc @@ -44,7 +44,7 @@ POST /api/endpoint/action/scan Indicates a successful call. `403`:: - Indicates insufficient privileges, or unsupported license level (minimum Enterprise license required). + Indicates insufficient privileges, or unsupported license level (Enterprise license required). ==== Response payload From 6700fb97ba9b19a07b117f63946c6acae8c88287 Mon Sep 17 00:00:00 2001 From: Ashokaditya Date: Mon, 1 Jul 2024 09:31:31 +0200 Subject: [PATCH 8/8] consistent 403 messages --- docs/management/api/execute-api.asciidoc | 2 +- docs/management/api/get-file-api.asciidoc | 2 +- docs/management/api/kill-process-api.asciidoc | 2 +- docs/management/api/running-procs-api.asciidoc | 2 +- docs/management/api/scan-api.asciidoc | 2 +- docs/management/api/suspend-process-api.asciidoc | 2 +- docs/management/api/upload-api.asciidoc | 2 +- 7 files changed, 7 insertions(+), 7 deletions(-) diff --git a/docs/management/api/execute-api.asciidoc b/docs/management/api/execute-api.asciidoc index 122c394688..5679491581 100644 --- a/docs/management/api/execute-api.asciidoc +++ b/docs/management/api/execute-api.asciidoc @@ -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 de0cb9a97f..4909c554ff 100644 --- a/docs/management/api/get-file-api.asciidoc +++ b/docs/management/api/get-file-api.asciidoc @@ -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 cd3131475f..7709162a04 100644 --- a/docs/management/api/kill-process-api.asciidoc +++ b/docs/management/api/kill-process-api.asciidoc @@ -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/running-procs-api.asciidoc b/docs/management/api/running-procs-api.asciidoc index 9335c97d91..0f351b7d1c 100644 --- a/docs/management/api/running-procs-api.asciidoc +++ b/docs/management/api/running-procs-api.asciidoc @@ -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 index 8a44d90586..49f522bfb5 100644 --- a/docs/management/api/scan-api.asciidoc +++ b/docs/management/api/scan-api.asciidoc @@ -44,7 +44,7 @@ POST /api/endpoint/action/scan Indicates a successful call. `403`:: - Indicates insufficient privileges, or unsupported license level (Enterprise license required). + Indicates insufficient user privilege (*Scan Operations* required), or unsupported license level (Enterprise license required). ==== Response payload diff --git a/docs/management/api/suspend-process-api.asciidoc b/docs/management/api/suspend-process-api.asciidoc index e0bbf38f8b..a3084360fa 100644 --- a/docs/management/api/suspend-process-api.asciidoc +++ b/docs/management/api/suspend-process-api.asciidoc @@ -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 bc302ceb33..ec1a0b4995 100644 --- a/docs/management/api/upload-api.asciidoc +++ b/docs/management/api/upload-api.asciidoc @@ -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