[8.15] Endpoint API documentation for scan response action (#5476)

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
 

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
 

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* <<endpoint-management-req,privilege>> and at least an Enterprise license to perform this action.
+You must have the *Process Operations* <<endpoint-management-req,privilege>> 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.

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. |

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[]

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* <<endpoint-management-req,privilege>> and at least an Enterprise license to perform this action.
+You must have the *Process Operations* <<endpoint-management-req,privilege>> 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.

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 <kibana host>:<port>/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"
+    }
+  }
+}
+
+--------------------------------------------------

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* <<endpoint-management-req,privilege>> and at least an Enterprise license to perform this action.
+You must have the *Process Operations* <<endpoint-management-req,privilege>> 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.

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