Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

[8.13] [8.13] Update Response Actions APIs as a result of introducing agentType (backport #4853) #4856

Merged
merged 3 commits into from
Mar 13, 2024
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
7 changes: 7 additions & 0 deletions docs/management/api/_common-reusable-content.asciidoc
Original file line number Diff line number Diff line change
@@ -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[]
Original file line number Diff line number Diff line change
@@ -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[]
9 changes: 4 additions & 5 deletions docs/management/api/execute-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
1 change: 1 addition & 0 deletions docs/management/api/get-action-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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",
Expand Down
7 changes: 2 additions & 5 deletions docs/management/api/get-file-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
|==============================================

Expand Down Expand Up @@ -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,
Expand Down
11 changes: 2 additions & 9 deletions docs/management/api/host-isolation-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
10 changes: 2 additions & 8 deletions docs/management/api/host-isolation-release-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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

Expand Down Expand Up @@ -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,
Expand Down
7 changes: 2 additions & 5 deletions docs/management/api/kill-process-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
|==============================================
Expand Down Expand Up @@ -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,
Expand Down
12 changes: 12 additions & 0 deletions docs/management/api/list-actions-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
|
|==============================================

Expand Down Expand Up @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand All @@ -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",
Expand Down
10 changes: 2 additions & 8 deletions docs/management/api/running-procs-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
Expand Down Expand Up @@ -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,
Expand Down
7 changes: 2 additions & 5 deletions docs/management/api/suspend-process-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
|==============================================
Expand Down Expand Up @@ -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,
Expand Down
7 changes: 2 additions & 5 deletions docs/management/api/upload-api.asciidoc
Original file line number Diff line number Diff line change
Expand Up @@ -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
|==============================================
Expand Down Expand Up @@ -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,
Expand Down