3.10. External Scanners And Post Actions

Under Inventory menu it is possible to configure custom External Scanners and custom Post Actions.

For both these options we must enter two fields:

  • a unique name (maximum 16 character ASCII only text)

  • a full path to your executable/interpreter, that will be called by the processing node

images/download/attachments/37416915/image2018-2-12_17-20-12.png

External Scanners

External Scanners are handled as scan engines from product side but are not updatable through the product.

Specification for external scanner process

  • INPUT

    • on standard input it gets the currently available scan result JSON without the extracted_files field

    • as last argument on the command line it gets the absolute path for the file to scan

  • OUTPUT

    • if everything goes well return value must be 0, non-zero return value indicates this scanner Failed.

    • scan result must be put on standard output in JSON format with the following fields

      • def_time: the definition time of this scanner in milliseconds since epoch that will be displayed by Metadefender Core V4

      • scan_result_i: the scan verdict for the file, see https://onlinehelp.opswat.com/corev3/Description_of_Scan_Results.html

      • threat_found: the found threat's description if any

      • If any of the above fields is missing or invalid, the result will automatically be Failed for this scanner

Number of External Scanners is a separately licensed feature. If you plan to use this feature please contact your OPSWAT reseller.

Example for a Custom Scanner

images/download/attachments/37416915/image2017-5-2_9-59-31.png

Example input for a Custom Scanner

{
"data_id": "091c07fe6203479983682f3b4a491ee6",
"file_info": {
"display_name": "archive.zip",
"file_size": 2123967,
"file_type": "application\/zip",
"file_type_description": "ZIP compressed archive",
"md5": "ec8fa3c2897c0956f0e9ed5c092310b9",
"sha1": "0027fc18ed97063387bca9c518a02a6faba85c38",
"sha256": "4fb0083cd3cd966817c1ee4fa3f02519d05eca0b57c2bf71109d3bd69acebd41",
"upload_timestamp": "2017-04-27T13:05:20.435Z"
},
"process_info": {
"blocked_reason": "Infected",
"file_type_skipped_scan": false,
"post_processing": {
"actions_failed": "",
"actions_ran": "",
"converted_destination": "",
"converted_to": "",
"copy_move_destination": ""
},
"profile": "File scan",
"progress_percentage": 100,
"result": "Blocked",
"user_agent": "webscan"
},
"scan_results": {
"data_id": "091c07fe6203479983682f3b4a491ee6",
"progress_percentage": 100,
"scan_all_result_a": "Infected",
"scan_all_result_i": 1,
"scan_details": {
"ClamAV": {
"def_time": "2017-04-27T06:59:21.000Z",
"location": "local",
"scan_result_i": 1,
"scan_time": 51,
"threat_found": "Win.Trojan.Trojan-1082 FOUND"
}
},
"start_time": "2017-04-27T13:05:20.471Z",
"total_avs": 1,
"total_time": 1444
},
"vulnerability_info": {}
}

Example valid output of a Custom Scanner

{
"def_time": 1491288912392,
"scan_result_i": 0,
"threat_found": ""
}

Example scan result where External Scanner found the file to be clean

...
"scan_results": {
"data_id": "091c07fe6203479983682f3b4a491ee6",
"progress_percentage": 100,
"scan_all_result_a": "Infected",
"scan_all_result_i": 1,
"scan_details": {
"ClamAV": {
"def_time": "2017-04-27T06:59:21.000Z",
"location": "local",
"scan_result_i": 1,
"scan_time": 51,
"threat_found": "Win.Trojan.Trojan-1082 FOUND"
},
"ExtScn_01": {
"def_time": "2017-02-27T05:19:11.000Z",
"location": "local",
"scan_result_i": 0,
"scan_time": 10,
"threat_found": ""
}
},
"start_time": "2017-04-27T13:05:20.471Z",
"total_avs": 1,
"total_time": 1444
...

Post Actions

Post Actions run after the scan of the file for any post functionality such as copying the file etc...

Specification for post action process

  • INPUT

    • on standard input it gets the currently available scan result JSON without the extracted_files field

    • as last argument on the command line it gets the absolute path for the file

  • OUTPUT

    • if everything goes well return value must be 0, non-zero return value indicates this action Failed.

Adding a Post Action is the same as in case of an External Scanner. The only difference is in the result handling.

All executed Post Action's result will be on the process_info.post_processing object of the scan result JSON. If the return value
of an action is zero it will be shown in the actions_ran field, if the return value of the action is non-zero then it will be listed in the actions_failed field.

Example of a Post Action

images/download/attachments/37416915/image2017-5-2_10-19-8.png

The scan result JSON if the Post Action returns 0

...
"process_info": {
"blocked_reason": "Infected",
"file_type_skipped_scan": false,
"post_processing": {
"actions_failed": "",
"actions_ran": "Pst_Act_01",
"converted_destination": "",
"converted_to": "",
"copy_move_destination": ""
},
"profile": "File scan",
"progress_percentage": 100,
"result": "Blocked",
"user_agent": "webscan"
},
...

The scan result JSON if the Post Action returns non-zero

...
"process_info": {
"blocked_reason": "Infected",
"file_type_skipped_scan": false,
"post_processing": {
"actions_failed": "Pst_Act_01 failed",
"actions_ran": "",
"converted_destination": "",
"converted_to": "",
"copy_move_destination": ""
},
"profile": "File scan",
"progress_percentage": 100,
"result": "Blocked",
"user_agent": "webscan"
},
...