-
Notifications
You must be signed in to change notification settings - Fork 180
Commit
This commit does not belong to any branch on this repository, and may belong to a fork outside of the repository.
[Upload] Documentation for the
upload
response action api (#3520)
* Documentation for the `upload` response action api * adjust command example * adjust example to `sh` instead of `console` * adjust example to `source,shell` * fix example * Apply suggestions from code review (Joe) Co-authored-by: Joe Peeples <[email protected]> --------- Co-authored-by: Joe Peeples <[email protected]>
- Loading branch information
1 parent
c39c016
commit c260bda
Showing
2 changed files
with
99 additions
and
0 deletions.
There are no files selected for viewing
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Original file line number | Diff line number | Diff line change |
---|---|---|
@@ -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 <kibana host>:<port>/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 "[email protected]" <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 | ||
} | ||
} | ||
} | ||
-------------------------------------------------- |