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:

  • malware: Malicious file
  • pua: Potentially unwanted application
  • Confirmed clean: A known clean file
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

200File was uploaded. Process in progressCheck the hash again later
202File transmitted!The upload was successfuly completed.
302FoundRedirection 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

400SHA256 hash mismatchThe uploaded file did not match the provided SHA256

401

Access denied!

You are not permitted to access the analysis report and artifcats

404No such resource found!The resource could not be found. Check the query syntax or URL
405Method Not AllowedThe 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:

  • malware: Malicious file
  • pua: Potentially unwanted application
  • Confirmed clean: A known clean file
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.

  • No labels