7.1.3.3. Fetch Processing Result by File Hash

Retrieve Processing Results Using Hash

Request

Value

Method

GET

URL

/hash/{md5|sha1|sha256 hash}

Request HTTP header parameters

name

type

required

value

rule

string

false

the name is the desired rule to query for (see 7.1.3.5. Fetching Available Processing Rules )

The retrieved result is always the most recent for the processed item, if rule is set then it will be the most recent - if exists - under the given rule.

Successful response

HTTP status code: 200

{
"data_id": "61dffeaa728844adbf49eb090e4ece0e",
"file_info": {
"display_name": "samplefile.txt",
"file_size": 81035,
"file_type": "text/plain",
"file_type_description": "ASCII text",
"md5": "c05017f68343a5257fc3c0db72aa58dc",
"sha1": "ba46b945f408cc729458380350b4e78f61741c81",
"sha256": "8805777d2d561255edcb499f7445ef0216b75737bacb6bc6665dbf9830272f53",
"upload_timestamp": "2015-08-14T12:46:59.360Z"
},
"scan_results": {
"data_id": "61dffeaa728844adbf49eb090e4ece0e",
"progress_percentage": 100,
"scan_all_result_a": "No Threat Detected",
"scan_all_result_i": 0,
"scan_details": {
"Engine1": {
"def_time": "2015-08-13T09:32:48.000Z",
"location": "local",
"scan_result_i": 0,
"scan_time": 1,
"wait_time": 3,
"threat_found": ""
},
"Engine2": {
"def_time": "2015-08-10T00:00:00.000Z",
"location": "local",
"scan_result_i": 0,
"scan_time": 3,
"wait_time": 1,
"threat_found": ""
}
},
"start_time": "2015-08-14T12:46:59.363Z",
"total_avs": 2,
"total_time": 389
}
"process_info": {
"processing_time": 400,
"progress_percentage": 100,
"user_agent": "webscan",
"profile": "File scan",
"queue_time": 24,
"result": "Allowed",
"blocked_reason": "",
"file_type_skipped_scan": false,
"outdated_data": [
"enginedefinitions"
]
},
"vulnerability_info": {...}
}

Response description:

  • data_id: data ID of the requested file

  • file_info: basic information of the processed file

  • scan_results: results of the scan

    • data_id: data ID of the requested file

    • progress_percentage: percentage of progress, if it is 100, then the scan is completed

    • scan_all_result_a: the overall scan result in string

    • scan_all_result_i: the overall scan result in number code

    • individual scan engine results will be consolidated according to the following priority:

      1. Threat found

      2. Object is suspicious

      3. Potentially Vulnerable File

      4. Filetype mismatch

      5. Archive is encrypted / too deep (archive only) / too big (archive only) / containing too many files (archive only) / extraction timeout exceeded (archive only)

      6. Encrypted Document

      7. No threat detected

      8. Object was not scanned / Whitelisted / Blacklisted

      9. Failed to scan the object

    • scan_details: scan results for each antivirus engine. The key is the name of the antivirus engine and the value is the result of the antivirus engine

      • def_time: the database definition time for this engine

      • location: place of scan engine

      • scan_result_i: numeric code of engine scan result

      • scan_time: time elapsed during scan with the engine in milliseconds

      • wait_time: time elapsed between sending file to node and receiving the result from the engine in milliseconds

      • threat_found: name of the scan result

    • start_time: start time of scan

    • total_avs: number of used antivirus engines

    • total_time: total time elapsed during scan in milliseconds

  • process_info: process information

    • processing_time: total time elapsed during processing file on the node in milliseconds

    • progress_percentage: percentage of processing completed

    • user_agent: who called this API

    • profile: the name of the rule used

    • queue_time: total time elapsed during file waits in the queue in milliseconds

    • result: the final result of processing the file (Allowed / Blocked / Processing)

    • blocked_reason: gives the reason if the file is blocked

    • file_type_skipped_scan: indicates if the input file's detected type was configured to skip scanning

    • outdated_data: array of flags - if occur - describing outdated data in the result, these can be

      • enginedefinitions: at least one of the AV engines the item was scanned with has a newer definition database

      • configuration: the process' rule - or any item used by the rule - was modified since the item was processed

      • sanitization: if item was sanitized this flag notifies that the sanitization information regarding this result is outdated, meaning the sanitized item is no longer available

  • vulnerability_info: see 7.1.6. Vulnerability Info In Processing Result

Possible overall and per engine scan results

scan_result_a

scan_result_i

No Threat Detected

0

Infected

1

Suspicious

2

Failed

3

Scan Skipped - Whitelisted

7

Scan Skipped - Blacklisted

8

Not Scanned

10

Exceeded Archive Depth

9

Encrypted Archive

12

Exceeded Archive Size

13

Exceeded Archive File Number

14

Exceeded Archive Timeout

16

Filetype Mismatch

17

Potentially Vulnerable File

18

In Progress

255

Successful response with archive detection

HTTP status code: 200

{
"data_id": "d7016058f0874d12b98a8c1ece9d3ea9",
"extracted_files": {
"files_in_archive": [
{
"data_id": "21d48f2c463c4ca89b7544c2c127e945",
"detected_by": 0,
"display_name": "samplezip.tar.gz/[Content]/samplezip/sampleimg.jpg",
"file_size": 215684,
"file_type": "image/jpeg",
"file_type_description": "JPEG image data",
"progress_percentage": 100,
"scan_all_result_i": 0
},
{
"data_id": "7cb298eb42614ca9bc87a4de4acad436",
"detected_by": 9,
"display_name": "samplezip.tar.gz/[Content]/samplezip/eicar",
"file_size": 69,
"file_type": "text/plain",
"file_type_description": "EICAR virus test files",
"progress_percentage": 100,
"scan_all_result_i": 1
},
]
},
"file_info": {
"display_name": "samplezip.tar.gf",
"file_size": 1486610,
"file_type": "application/x-gzip",
"file_type_description": "gzip compressed data",
"md5": "60d5fc5b07ecd1dcdc781bfa94ec8619",
"sha1": "992e40a2a6906c6d21f92034dfba779aae6d9ee7",
"sha256": "6ec5e258141528f004a43f7d25163a1c7486df76fde7976a793b140b11eda95d",
"upload_timestamp": "2015-08-14T12:46:59.360Z"
},
"scan_results": {
"last_file_scanned": "example.jim",
"data_id": "d7016058f0874d12b98a8c1ece9d3ea9",
"progress_percentage": 100,
"scan_all_result_a": "Infected",
"scan_all_result_i": 1,
"scan_details": {
"Engine1": {
"def_time": "2015-08-13T09:32:48.000Z",
"location": "local",
"scan_result_i": 0,
"scan_time": 1,
"wait_time": 3,
"threat_found": ""
},
"Engine2": {
"def_time": "2015-08-10T00:00:00.000Z",
"location": "local",
"scan_result_i": 0,
"scan_time": 3,
"wait_time": 1,
"threat_found": ""
}
},
"start_time": "2015-08-14T12:46:59.363Z",
"total_avs": 2,
"total_time": 389
}
"process_info": {
"processing_time": 400,
"progress_percentage": 100,
"user_agent": "webscan",
"profile": "File scan",
"queue_time": 24,
"result": "Blocked",
"blocked_reason": "Scan result: Infected",
"file_type_skipped_scan": false
},
"vulnerability_info": {...}
}

Completed response description with archive detection:

  • extracted_files: extracted files

    • files_in_archive: array of files in archive

      • detected_by: number of threat reporting engines

  • scan_results

    • last_file_scanned: If available, the name of the most recent processed file

Response (not existing hash)

HTTP status code: 200

{
"61dffeaa728844adbf49eb090e4ece0e": "Not Found"
}

Error response

Unexpected event on server

HTTP status code: 500

{
"err": "<error message>"
}

Note: Check Metadefender Core server logs for more information.