3.1 Retrieving scan reports using a data hash

Request

Value

Method

GET

URL

https://api.metadefender.com/v2/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

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

apikey

YES

file_metadata

Add additional information in the response, like pe_info

0 - don't add, 1 - add

NO

Response

HTTP Status Codes

Please refer to Status Codes for more information.

Body

Example of successful scan request:

{
"scan_result_history_length": 128,
"votes": {
"up": 0,
"down": 0
},
"file_id": "ZTE3MDgyMkh5UmZGTl94cV9a",
"data_id": "ZTE3MDgyMkh5UmZGTl94cV9aSEpEWlFyQ0xlMm0",
"archived": false,
"process_info": {
"user_agent": "",
"result": "Blocked",
"progress_percentage": 100,
"profile": "File scan",
"file_type_skipped_scan": false,
"blocked_reason": "Infected"
},
"scan_results": {
"scan_details": {
"AegisLab": {
"wait_time": 336,
"threat_found": "",
"scan_time": 70,
"scan_result_i": 0,
"def_time": "2018-11-03T01:00:00.000Z"
},
"Ahnlab": {
"wait_time": 81,
"threat_found": "",
"scan_time": 309,
"scan_result_i": 0,
"def_time": "2018-11-04T00:00:00.000Z"
},
"ByteHero": {
"wait_time": 2167,
"threat_found": "",
"scan_time": 7303,
"scan_result_i": 0,
"def_time": "2018-11-03T00:00:00.000Z"
},
"ClamAV": {
"wait_time": 1505,
"threat_found": "",
"scan_time": 4845,
"scan_result_i": 0,
"def_time": "2018-11-04T05:08:00.000Z"
},
"Cyren": {
"wait_time": 850,
"threat_found": "",
"scan_time": 212,
"scan_result_i": 0,
"def_time": "2018-11-04T05:53:00.000Z"
},
"Emsisoft": {
"wait_time": 949,
"threat_found": "",
"scan_time": 113,
"scan_result_i": 0,
"def_time": "2018-11-04T04:50:00.000Z"
},
"Filseclab": {
"wait_time": 1332,
"threat_found": "W32.OptimizerEliteMax.E.zcce",
"scan_time": 5018,
"scan_result_i": 1,
"def_time": "2018-11-03T00:49:00.000Z"
},
"K7": {
"wait_time": 242,
"threat_found": "Adware ( 004cc9ef1 )",
"scan_time": 8,
"scan_result_i": 1,
"def_time": "2018-11-04T00:50:00.000Z"
},
"NANOAV": {
"wait_time": 288,
"threat_found": "Riskware.Win32.SystemCare.evocpr",
"scan_time": 165,
"scan_result_i": 1,
"def_time": "2018-11-03T23:52:00.000Z"
},
"TACHYON": {
"wait_time": 86,
"threat_found": "Adware.GenericKD.3548029",
"scan_time": 26602,
"scan_result_i": 1,
"def_time": "2018-11-04T05:00:00.000Z"
},
"Quick Heal": {
"wait_time": 437,
"threat_found": "PUA.Onesystemc.Gen",
"scan_time": 94,
"scan_result_i": 1,
"def_time": "2018-11-03T10:47:00.000Z"
},
"Vir.IT eXplorer": {l
"wait_time": 192,
"threat_found": "PUP.Win32.OSCL.A",
"scan_time": 58,
"scan_result_i": 1,
"def_time": "2018-11-02T14:46:00.000Z"
},
"Vir.IT ML": {
"wait_time": 38303,
"threat_found": "",
"scan_time": 373,
"scan_result_i": 0,
"def_time": "2018-11-02T14:46:00.000Z"
},
"Xvirus Personal Guard": {
"wait_time": 590,
"threat_found": "",
"scan_time": 3847,
"scan_result_i": 0,
"def_time": "2018-11-03T10:11:00.000Z"
},
"Zillya!": {
"wait_time": 239,
"threat_found": "Adware.GenericKD.Win32.5471",
"scan_time": 11,
"scan_result_i": 1,
"def_time": "2018-11-02T11:01:00.000Z"
}
},
"rescan_available": true,
"data_id": "ZTE3MDgyMkh5UmZGTl94cV9aSEpEWlFyQ0xlMm0",
"scan_all_result_i": 1,
"start_time": "2018-11-04T08:08:56.173Z",
"total_time": 49339,
"total_avs": 15,
"total_detected_avs": 7,
"progress_percentage": 100,
"in_queue": 0,
"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": "PE32 executable (GUI) Intel 80386, for MS Windows",
"file_type_extension": "exe",
"display_name": "CleanupConsole.exe"
},
"top_threat": -1,
"share_file": 1,
"rest_version": "4"
}

Example of successful scan request for an archive:

{
"scan_result_history_length": 5,
"votes": {
"up": 0,
"down": 0
},
"file_id": "YTE3MDgwMlNKd1pQcmRmSlBX",
"data_id": "YTE3MDgwMlNKd1pQcmRmSlBXcmtrZDdlTlVfNlE",
"archived": false,
"process_info": {
"user_agent": "",
"result": "Blocked",
"progress_percentage": 100,
"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_result_i": 1,
"progress_percentage": 100,
"file_type": "application/msword",
"file_size": 23040,
"display_name": "test_doc.doc",
"detected_by": 1,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYckpXQmVOOHVhWA"
},
{
"scan_result_i": 15,
"progress_percentage": 100,
"file_type": "application/encrypted",
"file_size": 17920,
"display_name": "test_protected.docx",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYQmtkT2xWTGRwbQ"
},
{
"scan_result_i": 1,
"progress_percentage": 100,
"file_type": "application/vnd.ms-powerpoint",
"file_size": 86016,
"display_name": "test_ppt.ppt",
"detected_by": 1,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYU0p0X2xOTGRwWA"
},
{
"scan_result_i": 15,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYSDFxX2xFSV82WA",
"progress_percentage": 100,
"file_type": "application/encrypted",
"file_size": 37376,
"display_name": "test_protected.pptx",
"detected_by": 0
},
{
"scan_result_i": 15,
"progress_percentage": 100,
"file_type": "application/encrypted",
"file_size": 17920,
"display_name": "test_protected2.docx",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYU2tpdWc0TF9hUQ"
},
{
"scan_result_i": 0,
"progress_percentage": 100,
"file_type": "image/tiff",
"file_size": 819698,
"display_name": "test_tiff.tiff",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYU0pPZ1ZVZHA3"
},
{
"scan_result_i": 0,
"progress_percentage": 100,
"file_type": "application/pdf",
"file_size": 141555,
"display_name": "test_pdf.pdf",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYU2tndXg0TF82UQ"
},
{
"scan_result_i": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYQnlXT2dFOF9UUQ",
"progress_percentage": 100,
"file_type": "text/rtf",
"file_size": 42923,
"display_name": "test_rtf.rtf",
"detected_by": 0
},
{
"scan_result_i": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYU3l6X2xOSV9wNw",
"progress_percentage": 100,
"file_type": "application/vnd.openxmlformats-officedocument.spreadsheetml.sheet",
"file_size": 8261,
"display_name": "test_xlsx.xlsx",
"detected_by": 0
},
{
"scan_result_i": 0,
"progress_percentage": 100,
"file_type": "image/bmp",
"file_size": 151670,
"display_name": "test_bmp.bmp",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYQkpybE5JdTZY"
},
{
"scan_result_i": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYQnk0dWdWOHVhbQ",
"progress_percentage": 100,
"file_type": "application/vnd.openxmlformats-officedocument.presentationml.presentation",
"file_size": 32029,
"display_name": "test_pptx.pptx",
"detected_by": 0
},
{
"scan_result_i": 0,
"progress_percentage": 100,
"file_type": "application/vnd.ms-excel",
"file_size": 26624,
"display_name": "test_xls.xls",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYU0o4T2dFTHU2UQ"
},
{
"scan_result_i": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYSEpncmVOVWRUbQ",
"progress_percentage": 100,
"file_type": "text/html",
"file_size": 192,
"display_name": "test_html.html",
"detected_by": 0
},
{
"scan_result_i": 0,
"progress_percentage": 100,
"file_type": "image/jpeg",
"file_size": 101763,
"display_name": "test_jpg2.jpg",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYSEpQT3hOOF9UNw"
},
{
"scan_result_i": 0,
"progress_percentage": 100,
"file_type": "application/vnd.openxmlformats-officedocument.wordprocessingml.document",
"file_size": 12137,
"display_name": "test_docx.docx",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYQnlmcmdWVXVwbQ"
},
{
"scan_result_i": 0,
"progress_percentage": 100,
"file_type": "image/jpeg",
"file_size": 47003,
"display_name": "test_jpg.jpg",
"detected_by": 0,
"data_id": "WVRFM01EZ3dNbE5LZDFwUWNtUm1TbEJYUzFRU3hOTF82bQ"
}
],
"progress_percentage": 100,
"detected_by": 1,
"scan_result_i": 0
},
"scan_results": {
"scan_details": {
"AegisLab": {
"wait_time": -8,
"threat_found": "",
"scan_time": 71,
"scan_result_i": 0,
"def_time": "2018-11-12T01:00:00.000Z"
},
"Ahnlab": {
"wait_time": 30,
"threat_found": "",
"scan_time": 2,
"scan_result_i": 0,
"def_time": "2018-11-13T00:00:00.000Z"
},
"ByteHero": {
"wait_time": 8,
"threat_found": "",
"scan_time": 258,
"scan_result_i": 0,
"def_time": "2018-11-12T00:00:00.000Z"
},
"ClamAV": {
"wait_time": 0,
"threat_found": "",
"scan_time": 1235,
"scan_result_i": 0,
"def_time": "2018-11-12T22:07:00.000Z"
},
"Cyren": {
"wait_time": 21,
"threat_found": "",
"scan_time": 11,
"scan_result_i": 0,
"def_time": "2018-11-13T05:31:00.000Z"
},
"Emsisoft": {
"wait_time": 24,
"threat_found": "",
"scan_time": 8,
"scan_result_i": 0,
"def_time": "2018-11-12T19:06:00.000Z"
},
"Filseclab": {
"wait_time": 11,
"threat_found": "",
"scan_time": 208,
"scan_result_i": 0,
"def_time": "2018-11-12T00:50:00.000Z"
},
"K7": {
"wait_time": 30,
"threat_found": "",
"scan_time": 2,
"scan_result_i": 0,
"def_time": "2018-11-13T00:55:00.000Z"
},
"NANOAV": {
"wait_time": 23,
"threat_found": "",
"scan_time": 9,
"scan_result_i": 0,
"def_time": "2018-11-12T22:33:00.000Z"
},
"TACHYON": {
"wait_time": 5,
"threat_found": "",
"scan_time": 58,
"scan_result_i": 0,
"def_time": "2018-11-13T05:00:00.000Z"
},
"Quick Heal": {
"wait_time": 27,
"threat_found": "",
"scan_time": 5,
"scan_result_i": 0,
"def_time": "2018-11-12T12:28:00.000Z"
},
"Vir.IT eXplorer": {
"wait_time": 23,
"threat_found": "",
"scan_time": 9,
"scan_result_i": 0,
"def_time": "2018-11-12T14:46:00.000Z"
},
"Vir.IT ML": {
"wait_time": 27,
"threat_found": "",
"scan_time": 5,
"scan_result_i": 0,
"def_time": "2018-11-09T14:46:00.000Z"
},
"Xvirus Personal Guard": {
"wait_time": 11,
"threat_found": "",
"scan_time": 68,
"scan_result_i": 0,
"def_time": "2018-11-12T10:34:00.000Z"
},
"Zillya!": {
"wait_time": 28,
"threat_found": "",
"scan_time": 4,
"scan_result_i": 0,
"def_time": "2018-11-12T15:21:00.000Z"
}
},
"rescan_available": true,
"data_id": "YTE3MDgwMlNKd1pQcmRmSlBXcmtrZDdlTlVfNlE",
"scan_all_result_i": 0,
"start_time": "2018-11-13T13:38:52.680Z",
"total_time": 7001,
"total_avs": 15,
"total_detected_avs": 0,
"progress_percentage": 100,
"in_queue": 0,
"scan_all_result_a": "No threat detected"
},
"file_info": {
"file_size": 1286700,
"upload_timestamp": "2018-03-21T16:47:30.000Z",
"md5": "EF4A5B9ECC9D2E3380D035F71C00AFA1",
"sha1": "972695E77E75307EC38B2F089EDBE129C29FF870",
"sha256": "0C4161B19D8CE5B2721AA0AF2CDDE5F121DDAB81004DB3B7FF243D74CFFD3EA4",
"file_type_category": "O",
"file_type_description": "ZIP Archive",
"display_name": "archive.zip",
"file_type_extension": "-"
},
"top_threat": -1,
"share_file": 1,
"rest_version": "4",
"original_file": {
"detected_by": 0,
"progress_percentage": 100,
"scan_result_i": 0,
"data_id": "YTE3MDgwMlNKd1pQcmRmSlBXcmtrZDdlTlVfNlE"
}
}

Example of failed scan request:

{
"BED12FDA073BB386B54700138FB47EEA": "Not Found"
}

Descriptions of response:

scan_results.scan_details

Per engine scan results

scan_results.rescan_available

Whether this file can be rescanned or not

scan_results.scan_all_result_i

The scan returned code. Please refer to Description on scan result codes for more information.

scan_results.start_time

The time when the scan has started

scan_results.total_time

The total time it took to scan this file

scan_results.total_avs

The total number of AVs returned in the result

scan_results.total_detected_avs

The total number of AVs reporting this file as infected

scan_results.progress_percentage

The progress so far. Returns values between 0 and 100

scan_results.in_queue

If the file is waiting in queue to be scanned, this will show the total queue size

scan_results.scan_all_result_a

A text description of the scan results

file_info.file_type_extension

File extension, deduced from "file_type_description"

file_info.file_type_description

File description as returned by magic lib.

file_info.file_type_category

Category for file type. Please refer to Description of file categories for more information.

file_info.upload_timestamp

The time the file was first uploaded.

file_info.display_name

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

file_info.file_size

The size of the file, in bytes

top_threat

If this file is part of our top 50 most searched for threats, this value will reflect the threat rank. -1 for all else

data_id

Unique identifier for this particular scan of the file

file_id

Unique identifier of the file in our system

hash_results.vulnerability

Marks the fact that extra vulnerability data is available for this file

hash_results.vulnerability_severity

Vulnerability score calculated by OPSWAT

hash_results.wa

Marks the fact that appinfo data is available

votes.down

Crowd sourced community downvotes

votes.up

Crowd sourced community upvotes

exif

Marks if EXIF is available for this particular file or not. To retrieve exif info see 5.2 EXIF Lookup

pe_info

Marks if PEinfo is available for this particular hash. To retrieve peinfo see 5.3 PE Info Lookup

scan_result_history_length

The total number of scans

More levels for file_info level:

upload_timestamp

First time the file is uploaded to the server (even if file is rescanned this value will be preserved).

file_type_category

High level categorization of the file type.

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.

extracted_files.data_id

Same data_id as original file

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.

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.

  • 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

Please refer to Errors for more information.

Sample code (Node.js)

var http = require("https");
 
var options = {
"method": "GET",
"hostname": "api.metadefender.com",
"path": "/v2/hash/E71A6D8760B37E45FA09D3E1E67E2CD3",
"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/v2/hash/E71A6D8760B37E45FA09D3E1E67E2CD3 \
-H 'apikey: ${APIKEY}'