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:
- Hash lookup
- File upload
- 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_code | The http status response to the user's request |
| response_code | Indicates the status of the request:
|
| message | A description of what occurred |
| content | Contains information regarding the hash:
|
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:
| Description | response_code | http_status_code | message |
| When user submits invalid sha256 | -1 | 200 | Unsupported checksum type |
| Detection data | 1 | 200 | Detection data returned |
| Sample was already uploaded | 1 | 200 | Already uploaded. Process in progress |
| Non-existent route caught by the routing engine | 0 | 200 | API Version x.x, unknown call |
| When sha256 is missing from the API call | -1 | 400 | Missing or malformed parameters! |
| SHA256 of the file submitted doesn't match the sha256 submitted through API | -1 | 400 | SHA256 hash mismatch |
| File delivered to API is empty | -1 | 400 | Empty file! Aborted |
| Sandbox artifact cannot be displayed due to insufficient permission or wrong ownership | -1 | 401 | Access denied! |
| Sandbox artifact not found on the file system | -1 | 404 | No such resource found! |
| Disallowed characters in API call | -1 | 404 | Unknown or malformed call |
| If any of the backend runs unexpectedly, not caught by the API handlers | -1 | 500 | Internal 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.
| Description | response_code | http_status_code | message |
| When user submits invalid sha256 | -1 | 200 | Unsupported checksum type |
| Sample was already uploaded | 1 | 200 | Already uploaded. Process in progress. |
| Non-existent route caught by the routing engine | 0 | 200 | API Version x.x, unknown call. |
| File was uploaded | 1 | 200 | File transmitted |
When sha256 is missing from the API call | -1 | 400 | Missing or malformed parameters! |
Sha256 of the file submitted doesn't match the sha256 submitted through API | -1 | 400 | SHA256 hash mismatch |
Empty file was delivered to API | -1 | 400 | Empty file! Aborted |
Disallowed characters in API call. | -1 | 404 | Unknown or malformed call |
| Account's upload limit reached, current and subsequent uploads allowed | 1 | 429 | File transmitted |
| Account's upload limit reached, current and subsequent uploads prevented | -1 | 429 | File not transmitted |
If any of the backend runs unexpected, not caught by the API handlers. | -1 | 500 | Internal 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_code | The http status response to the user's request |
| response_code | Indicates the status of the request:
|
| message | A description of what occurred |
| content | Contains information regarding the hash:
|
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.
Overview
Content Tools
Apps