Get a File Reputation
Endpoint URL: https://sage.cybereason.com/rest/classification_v1/file_batch
Endpoint URI: classification_v1/file_batch
Action: POST
Returns details on a file’s reputation based on the Cybereason threat intelligence service.
Request Headers
You must add an Content-Type:application/json header with the request.
Note
If you are using cURL, add the authorization cookie details or the path to the file with cookie details with every request.
Request Body
Input: JSON
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
{
"requestData": [
{
"requestKey": {
"md5": "<file hash value>"
}
}
]
}
Request Parameters
URL/URI parameters: none
Request Body Parameters: The request contains the following fields/parameters:
Parameter |
Type |
Description |
---|---|---|
requestData |
Array |
An object that holds the list of items about which to return file reputation data. |
requestKey |
Array |
An object containing the file hash value on which you want to view threat intelligence data. You must add an md5 or sha1 field in this object. |
md5 |
String |
The md5 value of the file on which you want threat intelligence data. |
sha1 |
String |
The sha1 value of the file on which you want threat intelligence data. |
Response Status Code
This request can return the following status codes:
200: Success OK or an error message saying why
Response Success Schema
The response contains the following fields:
Field |
Type |
Description |
---|---|---|
classificationResponses |
Array |
An object containing details on the file reputation. |
requestKey |
Array |
An array containing md5 and/or sha1 file hash values for the requested files. |
sha1 |
String |
The sha1 hash value for the requested file. |
md5 |
String |
The md5 hash value for the requested file. |
ttl |
Integer |
Timestamp representing time the data is live. |
aggregatedClassification |
Array |
An object containing the classification details on the file requested. |
maliciousClassification |
Array |
An object containing malicious classification details on the file requested. |
type |
Enum |
The malicious classification type for the file. Possible values include:
|
classificationScore |
Integer |
The internal numerical value used by the Cybereason threat intelligence service to evaluate the malicious nature of an indicator. A score of -1 indicates a suspicious or malicious classification. |
typeScore |
Integer |
The internal numerical value used by the Cybereason threat intelligence service for the type assigned to the file. |
productClassification |
Array |
An object containing details on the product classification of the product that created the file. |
productType |
Enum |
The type of product that created the file. If there is no value found for this field the object and field is not included in the response. Possible values include:
|
type |
String |
The type of product. |
title |
String |
The title of the program that created the file. |
manufacturer |
String |
The company that produces the program that created the file. |
signatureVerified |
Boolean |
Indicates if the signature of the file was verified and known as legitimate. |
externalSignatureVerificationStatus |
Enum |
The status of the signature verification. Possible values include: |
link |
String |
The link to the source of the threat intelligence that provides the reputation for this file. |
lastUploadTimestamp |
Integer |
A timestamp (in epoch) when the information was last updated on the Threat Intel Server. |
Response Failure Schema
None
Important Response Fields
Important information is found in these fields:
classificationResponses object: An object containing details on all the file hashes you entered in the request body. Ensure there are entries in this object for each of the file hashes.
sha1: The sha1 file hash value for the file. This field may report null if there is not a parallel sha1 hash value for each md5 hash value.
md5: The md5 hash value for the file. This field may report null if there is not a parallel md5 hash value for each sha1 hash value.
type: The classification of the file based on the file hash.
productType: The type of product for which this file is used. The classification for the product is taken from the Cybereason platform’s product classification database.
title: The title of the program which uses the file as presented to users on the machine.
signatureVerified: Indicates whether or not the image file for the program which uses the file is signed.
signed: Indicates whether the file is signed.
link:** A link to learn more about the file classification.
Example: Get the reputation for a file
Request
curl --request POST \
--url https://sage.cybereason.com/rest/classification_v1/file_batch \
--header 'Content-Type:application/json'
--data '{
"requestData": [
{
"requestKey": {
"md5": "92f44e405db16ac55d97e3bfe3b132fa"
}
}
]
}'
Response
{
"classificationResponses": [
{
"requestKey": {
"sha1": null,
"md5": "92f44e405db16ac55d97e3bfe3b132fa"
},
"ttl": 62957583,
"aggregatedResult": {
"maliciousClassification": {
"type": "indifferent",
"classificationScore": -1,
"typeScore": -1
},
"productClassification": {
"productType": "SHELL",
"type": "SHELL",
"title": "Power Shell",
"manufacturer": "Microsoft Windows",
"signatureVerified": true,
"externalSignatureVerificationStatus": "SIGNATURE_VERIFICATION_STATUS_SUCCESS",
"signed": true
},
"link": "https://www.virustotal.com/file/6c05e11399b7e3c8ed31bae72014cf249c144a8f4a2c54a758eb2e6fad47aec7/analysis/1533661076/"
}
}
]
}
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
Use this request body:
{
"requestData": [
{
"requestKey": {
"md5": "92f44e405db16ac55d97e3bfe3b132fa"
}
}
]
}
Response
{
"classificationResponses": [
{
"requestKey": {
"sha1": null,
"md5": "92f44e405db16ac55d97e3bfe3b132fa"
},
"ttl": 62957583,
"aggregatedResult": {
"maliciousClassification": {
"type": "indifferent",
"classificationScore": -1,
"typeScore": -1
},
"productClassification": {
"productType": "SHELL",
"type": "SHELL",
"title": "Power Shell",
"manufacturer": "Microsoft Windows",
"signatureVerified": true,
"externalSignatureVerificationStatus": "SIGNATURE_VERIFICATION_STATUS_SUCCESS",
"signed": true
},
"link": "https://www.virustotal.com/file/6c05e11399b7e3c8ed31bae72014cf249c144a8f4a2c54a758eb2e6fad47aec7/analysis/1533661076/"
}
}
]
}
Request
Depending on your browser settings, this linked file may open in a separate tab instead of downloading directly to your machine. If this happens, use the Save As option in your browser to save the file locally.
import requests
import json
session = requests.session()
# Request URL
sage_url = "https://sage.cybereason.com"
endpoint_url = "/rest/classification_v1/file_batch"
api_url = sage_url + endpoint_url
# These are the variables that represent different fields in the request.
file_hash = "92f44e405db16ac55d97e3bfe3b132fa"
query = json.dumps({"requestData":[{"requestKey":{"md5":file_hash}}]})
api_headers = {'Content-Type':'application/json'}
api_response = session.request("POST", api_url, data=query, headers=api_headers)
your_response = json.loads(api_response.content)
print(json.dumps(your_response, indent=4, sort_keys=True))
Response
{
"classificationResponses": [
{
"requestKey": {
"sha1": null,
"md5": "92f44e405db16ac55d97e3bfe3b132fa"
},
"ttl": 62957583,
"aggregatedResult": {
"maliciousClassification": {
"type": "indifferent",
"classificationScore": -1,
"typeScore": -1
},
"productClassification": {
"productType": "SHELL",
"type": "SHELL",
"title": "Power Shell",
"manufacturer": "Microsoft Windows",
"signatureVerified": true,
"externalSignatureVerificationStatus": "SIGNATURE_VERIFICATION_STATUS_SUCCESS",
"signed": true
},
"link": "https://www.virustotal.com/file/6c05e11399b7e3c8ed31bae72014cf249c144a8f4a2c54a758eb2e6fad47aec7/analysis/1533661076/"
}
}
]
}