diff --git a/docs/management/api/_common-reusable-content.asciidoc b/docs/management/api/_common-reusable-content.asciidoc new file mode 100644 index 0000000000..93fa7a26e5 --- /dev/null +++ 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 new file mode 100644 index 0000000000..d258c45531 --- /dev/null +++ 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 index f762e8c4da..771c2ec897 100644 --- 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 index e164e27fb4..763203cf97 100644 --- 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 index cc0299f14f..8b5a4152f6 100644 --- 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 index 40fb6a741e..b3e8712ed9 100644 --- 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 index e39a03aa87..3aa39113df 100644 --- 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* <> 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 index 28fac5d1e7..b2e40bc4e8 100644 --- 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 index d6d04539ef..cdad22957e 100644 --- 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 index 132682b4ea..a360157d1e 100644 --- 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* <> 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 index 44e40cc377..cada0ba3cd 100644 --- 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 index c788caa614..11add1a8bf 100644 --- 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,