Endpoint Protection 14 REST API support for deleting or fetching a file based on hash value

book

Article ID: 164858

calendar_today

Updated On:

Products

Endpoint Protection

Issue/Introduction

You want to use REST API commands for Symantec Endpoint Protection and Symantec Advanced Threat Protection to delete or fetch a file based on hash value, but you are not sure what commands to use.

Resolution

For Symantec Endpoint Protection 14 and 14 MP1, you can use REST API commands to files from the client or fetch files from the client to send directly to Advanced Threat Protection (ATP) based on its hash value. The commands can delete portable executable (PE) files, such as .exe and .dll, as well as other files.

Each command supports different hash value types.

For the full REST API documentation, see Symantec Endpoint Protection Manager 14 REST API Reference.

Delete files based on hash value

You can delete files based on the MD5, SHA-1, or SHA-256 hash value. You do not need to indicate a file path.

To delete a file using REST API commands, perform an Evidence of Compromise Scan (search) on the file based on the hash value:

/api/v1/command-queue/eoc

POST (Experimental)

Sends a command from Symantec Endpoint Protection Manager to Symantec Endpoint Protection endpoints to request an "Evidence of Compromise" scan on the endpoint.

Request

Parameters

Name

Located in

Required

Description

Default

Schema

group_ids

query

yes

The list of groups on which to run the command.

-

string

computer_ids

query

yes

The list of computers on which to run the command.

-

string

body

body

yes

The evidence of compromise command in XML. See the example below for the proper format.

-

 

body

body

no

 

-

HttpServletRequest

Include <RemediationAction>REMEDIATE</RemediationAction> in the body of the command to automatically take action, depending on the Symantec Endpoint Protection Manager / client policy.

Example:

<EOC creator="Creator" version="1.1" id="60">
<DataSource name="Third-Party Provider" id="23" version="1.0"/>
<ScanType>FULL_SCAN</ScanType>
<RemediationAction>REMEDIATE</RemediationAction>
<Threat category="Suspects" type="to_investigate" severity="Medium" time="2017-01-29 4:54:01 PM">
<Description>Very basic test to search by hash</Description>
<Attacker></Attacker>
</Threat>
<Activity>
<OS id="1" name="" version="" patch="">
<Process></Process>
<Files>
<File name="suspicious_1" action="write">
<Hash name="SHA1" value="3c6250da5edf6b2e8d1a3930aa97a444bf3ba3de"/>
</File>
<File name="suspicious_2" action="write">
<Hash name="SHA1" value="374a884f7b650276df98bfde7d7efdaa6c4da27b"/>
</File>
</Files>
<Registry></Registry>
<Network></Network>
</OS>
</Activity>
</EOC>

Note: To delete a file based on the SHA-1 hash value, you must first run a full Power Eraser scan.

Fetch files based on hash value

You can fetch files based on the MD5 or SHA-256 hash value. You must provide the full file path.

To fetch a file using REST API commands:

  1. Request that the client upload the file:

api/v1/command-queue/files

POST (Experimental)

Sends a command from Symantec Endpoint Protection Manager to Symantec Endpoint Protection endpoints to request a suspicious file be uploaded back to Symantec Endpoint Protection Manager.

Request

Parameters

Name

Located in

Required

Description

Default

Schema

file_path

query

yes

The file path of the suspicious file.

-

string

computer_ids

query

yes

The list of computers on which to search for the suspicious file.

-

string

sha256

query

no

The SHA256 hash value of the suspicious file.

-

string

md5

query

no

The MD5 hash value of the suspicious file.

-

string

source

query

no

The file source from where to search for the suspicious file. Possible values are: FILESYSTEM (default), QUARANTINE, or BOTH.

-

string

body

body

no

 

-

HttpServletRequest

Response

Status Code

Reason

Response Model

200

The web service successfully processed the web request and returned a result.

 

400

The parameters are invalid.

-

401

The user that is currently logged on has insufficient rights to execute the web method, or the user is unauthorized.

-

404

The requested resource was not found.

-

500

The web service encountered an error while processing the web request.

-

  1. Using the following REST API command, get the details of the file with the file ID from Symantec Endpoint Protection Manager:

/api/v1/command-queue/file/{FILE_ID.EN_US}/details

GET (Experimental)

Gets the details of a binary file, such as the checksum and the file size.

Request

Parameters
 

Name

Located in

Required

 

Description

Default

Schema

file_id

path

yes

 

The file ID from which to get detailed information.

-

string

Response

Status Code

Reason

Response Model

200

The web service successfully processed the web request and returned a result.

BinaryFile

400

The parameters are invalid.

-

401

The user that is currently logged on has insufficient rights to execute the web method, or the user is unauthorized.

-

404

The requested resource was not found.

-

410

Cannot find the specified object.

-

500

The web service encountered an error while processing the web request.

-