This documentation contains work-in-progress information for future Elastic Stack and Cloud releases. Use the version selector to view supported release docs. It also contains some Elastic Cloud serverless information. Check out our serverless docs for more details.

« Upload file to host Trusted applications »

› › ›

Scan a file or folder

edit

Scan a file or folder

edit

Scan a file or folder for malware on a host running Elastic Defend.

You must have the Scan Operations Kibana privilege in the Security feature as part of your role and an Enterprise license to perform this action.

Request URL

edit

POST <kibana host>:<port>/api/endpoint/action/scan

Request body

edit

A JSON object with these fields:

Name	Type	Description	Required
`endpoint_ids`	Array (String)	The IDs of endpoints where you want to issue this action.	Yes
`agent_type`	String	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
`parameters.path`	String	The folder or file’s full path (including the file name).	Yes

Example requests

edit

Scan a file /usr/my-file.txt on a host with an endpoint_id value of ed518850-681a-4d60-bb98-e22640cae2a8 and comment Scan the file for malware:

POST /api/endpoint/action/scan
{
  "endpoint_ids": ["ed518850-681a-4d60-bb98-e22640cae2a8"],
  "parameters": {
    "path": "/usr/my-file.txt",
  },
  "comment": "Scan the file for malware"
}

Response code

edit

200: Indicates a successful call.
403: Indicates insufficient user privilege (Scan Operations required), or unsupported license level (Enterprise license required).

Response payload

edit

A JSON object with the details of the response action created.

Example response

edit

{
  "data": {
    "id": "27ba1b42-7cc6-4e53-86ce-675c876092b2",
    "agents": [
      "ed518850-681a-4d60-bb98-e22640cae2a8"
    ],
    "hosts": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "name": "gke-endpoint-gke-clu-endpoint-node-po-e1a3ab89-4c4r"
      }
    },
    "agentType": "endpoint",
    "command": "scan",
    "startedAt": "2023-07-28T19:00:03.911Z",
    "isCompleted": false,
    "wasSuccessful": false,
    "isExpired": false,
    "status": "pending",
    "outputs": {},
    "agentState": {
      "ed518850-681a-4d60-bb98-e22640cae2a8": {
        "isCompleted": false,
        "wasSuccessful": false
      }
    },
    "createdBy": "myuser",
    "parameters": {
      "path": "/usr/my-file.txt"
    }
  }
}

« Upload file to host Trusted applications »