diff --git a/docs/management/api/management-api-index.asciidoc b/docs/management/api/management-api-index.asciidoc index 805fdc9b2d..6abe6cf486 100644 --- a/docs/management/api/management-api-index.asciidoc +++ b/docs/management/api/management-api-index.asciidoc @@ -10,6 +10,7 @@ include::host-isolation-release-api.asciidoc[] include::kill-process-api.asciidoc[] include::suspend-process-api.asciidoc[] include::running-procs-api.asciidoc[] +include::upload-api.asciidoc[] include::trusted-apps-api.asciidoc[] include::event-filters-api.asciidoc[] include::host-isolation-exceptions-api.asciidoc[] diff --git a/docs/management/api/upload-api.asciidoc b/docs/management/api/upload-api.asciidoc new file mode 100644 index 0000000000..c788caa614 --- /dev/null +++ b/docs/management/api/upload-api.asciidoc @@ -0,0 +1,98 @@ +[[upload-api]] +=== Upload file to host + +Upload a file to 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 :/api/endpoint/action/upload` + +The request must include the `Content-Type: multipart/form-data` HTTP header. + + +==== Request body + +A `multipart/form-data` with the following: + +[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 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 +|============================================== + + +===== Example requests + +Upload a file named `fix-malware.sh` to a host with an `endpoint_id` value of `ed518850-681a-4d60-bb98-e22640cae2a8`. It assumes that the file is located in the same directory where the command is being entered: + + +[source,shell] +-------------------------------------------------- +curl -X POST "api/endpoint/action/upload" \ +-H 'kbn-xsrf: true' \ +-H 'Content-Type: multipart/form-data' \ +-F 'endpoint_ids: ["ed518850-681a-4d60-bb98-e22640cae2a8"]' \ +-F "file=@fix-malware.sh" <1> +-------------------------------------------------- +<1> The relative path to the file to upload. Note the path must be preceded with `@`. + + +===== 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": "9ff6aebc-2cb6-481e-8869-9b30036c9731", + "agents": [ + "ed518850-681a-4d60-bb98-e22640cae2a8" + ], + "hosts": { + "ed518850-681a-4d60-bb98-e22640cae2a8": { + "name": "Host-5i6cuc8kdv" + } + }, + "command": "upload", + "startedAt": "2023-07-03T15:07:22.837Z", + "isCompleted": false, + "wasSuccessful": false, + "isExpired": false, + "status": "pending", + "outputs": {}, + "agentState": { + "ed518850-681a-4d60-bb98-e22640cae2a8": { + "isCompleted": false, + "wasSuccessful": false + } + }, + "createdBy": "elastic", + "parameters": { + "file_name": "fix-malware.sh", + "file_id": "10e4ce3d-4abb-4f93-a0cd-eaf63a489280", + "file_sha256": "a0bed94220193ba4895c0aa5b4e7e293381d15765cb164ddf7be5cdd010ae42a", + "file_size": 69 + } + } +} + +--------------------------------------------------