2. Response Description

Top levels of Process Result

data_id

Metadefender provides asynchronous API calls (stateless) and data_id is used for identifying a specific process job. It is obtained from initial data (e.g., file) upload and can be used any time as long as scan history is preserved on the server side. It is generated randomly from the server and guaranteed to be unique so it can be used without worrying about having duplicate data_id. Not applicable for hash look up.

scan_results

scan result from each engines along with other metadata for scanning job.

file_info

static file information and analyzed file type based on contents

process_info

overall process status and information including applied workflow and action results such as sanitization.

extracted_files

list of files inside of an archive file. If file is not an archive file or not extracted, this block will not be present.

Minimum Required Parsing Process Results ( process_info)

This only applies if you are using workflow-based process.

There should always process_info field for process JSON message.

  1. Clients should use process_info.progress_percentage to know whether the process has been finished or still in progress.

  2. Clients should use process_info.result to check whether the file processed is allowed or blocked.

  3. When file is allowed, process_info.blocked_reason is empty string. If file is blocked, clients should use the field to retrieve detailed block reasons

  4. Clients should use process.profile to retrieve which profile is used when processing.

Clients should use process_info.file_type_skipped_scan to know if the input file's detected type is configured to skip scanning

If post processing is configured and applied, there will be process.post_processing field in JSON result. Clients should always check whether this field exists or not to find out if post_processing has been applied or not.

  1. If process_info.post_processing exists, clients could use process.post_processing.action_ran to check what actions have been applied and these actions are separated by "|". See details in [Description of Response]

  2. If process_info.post_processing exists, clients could use process.post_processing.action_failed to check which post_processing failed.

  3. If "Move" is in "action_ran", clients should check process.post_processing.converted_to to retrieve information of the target file type. And clients should call /file/converted/{data_id} to retrieve link to download converted files

  4. if "Copied" or "Moved" is in "action_ran", clients should check process.post_processing.copy_or_move_destination for the target directory info

Response Details For process_info

process_info

 

Process node

Only applied if user scanned with user_agent

progress_percentage

Percentage of processing completed

Scale of 0-100

user_agent

A string which identifies the user. This is used for mapping to a specific workflow.

 

profile

The profile name. This is what the user_agent mapped to.

 

result

The final result of processing the file

Possible values:

Possible Process Results (COM)

"Not processed": default value set in REST before the file is processed by Core

blocked_reason

The reason for a file being blocked

Possible list values:

"null": default value set in REST before the file is processed by Core

file_type_skipped_scan

Indicates if the input file's detected type was configured to skip scanning

JSON Boolean type

post_processing

Post processing node

Exists only if post processing was configured

actions_ran

List of post processing actions ran

Delimited by " | "

Possible list values: "Sanitized | Copied | Moved | Quarantined | Deleted | Ran Script"

*Copied and Moved will never exist together
*Quarantined and Deleted will never exist together
*(Copied/Moved) and (Quarantined/Deleted) will never exist together

actions_failed

List of post processing actions that failed

Delimited by " | "

Possible list values: "Sanitization Failed | Copy Failed | Move Failed | Quarantine Failed | Delete Failed | Ran Script Failed"

*Copy Failed and Move Failed will never exist together
*Quarantine Failed and Delete Failed will never exist together
*(Copy/Move Failed) and (Quarantine/Delete Failed) will never exist together

converted_to

Extension the file was converted to

If the string contains a file type, the converted file can be downloaded

copy_move_destination

Destination to where the file was copied/moved

 

converted_destination

Location where the converted file exists

 

Response Details For scan_results and others

file_id

Populated only when files are configured to be stored. Not applicable for hash look up. This is unique per file so if same file is scanned twice, file_id would be identifical.

scan_result

Global scan results, meta data, and scan reports from all engines.

file_info

File metadata, hash value, analyzed file types

scan_details

Array of scan results for engines

scan_result_i

See table below for descriptions

threat_found

Name of threat if detected by engine. Non ASCII characters removed.

def_time

Definition time of engine at the time of scan

scan_time

Elapsed scan time in mili-seconds per engine

rescan_available

This value will be set to true

  • if engine definition has changed.

  • any engine is missing scan results such as "failed to scan", "not scanned"

scan_all_result_i

See table below for descriptions

total_time

Elapsed scan time in milli-seconds from when scan is initiated with the first engine until the last engine has completed.

total_avs

Number of engines used for scanning

progress_percentage

Indicator if scan is in progress

in_queue

How many files are in queue before this scan request: 0 means it is being scanned or finished scanning.

upload_timestamp

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

file_type_category

High level categorization of file type see reference for descriptions

Additional Information For An Archive File

Note: Only applied when scanning an archive file

original_file

Basic information and reference to the data_id of the original file (actual archive file, not the extracted contents)

Object Structure
"original_file": {
"data_id": "96c7ce8170224bd29c427ec913e3d00b",
"scan_result_i": 1,
"progress_percentage": 100,
"detected_by": 1
}

extracted_files

Basic information about the included files in the archive can be found in the files_in_archive property.

  • Files_in_archive only contains maximum 20000 results.

  • Entries with a non-zero scan_result_i always appear first.

  • More information about individual entries can be queried with the data_id

The data_id under extracted_files is the reference to the engines summary or consolidated result for the archive

Object Structure
"extracted_files": {
"data_id": "e511f16da3cc422eaa4127ed88ee9446",
"scan_result_i": 0,
"progress_percentage": 100,
"detected_by": 0,
"files_in_archive": [{
"display_name": "\\U6367872802.exe",
"data_id": "c421c7cfc5c34733ad037116cfe2b6f3",
"scan_result_i": 0,
"progress_percentage": 100,
"file_size": -1,
"file_type": "",
"detected_by": 0
}
]
}

parent_data_id

When the scan result for a file within an archive is queried, this refer to the containing archive file.

Available Scan Results (scan_result_i, scan_all_result_i)

value

short description

long description

0

No Threats Found

No threat detection or the file is empty

1

Infected/Known

Threat is found

2

Suspicious

Classified as possible threat but not identified as specific threat.

3

Failed To Scan

Scanning is not fully performed (For example, invalid file or no read permission). If no engine is included and scan is enabled, this will be the final result.

4

Cleaned / Deleted

Threat is found and file is cleaned (repaired or deleted): repair is not supported yet

5

Unknown

Unknown signature. NOTE: this is only used in multiple hash lookup. For single hash lookup, scan_result_* are not returned as response. see Retrieve scan report by hash (duplicate) for more details.

6

Quarantined

File is quarantined

7

Skipped Clean

Scan is skipped because this file type is in white-list*

8

Skipped Infected

Scan is skipped because this file type is in black-list*

9

Exceeded Archive Depth

Threat is not found but there are more archive levels which were not extracted.

10

Not Scanned / No scan results

Scan is skipped by the engine either due to update or other engine specific reason. If scan is disabled, this will be the final result.

11

Aborted

The current scan was stopped by the server

12

Encrypted

File/buffer is not scanned because the file type is detected as encrypted (password-protected). If the Internal Archive Library is ON encrypted return type is not going to be returned through Metascan scan progress callbacks since the engines do not perform any scan operations. If the Internal Archive Library is OFF Metascan will pass the encrypted files to the engines directly, bypassing the detection.

13

Exceeded Archive Size

The extracted archive is too large to scan

14

Exceeded Archive File Number

There are more files in the archive than configured on the server

15

Password Protected Document

Document that is protected by a password [e.g., Office documents or PDFs that require a password to view its contents]. If a file is password protected document, no sanitization will be applied.

Metadefender Core supports detecting password protected document. Here is example of file extension we have tested. If any file extension is not listed here, use https://www.metadefender.com for you to test.

PDF, DOCX, DOC, DOCM, DOTX, DOTM, DOT, PPTX, PPT, POT, POTM, POTX, PPS, PPSM, PPSX, PPTM, PPTX, XLSX, XLS, XLSM, XLSB,XLS, XLTX, XLTM, XLT, XLAM, XLA

17

Mismatch

The file's extension does not match the detected file type. Only applicable when using workflows.

18

Potentially Vulnerable File

 

255

In Progress

 

Scan not started

This means the file has not yet been sent to the engines for scanning. The progress_percentage value will be 0 and the in_queue value will be non zero.

scan_results.scan_all_result_i = -1

scan_results.scan_all_result_a = ""

Scan partially completed

This means some engines have returned results but there are still more remaining. This progress_percentage value will be greater then 0 and less than 100.

  • Accumulated result at the time scan result was queried.

Scan is disabled or skipped

This means the request is complete but scanning has been disabled or has been skipped for some other reason such as file type mismatch. The progress_percentage value will be 100.

scan_results.scan_all_result_i = 100

scan_results.scan_all_result_a = "Not Scanned"

This is same as other Metascan interface such as COM interface and Java interface.

Available File Type Categories (file_type_category)

Mark

Note

"E"

Executable (EXE, DLL, …)

"D"

Document (MS Office word document, MS Office excel sheet)

"A"

Archive (Zip, Rar, Tar, …)

"G"

Graphical format (Jpeg, GIF, TIFF, BM P, …)

"T"

Text

"P"

PDF format

"M"

audio or video format

"Z"

mail messages (MSG, …)

"I"

Disk image

"O"

Other (anything that is not recognize d as one of the above)

Response Example

Status: 200
{
"extracted_files": {
"data_id": "b3a0949e833840128a346fdd7ec42477",
"scan_result_i": 0,
"detected_by": 8,
"files_in_archive": [
{
"display_name": "\\\\eicar.com",
"data_id": "372d93b94be04ed89da2a7d938b72452",
"file_type": "-",
"scan_result_i": 1,
"detected_by": 4,
"progress_percentage": 100,
"file_size": 68
},
{
"display_name": "\\\\Printout.pdf",
"data_id": "6acba97776694ac89b8e3c573439bfbe",
"file_type": "PDF/AI",
"scan_result_i": 0,
"detected_by": 0,
"progress_percentage": 100,
"file_size": 246121
}
]
},
"file_id": "",
"scan_results": {
"scan_details": {
"Ahnlab": {
"threat_found": "EICAR_Test_File",
"scan_result_i": 1,
"def_time": "2016-08-03T00:00:00Z",
"scan_time": 1
},
"Avira": {
"threat_found": "",
"scan_result_i": 0,
"def_time": "2016-08-03T00:00:00Z",
"scan_time": 15
},
"ClamAV": {
"threat_found": "Heuristics.PDF.ObfuscatedNameObject",
"scan_result_i": 1,
"def_time": "2015-07-03T00:00:00Z",
"scan_time": 31
},
"ESET": {
"threat_found": "",
"scan_result_i": 0,
"def_time": "2016-08-03T00:00:00Z",
"scan_time": 1
}
},
"rescan_available": false,
"data_id": "c0983103f31f4e74889cc7188f6c0cdd",
"scan_all_result_i": 1,
"start_time": "2016-08-03T17:08:52.949Z",
"total_time": 31,
"total_avs": 4,
"progress_percentage": 100,
"in_queue": 0,
"scan_all_result_a": "Infected"
},
"file_info": {
"file_size": 2073,
"upload_timestamp": "2016-08-03T17:08:52.949Z",
"md5": "4D6B72DDC54514F82DDCDDA2E9923AAF",
"sha1": "7B7B5487948E4EDC1AF62539ABF0DD72B456D03E",
"sha256": "1A90EA551EE596F357794DFF314F042D84A9AFC3D56ED2C995A4908395CBABBC",
"file_type_category": "P",
"file_type_description": "Adobe Portable Document Format",
"file_type_extension": "pdf/ai",
"display_name": "1470244133_dirty_315.pdf",
"original_file_path": ""
},
"process_info": {
"post_processing": {
"actions_ran": "Sanitized",
"actions_failed": "",
"converted_to": "pdf",
"copy_move_destination": "",
"converted_destination": "toConvert_[sanitized].pdf"
},
"progress_percentage": 100,
"user_agent": "cactus",
"profile": "default",
"result": "Blocked",
"blocked_reason": "Dirty",
"file_type_skipped_scan": false
},
"data_id": "c0983103f31f4e74889cc7188f6c0cdd",
"rescan_count": 0,
"source": "10.0.50.37",
"scanned_on": "10.0.50.52"
}