3.1 Retrieving scan reports using a data hash

Request

Value

Method

GET

URL

https://api.metadefender.com/v4/hash/:hash

Summary

Look up a hash by MD5, SHA1, or SHA256.

Request

URL Parameters

 

Description

Example

:hash

MD5, SHA1, or SHA256 of a file

6A5C19D9FFE8804586E8F4C0DFCC66DE

Header Parameters

 

Description

Allowed Values

Required

apikey

gives rights to use the endpoint (token authentication) (API Authentication Mechanisms)

apikey

YES

Response

HTTP Status Codes

Please refer to Status Codes for more information.

Body

Example of a successful request:

{
"scan_result_history_length": 154,
"file_id": "ZTE3MDgyMkh5UmZGTl94cV9a",
"data_id": "ZTE3MDgyMkh5UmZGTl94cV9aUzFsSWU3aGtVNA",
"process_info": {
"result": "Blocked",
"profile": "Sanitize",
"post_processing": {
"copy_move_destination": "",
"converted_to": "",
"converted_destination": "",
"actions_ran": "",
"actions_failed": ""
},
"file_type_skipped_scan": false,
"blocked_reason": "Infected"
},
"scan_results": {
"scan_details": {
"Zillya!": {
"threat_found": "Adware.GenericKD.Win32.5471",
"scan_time": 26,
"scan_result_i": 1,
"def_time": "2019-02-26T17:27:00.000Z"
},
...
"Vir.IT ML": {
"threat_found": "",
"scan_time": 2275,
"scan_result_i": 0,
"def_time": "2019-02-22T14:46:00.000Z"
}
},
"rescan_available": true,
"scan_all_result_i": 1,
"start_time": "2019-02-26T21:53:32.770Z",
"total_time": 11206,
"total_avs": 37,
"total_detected_avs": 15,
"progress_percentage": 100,
"scan_all_result_a": "Infected"
},
"file_info": {
"file_size": 765024,
"upload_timestamp": "2017-09-05T18:30:04.000Z",
"md5": "6A5C19D9FFE8804586E8F4C0DFCC66DE",
"sha1": "016CD548A5BA78015F85E2591BF6189658ACA066",
"sha256": "BE41E36233DD8DB2B28A109E7FC7C409E1353BF2D1710158BBE267280E163353",
"file_type_category": "E",
"file_type_description": "Executable File",
"file_type_extension": "exe",
"display_name": "CleanupConsole.exe"
},
"share_file": 1,
"rest_version": "4",
"additional_info": [],
"votes": {
"up": 0,
"down": 0
}
}

Example of a successful request for an archive:

{
"scan_result_history_length": 5,
"file_id": "YTE3MDgwMlNKd1pQcmRmSlBX",
"data_id": "YTE3MDgwMlNKd1pQcmRmSlBXcmtrZDdlTlVfNlE",
"process_info": {
"result": "Blocked",
"profile": "File scan",
"post_processing": {
"copy_move_destination": "",
"converted_to": "",
"converted_destination": "",
"actions_ran": "",
"actions_failed": ""
},
"file_type_skipped_scan": false,
"blocked_reason": "Infected"
},
"extracted_files": {
"data_id": "YTE3MDgwMlNKd1pQcmRmSlBXcmtrZDdlTlVfNlE",
"files_in_archive": [
{
"scan_result_i": 15,
"progress_percentage": 100,
"file_type": "application/encrypted",
"file_size": 14336,
"display_name": "test_protected.xlsx",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYcnlYdWxWVXVUbQ"
},
{
"scan_result_i": 15,
"progress_percentage": 100,
"file_type": "application/msword",
"file_size": 22528,
"display_name": "test_protected.doc",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYckpIX3hWVU82bQ"
}
]
},
"scan_results": {
"scan_details": {
"TrendMicro House Call": {
"threat_found": "",
"scan_time": 975,
"scan_result_i": 0,
"def_time": "2018-11-11T02:00:00.000Z"
},
...
"Vir.IT ML": {
"threat_found": "",
"scan_time": 5,
"scan_result_i": 0,
"def_time": "2018-11-09T14:46:00.000Z"
}
},
"rescan_available": true,
"scan_all_result_i": 1,
"start_time": "2018-11-13T13:38:52.680Z",
"total_time": 7001,
"total_avs": 35,
"total_detected_avs": 0,
"progress_percentage": 100,
"scan_all_result_a": "Infected"
},
"file_info": {
"file_size": 1286700,
"upload_timestamp": "2018-03-21T16:47:30.000Z",
"md5": "EF4A5B9ECC9D2E3380D035F71C00AFA1",
"sha1": "972695E77E75307EC38B2F089EDBE129C29FF870",
"sha256": "0C4161B19D8CE5B2721AA0AF2CDDE5F121DDAB81004DB3B7FF243D74CFFD3EA4",
"file_type_category": "",
"file_type_description": "ZIP Archive",
"display_name": "archive.zip"
},
"share_file": 1,
"rest_version": "4",
"additional_info": [],
"votes": {
"up": 0,
"down": 0
}
}

Example of failed scan request:

{
"error": {
"code": 404003,
"messages": [
"The hash was not found"
]
}
}

Descriptions of response:

Field

Description

Type

Values

scan_results.scan_details

Per engine scan results

object

 

scan_results.scan_details.<engine>

The individual engine results

object

List of anti-malware engines

scan_results.scan_details.<engine>.scan_time

How much time in milliseconds it took for the engine to scan the file

int

 

scan_results.scan_details.<engine>.scan_result_i

The scan code of the engine for this file

int

Description on scan result codes

scan_results.scan_details.<engine>.def_time

The engine definition time

date

 

scan_results.scan_details.<engine>.threat_found

If a threat was found, this field will contain the exact string of the infection returned by the engine

string

 

scan_results.rescan_available

Whether this file can be rescanned or not

boolean

 

scan_results.scan_all_result_i

The scan returned code

int

Description on scan result codes

scan_results.start_time

The time when the scan has started. This is different from the "file_info.upload_timestamp" field and the difference between these 2 fields show how much the file has been waiting in the queue to be scanned.

date

 

scan_results.total_time

The total time it took to scan this file

int

A positive number in milliseconds

scan_results.total_avs

The total number of AVs returned in the result

int

 

scan_results.total_detected_avs

The total number of AVs reporting this file as infected

int

 

scan_results.progress_percentage

The progress so far. Returns values between 0 and 100

int

 

scan_results.scan_all_result_a

A text description of the scan results

string

 

file_info.file_type_extension

File extension, deduced from "file_type_description"

string

 

file_info.file_type_description

File description as returned by the magic lib

string

 

file_info.file_type_category

Category for the file type

char

Description of file categories

file_info.upload_timestamp

The time the file was first uploaded

date

 

file_info.display_name

The name provided by the initial uploader of the file with the "filename" header

string

 

file_info.sha256

The sha256 of the file (we recommend using this hash as the reference)

hex

 

file_info.sha1

The sha1 of the file

hex

 

file_info.md5

the md5 of the file

hex

 

file_info.file_size

The size of the file, in bytes

int

 

data_id

Unique identifier for this particular scan of the file

string

 

file_id

Unique identifier of the file in our system

string

 

threat_name

OPSWAT generated threat name in the format "<malware_type>/<malware_family>!<unique_file_id>"

string

E.g: Ransomware/WannaCry!FifMs89q

votes.down

Crowdsourced community downvotes

int

 

votes.up

Crowdsourced community upvotes

int

 

additional_info

An array containing strings showing the existence of additional information

array

scan_result_history_length

The total number of scans

int

 

share_file

The privacy setting of the file. This is set by the "samplesharing" header at upload time

int

0 - the file is stored on our servers, can be rescanned

1 - the file is not stored. It was scanned once and deleted

Descriptions of archive scan response:

When scanning archives, the archive itself will be scanned as a file, and the files inside the archive will be extracted and scanned individually. The list of files in the archive, the scan results and total number of engines which detected the file as infected can be accessed in the parent archive scan results. For accessing the detailed scan results of the contained file, a separate call needs to be made to the file's data_id.

Field

Description

Type

Values

extracted_files.data_id

Same data_id as the original file

string

 

extracted_file. files_in_archive

The list of files extracted from the scanned archive; each item from the list contains a few scan result details.

array

 

extracted_file. files_in_archive.<>.data_id

The data_id of the individual file scan

string

 

extracted_file. files_in_archive.<>.detected_by

How many engines detected the file as infected

int

 

extracted_file. files_in_archive.<>.display_name

The name of the file as found in the archive

string

 

extracted_file. files_in_archive.<>.file_size

The size of the file

int

Bytes

extracted_file. files_in_archive.<>.file_type

The type of the file as returned by the magic lib, just as "file_info.file_type_description" above

string

 

extracted_file. files_in_archive.<>.progress_percentage

The scanning progress of the file

int

 

extracted_file. files_in_archive.<>.scan_result_i

The code of the scan result

int

Description on scan result codes

parent_data_id

The data_id of the archive that contains the accessed file (the parent archive). This property will only be found in files inside archives.

string

 

  • Supported archive types: ZIP, TAR, RAR, GZ, BZ2, 7Z, XZ, CRX, RPM, Z, LZ, XPI, CAB.

  • If the archive contains sanitizable file types when scanning an entire archive, the respective files won't be sanitized, being interpreted as non-sanitizable files. Please refer to Data Sanitization Request for more information about sanitization.

  • When accessing the extracted files from an archive, "Parent Archive" option is available to identify and access the archive that contains the respective files.

  • Rescan is available only for the entire archive; the extracted files cannot be rescanned one by one.

Errors

The format of error messages:

Field

Description

Type

Values

error.code

The unique error code

int

Errors

error.messages

An array of string messages with additional information about the error

array

 

Sample code (Node.js)

var http = require("https");
 
var options = {
"method": "GET",
"hostname": [
"api",
"metadefender",
"com"
],
"path": [
"v4",
"hash",
"6A5C19D9FFE8804586E8F4C0DFCC66DE"
],
"headers": {
"apikey": process.env.APIKEY
}
};
 
var req = http.request(options, function (res) {
var chunks = [];
 
res.on("data", function (chunk) {
chunks.push(chunk);
});
 
res.on("end", function () {
var body = Buffer.concat(chunks);
console.log(body.toString());
});
});
 
req.end();

Sample code (cURL)

curl -X GET \
https://api.metadefender.com/v4/hash/6A5C19D9FFE8804586E8F4C0DFCC66DE \
-H "apikey: ${APIKEY}"