From ba267a40ff692be75008d92582c7bead77dde2fb Mon Sep 17 00:00:00 2001 From: Paul Tavares Date: Thu, 22 Feb 2024 14:14:46 -0500 Subject: [PATCH 1/4] Add `agentType` property to get Action details API response example --- docs/management/api/get-action-api.asciidoc | 1 + 1 file changed, 1 insertion(+) 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", From 383142a2837a88a957cb817ebca27049331ada82 Mon Sep 17 00:00:00 2001 From: Paul Tavares Date: Thu, 22 Feb 2024 14:15:23 -0500 Subject: [PATCH 2/4] Update all create response action API's to include `agentType` as part of the request body --- ...onse-actions-api-reusable-content.asciidoc | 24 +++++++++++++++++++ docs/management/api/execute-api.asciidoc | 9 ++++--- docs/management/api/get-file-api.asciidoc | 7 ++---- .../api/host-isolation-api.asciidoc | 11 ++------- .../api/host-isolation-release-api.asciidoc | 10 ++------ docs/management/api/kill-process-api.asciidoc | 7 ++---- .../management/api/running-procs-api.asciidoc | 10 ++------ .../api/suspend-process-api.asciidoc | 7 ++---- docs/management/api/upload-api.asciidoc | 7 ++---- 9 files changed, 42 insertions(+), 50 deletions(-) create mode 100644 docs/management/api/_response-actions-api-reusable-content.asciidoc 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..7e7eeab1cb --- /dev/null +++ b/docs/management/api/_response-actions-api-reusable-content.asciidoc @@ -0,0 +1,24 @@ + +// 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. Accepted values are: + +* `endpoint` (default) +* `sentinel_one` (currently in Technical Preview) + +|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-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/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, From b06a88af6172c2bb4a61683264e49efad9a21fa6 Mon Sep 17 00:00:00 2001 From: Paul Tavares Date: Thu, 22 Feb 2024 15:41:23 -0500 Subject: [PATCH 3/4] update to list actions api --- .../management/api/_common-reusable-content.asciidoc | 7 +++++++ .../_response-actions-api-reusable-content.asciidoc | 9 ++------- docs/management/api/list-actions-api.asciidoc | 12 ++++++++++++ 3 files changed, 21 insertions(+), 7 deletions(-) create mode 100644 docs/management/api/_common-reusable-content.asciidoc 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 index 7e7eeab1cb..d258c45531 100644 --- a/docs/management/api/_response-actions-api-reusable-content.asciidoc +++ b/docs/management/api/_response-actions-api-reusable-content.asciidoc @@ -7,13 +7,8 @@ |`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. Accepted values are: - -* `endpoint` (default) -* `sentinel_one` (currently in Technical Preview) - +|`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 diff --git a/docs/management/api/list-actions-api.asciidoc b/docs/management/api/list-actions-api.asciidoc index d6d04539ef..5d452dfa21 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", From e95f485807ec1b6271558bfd6a94b36ce36d78c5 Mon Sep 17 00:00:00 2001 From: Paul Tavares <56442535+paul-tavares@users.noreply.github.com> Date: Fri, 23 Feb 2024 08:59:15 -0500 Subject: [PATCH 4/4] Apply suggestions from code review Co-authored-by: natasha-moore-elastic <137783811+natasha-moore-elastic@users.noreply.github.com> --- docs/management/api/list-actions-api.asciidoc | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/docs/management/api/list-actions-api.asciidoc b/docs/management/api/list-actions-api.asciidoc index 5d452dfa21..cdad22957e 100644 --- a/docs/management/api/list-actions-api.asciidoc +++ b/docs/management/api/list-actions-api.asciidoc @@ -41,10 +41,10 @@ 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: +|`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 +* `automated`: Actions that were triggered from rules +* `manual`: Actions that were triggered manually via API | |==============================================