Requests to the threatlookup.com domain will be affiliated to the EU region by default.

Use eu.threatlookup.com or us.threatlookup.com to ensure the data will be processed by servers located in EU or US, respectively.

The Sandbox Analysis Report package provides detection results for known and new advanced threats. It includes static and multiple dynamic analyses of uploaded files in an array of sandboxes. In addition, files that were uploaded and were sent for sandbox analysis will result with a sandbox report and additional artifacts such as PCAP file, dropped files and screenshots produced during the file analysis.

The process consists of three phases:

  1. Hash lookup
  2. File upload
  3. Check hash

Phase 1: Hash lookup request

This type of request can be made using HTTPS GET, supplying an object’s SHA256 hash. Responses are provided in JSON format.

Example of a HTTPS Request Header

GET /v1-1/HASH HTTP/1.1
 
Host: threatlookup.com
 
X-TOKEN-KEY: KEY


Example of curl request

curl -LH "X-TOKEN-KEY: KEY"  "https://threatlookup.com/v1-1/HASH"

Response

Upon receiving a valid request, the service will respond with information about the provided hash:


Response Item

Description

http_status_codeThe http status response to the user's request
response_code

Indicates the status of the request:

  • -1: An issue of some kind
  •  0: Process is ongoing
  •  1: Success
messageA description of what occurred
content

Contains information regarding the hash:

  • category: Threat type, currently they can be 
  • malware: Malicious file
  • pua: Potentially unwanted application
  • Confirmed clean: A known clean file
  • detection: Threat name, as given by Cyren Anti Malware
  • urls: A list of action URLs relevant to the queried hash:
    • upload: Used for uploading a copy of a file
    • sandbox_report: Used to access the sandbox report for the file
    • pcap: Used to access the packet capture artifact
    • dropped_files: Used to access the dropped files
    • screenshots: Used to access the analysis screenshots

Example response to a request for a malicious hash

The following is an example of a response for a hash with leading malicious indications.

{
  "http_status_code": 200,
  "response_code": 1,
  "message": "Accepted",
  "content": {
    "category": "malware",
    "detection": "CVE1711882",
    "urls": {
      "upload": "https://threatlookup.com/v1-1/file/<KEY>/<HASH>,
      "sandbox_report": "https://threatlookup.com/v1-1/<KEY>/<HASH>/resources/r"
    }
  }
}

Example response to a request for a hash which is not detected

The following is an example of a response for a hash with no leading malicious or benevolent indications.

{
  "http_status_code": 200,
  "response_code": 1,
  "message": "Accepted",
  "content": {
    "category": null,
    "detection": "Not detected",
    "urls": {
      "upload": "https://threatlookup.com/v1-1/file/<KEY>/<HASH>,
      "sandbox_report": "https://threatlookup.com/v1-1/<KEY>/<HASH>/resources/r"
    }
  }
}

Example response to a request for a confirmed clean hash

The following is an example of a response for a hash with leading benevolent indications.

{
  "http_status_code": 200,
  "response_code": 1,
  "message": "Accepted",
  "content": {
    "category": "Confirmed clean",
    "detection": null,
    "urls": {
      "upload": "https://threatlookup.com/v1-1/file/<KEY>/<HASH>,
      "sandbox_report": "https://threatlookup.com/v1-1/<KEY>/<HASH>/resources/r"
    }
  }
}

Example response to a request for a hash unknown to Cyren

If the requested hash proves to be unknown, Cyren’s Threat Lookup service will respond with the following: 

{
  "http_status_code": 200,
  "response_code": 1,
  "message": "Accepted",
  "content": {
    "category": null,
    "detection": null,
    "urls": {
      "upload": "https://threatlookup.com/v1-1/file/<KEY>/<HASH>
    }
  }
}


You should use the "upload_sample" URL to upload the file and submit it for further analysis and processing.

The following response codes may be returned:

Descriptionresponse_codehttp_status_codemessage
When user submits invalid sha256-1200Unsupported checksum type
Detection data1200Detection data returned
Sample was already uploaded1200Already uploaded. Process in progress
Non-existent route caught by the routing engine0200API Version x.x, unknown call
When sha256 is missing from the API call-1400Missing or malformed parameters!
SHA256 of the file submitted doesn't match the sha256 submitted through API-1400SHA256 hash mismatch
File delivered to API is empty-1400Empty file! Aborted
Sandbox artifact cannot be displayed due to insufficient permission or wrong ownership-1401Access denied!
Sandbox artifact not found on the file system-1404No such resource found!
Disallowed characters in API call-1404Unknown or malformed call
If any of the backend runs unexpectedly, not caught by the API handlers-1500Internal system error. Contact the system administrator


Phase 2: File upload

Upload File Request

You should use the "upload_sample" URL returned in the hash lookup request to upload a file and submit it for further analysis and processing.

This type of request must be made using HTTPS PUT. The SHA-256 hash must be provided for verifying the integrity, once uploading completes.

Responses are provided in JSON format.

Example of a HTTPS Request Header

PUT /v1-1/file/HASH HTTP/1.1
 
Host: threatlookup.com
 
X-TOKEN-KEY: KEY



Example of curl request

curl -LH "X-TOKEN-KEY: KEY" -X PUT "https://threatlookup.com/v1-1/file/HASH" --data-binary @myfile.exe


Response

Upon receiving a valid request, the service will issue a response with code 200, response code 1 and the message “File transmitted”

Files that were uploaded to the service and weren’t detected by anti-malware heuristics and static analysis will be sent for further sandbox analysis. The multiple sandbox analyses could take up to a few minutes.

A query can be run on the file hash to receive the results. 


Descriptionresponse_codehttp_status_codemessage
When user submits invalid sha256-1200Unsupported checksum type
Sample was already uploaded1200Already uploaded. Process in progress.
Non-existent route caught by the routing engine0200API Version x.x, unknown call.
File was uploaded1200File transmitted

When sha256 is missing from the API call

-1400Missing or malformed parameters!

Sha256 of the file submitted doesn't match the sha256 submitted through API

-1400SHA256 hash mismatch

Empty file was delivered to API

-1400Empty file! Aborted

Disallowed characters in API call.

-1404Unknown or malformed call
Account's upload limit reached, current and subsequent uploads allowed1429File transmitted
Account's upload limit reached, current and subsequent uploads prevented-1429File not transmitted

If any of the backend runs unexpected, not caught by the API handlers.

-1500Internal system error. Contact the system administrator


Phase 3: Check hash

Check hash request

After a file is submitted for analysis, it may take several minutes to get processed. A check hash request can be sent to inquire about the results.

To check the status of the file submitted for analysis, perform the same API call as in the first phase (hash lookup).

Example of a HTTPS Request Header

GET /v1-1/HASH HTTP/1.1
 
Host: threatlookup.com
 
X-TOKEN-KEY: KEY


Example of curl request


curl -LH "X-TOKEN-KEY: KEY"  "https://threatlookup.com/v1-1/HASH


Response

Upon receiving a valid request, the service will respond with information about the provided hash:

Response Item

Description

http_status_codeThe http status response to the user's request
response_code

Indicates the status of the request:

  • -1: An issue of some kind
  •  0: Process is ongoing
  •  1: Success
messageA description of what occurred
content

Contains information regarding the hash:

  • category: Threat type, currently they can be 
    • malware: Malicious file
    • pua: Potentially unwanted application
    • Confirmed clean: A known clean file
  • detection: Threat name, as given by Cyren Anti Malware
  • urls: A list of action URLs relevant to the queried hash:
    • upload: Used for uploading a copy of a file
    • sandbox_report: Used to access the sandbox report for the file
    • pcap: Used to access the packet capture artifact
    • dropped_files: Used to access the dropped files
    • screenshots: Used to access the analysis screenshots

 Example response for a check hash request

{
  "http_status_code": 200,
  "response_code": 1,
  "message": "Accepted",
  "content": {
    "category": "malware",
    "detection": "CVE1711882",
    "urls": {
      "upload": "https://threatlookup.com/v1-1/file/KEY/HASH",
      "sandbox_report": "https://threatlookup.com/v1-1/KEY/HASH/resources/r"
      "pcap": "https://threatlookup.com/v1-1/KEY/HASH/resources/p"
      "dropped_files": "https://threatlookup.com/v1-1/KEY/HASH/resources/d"
      "screenshots": "https://threatlookup.com/v1-1/KEY/HASH/resources/s"
    }
  }
}


You should use the "sandbox_report" URL to view the sandbox report.

For more information about the structure of the sandbox report view the sandbox report structure.

  • No labels