[8.13] Update Response Actions APIs as a result of introducing `agent…

…Type` (#4853) * Add `agentType` property to get Action details API response example * Update all create response action API's to include `agentType` as part of the request body * update to list actions api * Apply suggestions from code review Co-authored-by: natasha-moore-elastic <[email protected]> --------- Co-authored-by: natasha-moore-elastic <[email protected]> (cherry picked from commit 98c607a)
elastic · Feb 23, 2024 · aa63bcb · aa63bcb
1 parent eed82cc
commit aa63bcb
Show file tree

Hide file tree

Showing 12 changed files with 57 additions and 50 deletions.
diff --git a/docs/management/api/_common-reusable-content.asciidoc b/docs/management/api/_common-reusable-content.asciidoc
@@ -0,0 +1,7 @@
+
+// tag::agent-type-accepted-values[]
+Accepted values are:
+
+* `endpoint` (default)
+* `sentinel_one` (currently in Technical Preview)
+// end::agent-type-accepted-values[]
diff --git a/docs/management/api/_response-actions-api-reusable-content.asciidoc b/docs/management/api/_response-actions-api-reusable-content.asciidoc
@@ -0,0 +1,19 @@
+
+// tag::create-response-action-api-common-body-options[]
+[width="100%",options="header"]
+|==============================================
+// tag::create-response-actions-api-common-body-options-row-content[]
+|Name |Type |Description |Required
+
+
+|`endpoint_ids` |Array (String) |The IDs of endpoints where you want to issue this action. |Yes
+|`agent_type` |String a|The type of Agent that the host is running with.
+include::_common-reusable-content.asciidoc[tags=agent-type-accepted-values]
+|No
+|`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
+
+// end::create-response-actions-api-common-body-options-row-content[]
+|==============================================
+// end::create-response-action-api-common-body-options[]
diff --git a/docs/management/api/execute-api.asciidoc b/docs/management/api/execute-api.asciidoc
@@ -15,16 +15,14 @@ A JSON object with these fields:
 
 [width="100%",options="header"]
 |==============================================
-|Name |Type |Description |Required
+include::_response-actions-api-reusable-content.asciidoc[tags=create-response-actions-api-common-body-options-row-content]
 
-|`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` |Integer |The duration, in seconds, that the host waits for the command to complete. If no timeout is specified, it defaults to four hours. |No
+
 |==============================================
 
+
 NOTE: The `execute` action uploads a text file containing the results of the execution on the endpoint, which is rate-limited.  If you are using the `endpoint_ids` field to task multiple endpoints, you should batch your calls in groups of 10 at a time.
 
 ===== Example requests
@@ -72,6 +70,7 @@ A JSON object with the details of the response action created.
         "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
       }
     },
+    "agentType": "endpoint",
     "command": "execute",
     "startedAt": "2023-07-28T18:43:27.362Z",
     "isCompleted": false,

diff --git a/docs/management/api/get-action-api.asciidoc b/docs/management/api/get-action-api.asciidoc
@@ -32,6 +32,7 @@ GET /api/endpoint/action/fr518850-681a-4y60-aa98-e22640cae2b8
         "agents": [
             "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
         ],
+        "agentType": "endpoint",
         "command": "running-processes",
         "startedAt": "2022-08-08T15:24:57.402Z",
         "completedAt": "2022-08-08T09:50:47.672Z",

diff --git a/docs/management/api/get-file-api.asciidoc b/docs/management/api/get-file-api.asciidoc
@@ -15,12 +15,8 @@ A JSON object with these fields:
 
 [width="100%",options="header"]
 |==============================================
-|Name |Type |Description |Required
+include::_response-actions-api-reusable-content.asciidoc[tags=create-response-actions-api-common-body-options-row-content]
 
-|`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
 |==============================================
 
@@ -69,6 +65,7 @@ A JSON object with the details of the response action created.
         "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
       }
     },
+    "agentType": "endpoint",
     "command": "get-file",
     "startedAt": "2023-07-28T19:00:03.911Z",
     "isCompleted": false,

diff --git a/docs/management/api/host-isolation-api.asciidoc b/docs/management/api/host-isolation-api.asciidoc
@@ -15,15 +15,7 @@ Isolates a host running {elastic-defend} from the network.
 
 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 isolated event 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
-|==============================================
+include::_response-actions-api-reusable-content.asciidoc[tags=create-response-action-api-common-body-options]
 
 
 ===== Example requests
@@ -96,6 +88,7 @@ A JSON object with an `id` that refers to the submitted action.
     "id": "233db9ea-6733-4849-9226-5a7039c7161d",
     "agents": ["ed518850-681a-4d60-bb98-e22640cae2a8"],
     "command": "suspend-process",
+    "agentType": "endpoint",
     "isExpired": false,
     "isCompleted": true,
     "wasSuccessful": true,

diff --git a/docs/management/api/host-isolation-release-api.asciidoc b/docs/management/api/host-isolation-release-api.asciidoc
@@ -15,15 +15,8 @@ You must have the *Host Isolation* <<endpoint-management-req,privilege>> to perf
 
 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 released event will be logged in 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 |Attaches a comment to this action's log. The comment text will appear in associated cases. |No
-|==============================================
+include::_response-actions-api-reusable-content.asciidoc[tags=create-response-action-api-common-body-options]
 
 ===== Example requests
 
@@ -98,6 +91,7 @@ A JSON object with an `id` that refers to the submitted action.
     "id": "233db9ea-6733-4849-9226-5a7039c7161d",
     "agents": ["ed518850-681a-4d60-bb98-e22640cae2a8"],
     "command": "suspend-process",
+    "agentType": "endpoint",
     "isExpired": false,
     "isCompleted": true,
     "wasSuccessful": true,

diff --git a/docs/management/api/kill-process-api.asciidoc b/docs/management/api/kill-process-api.asciidoc
@@ -15,12 +15,8 @@ A JSON object with these fields:
 
 [width="100%",options="header"]
 |==============================================
-|Name |Type |Description |Required
+include::_response-actions-api-reusable-content.asciidoc[tags=create-response-actions-api-common-body-options-row-content]
 
-|`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.pid` |Number |The process ID (PID) of the process to terminate. |Yes, must provide either `parameters.pid` or `parameters.entity_id`, but not both
 |`parameters.entity_id` |String |The entity ID of the process to terminate. |Yes, must provide either `parameters.pid` or `parameters.entity_id`, but not both
 |==============================================
@@ -68,6 +64,7 @@ A JSON object with an `id` that refers to the submitted action.
     "id": "233db9ea-6733-4849-9226-5a7039c7161d",
     "agents": ["ed518850-681a-4d60-bb98-e22640cae2a8"],
     "command": "kill-process",
+    "agentType": "endpoint",
     "isExpired": false,
     "isCompleted": true,
     "wasSuccessful": true,

diff --git a/docs/management/api/list-actions-api.asciidoc b/docs/management/api/list-actions-api.asciidoc
@@ -36,7 +36,15 @@ Accepted values are:
 |`userIds` |string[] |A list of user IDs. |
 |`startDate` |string |A start date in ISO format or {ref}/common-options.html#date-math[Date Math format]. |
 |`endDate` |string |An end date in ISO format or {ref}/common-options.html#date-math[Date Math format]. |
+|`agentTypes`|string or string[] a|List of agent types to retrieve.
+include::_common-reusable-content.asciidoc[tags=agent-type-accepted-values]
+|
+|`withOutputs` |string or string[] |A list of action IDs that should include the complete output of the action.
+|
+|`types` |string or string[] a|A list of action types. Valid values are:
 
+* `automated`: Actions that were triggered from rules
+* `manual`: Actions that were triggered manually via API
 |
 |==============================================
 
@@ -85,6 +93,7 @@ GET /api/endpoint/action?agentIds=a123&agentIds=b456&commands=isolate&commands=k
                 "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
             ],
             "command": "running-processes",
+            "agentType": "endpoint",
             "startedAt": "2022-08-08T15:24:57.402Z",
             "isCompleted": true,
             "completedAt": "2022-08-08T09:50:47.672Z",
@@ -98,6 +107,7 @@ GET /api/endpoint/action?agentIds=a123&agentIds=b456&commands=isolate&commands=k
                 "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
             ],
             "command": "isolate",
+            "agentType": "endpoint",
             "startedAt": "2022-08-08T15:23:37.359Z",
             "isCompleted": true,
             "completedAt": "2022-08-08T10:41:57.352Z",
@@ -111,6 +121,7 @@ GET /api/endpoint/action?agentIds=a123&agentIds=b456&commands=isolate&commands=k
                 "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
             ],
             "command": "kill-process",
+            "agentType": "endpoint",
             "startedAt": "2022-08-08T14:38:44.125Z",
             "isCompleted": true,
             "completedAt": "2022-08-08T09:44:50.952Z",
@@ -125,6 +136,7 @@ GET /api/endpoint/action?agentIds=a123&agentIds=b456&commands=isolate&commands=k
                 "afdc366c-e2e0-4cdb-ae1d-94575bd2d8e0"
             ],
             "command": "unisolate",
+            "agentType": "endpoint",
             "startedAt": "2022-08-08T14:38:15.391Z",
             "isCompleted": true,
             "completedAt": "2022-08-08T09:40:47.398Z",

diff --git a/docs/management/api/running-procs-api.asciidoc b/docs/management/api/running-procs-api.asciidoc
@@ -13,15 +13,8 @@ You must have the *Process Operations* <<endpoint-management-req,privilege>> and
 
 A JSON object with these fields:
 
-[width="100%",options="header"]
-|==============================================
-|Name |Type |Description |Required
+include::_response-actions-api-reusable-content.asciidoc[tags=create-response-action-api-common-body-options]
 
-|`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
-|==============================================
 
 
 ===== Example requests
@@ -62,6 +55,7 @@ A JSON object with an `id` that refers to the submitted action.
     "id": "233db9ea-6733-4849-9226-5a7039c7161d",
     "agents": ["ed518850-681a-4d60-bb98-e22640cae2a8"],
     "command": "running-processes",
+    "agentType": "endpoint",
     "isExpired": false,
     "isCompleted": true,
     "wasSuccessful": true,

diff --git a/docs/management/api/suspend-process-api.asciidoc b/docs/management/api/suspend-process-api.asciidoc
@@ -15,12 +15,8 @@ A JSON object with these fields:
 
 [width="100%",options="header"]
 |==============================================
-|Name |Type |Description |Required
+include::_response-actions-api-reusable-content.asciidoc[tags=create-response-actions-api-common-body-options-row-content]
 
-|`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.pid` |Number |The process ID (PID) of the process to suspend. |Yes, must provide either `parameters.pid` or `parameters.entity_id`, but not both
 |`parameters.entity_id` |String |The entity ID of the process to suspend. |Yes, must provide either `parameters.pid` or `parameters.entity_id`, but not both
 |==============================================
@@ -68,6 +64,7 @@ A JSON object with an `id` that refers to the submitted action.
     "id": "233db9ea-6733-4849-9226-5a7039c7161d",
     "agents": ["ed518850-681a-4d60-bb98-e22640cae2a8"],
     "command": "suspend-process",
+    "agentType": "endpoint",
     "isExpired": false,
     "isCompleted": true,
     "wasSuccessful": true,

diff --git a/docs/management/api/upload-api.asciidoc b/docs/management/api/upload-api.asciidoc
@@ -18,12 +18,8 @@ A `multipart/form-data` with the following:
 
 [width="100%",options="header"]
 |==============================================
-|Name |Type |Description |Required
+include::_response-actions-api-reusable-content.asciidoc[tags=create-response-actions-api-common-body-options-row-content]
 
-|`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 history log. The comment text will appear in associated cases. |No
 |`parameters.overwrite` |Boolean |Overwrite the file on the host if it already exists. |No
 |`file` |Stream |The file content to be uploaded. |Yes
 |==============================================
@@ -73,6 +69,7 @@ A JSON object with the details of the response action created.
       }
     },
     "command": "upload",
+    "agentType": "endpoint",
     "startedAt": "2023-07-03T15:07:22.837Z",
     "isCompleted": false,
     "wasSuccessful": false,