8.1.3.2. Fetch processing result

Retrieving Scan Reports Using Data ID

Retrieve scan results.

Scan is done asynchronously and each scan request is tracked by a data ID. Initiating file scans and retrieving the results need to be done using two separate API calls. This request needs to be made multiple times until the scan is complete. Scan completion can be traced using “scan_results.progress_percentage” value from the response.

Request

Value

Method

GET

URL

/file/{data_id} or /process/{data_id}

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 8.1.3.5. Fetching available processing rules )

apikey

string

false

User's session id, if 8.1.3.1. Process a file has API key sent, then API key is required for fetching

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

Successful response

HTTP status code: 200

{
"data_id": "61dffeaa728844adbf49eb090e4ece0e",
"dlp_info": {
"hits": {
"ccn": {
"display_name": "Credit Card Number",
"hits": [
{
"after": "Duo case nulla dicunt eu\n",
"before": "velit..\nEos nostro recteque te. ",
"hit": "XXXXXXXXXXXX1113",
"severity": "0"
}
]
},
"regex_0": {
"display_name": "RegEx rule",
"hits": [
{
"after": "Text after the searched data \n",
"before": "animal voluptua.\nText matched data. ",
"hit": "sXXXXXXXXXXXXXXXXXXXn",
"severity": "0"
}
]
},
"ssn": {
"display_name": "Social Security Number",
"hits": [
{
"after": "Eam ad verear animal voluptua.\n",
"before": "doctus eligendi an vim.\nSSN: ",
"hit": "XXXXXXX7777",
"severity": "0"
}
]
}
},
"verdict": 1
},
"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",
"eng_id": "engine1_2_windows",
"location": "local",
"scan_result_i": 0,
"scan_time": 1,
"wait_time": 1,
"threat_found": ""
},
"Engine2": {
"def_time": "2015-08-10T00:00:00.000Z",
"eng_id": "engine2_4_windows",
"location": "local",
"scan_result_i": 0,
"scan_time": 3,
"wait_time": 2,
"threat_found": ""
}
},
"start_time": "2015-08-14T12:46:59.363Z",
"total_avs": 2,
"total_time": 389
},
"process_info": {
"post_processing": {
"actions_ran": "Sanitize",
"actions_failed": "",
"converted_to": "png",
"copy_move_destination": "",
"converted_destination": ""
},
"outdated_data": [
"sanitization",
"configuration"
]
"processing_time": 400,
"progress_percentage": 100,
"user_agent": "webscan",
"profile": "File scan",
"queue_time": 10,
"result": "Allowed",
"blocked_reason": "",
"file_type_skipped_scan": false,
"issues": [
{
description: "Probably blocked by a 3rd party software",
severity: "fatal"
}
]
},
"vulnerability_info": {...}
"yara_info":{"hits":{"source0.ExampleRule":{"description":"text"}},"verdict":1}
}

Response description:

  • data_id: data ID of the requested file

  • file_info: basic information of the scanned 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. Object is encrypted / too deep (archive only) / too big (archive only) / containing too many files (archive only) / extraction timeout exceeded (archive only)

      4. Filetype mismatch

      5. No threat detected

      6. Object was not scanned

      7. 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

      • eng_id: the unique identification string for the 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

    • post_processing: Contains information about result of data sanitization

      • "actions_ran": "Sanitized" or "" and the names of Post Actions that were also run.
        The separator is "|" (pipe). (e.g.: actions_ran: "PAscript" or actions_ran: "Sanitized | PAscript")

      • "actions_failed": "Sanitization Failed" or "" and the names of failed Post Actions.
        The separator is "|" (pipe). (e.g.: actions_failed: "PAscript failed" or actions_failed: "Sanitization Failed | PAscript failed" )

      • "converted_to": contains target type name of sanitization

      • "copy_move_destination": ""

      • "converted_destination": contains the name of the sanitized file

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

    • progress_percentage: percentage of processing completed

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

    • user_agent: who called this API

    • profile: the name of the rule used

    • 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

    • issues: task related issues (e.g.: blocked by 3rd party software, can not access file for 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 8.1.6. Vulnerability Info In Processing Result

  • dlp_info: information on matched sensitive data

    • hits: detailed results that contains:

      • type of matched rule: ccn (credit card number), ssn (social security number), regex_<number> (regular expression with a number in order to differentiate the RegEx rules if there are more.)

        • display_name: Credit Card Number, Social Security Number, or in case of RegEx, the name of the rule that has been given by the user

        • hits: the hits for that type

          • before: the context before the matched data

          • after: the context after the matched data

          • hit: the matched data

          • severity: can be 0 (detected) or 1 (suspicious)

    • verdict: the overall result for the scanned file. It can be

      • 0 - clean

      • 1 - found matched data

      • 2 - suspicious

      • 3 - failed

      • 4 - not scanned (e.g. not supported file type)

  • yara_info: information on data that matched yara rules

    • hits: detailed results that contains:

      • the name of the matched rules

      • a description

    • verdict: the overall result for the scanned file.

      • 0 - clean

      • 1 - found matched data

      • 2 - suspicious

      • 3 - failed

      • 4 - not scanned

Please find possible overall and per engine scan results here.

Successful response with archive detection

HTTP status code: 200

{
"data_id": "d7016058f0874d12b98a8c1ece9d3ea9",
"dlp_info": {...},
"extracted_files": {
"files_extracted_count": 2,
"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",
"process_info": {
"blocked_reason": "",
"progress_percentage": 100,
"result": "Allowed"
},
"progress_percentage": 100,
"scan_all_result_a": "Whitelisted",
"scan_all_result_i": 7,
"scanned_with": 0
},
{
"data_id": "7cb298eb42614ca9bc87a4de4acad436",
"detected_by": 2,
"display_name": "samplezip.tar.gz/[Content]/samplezip/eicar",
"file_size": 69,
"file_type": "text/plain",
"file_type_description": "EICAR virus test files",
"process_info": {
"blocked_reason": "Infected",
"progress_percentage": 100,
"result": "Blocked"
},
"progress_percentage": 100,
"scan_all_result_a": "Infected",
"scan_all_result_i": 1,
"scanned_with": 2
},
],
"first_index": 0,
"page_size": 20,
"worst_data_id": "7cb298eb42614ca9bc87a4de4acad436"
},
"file_info": {
"display_name": "samplezip.tar.gz",
"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": "eicar",
"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",
"eng_id": "engine1_1_linux",
"location": "local",
"scan_result_i": 0,
"scan_time": 1,
"wait_time": 3,
"threat_found": ""
},
"Engine2": {
"def_time": "2015-08-10T00:00:00.000Z",
"eng_id": "engine2_1_linux",
"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": {
"blocked_reason": "Infected",
"file_type_skipped_scan": false
"outdated_data": [
"enginedefinitions"
],
"post_processing": {
"actions_ran": "",
"actions_failed": "",
"converted_to": "",
"copy_move_destination": "",
"converted_destination": ""
},
"processing_time": 400,
"progress_percentage": 100,
"user_agent": "webscan",
"profile": "File scan",
"queue_time": 20,
"result": "Blocked",
},
"vulnerability_info": {...},
"yara_info":{...}
}

Completed response description with archive detection:

  • extracted_files: information about extracted files

    • files_extracted_count: the number of extracted files

    • files_in_archive: array of files in archive

      • detected_by: number of engines reported threat

      • scanned_with: number of engines used for scanning the file

    • first_index: it tells that from which file (index of the file, 0 is the first) the result JSON contains information about extracted files. (default=0)

    • page_size: it tells how many files the result JSON contains information about (default=20). So by default, the result JSON contains information about the first 20 extracted files.

    • worst_data_id: data id of the file that has the worst result in the archive

  • scan_results

    • last_file_scanned (stored only in memory, not in database): If available, the name of the most recent processed file

Response (not existing data_id)

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.

Retrieving Scan Reports Using Data ID containing all files in archive

Using this method under extracted_files key all the info about extracted files will be listed recursively.

Request

Value

Method

GET

URL

/archive/{data_id}

Successful response containing all extracted files

HTTP status code: 200

{
"data_id": "8a8150d5b2aa4367be44f4a19c8dbb57",
"dlp_info": {},
"file_info": {
"display_name": "testzip.zip",
"file_size": 480,
"file_type": "application/zip",
"file_type_description": "ZIP Archive",
"md5": "0197200212f86efb5ac23150feab45c0",
"sha1": "084b89478b099a98971f62dc3aacbf3f7808d1a4",
"sha256": "9f6e906a3c4c8581687a63fb768bca244081e9940dc43a07a9cc6cb073e1a52a",
"upload_timestamp": "2019-03-25T07:48:25.003Z"
},
"process_info": {
"blocked_reason": "",
"file_type_skipped_scan": false,
"post_processing": {
"actions_failed": "",
"actions_ran": "",
"converted_destination": "",
"converted_to": "",
"copy_move_destination": ""
},
"processing_time": 79,
"profile": "File process",
"progress_percentage": 100,
"queue_time": 3,
"result": "Allowed",
"user_agent": "webscan",
"verdicts": [
"No Threat Detected"
]
},
"scan_results": {
"data_id": "8a8150d5b2aa4367be44f4a19c8dbb57",
"progress_percentage": 100,
"scan_all_result_a": "No Threat Detected",
"scan_all_result_i": 0,
"scan_details": {},
"start_time": "2019-03-25T07:48:25.006Z",
"total_avs": 1,
"total_time": 76
},
"vulnerability_info": {
"verdict": 0
},
"yara_info": {},
"extracted_files": [
{
"data_id": "3b503f416a1d40ffacf79a8141baa1e7",
"dlp_info": {},
"file_info": {
"display_name": "test.zip",
"file_size": 168,
"file_type": "application/zip",
"file_type_description": "ZIP Archive",
"md5": "9a061b387f4d94babe13be5aa7c80077",
"sha1": "b70a3bcaa67217b410211a8e6511c8f14b571ce1",
"sha256": "1af488779d0fabf4b4bc7d920627d85c7256b4241bfda486cec6ba278eea1192",
"upload_timestamp": "2019-03-25T07:48:25.013Z"
},
"process_info": {
"blocked_reason": "",
"file_type_skipped_scan": false,
"post_processing": {
"actions_failed": "",
"actions_ran": "",
"converted_destination": "",
"converted_to": "",
"copy_move_destination": ""
},
"processing_time": 69,
"profile": "File process",
"progress_percentage": 100,
"queue_time": 5,
"result": "Allowed",
"user_agent": "webscan",
"verdicts": [
"No Threat Detected"
]
},
"scan_results": {
"data_id": "3b503f416a1d40ffacf79a8141baa1e7",
"progress_percentage": 100,
"scan_all_result_a": "No Threat Detected",
"scan_all_result_i": 0,
"scan_details": {
"ClamAV": {
"def_time": "2019-03-24T08:46:29.000Z",
"eng_id": "clamav_1_linux",
"location": "local",
"scan_result_i": 0,
"scan_time": 3,
"threat_found": "",
"wait_time": 2
}
},
"start_time": "2019-03-25T07:48:25.018Z",
"total_avs": 1,
"total_time": 55
},
"vulnerability_info": {
"verdict": 0
},
"yara_info": {},
"extracted_files": [
{
"data_id": "1014ec91e0b246489fa357ce1d02f8b1",
"dlp_info": {},
"file_info": {
"display_name": "test.txt",
"file_size": 2,
"file_type": "text/plain",
"file_type_description": "ASCII text",
"md5": "60b725f10c9c85c70d97880dfe8191b3",
"sha1": "3f786850e387550fdab836ed7e6dc881de23001b",
"sha256": "87428fc522803d31065e7bce3cf03fe475096631e5e07bbd7a0fde60c4cf25c7",
"upload_timestamp": "2019-03-25T07:48:25.025Z"
},
"process_info": {
"blocked_reason": "",
"file_type_skipped_scan": false,
"post_processing": {
"actions_failed": "",
"actions_ran": "",
"converted_destination": "",
"converted_to": "",
"copy_move_destination": ""
},
"processing_time": 47,
"profile": "File process",
"progress_percentage": 100,
"queue_time": 4,
"result": "Allowed",
"user_agent": "webscan",
"verdicts": [
"No Threat Detected"
]
},
"scan_results": {
"data_id": "1014ec91e0b246489fa357ce1d02f8b1",
"progress_percentage": 100,
"scan_all_result_a": "No Threat Detected",
"scan_all_result_i": 0,
"scan_details": {
"ClamAV": {
"def_time": "2019-03-24T08:46:29.000Z",
"eng_id": "clamav_1_linux",
"location": "local",
"scan_result_i": 0,
"scan_time": 0,
"threat_found": "",
"wait_time": 4
}
},
"start_time": "2019-03-25T07:48:25.029Z",
"total_avs": 1,
"total_time": 35
},
"vulnerability_info": {
"verdict": 0
},
"yara_info": {}
}
]
},
{
"data_id": "a80f3b43192843f28998abcfe073c3be",
"dlp_info": {},
"file_info": {
"display_name": "test.txt",
"file_size": 2,
"file_type": "text/plain",
"file_type_description": "ASCII text",
"md5": "60b725f10c9c85c70d97880dfe8191b3",
"sha1": "3f786850e387550fdab836ed7e6dc881de23001b",
"sha256": "87428fc522803d31065e7bce3cf03fe475096631e5e07bbd7a0fde60c4cf25c7",
"upload_timestamp": "2019-03-25T07:48:25.012Z"
},
"process_info": {
"blocked_reason": "",
"file_type_skipped_scan": false,
"post_processing": {
"actions_failed": "",
"actions_ran": "",
"converted_destination": "",
"converted_to": "",
"copy_move_destination": ""
},
"processing_time": 33,
"profile": "File process",
"progress_percentage": 100,
"queue_time": 3,
"result": "Allowed",
"user_agent": "webscan",
"verdicts": [
"No Threat Detected"
]
},
"scan_results": {
"data_id": "a80f3b43192843f28998abcfe073c3be",
"progress_percentage": 100,
"scan_all_result_a": "No Threat Detected",
"scan_all_result_i": 0,
"scan_details": {
"ClamAV": {
"def_time": "2019-03-24T08:46:29.000Z",
"eng_id": "clamav_1_linux",
"location": "local",
"scan_result_i": 0,
"scan_time": 0,
"threat_found": "",
"wait_time": 1
}
},
"start_time": "2019-03-25T07:48:25.015Z",
"total_avs": 1,
"total_time": 23
},
"vulnerability_info": {
"verdict": 0
},
"yara_info": {}
}
]
}

Using this method the following fields will not be shown compared to /file request containing extracted files

  • files_extracted_count

  • files_in_archive

  • first_index

  • page_size

  • worst_data_id

Also the "outdated_data" field will only be shown in the root archive.

Response (not existing data_id)

HTTP status code: 200

{
"61dffeaa728844adbf49eb090e4ece0e": "Not Found"
}

Response (requested file is not an archive)

HTTP status code: 200

{
"61dffeaa728844adbf49eb090e4ece0e": "Invalid request"
}

Error response

Unexpected event on server

HTTP status code: 500

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