Fetch Scan 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}

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",
"location": "local",
"scan_result_i": 0,
"scan_time": 1,
"wait_time": 1,
"threat_found": ""
},
"Engine2": {
"def_time": "2015-08-10T00:00:00.000Z",
"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": {...}
}

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

      • 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 Vulnerability Info In Scan 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)

Possible overall and per engine scan results

scan_result_a

scan_result_i

No Threat Detected

0

Infected

1

Suspicious

2

Failed

3

Cleaned / Deleted

4

Scan Skipped - Whitelisted

7

Scan Skipped - Blacklisted

8

Exceeded Archive Depth

9

Not Scanned

10

Encrypted Archive

12

Exceeded Archive Size

13

Exceeded Archive File Number

14

Password Protected Document

15

Exceeded Archive Timeout

16

Filetype Mismatch

17

Potentially Vulnerable File

18

Canceled

19

Sensitive data found

20

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,
"scanned_with": 10
},
{
"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,
"scanned_with": 10
},
]
},
"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": "example.pdf",
"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": 10,
"total_time": 389
}
"process_info": {
"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",
"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

      • scanned_with: number of engines used for scanning the file

  • scan_results

    • last_file_scanned: 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.