API V1 is no longer supported. Please refer to Sandbox Analysis Report API V1-1.
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.
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 /HASH HTTP/1.1 Host: us.threatlookup.com X-TOKEN-KEY: KEY
Example of curl request
curl -LH "X-TOKEN-KEY: KEY" "https://us.threatlookup.com/HASH"
Upon receiving a valid request, the service will respond with information about the provided hash
Response
Response Item | Description |
detection | Threat name, as given by Cyren Anti Malware |
category | Threat type. Current API provides the following three categories:
|
| urls (optional) | A list of action URLs relevant to the queried hash: upload_sample – Used for uploading a copy of the file in question. sandbox_files – Includes a list of URLs for downloading files generated during sandbox execution. The list of URLs are accessible only if you have the "Sandbox Analysis Report" license |
Example response to a request for a hash known to Cyren
{
"category" : "malware",
"detection" : "JS/Nemucod.CA3"
}
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:
{
urls: {
upload_sample: "URL",
sanbox_files: `{
pcaps: "URL"
dropped_files: "URL"
sandbox_report: "URL"
screenshots: "URL"
}
}
}
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:
Response code | Body Text | Description |
200 | `{json_document} | Indicates a successful hash query, and content was delivered in JSON format |
| 200 | File was uploaded. Process in progress | Check the hash again later |
| 202 | File transmitted! | The upload was successfuly completed. |
| 302 | Found | Redirection may sometimes occur. In order to get the final response, the client must be configured to follow redirects |
400 | Missing or malformed parameters! | Indicates an error in the hash query due to missing parameters |
| 400 | SHA256 hash mismatch | The uploaded file did not match the provided SHA256 |
401 | Access denied! | You are not permitted to access the analysis report and artifcats |
| 404 | No such resource found! | The resource could not be found. Check the query syntax or URL |
| 405 | Method Not Allowed | The uploads are restricted to higher-tier license |
Phase 2: File upload
Upload File Request
You should use the "upload_sample" URL returned in the hash lookup request to upoad a file and submit it for further analysis and processing.
This type of request must be made using HTTPS PUT. A filename must be specified; any filename will do. In addition, the SHA256 hash must also be provided for verifying the integrity, once uploading completes.
Responses are provided in JSON format.
Example of a HTTPS Request Header
PUT /file/HASH?filename=FILENAME HTTP/1.1 Host: us.threatlookup.com X-TOKEN-KEY: KEY
Example of curl request
curl -LH "X-TOKEN-KEY: KEY" -X PUT "https://us.threatlookup.com/file/HASH&filename=myfile.exe" --data-binary @myfile.exe
Response
Upon receiving a valid request, the service will issue a response with code 202 and body text “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 recive the results.
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 /HASH HTTP/1.1 Host: us.threatlookup.com X-TOKEN-KEY: KEY
Example of curl request
curl -LH "X-TOKEN-KEY: KEY" "https://us.threatlookup.com/HASH"
Response
Upon receiving a valid request, the service will respond with information about the provided hash:
Response Item | Description |
detection | Threat name, as given by Cyren Anti Malware |
category | Threat type. Current API provides the following three categories:
|
| urls | A list of action URLs relevant to the queried hash: upload_sample – Used for uploading a copy of the file in question. sandbox_files – Includes a list of URLs for downloading files generated during sandbox execution. The list of URLs are accessible only if you have the "Sandbox Analysis Report" license |
Example response for a check hash request
{
"category" : "malware",
"detection" : "JS/Nemucod.CA3"
"urls" : {
"upload_sample": "URL",
"sanbox_files": `{
"pcaps": "URL"
"dropped_files": "URL"
"sandbox_report": "URL"
"screenshots": "URL"
}
}
}
For more information about the structure of the sandbox report view the sandbox report structure.You should use the "sandbox_files" URLs to view the sandbox report and analysis artifacts.
Overview
Content Tools
Apps