Execute and Get File API documentation (#3653) (#3740)

* Execute and Get File API documentation * PR Comments * pr comments * Update docs/management/api/get-file-api.asciidoc Co-authored-by: natasha-moore-elastic <[email protected]> --------- Co-authored-by: natasha-moore-elastic <[email protected]> (cherry picked from commit 96ae839) Co-authored-by: Kevin Logan <[email protected]>
elastic · Aug 22, 2023 · 46e7e26 · 46e7e26
1 parent e4faae8
commit 46e7e26
Show file tree

Hide file tree

Showing 4 changed files with 193 additions and 0 deletions.
diff --git a/docs/management/api/execute-api.asciidoc 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 <kibana host>:<port>/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
@@ -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 <kibana host>:<port>/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
@@ -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
@@ -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[]