Retrieve Evidence API

Last updated
Save as PDF

Advanced DLP: Save Shadow/Web DLP Evidence (an advanced DLP capability) requires additional entitlement. Contact Skyhigh Support or your account manager for assistance.

Using the Retrieve Evidence API, you can download saved evidence files or match highlight files associated with an incident. Each evidence file has a maximum limit of 150 MB. The files are retrieved from your configured Data Storage, decrypted, and returned. For details on saving the evidence files, see Save Shadow/Web DLP Evidence and Match Highlights.

NOTE: You can also download evidence files and view match highlights linked to DLP incidents individually from the Shadow/Web DLP Policy Incident Cloud Card on the Policy Incidents page. For details, see Download Shadow/Web DLP Evidence and View Match Highlights for Shadow/Web DLP Incidents.

API Location

The API expects a GET request to retrieve_evidence endpoint. Depending on your tenant's location, use the following URLs:

The API endpoint is as follows:

GET /evidence/v1/evidence

Authentication

Authentication is required to use the API. The authentication shall be an IAM v2.0 token obtained from iam.skyhigh.cloud:

URL Example: https://iam.skyhigh.cloud/iam/v2/token.

The token obtained will then be supplied to the API as an HTTP header: Authorization: Bearer TOKEN.

Headers

Some additional headers may be supplied to help.

Header name	Required	Description
X-RequestID	No	Optional header. The string supplied will be sanitized and used in the system logging to facilitate tracking throughout the system.

Query Parameters

Parameter Name	Description
tenant	The ID of the tenant on behalf of whom the request is being made. This needs to match the tenant from the IAM token.
ObjectID	Identifier of the object within the cloud storage location. The client must ensure the ID is correctly URL-encoded. This is obtainable from the incident.

Responses

Success

On successfully obtaining the evidence file from the customer storage location and decrypting the data, the system shall respond with:

200 OK

The body of the response will be of type application/octet-stream and contain the decrypted data.

Sample Request

GET /evidence/v1/retrieve_evidence?tenant=fbd752c4-f939-1037-9f75-
69bb489d9a5a&ObjectID=6%2Fe%2Ff%2Fs_3c31_3f46_36a06eff_8297_4137_a8d1_f83d8fbcd341-body.rtf.dlpenc 
Authorization:Bearer eyJ0eXAiOiJKV1QiLCJhbGciOiJSUzI1NiIsIng1dCI6Im5ETVpoQkV0bmpZcnlPbU00M1ByYnJITmlKSSIsImtpZCI6Im5ETVpoQkV0bmpZcnl
PbU00M1ByYnJITmlKSSJ9.eyJuYmYiOjE2NzI4MzgzNTAsImV4cCI6MTY3MjgzODk2MCwiY2xpZW50X2lkIjoic1NiSDJXaGJnZHRSRW9CUW1QMXE5b1FRWiIsInN1YiI6InNT
YkgyV2hiZ2R0UkVvQlFtUDFxOW9RUVoiLCJpc3MiOiJodHRwczovL3ByZXByb2QuaWFtLm1jYWZlZS1jbG91ZC5jb20vaWFtL3YxLjAiLCJ0Z
W5hbnRfaWQiOiIwMDAwMDAwMC0wMDAwLTAwMDAtMDAwMC0wMDAwMDAwMDAwMDAiLCJjbGllbnRfdHlwZSI6IkR4bFN0cmVhbWluZ1VzZXIiLCJhdWQiOiJtY2FmZWUiL
CJzY29wZSI6ImR4bHMuZXZ0LnciLCJ0b2tlbl9pZCI6ImRUbnNxd1pkdjNfWVp3MUdYaFBEVERPME0ifQ.27aEqZPZf5JCUmD3wH645ruzupqUE-RqlV0z7EPJemzws-
FANUlwhRZsqy9aTDSbymdkNhSBfH-Cz638bqusQzlPUfLW63HFc3xKLN2sVyCYrjBFxI8WzNZRKLjPGCqKmUB9lVs096HtzZZD3m4bmg7jDTminfds9LJNF9BFosmorAB11icidQCr
7rkSukBdWPzBC7DJXHIDERzi8dufS7vZLJZ2ybetMBSDQqzgk1VLZSMhc645frzvIitMgD28y7Cu1XfEz3Qa9yhBj13O7W95aDRgf6Uo6PuuU5gi-I-bDEPlpH7tbZFiNF7-6zpKcS
EDtHWtLoJYQIVjPe7SAA
X-RequestID:2006-08-14T02:34:56-06:00

Sample Response

200 OK 
Date:2006-08-14T02:34:56-06:00 
Connection:Close 
X-RequestID:2006-08-14T02:34:56-06:00 
Content-Type:application/octect-stream
 
Here is my decrypted evidence

Error Schema

Errors return a document of Content-Type: application/json containing additional information about the error.

{ 
    “error”:“string”, 
    “message”:“string” 
}

Attribute Name	Description
error	String enum representing the error. All enum values TBD but may include BUCKET_REMOVED, BUCKET_PERMISSIONS, BAD_OR_MISSING_HEADER.
message	Descriptive message about the error designed to be human-readable.

HTTP Error Codes

Code	Response	Description
400	Bad Request	For example, missing required parameter.
401	Unauthorized	Client authentication is missing or invalid.
403	Forbidden	The client lacks sufficient authority to retrieve the requested resource.
404	Not Found	The requested object was not found.
500	Internal Server Error	Something went wrong when processing the request.
502	Bad Gateway	An upstream server e.g. AWS returned an unexpected response.
504	Gateway Timeout	An upstream server e.g. AWS S3 did not respond in a timely manner.