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

Note: Since MetaDefender Core 5.2.2, External Scanner and Post Action no longer apply to all the requests. It now binds to Workflow. Therefore, after creating either External Scanner or Post Action, we need to add them into our desired Workflow Rules or Workflow Templates.

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
    • If the command path contains space character, then must nest the command path into double quote. For example: "C:\Test Space\Hello.exe"

  • OUTPUT

    • If everything goes well, the return value must be 0; otherwise, to indicate that the scanner has Failed, a value in the range of 1 to 255 on Linux and 1 to 2,147,483,647 on Windows should be returned.
    • 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
      • scan_result_i: the scan verdict for the file, see the GET Fetch Analysis ResultAPI > scan_all_result_i
      • 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

Example input for a Custom Scanner

response.json
Copy

Example valid output of a Custom Scanner

JSON
Copy

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

JSON
Copy

Post Actions

Post Actions (PA) 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, the return value must be 0; otherwise, to indicate that the action has Failed, a value in the range of 1 to 255 on Linux and 1 to 2,147,483,647 on Windows should be returned.

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.

Two types of Post Action

Currently, MetaDefender Core supports two types of Post Action: Sub-process and Webhook.
  • Sub-process: MetaDefender Core will call the PA as a sub-process
  • Webhook: MetaDefender Core will call a POST request to customers' self-hosted server (customers needs to deploy and maintain this server)

Example of a Sub-process Post Action

The scan result JSON if the Post Action returns 0

The field post_action will look like this

JSON
Copy
JSON
Copy

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

JSON
Copy

Example of a Webhook Post Action

When a file is done, MetaDefender Core will call a POST request to the Callback URL, in this case http://mypaserver.com:8888

MetaDefender Core will wait for a timeout, that can easily configure via each workflow settings, under the tab "Post Action"

Specification for post action webhook

INPUT

MetaDefender Core will send this body (json) to PA webhook server

JSON
Copy

Please note that current_processing_result_of_file (that webhook server received) is just the current result of the file (has not done yet), so the processing_time will be -1

If you want to read the file in resource_path the webhook server need to be on the same machine of MetaDefender Core

OUTPUT

If everything goes well, the return value must be 200 HTTP status code; other status code rather than 200 will be consider at Failed.

The value of post_action.details.return_value will be the status of return code of webhook server.

For example: MetaDefender Core call POSThttp://mypaserver.com:8888`` the server return 200 -> post_action.details.return_value = 200

Example details of a file when run with PA - webhook

JSON
Copy
Type to search, ESC to discard
Type to search, ESC to discard
Type to search, ESC to discard
Next to read:
Hardening External Scanner and Post Action feature
On This Page
External Scanners And Post ActionsExternal ScannersExample for a Custom ScannerExample input for a Custom ScannerExample valid output of a Custom ScannerExample scan result where External Scanner found the file to be cleanPost ActionsTwo types of Post ActionExample of a Sub-process Post ActionThe scan result JSON if the Post Action returns 0The scan result JSON if the Post Action returns non-zeroExample of a Webhook Post ActionSpecification for post action webhook