software.opswat.comsoftware.opswat.com/metascan/Documentation/Metascan/documen… · File Scan...

Metadefender Core 3.12.2 Product Documentation


1


Table of Contents Copyright ......................................................................................................................... 5 About This Guide ............................................................................................................ 6

Feedback ..................................................................................................................... 6 Installing or Upgrading Metadefender Core ..................................................................... 7

Installation Packages ................................................................................................... 7 Metadefender Core Installation Packages ............................................................... 7 Optional Components .............................................................................................. 7

Installing Metadefender Core ....................................................................................... 8 Metadefender Core Installation Options ................................................................... 8 Installing Metadefender Core using the Install Wizard ............................................. 8 Installing Metadefender Core using the Command Line .......................................... 9

Upgrading Metadefender Core .................................................................................. 11 Upgrading from version 3.5 or earlier ..................................................................... 12

Metadefender Core Licensing .................................................................................... 12 Activating Metadefender Core Licenses ................................................................. 12 License Manager CLI ............................................................................................. 21

Installing Metadefender Client for Linux Using the Command Line ............................... 25 Preliminary Notes ...................................................................................................... 25 Debian Package (.deb) .............................................................................................. 25 Red Hat Enterprise Linux/CentOS Package (.rpm).................................................... 25 Usage ........................................................................................................................ 25

Command .............................................................................................................. 25 Options ................................................................................................................... 25 Example ................................................................................................................. 26

Configuring Metadefender Core .................................................................................... 27 Metadefender Core Configuration Tools .................................................................... 27

Metadefender Core Management Console ............................................................ 27 Command Line Utility ............................................................................................. 27 omsConfig.ini ......................................................................................................... 28 omsConfig.exe ....................................................................................................... 28

Multi-scanning Configuration ..................................................................................... 28 Multi-scanning Configuration .................................................................................. 29 Engine Configuration .............................................................................................. 29 Workflow Configuration .......................................................................................... 33 Caching .................................................................................................................. 40 Scan Configuration ................................................................................................. 41 ScanEx Configuration ............................................................................................ 43 Data Sanitization .................................................................................................... 46

Metadefender Core Sources Configuration ............................................................... 47 Metadefender Client Configuration ......................................................................... 47 Installing Metadefender Client for Linux Using the Command Line ........................ 51 Metadefender Proxy Configuration ......................................................................... 52 Metadefender Email Configuration ......................................................................... 54

Logging ...................................................................................................................... 62

2


File Scan History .................................................................................................... 62 Metadefender Core System Events ....................................................................... 63 Windows Event Log ............................................................................................... 64 Configuration .......................................................................................................... 65 Debug Logging ....................................................................................................... 67

Quarantine ................................................................................................................. 67 Using Metadefender Proxy ........................................................................................ 67

Use Cases ............................................................................................................. 68 Blue Coat ProxySG integration .............................................................................. 68 Squid Integration .................................................................................................... 74 F5 Big-IP Integration .............................................................................................. 76 Other Proxy Servers ............................................................................................... 79 Metadefender Proxy Management ......................................................................... 79 Reference and useful links for ICAP ...................................................................... 85 Sample ICAP requests and responses .................................................................. 85

Advanced Configuration Options ............................................................................... 86 Additional Command Line Functionality ................................................................. 86 Post Action Script ................................................................................................... 88 Engine Specific Configuration ................................................................................ 91 Special Tools ......................................................................................................... 92 REST Server Configuration .................................................................................... 95 RAM Disk Configuration ....................................................................................... 103 Hardening Options ............................................................................................... 104 Database Configuration ....................................................................................... 105

Metadefender Core Developer Guide .......................................................................... 107 System Integration Requirement ............................................................................. 107

System Requirements for Metadefender Core ..................................................... 107 Browser Requirements for the Metadefender Core Management Console .......... 107

Integration Upgrade Tips ......................................................................................... 108 Important Concepts and Terminology ...................................................................... 108

Usable AVs (Usable AMs) .................................................................................... 108 Current AVs ......................................................................................................... 108 Synchronous/Asynchronous Scan ....................................................................... 109 Valid File Name .................................................................................................... 109

Programming with Metadefender Core .................................................................... 110 Selecting Where Metadefender Core Is Installed ................................................. 110 Select Your API .................................................................................................... 111

Metadefender Core Command Line Utility ............................................................... 111 Metadefender Core COM API .................................................................................. 114

Overview .............................................................................................................. 114 Scan Outcome Return Type ................................................................................. 115 Other Important Return Types.............................................................................. 116 Metadefender Core Methods ............................................................................... 117 Metadefender Core Deprecated Methods ............................................................ 141 COM Connection Points ....................................................................................... 147

Metadefender Core Web API ................................................................................... 153

3


REST API ............................................................................................................. 153 Using Sample Code ................................................................................................. 189

PHP Sample Code for IIS 7 ................................................................................. 189 ASP Sample ......................................................................................................... 190 Java Sample ........................................................................................................ 191

Building Custom Engines for Metadefender Core .................................................... 192 How to Deploy or Enable Custom Engine ............................................................ 192 C Interface ........................................................................................................... 193 VB NET C Interface with C wrapper ..................................................................... 200 Additional Steps for VB C custom engine ............................................................ 206 When you uninstall or upgrade Metadefender Core ............................................. 206

Metadefender® Core Release Notes .......................................................................... 207

4


Copyright DISCLAIMER OF WARRANTY OPSWAT Inc. makes no representation or warranties, either express or implied by or with respect to anything in this document, and shall not be liable for any implied warranties of merchantability or fitness for a particular purpose or for any indirect special or consequential damages. COPYRIGHT NOTICE OPSWAT, OESIS, Metascan, Metadefender, AppRemover and the OPSWAT logo are trademarks and registered trademarks of OPSWAT, Inc. All other trademarks, trade names and images mentioned and/or used herein belong to their respective owners. No part of this publication may be reproduced, stored in a retrieval system or transmitted, in any form or by any means (photocopying, recording or otherwise) without prior written consent of OPSWAT Inc. No patent liability is assumed with respect to the use of the information contained herein. While every precaution has been taken in the preparation of this publication, OPSWAT Inc. assumes no responsibility for errors or omissions. This publication and features described herein are subject to change without notice.

5


About This Guide Metadefender Core provides a comprehensive framework for systems integrators, enterprise developers, and technology vendors seeking to create malware scanning solutions using multiple anti-malware engines. The purpose of this guide is to introduce you to the flexible configuration options available in Metadefender Core, which can be optimized to best suit your application.

Feedback

For comments and questions regarding this document, please contact OPSWAT on the Support tab at https://portal.opswat.com/.

6

https://portal.opswat.com/


Installing or Upgrading Metadefender Core

Installation Packages

Metadefender Core Installation Packages

Metadefender Core is available in five packages with different embedded anti-malware engines.

Package Embedded anti-malware engines

Metadefender Core 1 ClamAV

Metadefender Core 4 Ahnlab, ESET, Avira, ClamAV

Metadefender Core 8 Everything in Metadefender Core 4 PLUS Total Defense, Quick Heal, Zillya!, Bitdefender

Metadefender Core 12 Everything in Metadefender Core 8 PLUS Ikarus, K7, nProtect, AVG

Metadefender Core 16 Everything in Metadefender Core 12 PLUS Kaspersky, F-Prot, Emsisoft, Virusblokada

Metadefender Core 20 Everything in Metadefender Core 16 PLUS McAfee, Sophos, NANOAV, Vir.IT eXplorer

In addition to the standard Metadefender Core installation there are optional components which can be installed based on your needs.

Optional Components

• RAM drive

Note: Sample integration code, documentation, and other useful utilities are available under Downloads at https://portal.opswat.com/

Note: RAM drive installation will appear in a separate pop-up window. Click Install to continue the installation of the RAM drive component.

7



Installing Metadefender Core

Metadefender Core Installation Options

All Metadefender Core packages can be installed in two ways:

Windows Install Wizard Command Line

Note: OPSWAT recommends installing Metadefender Core with Administrator privileges.

Installing Metadefender Core using the Install Wizard

To install Metadefender Core using the Install Wizard, follow the steps listed here:

1. Locate the Metadefender Core Installation File. If this was not provided to you by OPSWAT, it can be found here.

Note: This file will be named Metadefender_Core_<X>_<Y>_<Z>.exe’ where <X> is the Metadefender Core package you are installing, <Y> is the version of Metadefender Core, and <Z> is the build number.

2. Double-click on the desired Metadefender Core Installation File to launch the Metadefender Core installer. If this does not work, right-click on the file and select “Open”. 3. Follow the on-screen instructions.

8

https://my.opswat.com/hc/en-us/articles/202357070-Metascan


a. Choose install directory (we recommend that you accept the default location). b. For any components you would like to add / remove from the installation, click on the ‘Drive’ symbol which appears next to each one to open a drop-down menu. From here, you can choose whether to install them or make them unavailable. c. Once satisfied with your components, click ‘Next’ and then ‘Install’.

Installing Metadefender Core using the Command Line

Note: Installing Metadefender Core from the command line requires Windows Installer 3.0 or higher.

Command Line Options

The following command line options are available with Metadefender Core. Note: The packages column indicates which Metadefender Core package(s) each command line switch is available for: 1, 4, 8, 12, 16, 20, ALL. Note: All arguments are case sensitive.

Command Line Option Description Example Packages

/install Install Metadefender Core

c:\metadefender_core.exe /install ALL

/uninstall Uninstall Metadefender Core

c:\metadefender_core.exe /uninstall ALL

/log <log-file-name> Create installation log file

c:\metadefender_core.exe /log c:\omsinst.log ALL

/quiet Run Metadefender Core installation silently

c:\metadefender_core.exe /silent

ALL

INSTALLLOCATION=<install-path>

Sets the installation location for Metadefender Core

c:\metadefender_core.exe /i c:\Metascan.msi INSTALLLOCATION="c:\Metascan"

ALL

ADDLOCAL=<comma-separated-feature-list>

Install selected features

c:\metadefender_core.exe ADDLOCAL="RamdrvSupport, EsetEng,CaEng"

ALL

9


only. Please see table below for list of features.

REST=0 This will avoid IIS Express, the webserver and all features that rely on the webserver to work. This includes all REST APIs, Web Management Console, Mail Agent & Metascan Client

c:\metadefender_core.exe REST=0 ALL

Note: All feature names below are case-sensitive.

Feature Name Description Packages

RamdrvSupport RAM Drive ALL

RestSvcE Metascan REST Server ALL

Docs Documentation ALL

MetascanClient Metascan Client ALL

ClamavEng ClamAV scan engine ALL

AhnlabEng Ahnlab scan engine 4, 8, 12, 16, 20

AviraEng Avira scan engine 4, 8, 12, 16, 20

EsetEng ESET scan engine 4, 8, 12, 16, 20

CaEng Total Defensescan engine 8, 12, 16, 20

ZillyaEng Zillya! scan engine 8, 12, 16, 20

QuickhealEng Quick Heal scan engine 8, 12, 16, 20

BitDefenderEng BitDefender scan engine 8, 12, 16, 20

IkarusEng Ikarus scan engine 12, 16, 20

IncaEng nProtect scan engine 12, 16, 20

K7Eng K7 scan engine 12, 16, 20

10


AVGEng AVG scan engine 12, 16, 20

VirusBlokAdaEng VirusBlokAda scan engine 16, 20

EmsisoftEng Emsisoft scan engine 16, 20

FriskEng F-Prot scan engine 16, 20

KasperskyEng Kaspersky scan engine 16, 20

McAfeeEng McAfee scan engine 20

NanoEng NanoAV scan engine 20

SophosEng Sophos scan engine 20

Upgrading Metadefender Core

Unlike certain other programs, when upgrading from one Metadefender Core version to another, you must uninstall the version you currently have and install the newer one. Before doing this, there are certain precautionary steps that can be taken. Please see the steps below to complete a full upgrade:

1. Export Metadefender Core Configuration omsConfig.exe export <directory> [<option>] This will export the Metadefender Core Properties (e.g., max archive size or temporary directory), database settings, REST server settings (e.g., API keys or REST port), SYSLOG settings, and MongoDB settings in zip file. [<option>] is optional, it should be in the format /pass=password

2. Uninstall Metadefender Core through the Control Panel

3. Reboot your system (required only if you had RAM Drive installed)

4. Run the Metadefender Core installer for the version which you are upgrading to

5. Once installation is complete, import the file from step 1 with the following command: omsConfig.exe import <file path> [<option>]

11


Note: omsConfig.exe is installed in the Metadefender Core Installation directory (e.g., c:\program files(x86)\opswat\Metadefender Core 8). Note: If you are upgrading and your previously set management console password stops working perform the following steps:

1. Open the Windows Registry (regedit.exe) 2. Navigate to the Metadefender Core registry hive HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OPSWAT\Metascan 3. Double click on "rest_stat_admin_apikey" string item in the list and erase any value data in it. 4. Restart the Metadefender Core services. (Metascan and Metascan REST)

Upgrading from version 3.5 or earlier

Version 3.5 and versions used a different licensing mechanism that is not supported in the current release of Metadefender Core. To obtain a new license key that will work with the current version of Metadefender Core, please contact [email protected].

Metadefender Core Licensing

Activating Metadefender Core Licenses

Activating Metadefender Core Licenses

All types of Metadefender Core licenses (Server, Custom Engine, Remote Client, etc) are activated through the Metadefender Core Management Console or through the License Manager CLI. Note: This section only applies to serial key-based licenses. If you have NOT received a serial key from OPSWAT and have an older form of licensing, please contact [email protected]. Metadefender Core 1, 4 and 8 packages come with a 15-day evaluation license. For Metadefender Core 12, 16, and 20 trial licenses, please contact [email protected]. Note: Once the evaluation period starts, uninstalling and installing Metadefender Core will NOT extend the evaluation license.

12

mailto:[email protected]




Note: Metadefender Core licenses are strongly bound to the Volume ID, MAC address and NetBIOS name of the computer. Changing any of these attributes will disable Metadefender Core, even if you have not yet activated Metadefender Core with a license. If one of these values has changed, please contact support at [email protected] to receive a new license. Note: For information on purchasing Metadefender Core licenses, click ‘Contact Sales’ here.

Activation Options

Activation Options

Metadefender Core licenses can be activated in two ways:

1. Online Activation Metadefender Core licenses can be activated online if the Metadefender Core

server is connected to the Internet. 2. Offline Activation If the Metadefender Core Server is not connected to the Internet, Metadefender

Core licenses can be activated offline through the OPSWAT Activation Portal.

1) Online activation of license

Note: The Metadefender Core Server must be connected to the Internet for Online Activation. The following are required for online activation:

• A Metadefender Core Server • A serial key that matches the Metadefender Core package installed on that

Metadefender Core Server. Metadefender Core licenses can only be used with the package for which they were created (1, 4, 8, 12, 16, 20 and Custom). For example, a serial key for Metadefender Core 4 will not work with Metadefender Core 8

You can use the following methods for online license activation:

a. The Metadefender Core Management Console included with the Metadefender Core installation

b. The License Manager Command Line Interface (CLI)

13


http://www.opswat.com/buy


a. Online activation of licenses using the Metadefender Core Management Console

The Metadefender Core Management Console is installed by default and can be launched from the Start menu. The Metadefender Core Management Console can also be accessed directly from any machine with network access to the Metadefender Core Server at http://<metadefender core server>:8008/management.

1. In the Metadefender Core Management console, navigate to the Licenses tab to check the current license information.

2. Enter the Metadefender Core serial key, company name, and contact e-mail address for the instance of Metadefender Core you wish to activate. Example:

14


3. Click on the ‘Activate’ button to apply the license.

4. Confirm that the license activation was successful and that the license expiration date matches the expiration date on your Metadefender Core contract.

b. Online activation of licenses using the License Manager CLI

1. Open a Command Prompt. Start -> Run -> CMD

2. Change the working directory to the Metadefender Core install directory. cd <Metadefender Core install dir> e.g., cd “c:\Program Files (x86)\OPSWAT\Metadefender Core 4”

15


3. Verify that your installation of Metadefender Core is NOT already activated. omsLicMgrCLI.exe checklicense [package] e.g., omsLicMgrCLI.exe checklicense 4

4. Activate license omsLicMgrCLI.exe activateonline <license key> “<email>” “<company>” [package]

16


5. After Metadefender Core activation completes successfully, the updated license status will be displayed. Verify that the license status listed is “Activated” and that the expiration date matches the expiration date on your Metadefender Core contract.

Note: If online activation is not successful, check to ensure the Metadefender Core Server’s Internet connection is working. If online activation is still unsuccessful, follow the steps for offline activation below. For more on using this tool, see section below titled “License Manager CLI”.

2) Offline activation of license

The following are required for offline activation:

• A Metadefender Core Server • A serial key that matches the Metadefender Core package installed on

that Metadefender Core Server. Metadefender Core licenses can only be used with the package for which they were created (1, 4, 8, 12, 16, 20 and Custom). For example, a serial key for Metadefender Core 4 will not work with

17


Metadefender Core 8

You can use the following methods for offline license activation:

• The Metadefender Core Management Console included with the Metadefender Core installation

• The License Manager Command Line Interface (CLI) (see section below for more information on this)

a. Offline activation of licenses using the Metadefender Core Management Console

The Metadefender Core Management Console is installed by default and can be launched from the Start menu or in any browser with network access to the Metadefender Core Server.

1. In the Metadefender Core Management Console, click on the Licenses tab to check the current license information.

2. Tick the “Activate Offline” option and copy or take note of the Install Code, which is needed to obtain the unlock keys.

18


3. To obtain the unlock keys, visit the Metadefender Core offline activation portal at https://portal.opswat.com/activation .

4. Enter your company name and other contact information.

5. Enter your serial key and the Install Code from Step 2. Example:

19

https://portal.opswat.com/activation


6. Click “Request Unlock Key”, which will forward you to a result page with 2 unlock keys. Copy or take note of both of these.

7. Go back to the Metadefender Core Management Console. Enter the license key and unlock keys in the dialog box along with the company name.

20


8. Click the ‘Activate’ button and confirm that the license expiration date has been updated and that it matches the Metadefender Core contract.

b. Offline activation of licenses using the License Manager Command Line Interface (CLI)

See the “activateoffline” command in the section directly below this one for more information.

License Manager CLI

License Manager CLI

The License Manager Command Line Interface can be used to apply, update, or activate a Metadefender Core license. It can also be used to check the license status of Metadefender Core or Remote Clients. This tool (omsLicMgrCLI.exe) is installed in the Metadefender Core installation directory. To use this tool, open a Command Prompt. Start -> Run -> CMD

21


License Manager CLI Commands and Arguments

Command Arguments Description

help Display each available command and its parameters.

checklicense [package] Retrieve license status.

installcode Retrieve Install Code which is required for generating unlock keys in order to activate offline.

activateonline <serial key> <email> <company> [package]

Activate license with a serial key through the Internet. The Metadefender Core Server where the license is being activated must have an Internet connection.

activateoffline <serial key> <company> <unlock key> <unlock key2> <package>

Activate license on a Metadefender Core Server without a direct connection to the Internet. This command requires a serial key and 2 unlock keys. Obtain the two unlock keys following the steps in the section 2) Offline activation of license'

finishactivation <unlock key> <unlock key2> [package]

Finish activation if the license status is “Activation Required”.

Argument Values

Arguments Value Description

22


[package] 1 4 8 12 16 20

Optional parameter, if not specified, package of the currently installed Metadefender Core service will be used. 1: Metadefender Core 1 4: Metadefender Core 4 8: Metadefender Core 8 12: Metadefender Core 12 16: Metadefender Core 16 20: Metadefender Core 20

<serial key> Serial number consisting of 6 blocks of 5 characters

The Serial Number is your proof of purchase. It is unique and will look like this: dO8uc-G1iC9-jOGeA-BqgEX-U71lD-0V1VX Although the serial key and unlock key have the same format, their properties are completely different. You must not mix them up and should keep them separate.

<email> E-mail address An e-mail address of the contact who is responsible for Metadefender Core licenses. e.g. [email protected]

<company> Name of company who owns the license

Used for the “company” property in Metadefender Core .

<unlock key> <unlock key2> Serial number consisting of 6 blocks of 5 characters Keys tied to a unique machine and serial key. These are obtained from OPSWAT through phone, email, or the web activation portal for offline activation.

Common License Activation Errors

The following are common errors encountered during activation and their potential causes.

Error Possible Causes Notes

INVALID KEY

An unrecognized serial key was entered A serial key is specific to the type of Metadefender Core

23


package. For example, a serial key for Metadefender Core 4 cannot be used for Metadefender Core 8 or 12.

invalid unlock keys

An unrecognized unlock key was entered Unlock keys are tied to a specific serial key and machine where the Install Code was generated. Using an unlock key on a different system, or with a different serial key will result in this error.

No internet connection

Metadefender Core is unable to connect to the Metadefender Core license server

Check your Internet connection or follow the steps for offline activation.

Other In cases of other errors, an error code will be displayed along with this message. e.g.,

Please contact OPSWAT support ([email protected]) with the error code.

24

mailto:


Installing Metadefender Client for Linux Using the Command Line

Preliminary Notes

If the Metadefender Client package dependencies are not installed on your system, make sure you have a working Internet connection and have provided the Installation media during the installation. Consult your Operating System documentation on how to use Installation media as a package repository.

Debian Package (.deb)

sudo dpkg -i <filename> || sudo apt-get install -f

Red Hat Enterprise Linux/CentOS Package (.rpm)

sudo yum install <filename>

Usage

ometascanclient <COMMAND> [OPTION]

Command

filescan scan a single file folderscan scan a single folder fullsystemscan scan the full system processscan scan all running processes

deepprocessscan scan all running process deeply (loaded modules)

Note: all commands require the option "-u <URL>"

Options

-h, --help print this help and exit -v, --version print the full version and exit

25


-u <URL>, --url=<URL> resolve Metascan server host and port from URL

-p <PATH>, --path=<PATH> path if file or folder scan requested

-k <KEY>, --key=<KEY> provide an API key --verbose-debug verbose debug output to stderr

Example

The following command will scan the file located at /tmp/testfile with Metadefender Core server found at 10.0.3.108: ometascanclient filescan -p /tmp/testfile -u http://10.0.3.108:8008/metascan_rest

26


Configuring Metadefender Core

Metadefender Core Configuration Tools

Metadefender Core Management Console

The Management Console can be accessed through any browser that has access to the Metadefender Core system. A link to the Management Console is added to the Start menu during installation.

The Management Console can also be accessed directly in any web browser by going to:

http://<Metadefender Core Server>:8008/management <Metadefender Core Server> will be the name or IP address of the system where

Metadefender Core is installed

Command Line Utility

Metadefender Core also provides a Command Line Utility that enables users to run Metadefender Core operations such as scanning a file or setting preferences/properties, etc.

27


1. Run -> “CMD”.

2. Change Directory to the directory where Metadefender Core is installed.

3. Run “config” command with omsCmdLineUtil.exe to bring up a list of options to configure.

In the sections below, the Command Line Utility commands are provided for each configuration setting.

omsConfig.ini

Additional, less commonly used, options are set in the omsConfig.ini file located in the installation directory of Metadefender Core. Consult with the Metadefender Core Support team before changing any settings other than proxy settings. The Metadefender Core service must be restarted after making any changes to this file.

omsConfig.exe

By default Metadefender Core is installed to use MongoDB for all database purposes. Most users will not need to make any configuration changes to the Metadefender Core database, however some users may need to make changes for their specific use case.

Multi-scanning Configuration

28


Multi-scanning Configuration

The following Metadefender Core multi-scanning options are configured on the 'Configuration' tab in the Metadefender Core Management Console:

1. Engines 2. Workflows 3. Caching 4. Scanning Behavior 5. Data Sanitization

Engine Configuration

Configuring Metadefender Core Engines

The Engines section of the Configuration tab is where engine updates can be configured and offline updates can be applied.

All bundled engines as well as custom and customer licensed engines that can be used in Metadefender Core will be listed on this page. Each engine can be activated or deactivated by selecting the checkbox and then clicking on the ‘Apply’ button at the bottom of the page. If applicable, an engine’s heuristic scanning feature can be activated or deactivated as well. These changes will take effect after the Metadefender Core service has been restarted.

29


Any customer licensed engine will not be enabled by default for Metadefender Core 4, 8, 12, 16, and 20 packages. Customer licensed engines must be enabled before they will be used by Metadefender Core to process scan requests.

Offline Updates

If your Metadefender Core server is deployed in an offline environment without connectivity to the Internet, you can deploy engine definition updates through the Offline Updates section of this page.

These update packages can be downloaded from the OPSWAT Portal or with the Automatic Definition Update Download Utility. For more information on how to download these updates, please visit the OPSWAT Portal at https://portal.opswat.com/. Then click the Downloads tab, and click Download Offline Definition Updates under Related Links in the left navigation panel.

Online Update Configuration

The following settings apply to Metadefender Core's automatic engine definition update functionality:

30

https://portal.opswat.com/en/content/offline-definition-updates


Property Description Default Value CLI config Behavior During Updates

Specifies scanning behavior when an engine is in the process of having its definitions updated. Scans can configured to either be skipped or paused during updates.

Skip Scans (Pause) wu=<0|1> (Skip) su=<0|1>

Update Timeout Specifies how long Metadefender Core should wait for an update to happen before timing out.

600 seconds to=<time in milliseconds>

Update Interval Specifies how often engines should be updated

1440 minutes (1 day)

um=<time in minutes>

Proxy settings can also be defined in the omsConfig.ini configuration file (located in the Metadefender Core installation directory). Proxy settings defined in omsConfig.ini will only be used if the proxy configuration is not set in the Metadefender Core Management Console. Property Description Default Value omsConfig.ini

Property Enable Updates Through Proxy

Specifies whether the Metadefender Core server will be retrieving engine updates through a proxy server

Unselected enable_proxy

Server Address The proxy server to use proxy_server Port The proxy server port to use proxy_port Username If authentication is required, the

username for the proxy server proxy_user

Password If authentication is required, the proxy_password

31


password for the proxy server

Enabling and Disabling Engines from the CLI

If you would like to enable or disable engines from the Command Line Interface, run the following commands from the Metadefender Core installation directory.

Retrieving the List of Available Engines

omsCmdLineUtil.exe getinfo

Enabling an Engine

omsCmdLineUtil.exe config in=<engine(s) to be included> e.g., omsCmdLineUtil.exe config in="eset scan engine|avira scan engine"

Disabling an Engine

omsCmdLineUtil.exe config ex=<engine(s) to be excluded> e.g., omsCmdLineUtil.exe config ex="eset scan engine|avira scan engine" If you are enabling or disabling multiple engines the engine names should be separated by the ‘|’ character.

Supporting Customer-Licensed Engine

omsCmdLineUtil.exe config sp={0|1} e.g., omsCmdLineUtil.exe config sp=1 This property determines whether Metadefender Core will attempt to use antivirus engines that are installed on the system outside of Metadefender Core . These engines will often have reduced performance compared to embedded engines and may also reduce overall Metadefender Core performance. By default, customer licensed engines will be enabled in Metadefender Core 1 and disabled in Metadefender Core 4, 8, 12, 16, and 20 packages.

32


Workflow Configuration

Workflow Profiles

Metadefender Core allows the definition of as many different workflow profiles as are needed to meet security requirements. Defining multiple workflows allows for files from different sources or users to be processed with the appropriate security policies. The workflows defined in the Management Console can be used with the 'process' REST API. Several profiles are included by default in every Metadefender Core installation. The 'Default' profile is used to process requests that are not mapped to any other profiles. The Guest profile is intended to be used to process files by guests that do not have a defined account within an organization.

Workflow Info

The workflow info screen allows the administrator to define the name and description of a workflow profile, as well as specify which user agents should use this profile. These values can be changed for all profiles except for the Default profile.

33


Archive Handling

The archive handling configuration options determine how archives are handled in a given Metadefender Core workflow profile. If archive handling is enabled, Metadefender Core will extract archives and scan the individual files within the archive.

Most common archive formats are supported, including 7z, XZ, BZIP2, GZIP, TAR, ZIP, WIM, ARJ, CAB, CHM, CPIO, CramFS, DEB, DMG, FAT, HFS, ISO, LZH, LZMA, MBR, MSI, NSIS, NTFS, RAR, RPM, SquashFS, UDF, VHD, WIM, XAR and Z. Metadefender Core can also extract self-extracting archives created by both 7zip and WinRAR.

34


The following settings apply if archive handling is enabled: Property Description Default

Value CLI config Additional info

Enable Archive This enables Metadefender Core's archive library handling

Enabled le=<0|1>

Max Recursion Level

The maximum depth that Metadefender Core will continue to extract archives for scanning. Once this depth is reached, Metadefender Core will not extract further archives but will scan those archives as entire files. If this is set to 0 archives will not be extracted.

5 rl=<levels> Maximum value: 2147483646

Number of Files The maximum number of files that can be in an archive that Metadefender Core is extracting. If the number of files in an archive exceeds this value, Metadefender Core will return the result as a potential threat.

50 an=<number> Maximum value: 2147483646

Total Size The maximum total size of files that can be in an archive that Metadefender Core is extracting. If the total size of files in an archive exceeds this value, Metadefender Core will return the result as a potential threat. Note:

2 GB as=<size in MB>

Maximum value: Half the current available free space of the Metadefender Core temporary directory. If two temporary directories are set from different drives, the highest available space will be used.

35


Simultaneous Specifies if multiple archive files undergo extraction concurrently. This may improve performance on a multi-core CPU, but means that the ram-drive size should be increased (since more unpacked archives may reside on it at the same time).

Disabled ec=<0|1>

Self-Extracting Specifies if self-extracting archives should be extracted and treated as archives

Disabled sx=<0|1>

Scan Original Un-extracted File

In addition to scanning files inside of an archive after extraction, un-extracted archives are sent directly to engines for scanning. Note: If “extract_archive” for an engine is enabled, this potentially exposes performance overhead since extraction happens twice, once by Metadefender Core and once by the engine.

Disabled soa=<0|1>

Note: DOCX and DOCM files can be detected as archive files. OPSWAT recommends that the option to scan the original un-extracted archive is enabled so that these files are properly scanned.

File Type Analysis

The file type analysis configuration allows the administrator to specify whether file type analysis should be performed, and how Metadefender Core should handle file type mismatches (where the detected type of the file differs from its extension.

36


The Filtration configuration allows a Metadefender Core administrator to specify that certain file types should be blocked, or that only certain file types should be allowed.

Scan

This page allows a Metadefender Core administrator to enable or disable scanning by the active engines in Metadefender Core. The administrator can also specify files that should be skipped. By default, large video files are excluded from scanning for efficiency purposes.

37


Data Sanitization

The data sanitization configuration determines how files are handled after scanning is complete. Data sanitization is configured separately for allowed and blocked files. Both allowed and blocked files can be configured to sanitize specific types of files and convert them to other formats. This can remove any threats embedded within the original file. If configured, the original file can be deleted after the santization.

38


File Handling

The file handling configuration determines how files are handled after data sanitization is complete. File Handling is configured separately for allowed and blocked files.

39


Blocked files can be configured to be removed, either by quarantining or deleting the blocked file. Both blocked and allowed files can be configured to be copied to a specified directory path.

Caching

The caching configuration determines the size and behavior of the Metadefender Core scan result cache. The cache allows Metadefender Core to return results from a previous file scan with Metadefender Core if those scan results were cached and have not yet expired. Caching can only be configured through omsCmdLineUtil.exe. The following settings apply if caching is enabled: Property Description Default Value CLI config Enable Caching This enables Metadefender Core's

scan result caching. Disabled cs=<0|1>

Reset cache on engine update

Specifies whether the cache should be reset (and all cached results

Disabled rc=<0|1>

40


discarded) whenever there has been an engine definition update.

Cache Expiration Specifies how long (in hours) cached results remain available after a scan. After this time the cached results will be deleted.

72 hours kc=<time in seconds>

Maximum Cache Size

The maximum size of the cache in RAM. This is only the amount of space required to store the cached scan results, not the files themselves.

100 MB ms=<size in MB>

To manually reset the cache, do the following.

1. Stop the Metadefender Core service (net stop metascan) 2. Delete the cache database (<installation directory>\Data\omsCK_KN.db3) 3. Restart the Metadefender Core service (net start metascan)

Scan Configuration

The scan configuration settings define the behavior of Metadefender Core when it is scanning files.

41


The following settings can be configured through the Scan Configuration page:

Property Description Default Value

CLI config

Detect Scan Failures

Specifies the number of engines that need to fail to scan a file for the overall result to be 'failed to scan'. For instance, if set to 2 then a single engine failing will not result in the file being labeled 'failed to scan' but if 2 or more engines fail the overall result will be 'failed to scan'. If set to '0' then the file will only be labeled 'failed to scan' if all engines fail to scan the file.

0 dsf=<0-n-1>, where n is the total number of current AV engines.

Primary Temp Directory

Directory used to copy files for scanning.

RAMDisk (if installed) or the system temporary

td=<directory|secondary directory>

42


directory Secondary Temp Directory

Optional. Will only be used if the size of an extracted archive exceeds the space available in the primary directory.

Number of simultaneous scans

The number of scans that can be run at the same time. Recommended value is 3x the number of physical processing cores available or 20, whichever is greater.

20 tp=<0-400>

Terminate engine if scan exceeds

The amount of time that Metadefender Core will wait for an engine to complete scanning before it terminates the engine process.

5 minutes te=<time in seconds>

Maximum File Size for Files Scanned through the web interface

The largest allowable size for files scanned through the Metadefender Core web interface.

Do not calculate hashes for files larger than

The maximum size of files to compute the hash. Computing hashes for very large files can take a long time and can significantly affect Metadefender Core's performance.

100 MB tfi=<size>

ScanEx Configuration

This configuration is used when calling the Metadefender Core APIs that do not use the Metadefender Core workflows, and only scan files. This includes files scanned through Metadefender Core's ICAP interface, files scanned with Metascan Client, files scanned through the Java API, and the sample code provided on the OPSWAT Portal.

Archive Handling

The archive handling configuration options determine how archives are handled. If archive handling is enabled, Metadefender Core will extract archives and scan the individual files within the archive.

43


Most common archive formats are supported, including 7z, XZ, BZIP2, GZIP, TAR, ZIP, WIM, ARJ, CAB, CHM, CPIO, CramFS, DEB, DMG, FAT, HFS, ISO, LZH, LZMA, MBR, MSI, NSIS, NTFS, RAR, RPM, SquashFS, UDF, VHD, WIM, XAR and Z. Metadefender Core can also extract self-extracting archives created by both 7zip and WinRAR. The following settings apply if archive handling is enabled: Property Description Default

Value CLI config Additional info

Enable Archive This enables Metadefender Core's archive library handling

Enabled le=<0|1>

Max Recursion Level

The maximum depth that Metadefender Core will continue to extract archives for scanning. Once this depth is reached, Metadefender Core will not extract further archives but will scan those archives as entire files. If this is set to 0 archives will not be extracted.

5 rl=<levels> Maximum value: 2147483646

44


Number of Files The maximum number of files that can be in an archive that Metadefender Core is extracting. If the number of files in an archive exceeds this value, Metadefender Core will return the result as a potential threat.

50 an=<number> Maximum value: 2147483646

Total Size The maximum total size of files that can be in an archive that Metadefender Core is extracting. If the total size of files in an archive exceeds this value, Metadefender Core will return the result as a potential threat. Note:

2 GB as=<size in MB>

Maximum value: Half the current available free space of the Metadefender Core temporary directory. If two temporary directories are set from different drives, the highest available space will be used.

Simultaneous Specifies if multiple archive files undergo extraction concurrently. This may improve performance on a multi-core CPU, but means that the ram-drive size should be increased (since more unpacked archives may reside on it at the same time).

Disabled ec=<0|1>

Self-Extracting Specifies if self-extracting archives should be extracted and treated as archives

Disabled sx=<0|1>

Scan Original Un-extracted File

In addition to scanning files inside of an archive after extraction, un-extracted archives are sent directly to engines for scanning. Note: If “extract_archive” for an engine is enabled, this potentially exposes

Disabled soa=<0|1>

45


performance overhead since extraction happens twice, once by Metadefender Core and once by the engine.

Note: DOCX and DOCM files can be detected as archive files. OPSWAT recommends that the option to scan the original un-extracted archive is enabled so that these files are properly scanned.

Post Processing Configuration

The Post Processing configuration allows an administrator to specify a script that should be executed for all allowed and/or blocked files. By clicking on ‘Run custom command line script’, a message can be put in place for both infected and clean files. An administrator can also choose to delete or quarantine infected files.

Data Sanitization

The data sanitization configuration determines how long files that have been sanitized by Metadefender Core workflows will be available through the REST API.

46


If enabled, Metadefender Core will automatically delete the sanitized version of files after the time specified.

Metadefender Core Sources Configuration

Metadefender Client Configuration

The Clients configuration page specifies the settings for the Metadefender Client package that will be available through the client download page, the location of which is listed at the bottom of the configuration page. After a client has been generated, the Metadefender Client download page can be shared with anyone who should be able to use Metadefender Client to scan files with this Metadefender Core server. Note that the Windows Metadefender Client is only supported to run on endpoints running Windows 7 or later.

47


The following properties can be set for the Metadefender Client download package. These properties can also be set by modifying the Metadefender Client INI file, which is located by default at C:\Program Files (x86)\OPSWAT\Metadefender Core <1|4|8|12|16>\MetascanClient\MetascanClientConf.ini.

Property Description Default Value

Metascan

Server

This is the address that Metadefender

Client will use to access the

Metadefender Core server. This

should be an address (IP address or

machine name) that will be accessible

from every machine where

<IP

Address>:8008/metascan_rest

48


Metadefender Client will be run.

File Size

Limit

The maximum size of files to be

scanned by Metadefender

Client. Files larger than this size will

not be scanned.

5 MB

Batch

Size

The number of files that will be

processed concurrently by

Metadefender Client

100

Thread

Count

The number of threads Metadefender

Client will use to scan files. This

should only be increased if

Metadefender Client is expected to

run on systems with a high number of

processor cores.

10

User

Interface

This specifies whether Metadefender

Client will allow the end user to select

what type of scan they want to run. If

Metadefender Client is set to run in

Automatic mode then it will run

silently without any user interaction

Allow User Selection

Scan

Types

Specifies which scan types will be

available for the user to choose from.

· Fast Scan – scan all running

processes

· Intermediate Scan – Scan running

processes and loaded libraries

· Full Scan – Scan entire system

· Custom Scan – Scan the files and

directories the user selects

All allowed, Fast Scan selected

as default

49


Local Log

Directory

The directory where Metadefender

Client will log all scanning activity

C:\MetascanClient.log

After configuration changes have been made, a new Metadefender Client downloadable package can be generated by clicking the ‘Update Client Download’ button.

Metadefender Client Command Line Options

All of the options specified in the configuration file can also be set on the command line. Options set on the command line will override the same options set in the configuration file. The following table specifies additional options which can be set on the command line. Default values are in bold.

Variable Description

show_ui Determines whether the Metadefender Client User Interface will be displayed Possible values: 0: Metadefender Client will run silently 1: The Metadefender Client user interface will be displayed to the user

exit_on_clean Determines whether the Metadefender Client user interface will exit if all files scanned are clean Possible values: 0: Metadefender Client will not immediately exit after a scan where all files are clean 1: Metadefender Client will immediately exit after a scan where all files are clean

exit_on_dirty Determines whether the Metadefender Client user interface will exit if there are dirty files found during a scan Possible values: 0: Metadefender Client will not immediately exit after a scan where one or more dirty files are found 1: Metadefender Client will immediately exit after a scan where one or more dirty files are found

auto_start Determines if the Metadefender client will start scanning immediately once application launches. Possible values: 0: Metadefender Client will not immediately start scanning 1: Metadefender Client will immediately start scanning. NOTE: show_ui=0 will be ignored if auto_start is not set to 1.

auto_save_result Determines if the scan results should be saved automatically.

50


Possible values: 0: Metadefender Client will not save results automatically 1: Metadefender Client will automatically save scan results at the location where Metadefender Client is located.

key API key given by OPSWAT when OPSWAT hosted server is used.

CLI Usage Example:

Following is an example command to start a fast scan automatically against a Metadefender Core server with the IP address 10.0.0.1. MetascanClient.exe server=10.0.0.1:8008/metascan_rest auto_start=1 allowed_scan_levels=1

Installing Metadefender Client for Linux Using the Command Line

Preliminary Notes

If the Metadefender Client package dependencies are not installed on your system, make sure you have a working Internet connection and have provided the Installation media during the installation. Consult your Operating System documentation on how to use Installation media as a package repository.

Debian Package (.deb)

sudo dpkg -i <filename> || sudo apt-get install -f

Red Hat Enterprise Linux/CentOS Package (.rpm)

sudo yum install <filename>

Usage

ometascanclient <COMMAND> [OPTION]

Command

filescan scan a single file folderscan scan a single folder fullsystemscan scan the full system processscan scan all running processes

deepprocessscan scan all running process deeply (loaded modules)

51


Note: all commands require the option "-u <URL>"

Options

-h, --help print this help and exit -v, --version print the full version and exit

-u <URL>, --url=<URL> resolve Metascan server host and port from URL

-p <PATH>, --path=<PATH> path if file or folder scan requested

-k <KEY>, --key=<KEY> provide an API key --verbose-debug verbose debug output to stderr

Example

The following command will scan the file located at /tmp/testfile with Metadefender Core server found at 10.0.3.108: ometascanclient filescan -p /tmp/testfile -u http://10.0.3.108:8008/metascan_rest

Metadefender Proxy Configuration

Metadefender Core's ICAP server functionality allows for integration with any proxy server that implements the ICAP interface. The Metadefender Core ICAP server can be configured and started from the Metadefender Proxy Configuration page. The Metadefender Core ICAP server is not started by default when Metadefender Core is installed.

52


The following settings apply to Metadefender Core's ICAP server functionality: Property Description Default Value CLI config ICAP Port The port the Metadefender ICAP

server is operating on 1344

Maximum Sockets Specifies how many concurrent

connections should be allowed to the Metascan ICAP server

60

After changes have been made click the ‘Apply’ button to save the changes. Click the ‘Restart ICAP Service’ or ‘Start ICAP Service’ button to restart or start the Metadefender Core ICAP server. A custom ICAP block page can be uploaded to Metadefender Core to be displayed whenever a malicious file has been found. To upload a custom block page, browse to select the appropriate HTML file and then click to upload it.

53


Metadefender Email Configuration

Metadefender Email Configuration

Metadefender Email protects your organization from incoming malware, such as viruses and other malicious code, transmitted in e-mail content or attachments. It can also protect your organization’s outgoing e-mail traffic, to ensure that no malware is transmitted from your organization.

Overview

Metadefender Email requires an existing third party e-mail gateway and a third party mail server in order to provide the necessary defense layer. You must install Metadefender Email as a relay server between these two servers. Metadefender Email captures SMTP traffic from the e-mail gateway and forwards scanned and/or sanitized e-mails to your mail server (incoming protection), while also capturing traffic from the mail server and forwarding scanned and/or sanitized e-mails to your outbound gateway (outgoing protection). Metadefender Email is installed by default as part of the Metadefender Core installation process.

Installing and Configuring Incoming Threat Protection

In order to install and configure Metadefender Email incoming threat protection, you must configure the routing of the incoming threat protection, verify the routing settings, and then connect to your e-mail gateway.

Configure Routing

In this section, you will connect Metadefender Email to your mail server.

1. Open the Metadefender Core Management Console.

54


2. Select Sources > Metadefender Email > Setup.

3. In the Email Relay Out Server field, specify the IP address (or name) of your mail

server and the SMTP protocol port that the mail server is listening on (usually port 25).

4. In the Email Direction field, select Incoming. 5. Click Apply to save your changes.

Verify Routing Settings

You can use the telnet client to verify that Metadefender Email is successfully forwarding e-mails to your mail server. If you do not have the telnet client installed, go here for installation instructions. Note: This step is optional.

1. Open a command prompt. 2. Enter the following:

c:\>telnet.exe Expected response: Welcome to Microsoft Telnet Client Escape Character is 'CTRL+]' Microsoft Telnet>

3. Connect to Metadefender Email's SMTP server by entering the following: open localhost 10025. Expected response: 220 [server name] -- E-MailRelay V1.9 -- Service ready

4. Perform a handshake with the SMTP server by entering the following: HELO test.com Expected response: 250 OK

55

https://technet.microsoft.com/en-us/library/cc771275(v%3dws.10).aspx


5. Specify a sender e-mail address by entering the following: MAIL FROM:<my_email_address@my_company.com> where my_email_address@my_company.com is your e-mail address. Expected response: 250 OK

6. Specify a recipient e-mail address by entering the following: RCPT TO:<my_email_address@my_company.com> where my_email_address@my_company.com is your e-mail address. Expected response: 250 OK

7. Begin creating e-mail content by entering the following: DATA Expected response: 354 start mail input -- end with <CRLF>.<CRLF>

8. Continue creating e-mail content by entering the following: Subject: Metadefender Email Test This is a test email to verify Metadefender Email routing settings. . Note: Email content transmission must be finished with a . (dot) on a blank line followed by a carriage return. Expected response: 250 OK

9. Close the connection by entering the following: QUIT

10. Go to your mailbox and verify that you have received an e-mail with the subject ‘Metadefender Email Test’. If you have received this e-mail, e-mail routing is working as expected.

Connect to the E-mail Gateway

For Metadefender Email to start scanning all your incoming e-mails, you must configure your third party e-mail gateway to forward all e-mails to the Metadefender Email server, rather than directly to the mail server.

1. From Sources > Metadefender Email > Setup, go to the Step 2 - Connect E-mail Gateway to Metadefender Email section.

2. Verify and/or change the SMTP port. Note: By default, Metadefender Email listens on SMTP port 10025. Make sure that your firewall allows traffic on the port used by the Mail Agent.

3. Send an e-mail from an external source to a local mailbox and verify that the e-mail is being delivered as expected.

4. Go to the Metadefender Core Management Console Dashboard and verify that the e-mail has been scanned.

56


Installing and Configuring Outgoing Threat Protection

In order to install and configure Metadefender Email outgoing threat protection, you must configure the routing of the outgoing threat protection, verify the routing settings, and then connect your mail server to Metadefender Email.

Configure Routing

In this section, you will connect Metadefender Email to your gateway.

1. Open the Metadefender Core Management Console. 2. Select Sources > Metadefender Email > Setup.

3. In the Email Relay Out Server field, specify the IP address (or name) of your

outbound gateway and the SMTP protocol port that the outbound gateway is listening on.

4. In the Email Direction field, select Outgoing. 5. Click Apply to save your changes.

Verify Routing Settings

You can use the telnet client to verify that Metadefender Email is successfully forwarding e-mails to your gateway. If you do not have the telnet client installed, go here for installation instructions. Note: This step is optional.

57

https://technet.microsoft.com/en-us/library/cc771275(v%3dws.10).aspx



c:\>telnet.exe Expected response: Welcome to Microsoft Telnet Client Escape Character is 'CTRL+]' Microsoft Telnet>

3. Connect to Metadefender Email's SMTP server by entering the following: open localhost 10025 Expected response: 220 [server name] -- E-MailRelay V1.9 -- Service ready

4. Perform a handshake with the SMTP server by entering the following: HELO test.com Expected response: 250 OK

5. Specify a sender e-mail address by entering the following: MAIL FROM:<my_email_address@my_company.com> where my_email_address@my_company.com is your e-mail address. Expected response: 250 OK

6. Specify a recipient e-mail address by entering the following: RCPT TO:<my__external [email protected]> where [email protected] is your external e-mail address, such as Gmail. Expected response: 250 OK >

7. Begin creating e-mail content by entering the following: DATA Expected response: 354 start mail input -- end with <CRLF>.<CRLF>

8. Continue creating e-mail content by entering the following: Subject: Metadefender Email Test This is a test email to verify Metadefender Email routing settings. . Note: Email content transmission must be finished with a . (dot) on a blank line followed by a carriage return. Expected response: 250 OK

9. Close the connection by entering the following: QUIT

10. Go to an external mailbox and verify that you have received an e-mail with the subject ‘Metadefender Email Test’. If you have received this e-mail, e-mail routing is working as expected.

Connect Your Mail Server to Metadefender Email

58


For Metadefender Email to start scanning all your outgoing e-mails, you must configure your mail server to forward all e-mails to the Metadefender Email server, rather than directly to the e-mail gateway.

1. From Sources > Metadefender Email > Setup, go to the Step 2 - Connect E-mail Gateway to Metadefender Email section.

2. Verify and/or change the SMTP port. Note: By default, all e-mail gateways listen on SMTP port 25. Make sure that your firewall allows traffic on the port used by the Mail Agent.

3. Send an e-mail from a local mailbox to an external source and verify that the e-mail is being delivered as expected.

4. Go to the Metadefender Core Management Console Dashboard and verify that the e-mail has been scanned.

Setting Up Alerts For Unexpected Events

Metadefender Email can alert an administrator if unexpected events occur, such as loss of connection to Metadefender Core, Mail Sever/Gateway or queue build ups. Note: To enable alerts, you must use the alertenabler.exe tool.


• Metadefender Core configured to use HTTP: alertenabler.exe -a <[email protected]> where [email protected] is your administrator's e-mail address.

• Metadefender Core configured to use HTTPS: alertenabler.exe -a <[email protected]> -s where [email protected] is your administrator's e-mail address.

Setting Up Notifications

Metadefender Email can send notifications if an e-mail is infected or has been sanitized.

1. From Sources > Metadefender Email > Settings, go to the E-Mail Settings for Notifications section.

59


2. Configure the SMTP settings and set the Status to connected. If you have already done this step, go to step 3.

a. Click Update. b. In the Host field, specify the IP address or name of your mail server.

Note: You may also use an alternative mail server to deliver reports and notifications. To do this, replace the Host value with your alternative mail server address and specify Port, SSL, Username and Password settings as required for the alternative mail server.

c. Click Save. d. Metadefender Core will verify that the SMTP connection can be

established with your mail server and if so, the Status field is updated to Connected.

3. To send e-mail notifications when an infected e-mail is detected or a sanitization takes place, move the On/Off slider to On for the Infection E-Mail Notifications and/or Sanitized E-Mail Notifications sections, respectively.

4. Specify the sender's e-mail address, and modify subject and body as desired.

Note: To provide information about the infected or sanitized e-mail in the notification body, do not change the %[]code[]% placeholders in the Message value.

60


Setting Up Quarantine Reports

You can configure Metadefender Core so that it notifies administrator(s) of any e-mails that have been quarantined or sanitized during scanning.

1. In the Metadefender Core Management Console, go to Quarantine and click Configure Quarantine Reports.

2. Configure the SMTP settings and set the status to Connected. If you have already done this step, go to step 3.

a. In the SMTP Configuration Settings section, click Update.

b. In the Host field, specify the IP address or name of your mail server. Note: You may also use an alternative mail server to deliver reports and notifications. To do this, replace the Host value with your alternative mail server address and specify Port, SSL, Username and Password settings as required for the alternative mail server.

c. Click Save. d. Metadefender Core will verify that the SMTP connection can be

established with your mail server and if so, the Status field is updated to Connected.

2. Enable Quarantine Reports by moving the On/Off slider to On.

61


3. Specify the scheduling interval for report generation, along with the sender, recipient and optional subject and message body.

4. Click Save to save the quarantine report settings.

Managing the Mail Agent Workflow

You can modify the Mail Agent workflow used when scanning e-mails.

1. Go to Sources > Metadefender Email > Workflow. 2. Click Mail Agent to open the workflow. 3. View or change workflow settings by navigating through the workflow steps.

Note: For more information, refer to the Workflow Configuration section.

Logging

File Scan History

File results can be filtered to display a specific time period. To view detailed scan results, select a result from the list.

The following values are shown for each file in the file scan history

Property Description Result The scan result for that file

62


Filename

The filename specified at the time of the scan request. This is determined by the following for the different Metadefender Core interfaces

• REST: The value specified in the 'filename' header in the scan request

• COM: The name of the file from where it is scanned on the Metadefender Core system

• ICAP: The value of the 'filename' header in the ICAP request. If this is not specified then this will be the portion of the URL after the final forward slash (/)

File type The detected file type of the scanned file. This value will only be present if file type analysis is enabled

Scan Time The amount of time it took Metadefender Core to scan the file

Time The timestamp of when the scan was requested

Metadefender Core System Events

This section of the Metadefender Core logs contains internal Metadefender Core DB event logging.

63


Windows Event Log

This section of the Metadefender Core logs contains system application event logging of all Metadefender Core -related components.

64


Configuration

All events in the Event Log section can also be configured to be sent to a Syslog server.

65


The following settings apply to Metadefender Core's Syslog logging functionality. Property Description Default Value Enable syslog messages

Indicates whether the following settings will be used to send messages to a Syslog server.

Disabled

IP Address The IP address of the Syslog server. Port The port that the Syslog server is

listening on. 514

Facility Level The facility level can be configured for an additional level of filtering of messages on the Syslog server.

User-Level

Example of Metadefender Core event and dirty result log in syslog: 2014-06-19 15:05:15 User.Notice 10.0.3.101 Metascan: Changed property [thread_pool_size] = [20] 2014-06-19 15:05:15 User.Notice 10.0.3.101 Metascan: Changed property [enable_cache_scan] = [1] Note: Only infected files scanned through Metadefender Core's REST API will result in syslog messages. Files scanned through any other interface will not produce syslog messages. Files scanned using Metadefender Core's workflows will not be logged to syslog.

66


Debug Logging

Debug information can be generated if needed for troubleshooting purposes. To generate the debug log packages, click on the links to either export a quick or verbose debug log.

Quarantine

E-Mail messages or files that have been quarantined by Metadefender Core will be listed in the Quarantine tab. From this tab an administrator can choose to delete, download, or release files and e-mails that have been quarantined.

Note: Port 8000 needs to be open on the Metadefender Core server for the Quarantine history to be displayed correctly.

Using Metadefender Proxy

67


Use Cases

Use Cases

Scanning File During Download/Upload via HTTP

When a user sends an HTTP request (PUT, POST), your HTTP proxy can redirect messages for scanning before uploading to an external server via the ICAP 1.0 protocol. The Metadefender Core ICAP server may either:

• Accept: If attached data is clean, returns UNMODIFIED HTTP request, and the message is forwarded normally

• Reject: If attached data is identified as a threat, HTTP message (request) will be modified (e.g., a custom html message) and be returned back to the sender without continuing to its destination

The same process works for HTTP GET requests, where rather than uploading data, a user is downloading data from an external server. In this case, the contents of the reply are scanned before being sent to the user’s computer. If a threat is found, as in the previous case, a custom error message will be displayed to the user that initiated the request.

Blue Coat ProxySG integration

Configuration Overview

Configure ProxySG from the ProxySG Management Console interface. The following sections contain the minimum configuration required for Metadefender Core ICAP integration with ProxySG. Please refer to the ProxySG manual for advanced proxy configuration.

• System Requirements for ProxySG Configuration • Configuring Metascan • Configuring the Blue Coat ProxySG Server • Enabling Blue Coat to Intercept SSL Traffic • Limitations • Overcoming Certificate Issues

Open a web browser and load the ProxySG Management Console. (Please refer to the ProxySG manual for details about how to open the ProxySG Management Console.)

68


System Requirements for ProxySG Configuration

• Blue Coat ProxySG Server • One or more Metascan servers

Configuring Metascan

By default, the ICAP service is disabled in Metascan. To enable the ICAP service:

1. Open the Metascan Management Console (http://<server ip>:8008/management).

2. Navigate to the Sources-> ICAP Server Configuration page. 3. Click on Apply.

This starts the Metascan ICAP server with the default settings.

Persistent Connections

Blue Coat reuses connections to the ICAP server. OPSWAT recommends that you enable persistent connections on the ICAP side (see Configuration via Metadefender Core Management Console), or the Blue Coat might detect some ICAP connection drop errors under high load.

Metascan Licensing

Metascan must have a valid license, including licensing for the appropriate number of remote clients, to function correctly.

Configuring the Blue Coat ProxySG Server

Disabling Automatic Cache Refresh

1. Click on the Configuration tab, and navigate to “Proxy Settings” > “HTTP Proxy”. 2. Click on the Freshness tab and select "Disable refreshing”.

3. Click on the Acceleration Profile tab and uncheck the following options: o Pipeline embedded objects in client request o Pipeline redirects for client request

69


o Pipeline embedded objects in prefetch request o Pipeline redirects for prefetch request

4. Click on Apply to save the settings.

Adding REQMOD Service (Upload Mode)

1. Click on the Configuration tab, and navigate to 'External Services' > 'ICAP'. 2. Click on New, enter a service name, and click on OK. Note: “MetascanReqmod” is used as the service name in this documentation, but you can use any name. 3. In the services list, select MetascanReqmod and click on Edit. 4. Update the following values.

- In ICAP Service: a. Set service URL to “icap://<Metadefender Core server name or IP>/OMSScanReq-AV” b. Select 'Use vendor’s “virus found” page'.

- In ICAP Service Ports a. Select “This service supports plain ICAP connections” b. Set “Plain ICAP port” to your Metadefender Core ICAP port (default port: 1344).

- In ICAP v1.0 Options: a. Select “Request modification”. b. Select “Send Client address”.

5. Click on OK. 6. Click on Apply to save the configuration.

Adding RESPMOD Service (Download Mode)

1. Click on the Configuration tab, and navigate to 'External Services' > 'ICAP'.

70


2. Click on New, enter a service name, and click on OK. Note: “MetascanRespmod” is used as the service name in this documentation, but you can use any name.

3. In the services list, select MetascanRespmod and click on Edit. 4. Update the following values.

- In ICAP Service: a. Set service URL to “icap://<Metadefender Core server name or IP>/OMSScanResp-AV” b. Select 'Use vendor’s “virus found” page'.

- In ICAP Service Ports a. Select “This service supports plain ICAP connections” b. Set “Plain ICAP port” to your Metadefender Core ICAP port (default port: 1344).

- In ICAP v1.0 Options: a. Select “Request modification”. b. Select “Send Client address”.

5. Click on OK. 6. Click on Apply to save the configuration.

Creating Metascan RESPMOD Policy

1. Click on the Configuration tab, and navigate to 'Policy > 'Visual Policy Manager'. 2. Click on Launch.

3. In the 'BlueCoat Visual Policy Manager' window, navigate to 'Policy' > 'Add Web Content Layer'. 4. Enter a layer name and click on OK.

71


Note: “Metascan ICAP RespMod” is used as the layer name in these instructions, but you can use any name. 5. Click on the newly created Metascan ICAP RespMod tab, right-click on Use Default Caching, and select 'Set…'. 6. In the 'Set Action Object' window, click on New and select 'Set ICAP Response Service…'. 7. In the 'Add ICAP Response Service Object' window, set the following values: - Set 'name' to “Metascan ICAP Response Service” - In 'Available services', select 'metascanrespmod' and click on Add. 8. Click on OK. 9. Click on Apply to save the configuration.

Creating Metascan REQMOD Policy

1. Click on the Configuration tab, and navigate to 'Policy > 'Visual Policy Manager'. 2. Click on Launch.

3. In the 'BlueCoat Visual Policy Manager' window, navigate to 'Policy' > 'Add Web Content Layer'. 4. Enter a layer name and click on OK. Note: “Metascan ICAP ReqMod” is used as the layer name in these instructions, but you can use any name.

5. Click on the newly created Metascan ICAP ReqMod tab, right-click on Use Default Caching and select 'Set…'

72


6. In the 'Set Action Object' window, click on New and select 'Set ICAP Request Service…' 7. In the 'Add ICAP Request Service Object' window, set the following values: - Set 'name' to “Metascan ICAP Request Service” - In 'Available services', select 'metascanreqmod' and click on Add. 8. Click on OK. 9. Click on Apply to save the configuration.

Enabling Blue Coat to Intercept SSL Traffic

By default SSL (HTTPS) connections are not intercepted by Blue Coat and therefore data in them are not scanned by the ICAP server. If you would like to scan files which were sent using secure connection, then you can optionally configure Blue Coat to decrypt SSL connections. To configure Blue Coat, refer to Blue Coat documentation.

Limitations

If the ICAP server is not connected directly to Blue Coat or it is not in a private network, then the connection between Blue Coat and ICAP will no longer be secure, and the decrypted data could be in danger. Valid SSL certificates are needed for Blue Coat and user experience could be altered by certification notifications.

Overcoming Certificate Issues

1. When creating a keyring and certificate as explained in the Blue Coat documentation, note that the Common name "must match the ProxySG name or IP address that the client expects".

73

https://bto.bluecoat.com/webguides/proxysg/security_first_steps/index.htm%23Solutions/SSL/ssl_solution.htm




2. After the keyring and the certificate is ready go to Statics → Advanced → SSL → Download a ProxySG Certificate as a CA certificate in ProxySG Management Console.

3. Select the previously created certificate and download/install it to the browser in use.

4. This certificate should be set under Proxy Settings → SSL Proxy and under the SSLInterception which was created during configuring SSL interception.

Squid Integration

Squid Integration

Requirement

Squid-3.1 for Linux

Configuration

Squid configuration should be done by modifying “squid.conf” (e.g, /etc/squid3/squid.conf). Below is an example of a simplified version of configuration for Squid. For more detailed documentation, please refer to the Squid manual.

1. Enable acl localnet. Search for “acl localnet” section, uncomment all “acl localnet” lines. Below is an example of how the configuration might look:

acl localnet src 10.0.0.0/8 acl localnet src 172.16.0.0/12 # RFC1918 possible internal network acl localnet src 192.168.0.0/16 # RFC1918 possible internal network acl localnet src fc00::/7 # RFC 4193 local private network range acl localnet src fe80::/10 # RFC 4291 link-local (directly plugged) machines acl SSL_ports port 443 acl Safe_ports port 80 # http acl Safe_ports port 21 # ftp acl Safe_ports port 443 # https acl Safe_ports port 70 # gopher acl Safe_ports port 210 # wais acl Safe_ports port 1025-65535 # unregistered ports acl Safe_ports port 280 # http-mgmt

74


acl Safe_ports port 488 # gss-http acl Safe_ports port 591 # filemaker acl Safe_ports port 777 # multiling http acl CONNECT method CONNECT

2. Allow localnet and localhost access by adding the following lines.

http_access allow localnet http_access allow localhost http_access deny all

3. Enable ICAP.

icap_enable on

icap_send_client_ip on

http_access deny all

- Enable ReqMod (upload mode) icap_service metascan_req reqmod_precache bypass=0

icap://<Metascan>:1344/OMSScanReq-AV

adaptation_access metascan_req allow all

- Enable RespMod (download mode) icap_service metascan_resp respmod_precache bypass=0

icap://<Metascan>:1344/OMSScanResp-AV

adaptation_access metascan_resp allow all

4. Restart Squid to apply the new configuration.

Scanning HTTPS Content

Learn how to configure Squid to scan HTTPS content below. This allows Squid to send HTTPS content to the Metadefender Proxy server for scanning purposes.

Requirements

75


Squid must be compiled with SSL support. For more information, see http://docs.diladele.com.

Configuration

1. Tell Squid to listen on the following ports by entering the following in the squid.conf file:

ttp_port 3128 ssl-bump generate-host-certificates=on dynamic_cert_mem_cache_size=4MB cert=<SQUIDFOLDER>\etc\ssl\myc.pem # intercepted traffic https_port 3130 ssl-bump intercept generate-host-certificates=on dynamic_cert_mem_cache_size=4MB cert=<SQUIDFOLDER>\etc\ssl\myc.pem

2. In addition, insert the following lines:

sslcrtd_program <SQUIDFOLDER>\lib\squid|ssl_crtd.exe - s <SQUIDFOLDER>\var\cache\squid_ssldb -M 4MB

ssl_bump stare all ssl_bump bump all

Certification

1. Generate a new root certification for Squid by entering the following in the squid.conf file:

openssl.exe reg -new-newkey rsa:1024 -days 1000 - nodes -x509 -keyout myc.pem -out myc.pem

2. Reinitialize the certification storage by deleting the <SQUIDFOLDER>\var\cache\squid_ssldb folder and running the following:

<SQUIDFOLDER>\lib\squid\ssl_crtd.exe -c -s

<SQUIDFOLDER>\var\cache\squid_ssldb 3. The certification has been added to the browser. Restart Squid.

F5 Big-IP Integration

F5® BIG-IP® Local Traffic Manager™ (LTM®) integration

Configuration

76

http://docs.diladele.com/


The F5 BIG-IP LTM can be configured from the F5 BIG-IP Configuration utility interface. The following topics contain the minimum configuration required for Metadefender Core ICAP integration with F5 BIG-IP LTM. Please refer to the F5 BIG-IP LTM manual for advanced configuration. Open a web browser and load the F5 BIG-IP Configuration utility. (Please refer to the BIG-IP manual for details about how to open the F5 BIG-IP Configuration utility.)

Configuring REQMOD Service

In order to configure F5 BIG-IP LTM to only forward HTTP requests to the Metadefender Core ICAP server, follow the steps described below. In the case you want to configure F5 BIG-IP LTM to forward both HTTP requests and responses, refer to the "Configuring REQMOD and RESPMOD Services" section.

1. Open a Web browser and follow the instructions from the page: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/ltm-implementations-11-3-0/12.html

2. Update the REQMOD ICAP service profile. 1. Go to “Local Traffic” > “Profiles” > “Services” > “ICAP”. 2. In the list that appears select your ICAP Request mod service. 3. Set “Preview Length” to 0 and make sure the checkbox next to it is

checked. 4. Click “Update” to apply the changes.

3. Update the Request Adapt profile. 1. Go to “Local Traffic” > “Profiles” > “Services” > “Request Adapt”. 2. In the list that appears select your request adapt service. 3. Set “Preview Size” to 0 and make sure the checkbox next to it is checked. 4. Click “Update” to apply the changes.

Configuring REQMOD and RESPMOD Services

In order to configure F5 BIG-IP LTM to forward both HTTP requests and responses to the Metadefender Core ICAP server, follow the steps described below. In the case you want to configure F5 BIG-IP LTM to only forward HTTP responses, refer to the "Configuring REQMOD Service" section.

1. Open a Web browser and follow the instructions from the page: https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/ltm-implementations-11-3-0/13.html

2. Update your REQMOD ICAP service profile. 1. Go to “Local Traffic” > “Profiles” > “Services” > “ICAP”. 2. In the list that appears select your ICAP Request mod service.

77


3. Set “Preview Length” to 0 and make sure the checkbox next to it is checked.

4. Click “Update” to apply the changes. 3. Update your RESPMOD ICAP service profile.

1. Go back to “Local Traffic” > “Profiles” > “Services” > “ICAP”. 2. In the list that appears select your ICAP Response mod service. 3. Set “Preview Length” to 0 and make sure the checkbox next to it is

checked. 4. Click “Update” to apply the changes.

4. Update your Request Adapt profile. 1. Go to “Local Traffic” > “Profiles” > “Services” > “Request Adapt”. 2. In the list that appears select your request adapt service. 3. Set “Preview Size” to 0 and make sure the checkbox next to it is checked. 4. Click “Update” to apply the changes.

5. Update Response Adapt service profile (only if RESPMOD is used) 1. Go to “Local Traffic” > “Profiles” > “Services” > “Response Adapt”. 2. In the list that appears select your response adapt service. 3. Set “Preview Size” to 0 and make sure the checkbox next to it is checked. 4. Click “Update” to apply the changes.

Configuring SSL Interception

The procedure used to scan data transmitted via an SSL connection is similar to the other F5 BIG-IP LTM configuration procedures. The only difference is that you should set up an HTTPS pool and virtual server instead of plain HTTP. Click on the following links to the F5 website to set up HTTPS connection handling:

• Managing client-side HTTPS traffic using a self-signed certificate • Managing client and server HTTPS traffic using a self-signed certificate • Managing client-side HTTPS traffic using a CA-signed certificate

Configuring Service Down Actions

If you followed the steps described in "Configuring REQMOD Service" or "Configuring REQMOD and RESPMOD Services". BIG-IP will be configured to drop all connections when the ICAP service is down.

78

https://support.f5.com/kb/en-us/products/big-ip_ltm/manuals/product/ltm-implementations-11-3-0/9.html%23conceptid




F5 can be configured to forward HTTP data to the web server/web client in the case the ICAP server is unreachable. If you are using an ICAP server pool that contains more than one Metadefender Core ICAP server, F5 can also be configured to forward the HTTP content to a different pool member.

Bypass ICAP server on service down

Note that bypassing ICAP on service down may lower your organization's security as content will be forwarded without being scanned.

1. Open the “Request adapt” profile (“Profiles” > “Services” > “Request Adapt”) 2. Set “Service Down Action” to “Ignore”. 3. Click the "Update" button to apply the changes.

Transfer content to different pool member

If you are using an ICAP server pool that contains more than one Metascan ICAP server, you can also configure BIG-IP to send the HTTP content to a different ICAP pool member.

1. Open your ICAP services pool properties ("Pools" > "Pool List"). 2. Set the "Configuration" list to "Advanced". 3. Set the “Action on Service Down” property to “Reselect”. 4. Click the "Update" button to apply the changes.

Other Proxy Servers

Other Proxy Servers

Metadefender Core ICAP server supports ICAP version 1.0, and is designed to work with any proxy that supports this standard. We have comprehensively verified this behavior with Blue Coat, F5 BIG-IP LTM, Squid, but other proxy servers may also be viable options. For more detailed information regarding support for other HTTP proxies, please contact [email protected].

Metadefender Proxy Management

Metadefender Proxy Management

Starting and Stopping Metadefender Core ICAP Server

79



After a fresh install of Metadefender Core, the Metadefender Core ICAP server will not be running, nor will it start on system reboot. The ICAP server can be started from the Windows Service Control Manager (see below screenshot) or from Metadefender Core Management Console (see next section).

Configuration via Metadefender Core Management Console

To start the ICAP server from the Metadefender Core Management Console, follow the steps below and see the screenshot:

1. In your browser, go to http://localhost:8008/management/dashboard

2. Click on the 'Workflow' tab.

3. Click on 'Metadefender Proxy' on the left side.

4. Select 'Start ICAP Service'.

80

http://localhost:8008/management/dashboard


Configuration via INI

Metadefender Core ICAP server can be configured using an ini configuration file which is installed under Metadefender Core install directory.

String Value Description Supported Values Default

maxnum_sockets Configures the number of threads that will be used by the Metadefender Core ICAP server for handling requests. For optimal

1~1000 60

81


performance, this should be set to a value higher than the number of processor cores available to the Metadefender Core system.

maxnum_connections The maximum number of simultaneous connections that the ICAP server is able to support. Certain proxy servers will use this value to restrict the requests that are made of the Metadefender Core ICAP server and will not send more than this number of simultaneous requests to the Metadefender Core ICAP server.

355

port The port the server is listening to.

1344

path_to_custom_html Path to response contents if message is

File path omslCAPdefault.htm

82


modified.

block_on_max_capacity 0 : Allow files when overloaded. 1 : Block files when overloaded.

0 or 1 0

scan_health_checks

0: Disables scanning for health checks, which improves performance. 1: Scans the client for specific health checks.

0 or 1 0

dump_invalid_requests 0: Disables dumping invalid (ICAP 400 response) raw requests to a file. 1: Dumps invalid (ICAP 400 response) raw requests to a file.

0 or 1 0

log_file

The path to the debug log file.

Absolute file path relative to omsICAPServer.exe directory

<empty>

skip_too_big_file

Allows the ICAP server to skip scanning a file if the file is too large.

0 - Max Unsigned Long

0

83


use_persistent_connections 0 : ICAP server is not using persistent connections. Connections are closed after serving a request. 1 : ICAP server is using persistent connections. Connections are kept open after serving a request.

0 or 1 0

Proxy content caching management

The proxy server should be configured to only cache objects after scanning by the ICAP server. For more information about how your proxy server handles caching with ICAP, please refer to your proxy documentation. The Metadefender Core ICAP server returns a specific tag (called ISTag) to the proxy server with each scan response. This tag is used by the proxy server to determine when its local cache is invalidated. The ISTag represents the current Metadefender Core server configuration. The scan result for a specific object will always be the same as long as the ICAP server stays the same. The proxy server should only cache objects after they are processed by the Metadefender Core ICAP server. The cached object can then be returned to any client requesting it without having to process it through the ICAP server again. To ensure optimal security, the proxy server should be configured to invalidate its cache as soon as the ICAP server ISTag is modified. The following events trigger an ISTag update:

• List of included engines was changed • One or more engines updated

Blocked ICAP Responses

When not allowed content is found in an HTTP request, the ICAP server communicates back the blocked reason to the proxy server.

84


The blocked reason is provided to the proxy from the ICAP server using the following header:

• X-Blocked-Reason: Contains the blocking reason of the content (e.g., "X-Blocked-Reason: Infected", "X-Blocked-Reason: Exceeded Archive File Number").

Reference and useful links for ICAP

Reference and Useful Links for ICAP

ICAP forum: http://www.icap-forum.org/ RFC 3507: http://www.rfc-editor.org/rfc/rfc3507.txt

Sample ICAP requests and responses

REQMOD requests

REQMOD GET request

REQMOD icap://10.0.50.36:1344/OMSScanReq-AV ICAP/1.0 Host: 10.0.50.36:1344 Date: Tue, 02 Sep 2014 21:08:28 GMT Encapsulated: req-hdr=0, null-body=322 Allow: 204 X-Client-IP: 10.0.50.105 GET http://10.0.50.105/ HTTP/1.1 Host: 10.0.50.105 User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:31.0) Gecko/20100101 Firefox/31.0 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept-Language: en-US,en;q=0.5 Accept-Encoding: gzip, deflate Pragma: no-cache Cache-Control: no-cache

85

http://www.icap-forum.org/

http://www.rfc-editor.org/rfc/rfc3507.txt


REQMOD GET Response

ICAP/1.0 200 OK Date: Tue, 2 Sep 2014 21:08:36 GMT ISTag: "04201401171404" Encapsulated: req-hdr=0, null-body=322 Server: Metascan/3700 GET http://10.0.50.105/ HTTP/1.1 Host: 10.0.50.105 User-Agent: Mozilla/5.0 (Windows NT 6.1; WOW64; rv:31.0) Gecko/20100101 Firefox/31.0 Accept: text/html,application/xhtml+xml,application/xml;q=0.9,*/*;q=0.8 Accept-Language: en-US,en;q=0.5 Accept-Encoding: gzip, deflate Pragma: no-cache Cache-Control: no-cache REQMOD GET 204 Response

Advanced Configuration Options

Additional Command Line Functionality

Additional Command Line Functionality

Other Scanning Configurations

Further action on infected files Property Name clean_action

Description Specifies the action to take when an infected file is found.

0: no action 1: quarantine 2: delete

CLI omsCmdLineUtil.exe config ca={0|1|2}

Remark By default, no action will be taken on a file which is identified as infected. This property will be overridden if ScanEx API call parameters specify differently. For more details, refer to “ScanEx” API section of the Software Developer Guide.

Analyze File Type before Scan

86


Property Name analyze_before_scan

Description This is a global setting to decide if the file type of a file should be analyzed. This can be overridden per scan using ScanEx. See the AnalyzeFileTypeEx API for more details.

CLI omsCmdLineUtil.exe config af={0|1}

Remark By default, file type is not analyzed before scanning a file.

Non-English Filenames Property Name adjust_non_english_filenames

Description

This property has 3 possible values. 0: No additional action, pass the file directly to the engines. 1: If we see a non-English file name, copy the file to the Metadefender Core Temp Dir in an English name, scan the temp file, then delete the temp file 2: If we see a non-English file name, and the file is on the same logical drive as Metadefender Core Temp Dir then move the file to a temp file, scan the temp file, then move it back. Otherwise, behave same as option 1.

CLI omsCmdLineUtil.exe config ne={0|1|2}

Remark By default, files with non-English filenames are passed directly to the engines without modification.

Read-only properties

Product version Property Name version

Description The product version, consisting of major version, minor version, build number, and revision separated by comma or period. (e.g., 3.1.0.1212).

CLI omsCmdLineUtil.exe about Current antiviruses Property Name current_avs

Description A list of the anti-malware products that are currently being used for scan or update requests.

CLI omsCmdLineUtil.exe getinfo

Remark If you use API GetProperty, the returning string has the following form: “engine 1|engine2|…|engine N” (where engine 1 ~ N represents the name of engines which are separated by “|”(pipe)).

87


Post Action Script

Post Action Script

Running Script on Clean/Infected Files

Creating a post action script provides the capability to handle simple or advanced application logic. Once a file is scanned by engines, the script will be executed on a file based on scan results.

XML Format for Post Action Script

<post_action> <scripts>

<if type="[scan result]">[script]</if> … <if type="[scan result]">[script]</if>

</scripts> <user_vars>

<user_var name="[user variable]">[user variable string]</user_var> … <user_var name="[user variable]">[user variable string]</user_var>

</user_vars> </post_action>

Description Example

[script] Batch script supported by cmd.exe. For multiline scripts, “&&” must be used. (“&&” for xml)

DEL c:\eicar.com

[scan result] Refer to asynchronous scan API in Software Developer Guide

for clean files, 0

[user variable] Variables that you define data_folder

[user variable string] Value for user variables C:\ data_folder_for_archiving

Pre-defined Variables

88


variables description Note

%%%file_path%%% Absolute path to the file to be scanned.

This variable is only supported on local COM scans

%%%threat_name%%%

Name of threats found by engines. Only applies to infected(“1”) scan result

%%%scan_finished%%%

The time when scan is finished

Post Action Property

Property Name post_action

Description XML-formatted scripts applied per scan result with support of pre-defined variables and user-defined variables.

CLI omsCmdLineUtil.exe config pa=<xml file path>

Management Console

On the Metadefender Core Management Console, only the script should be used in the text box instead of the XML format for Post Action Script described in the above section.

89


Remark Any character which has special meaning to XML (e.g., &, <, >) must be escaped.

Example of Post Action Script XML

Note: In the following examples any variable surrounded with %%% that is not already defined in Pre-defined Variables will need to either be defined in your Post Action XML or replaced with the actual values you intend to use. Moving clean file and infected files to different folder

<post_action> <scripts> <if type="0">move %%%file_path%%% c:\archive_data\clean</if> <if type="1">move %%%file_path%%% c:\archive_data\infected</if> </scripts> </post_action>

90


Uploading infected file to ftp server

<post_action> <scripts>

<if type="1">echo OPEN %%%server%%%> ftp.scr&& echo %%%username%%%>> ftp.scr&& echo %%%password%%%>> ftp.scr&& echo cd test_post_action>> ftp.scr&& echo put %%%file_path%%%>> ftp.scr&& echo CLOSE>> ftp.scr&& echo quit>> ftp.scr && ftp -s:ftp.scr </if> </scripts>

<user_vars> <user_var name="server">127.0.0.1</user_var> <user_var name="username">ftp_user</user_var> <user_var name="password">1234abcd</user_var> </user_vars> </post_action>

Engine Specific Configuration

Configuration specific to each built-in engine should be done via configuration file, “omsConfig.ini”. This file is located in the directory where Metadefender Core is installed. The following table shows which configurations are available for each engine. IMPORTANT: The Metadefender Core service must be restarted to apply any changes.

Heuristic Scan / Extract Archive

Some engines allow you to scan files using heuristics, which can detect viruses that are not yet in the engine’s virus definition database. Enabling heuristic scanning for engines will increase detection of potential new viruses, but will also increase the false positive rate. Note: Enabling heuristic scanning can also increase the engine's scan time.

91


Engine [CATEGORY] Configuration [ATTRIBUTE] Value

AVG [avg] Heuristic scan [heuristic_scan]

1: Enable 0: Disable No entry: default level

Archive library [extract_archive]

ESET [eset] Heuristic_scan [heuristic_scan]


GFI [sunbelt] Heuristic_scan [heuristic_scan]


VirusBuster [virusbuster] Heuristic_scan [heuristic_scan]


Quick Heal [quickheal] Heuristic_scan [heuristic_scan]


Total Defense [ca] Heuristic_scan [heuristic_scan]


Special Tools

92


Special Tools

Import/Export Configuration

You can import and export your Metadefender Core configuration using the omsConfig.exe command line utility. This can be useful for preserving configurations during an upgrade or when deploying multiple Metadefender Core installations with the same configuration.

Help

Syntax: help This function prints the available command line options.

Import

Syntax: import <full file path> [<option>] This command imports configurations from a file. All settings will take effect after a restart of the Metadefender Core services.

Export

Syntax: export <directory> [<option>] This command exports current configurations to a file.

Options

The following argument can be used with the import & export commands.

options description /pass Password to encrypted & extract configuration

93


Quarantine Manager CLI

The Metadefender Core Quarantine Manager CLI (omsQMCLI.exe) should be used to browse and manage quarantines. The size of the Metadefender Core quarantine is limited to 100 MB.

Help

Syntax: help This function prints the available command line options.

Quarantine File

Syntax: quarantine <file path> <threat name> This command adds the specified file to the quarantine database under the given threat name.

Delete Quarantine

Syntax: delete <file path> This command permanently deletes a file which has been quarantined. Note: Disk space will be reused without returning to the OS.

Restore Quarantine

Syntax: restore <quarantine ID> [target directory] This command restores a quarantined file back to the original location. If a file already exists with the same name, a number will be appended to the file name. You can override the location the file is to be restored to by specifying the target directory.

Browse Quarantine

94


Syntax: list [<minimum number of quarantines to display>] This command lists quarantined files.

Whitelist/Blacklist

You can specify a whitelist and/or blacklist for Metadefender Core to use in scanning via the omsFilterCLI.exe tool. The default path of this tool is C:\Program Files (x86)\OPSWAT\Metadefender Core 1/4/8/12/16\omsFilterCLI.exe. Whitelist: Files that will not be scanned and will automatically be marked as clean Blacklist: Files that will not be scanned and will automatically be marked as a threat Command Description addtoblack <path> <type> <threat>

add the file to the blacklist

addtowhite <path> <type> add the file to the whitelist

list <type> retrieve whitelist and blacklist

about shows the info of the current version

Argument Description <type> 0: all, 1: archive library, 2: engines

<threat> Name of threat for reference

<path> Absolute file path

REST Server Configuration

REST Server Configuration

How to Enable IIS Logging

95


By default, Internet Information Services (IIS) logging is disabled in the Metadefender Core REST server. In order to enable IIS logging, please follow these steps:

1. Go to the ‘REST\Config’ folder inside Metadefender Core's installation directory and open the ‘applicationhost.config’ file.

For Example: C:\Program Files(x86)\OPSWAT\Metadefender Core

4\REST\Config\applicationhost.config 2. Uncomment these 2 properties in ‘applicationhost.config’ file:

<! -- <add name="HttpLoggingModule" image="%IIS_BIN%\loghttp.dll" /> --> <! -- <add name="HttpLoggingModule" lockItem="true" /> -->

Restart Metadefender Core REST server using these steps: Using Windows services panel:

1. Go to Start menu > Administrative Tools and click on ‘Services’. 2. In the Services panel, right-click on ‘Metascan REST Service’ and click

‘Start’.

Using the command line:

1. Go to Start menu > Command prompt. 2. To stop the service, execute the ‘net stop omsrest’ command. 3. To restart the service, execute the ‘net start omsrest’ command.

Enabling HTTPS

By default, communication with the RESTful web server will not be encrypted. By setting up an HTTPS server, the server can enforce secure connections between client and server on an SSL channel. Outlined in the sections below are the steps to configure IIS Express to host an HTTPS server.

Requirements

• A trusted certificate issued by a certificate authority OR a self-signed certificate used for development testing

• See below on installing a self-signed server certificate • See here on installing a CA-signed server certificate

96

http://www.microsoft.com/technet/prodtechnol/WindowsServer2003/Library/IIS/a2f35fcd-d3b6-4f39-ba93-041a86f7e17f.mspx?mfr=true


Installing a Certificate

1. Click on Start menu, type “MMC.exe” in the Search box and execute. 2. In the MMC window, click on File > Add/Remove Snap In. 3. In the ‘Available snap-ins’ list, select ‘Certificates’ and click ‘Add’. 4. Select ‘Computer Account’, click ‘Next’, ‘Finish’ (Note: This is why you can't just run certmgr.msc) and add it.

5. Click ‘Ok’ to load the certificates snap-in. 6. Expand the ‘Certificates’ menu and browse to your certificate location. We will use ‘metascan_rest’ certificate as an example. Your certificate may have any name.

7. Double-click on the certificate name you want to use for the Metadefender Core REST Server and go to the ‘Details’ tab.

97


8. Select ‘Thumbprint’ in the list and copy the value into a text editor for later use

. 9. Click on ‘Start’ menu and run ‘Command Prompt’. 10. Execute the following command in the console: netsh http add sslcert ipport=0.0.0.0:443 appid={214124cd-d05b-4309-9af9-9caa44b2b74a} certhash=<certificate thumbprint retrieved on step 8> The following message should appear:

Note: The spaces in the thumbprint should be removed for the command to execute properly.

98


Enable HTTPS on IIS Express

1. Open the ‘<Metadefender Core installation directory>\REST\Config folder’ (e.g., C:\Program Files (x86)\OPSWAT\Metadefender Core 16\REST\Config).

2. Open the ‘applicationhost.config’ file in a text editor. 3. Go to the ‘<sites>’ tag and add the HTTPS binding to the ‘metascan_rest’ website

as shown in the example below. Note that this port can not be in use by any other applications.

4. OPTIONAL: If you want to keep REST HTTPS only, remove the <binding protocol="http" bindingInformation=":8008:" /> line from applicationhost.config.

5. Save and close the ‘applicationhost.config’ file. 6. See above on how to restart the Metadefender Core REST Service (execute ‘net

stop omsREST’ and then ‘net start omsREST’ in command prompt). 7. Test that the site works by visiting https://localhost. You should see the following

result:

Configuring Metadefender Core Quarantine to use HTTPS

1. Configure Metadefender Core to use HTTPS by following the steps in the preceding section.

99

https://localhost/


2. Navigate to the Quarantine folder (by default C:\Program Files (x86)\OPSWAT\Metadefender Core X\Metascan Quarantine)

3. Open Metadefender.Quarantine.Service.exe.config and change the following section

<setting name="RestBaseUrl" serializeAs="String"> <value>http://localhost:8000</value> </setting> <setting name="QuarantineBaseUrl" serializeAs="String"> <value>http://localhost:8000</value> </setting> <setting name="QuarantineProtocol" serializeAs="String"> <value>REST</value> </setting> <setting name="MetascanUrl" serializeAs="String"> <value>http://localhost:8008/metascan_rest/</value> </setting> <setting name="WebBaseUrl" serializeAs="String"> <value>http://localhost:8008/management/#</value> </setting>

to <setting name="RestBaseUrl" serializeAs="String"> <value>https://localhost</value> </setting> <setting name="QuarantineBaseUrl" serializeAs="String"> <value>https://localhost</value> </setting> <setting name="QuarantineProtocol" serializeAs="String"> <value>REST</value> </setting> <setting name="MetascanUrl" serializeAs="String"> <value>https://localhost/metascan_rest/</value> </setting> <setting name="WebBaseUrl" serializeAs="String"> <value>https://localhost/management/#</value> </setting> 5. Restart the Metadefender Core Quarantine Service

Configuring Mail Agent for HTTPS

100

http://localhost:8000/


http://localhost:8008/metascan_rest/

http://localhost:8008/management/

https://localhost/

https://localhost/

https://localhost/metascan_rest/

https://localhost/management/


1. Edit the Mail Agent configuration file, usually located at C:\Program Files (x86)\OPSWAT\Metadefender Core X\Metadefender Mail Agent\Metadefender.Email.Engine.Service.exe.config

1. Change

<setting name="RestBaseUrl" serializeAs="String"> <value>http://localhost:8000</value> </setting> <setting name="QuarantineBaseUrl" serializeAs="String"> <value>http://localhost:8000</value> </setting> <setting name="QuarantineProtocol" serializeAs="String"> <value>REST</value> </setting> <setting name="MetascanUrl" serializeAs="String"> <value>http://localhost:8008/metascan_rest</value> </setting>

To

<setting name="RestBaseUrl" serializeAs="String"> <value>https://localhost</value> </setting> <setting name="QuarantineBaseUrl" serializeAs="String"> <value>https://localhost</value> </setting> <setting name="QuarantineProtocol" serializeAs="String"> <value>REST</value> </setting> <setting name="MetascanUrl" serializeAs="String"> <value>https://localhost/metascan_rest</value> </setting>

2. Restart the Metadefender Generic Mail Agent service

Advanced REST Server Configuration

Storing Data on the REST Server

The server can be configured so that any data requested for scanning can be stored. This should be configured on the Metascan registry key (HKEY_LOCAL_MACHINE\SOFTWARE \OPSWAT\Metadefender Core on x86, HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OPSWAT\Metadefender Core

101



http://localhost:8008/metascan_rest

https://localhost/

https://localhost/

https://localhost/metascan_rest


on x64)). The Metadefender Core REST service must be restarted after this key has been updated for the change to take effect.

String value Value Description

rest_filedb_type NONE or mongoDB

Set to mongoDB to enable storing files, the default is NONE. This key does not exist by default and must be created on the Metadefender Core system.

rest_store_file 0 or 1 Set to 1 to enable storing files, the default is 0.

Client Session Control

REST server can be configured to control clients under session. This is useful if you have multiple Metadefender Core REST servers and plan to load balance the number of clients per server. This should be configured on Metadefender Core registry key (HKEY_LOCAL_MACHINE\SOFTWARE \OPSWAT\Metadefender Core on x86, HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OPSWAT\Metadefender Core on x64)


rest_max_clients integer The maximum number of clients which should be handled by the server.

rest_session_timeout

integer The seconds in which clients will be removed from session. Setting this to 0 indicates to disable usage of session. By default, this is configured to 180 (3 minutes).

Reload Configuration

In order to update any modified setting, you must restart the Metadefender Core REST server. It can be restarted with the Windows service controls. See above for instructions.

Load Balancing

When multiple instances of Metadefender Core are serving multiple clients with higher

load than one Metadefender Core can handle, clients should make progress

(file\<data_id>) on a specific server. Setting this value results in initial file upload

102


response to provide rest_ip information so that client can make follow up request to this

specific server. This should be configured on Metadefender Core registry key

(HKEY_LOCAL_MACHINE\SOFTWARE \OPSWAT\Metadefender Core on x86,

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OPSWAT\Metadefender

Core on x64)


rest_ip integer <IP address or URL> that client can utilizes

RAM Disk Configuration

Overview / Use case

The RAM Disk (or RAM Drive) is configured from the Windows device property dialog. The RAM Disk turns a chunk of your system’s RAM into a disk drive.

• The default RAM disk install size is 1 GB. You can change this via the Disk Size field in the RAM Disk Device Manager after installation.

• The RAM Disk is more secure than a fixed disk because the contents of the disk will be wiped clean on a system reboot

• It provides a speed optimization because the AV scanners being used do not have to fetch the data from a physical disk. The file is already stored in RAM

• Here are two use cases: o Temporary directory for extracting archive files before scanning

Set “temp_dir” property of Metadefender Core to RAM Disk. o As a temp directory for your application

You could use the RAM Disk if your application accepts files which are uploaded by your customers and you want to perform some temporary actions on that content before scanning.

RAM Disk as Temporary Directory

When you utilize the RAM Disk as a temporary directory, Metadefender Core uses this directory for the following purposes:

• Extracting archive files (when “internal_archive_lib” is set to “1” (true))

103


• Writing data to a file in this directory if using any of the Metadefender Core Buffer (stream) APIs

Note: If the buffer is bigger than the available RAM Disk space, scan APIs will return E_FAIL

• If the RAMDisk is used as the primary temp directory, the maximum

extracted archive file size will be ½ the size of the RAMDisk for a single archive. If an archive exceeds that size an error will be returned unless a secondary temp file is configured. If a secondary temp file is configured then the archive will use it to extract the archive. The size of the secondary temp files is always ½ the available space on the drive

Device Property

In order to change the RAM Disk properties, open the Device Manager using the following steps:

• Start -> Run -> devmgmt.msc -> 'Ram Drive' category -> Right-click 'OPSWAT Secure RAM Disk' -> Properties

Hardening Options

CORS Configuration

Metadefender Core's cross-origin resource sharing (CORS) configuration can be hardened to only allow access from a restricted list of systems. The following edits can be made in C:\Program Files (x86)\OPSWAT\Metadefender Core X\REST\Web\web.config. To restrict access to the local system, the line

<add name="Access-Control-Allow-Origin" value="*"/> can be changed to

<add name="Access-Control-Allow-Origin" value="http://localhost"/> then add a new rule to <system.webServer><rewrite><outboundRules>

<rule name="Allow CORS on specify ip/subnet" > <match serverVariable="RESPONSE_Access-Control-Allow-Origin" pattern=".+" /> <conditions>

104


<add input="{REMOTE_ADDR}" pattern="^(192.168.200.*|192.168.201.102)$" /> </conditions> <action type="Rewrite" value="*" /> </rule>

Database Configuration

Overview

Metadefender Core supports comprehensive logging to a database. MongoDB is included in the Metadefender Core installation.

Supported Database Management Systems

MongoDB is the recommended database and is included in the Metadefender Core installation. By default, remote connections to MongoDB are disabled. Updating <Metadefender Core install dir>\Mongo\mongodb.conf and fully restarting Metadefender Core and the MongoDB process will enable remote connections.

Database Scheme

The Metadefender Core database scheme is not intended for use by external applications and may change from release to release. Building custom applications that directly access the Metadefender Core database is discouraged.

Manual Configuration

Metadefender Core supports manually configuring the database after the installation of Metadefender Core . Changing these configurations should be done while the Metadefender Core service is stopped. You will use omsConfig.exe to import the configuration from an INI file you create which contains a [database] section.

String Value Description Supported Values Remark db_auth_type Legacy registry

which is no longer used.

db_instance The name of database instance

Valid name of database instance or host name

Common instance names include the machine name

db_name The name of database

Valid name of database omsdb

db_type database type • mongoDB NONE is used to disable

105


• NONE logging to database db_port database port MongoDB db_user Username for the

account which has access to database

The MongoDB username

db_pass Password for the account which has access to database

The MongoDB password

Disabling Specific Types of Logging

Metadefender Core DB Controller provides a flexible way to disable specific types of logs. This should be done in the “omsConfig.ini” file [db controller] section before Metadefender Core service starts running. Note: OPSWAT should be consulted prior to making any database configuration changes. The following table shows the log types and the name of the attribute in the INI file which can be disabled. Note: To apply any change, the Metadefender Core service must be restarted. Note: If an attribute is not provided, the default value will be applied. Configuration [ATTRIBUTE]

Value

log_file_info 0: disable logging of detected file type for scanned files/data 1: enable logging of detected file type for scanned files/data

log_all_scan_history o: only log scan results for infected files 1: log scan results for all files

Remote Logging

As mentioned in the table in Manual Configuration section above, the name of the db_instance should include the IP address or system name of the server which has the DBMS you wish to log to.

Troubleshooting

If logging does not appear to be working, please check the Windows Event Log for relevant messages.

106


Metadefender Core Developer Guide

System Integration Requirement

System Requirements for Metadefender Core

• Operating System: Windows 7 / 8 / 8.1 / 10 / 2008 / 2008 R2 / 2012 / 2012 R2

• .NET 4.x • Windows hotfix for Windows Server 2008 R2 or Windows 7

Browser Requirements for the Metadefender Core Management Console

One of the following browsers is required to view the Metadefender Core Management Console:

• Internet Explorer 10 or later • Safari 5.1 or later • Firefox 3.5 or later • Chrome

The standard Metadefender Core packages require the following amounts of RAM and free hard drive space:

Package System RAM

Free Hard Drive Space

Metadefender Zero

4 GB 16 GB

Metadefender 4

8 GB 32 GB

Metadefender 8

8 GB 32 GB

Metadefender 12

16 GB 32 GB

107

http://support.microsoft.com/kb/2731284


Metadefender 16

16 GB 32 GB

Metadefender 20

16 GB 32 GB

Integration Upgrade Tips

OPSWAT is committed to making the Metadefender Core API backward compatible to any older version of Metadefender Core. With the growing capabilities and features of Metadefender Core, it is necessary to add new APIs, new COM Connection Points, and new return types. When you upgrade your integration to Metadefender Core to a newer version, please keep the following factors in mind:

• C/C++ application: By the design of COM, all Connection Points are required to be implemented in your application. Please check Metascan.idl for newly added Connection Points

• Extended API: We strongly recommend replacing any API call with the “-Ex” postfix API call if applicable. For example, GetUpdateStatus can be replaced by GetUpdateStatusEx

Important Concepts and Terminology

Usable AVs (Usable AMs)

Usable AVs are the anti-malware engines which Metadefender Core can use to process scan requests. All embedded engines are usable anti-malwares engines. For anti-malware applications which are installed by you, please check the list of products Metadefender Core supports. This list can be retrieved from:

• Init API

• Any command line utility(omsCmdUtil.exe) command

• Metadefender Core Management Console Configuration Page

Current AVs

108

http://www.opswat.com/products/metascan/packages

http://www.opswat.com/products/metascan/packages


Current AVs are anti-malware engines which Metadefender Core automatically utilizes for scans and updates. This list is affected by license and properties such as included antiviruses, excluded antiviruses, and supported pre-installed antiviruses. For example, if you installed Metadefender Core 8 and you have McAfee VirusScan installed on your machine but you exclude the ESET scanning engine and disable customer-licensed products, your usable AVs and current AVs will be designated as below: Usable AVs (Usable AMs) Current AVs

- Avira scan engine - ESET scan engine - ClamAV scan engine - AhnLab scan engine - ThreatTrack scan engine - Bitdefender scan engine - Total Defense scan engine - Quick Heal scan engine - McAfee VirusScan

- Avira scan engine - ClamAV scan engine - AhnLabscan engine - ThreatTrack scan engine - Bitdefender scan engine - Total Defense scan engine - Quick Heal scan engine

Synchronous/Asynchronous Scan

Metadefender Core can be delegated to queue scan requests and return the results of queued scans via callbacks with extensive scan details. Even if your application is single threaded, you can process many scan requests without blocking. In other words, as soon as you have data to be scanned and you call the asynchronous scan API of Metadefender Core (for example, PutToScanQueue), you can continue to request scans without waiting for the results of the scan. Contrarily, synchronous scan is more suitable if your application creates scan requests in many threads. Refer to the ScanEx section on how to retrieve scan details when scanning synchronously.

Valid File Name

A valid file name as a parameter for any API related to scanning files, should meet the following requirements:

• Absolute path to file, folder, and drive e.g., c:, C:\Windows, C:\boot.ini

• File path should be limited to the local machine. For example, “\\remote_machine\testfile.txt” would be recognized as an invalid path

109


Programming with Metadefender Core

When you write your application that uses Metadefender Core to scan the content, you have the option of utilizing various kinds of API and deployment scenarios.

Selecting Where Metadefender Core Is Installed

Based on your application’s architecture and requirements, you have two options in terms of integrating Metadefender Core.

1. Metadefender Core is installed locally

Your application integrates with Metadefender Core, which is installed on the same system as the one on which your application is running.

2. Metadefender Core is installed remotely Your application integrates with a Metadefender Core server that is installed on a separate system.

110


Select Your API

Based on where you have Metadefender Core installed, you have various options in terms of programming interfaces for Metadefender Core.

Local Installation

When Metadefender Core is installed locally on the system, you have the following options to interface with:

• Metadefender Core COM API

• Java API (Documentation is available as part of your Metadefender Core installation under the “Docs” folder)

• Metadefender Core Command Line Utility

Remote Installation

When Metadefender Core is installed on a remote system, you have the following options to interface with:

• Metadefender Core Web API

• Metadefender Client

Metadefender Core Command Line Utility

Metadefender Core provides a Command Line Utility (omsCmdLineUtil.exe) that enables a user to run Metadefender Core operations such as scanning files, getting or setting preferences/properties, etc.

Help

This function prints the available command line options. Syntax: help

Advanced commands

111


This function prints the available command line that is experimental. Please use after consulting with OPSWAT. Syntax: helpex

Scan a file

This function allows a user to scan a file using all usable antivirus products on the machine. Syntax: scan <file path> Example: scan C:\test.txt

Scan a buffer

Similar to scanning a file, command line utility has an option to scan a memory buffer. Syntax: scan {<file path to the file to read as buffer>} Example: scan {C:\test.txt}

Scan a boot sector

Scan the boot sector of a drive. Scanning a drive does not include scanning a boot sector. This call should be made separately to scan the boot sector of a drive. Syntax: scanbootsector <drive letter> Example: scanbootsector {C:}

Scan based on file signature

Scan based on the signature of a file. Currently only SHA256-based signature is supported. The signature should be hex-style string representation (64 characters). Syntax: scansignature <file signature> Example: scansignature FABD7FF543FF8B42E1640B55E781E60DAD08BAE8

112


Get Information

Prints the current Metadefender Core property values as described in the Properties section. Syntax: getinfo

Update anti-malware Products

Updates Metadefender Core antivirus engines and prints whether the updates were succeeded or failed. If the engine name is not specified, an update for all engines is initiated. Syntax: update Syntax: update <engine name> *engine name MUST be full name (case is NOT sensitive). Double quotations (“”) are required for engine name with space. Example: update “CA scan engine”

Configuration

This method allows a user to set Metadefender Core properties. Syntax: config {options=args} -update_interval_minutes(um)=<minutes> -update_timeout_millis(to)=<millisecond> -included_avs(in)=<included antivirus> -excluded_avs(ex)=<excluded antivirus> -support_preinstalled(sp)={0|1} -thread_pool_size(tp)={the number of pool size} -temp_dir(td)={directory path} -internal_archive_lib_enable(le)={0|1} -internal_archive_lib_recursion_level(rl)={recursive level} -internal_archive_lib_extract_concurrently(ec)={0|1} -wait_on_update(wu)={0|1} -report_on_scan_start(ss)={0|1}

113


-report_on_async_scan_progress(rasp)={0|1} -enable_cache_scan(cs)={0|1}

-clean_action(ca)={0|1|2} Example: config tp=50 (To set the thread pool size to 50)

AnalyzeFileType

Prints the file type and file extension of input file name. Syntax: analyzefiletype <file path> Example: analyzefiletype c:\test.txt

GetUpdateInfo

Updates the antivirus information currently associated with Metadefender Core. Syntax: getupdateinfo

ScanAndClean

This method is used to scan and clean the input file. Syntax: scanandclean <file path> Example: scanandclean c:\test.txt

CheckLicense

This method is used to check if the license is valid and when it expires. Syntax: checklicense Example: checklicense

Metadefender Core COM API

Overview

114


The Metadefender Core COM server externalizes COM (Microsoft’s Component Object Model) interfaces. The interfaces are all based on the IDispatch automation interface making integration possible from many scripting languages. When the Metadefender Core Server is started (this happens when the user logs in, or upon the first invocation of the server from a client), it starts updating all the supported antivirus engines on the system. The server repeats the update process at configurable intervals. Before any method is called, a client instance must be initialized by calling Init or InitEx (deprecated). For APIs via callbacks, please refer to the COM Connection Points section.

Scan Outcome Return Type

Metadefender Core categorizes files as 'blocked' or 'allowed' based on the scan result. The following scan results causes a file to be labeled as 'blocked': Infected/Known, Suspicious, Failed To Scan, Cleaned, Unknown, Quarantined, Skipped Dirty, Not Scanned, Aborted, Encrypted. Return value

Description Note

0 Clean 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 Threat is found and file is cleaned (repaired or deleted)

5 Unknown Unknown scan result

6 Quarantined File is quarantined

7 Skipped Clean Scan is skipped because this file type is in whitelist

8 Skipped Dirty Scan is skipped because this file type is in blacklist

9 Exceeded Archive Depth

Threat is not found but there are more archive levels which were not extracted. This is affected by the Metadefender Core property,

115


‘internal_archive_recursive_level’

10 Not Scanned 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 All ongoing scans are purged by StopScan API call

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 Metadefender Core scan progress callbacks since the engines do not perform any scan operations. If the Internal Archive Library is OFF Metadefender Core will pass the encrypted files to the engines directly, bypassing the detection.

13 Exceeded Archive Size

The extracted archive is larger than set in the maximum file size for archive. (For more details, refer to “archive_lib_max_size” properties in Metadefender Core Configuration Guide)

14 Exceeded Archive File Number

There are more files in the archive than set in the maximum number of files extracted. (For more details, refer to “archive_lib_max_num_files” properties in Metadefender Core Configuration Guide)

Other Important Return Types

Return Type Values API/Connection points which

use this return type ThreatList A threat list found on the scanned

object, otherwise null (Threat name should NOT be used in a way that affects the application logic. For example, a threat name can be an empty string )

Scan ScanEx ScanAndClean PutToScanQueue PutToScanAndCleanQueue

FileTypeShort “E” – Executable (EXE, DLL, …) “D” – Document (MS Office word

116


document, MS Office excel sheet) “A” – Archive (Zip, Rar, Tar, …) “G” – Graphical format (Jpeg, GIF, TIFF, BMP, …) “F” – Folder “Y” – Logical drive “I” – Disk image “T” – Text “P” – PDF format “M” – audio or video format “Z” – mail messages (MSG, …) “O” – Other (anything that is not recognized as one of the above) Note: An ISO is treated as an archive file type (type “A”) and not as a disk image (type “I”).

Metadefender Core Methods

Metadefender Core Methods

This section lists all the methods available via Metadefender Core COM object. Before you can call any of the methods listed here, you need to create Metadefender Core COM object called ‘Metascanner’. When you install Metadefender Core, Metascanner is registered on the system as part of the type library MetascanLib. Metascanner Program ID: Metascan.Metascanner.1

Init

This method is called to initialize the connection to the Metadefender Core service. This method needs to be called before any other method can be called. HRESULT Init (

[out, retval] VARIANT *UsableAntiMalwares ) Arguments

117


Argument Description Data Type

UsableAntiMalwares The list of anti-malware engine names available to be used with this instance of Metadefender Core

Array of strings (VT_BSTR)

Process

This method processes a file through a workflow based on the specified user agent. HRESULT Process (

[in] VARIANT ContentsToBeProcessed, [in] VARIANT ContentsType, [in] VARIANT UserAgent, [in] VARIANT InArgsArray, [out]VARIANT *OutDetail, [out,retval]VARIANT *OutArgsArray

) Arguments Argument Description Data Type

ContentsToBeProcessed

Full path to the file to be processed string

ContentsType 0 : holds a file path (Currently this is ignored since only 0 is supported)

UINT32

UserAgent

A string to identify the user. Used for mapping to a specific workflow.

string

118


InArgsArray A list of input arguments in following order: 0: Sync flag (Reserved for future use. Currently this is ignored) 1: Custom ticket (for now, only integer range value is supported and future it will support more ) 2: Password for archives (Reserved for future use. Currently this is ignored) 3: AdditionalLoggingParameter This is passed to the User description argument in ScanEx if scanning is enabled on the workflow. (Reserved for future use. Is currently ignored.) 4. File Display Path (The full path of the file from the source machine to display to the user after processing) 5. Disable Logging (Disallow Metadefender Core to log any file type analysis and scan results)

Safearray of variants with the following order 0: boolean 1: string 2: string 3: string 4: string 5.boolean

OutDetail JSON result details string Example JSON { "Ticket": "974989300" } In case of error [e.g. invalid license, server too busy, etc...] : { "Error": "Invalid License" }

string

119


OutArgsArray 0: Ticket number to be used to associate callback results.

Safearray of variants with the following order 0: string

Note: When the Metadefender Core server is too busy, the HRESULT value returned will be E_OUTOFMEMORY

OnProcess

This callback is fired after each Process method when a pre-defined event is found. void onProcess (

[out] VARIANT *OutDetail, [out,retval]VARIANT *OutArgsArray

) Arguments

Argument Description Data Type

OutDetail The details from this event. The JSON schema depends on the callback type. See "Callback Type:" for more details.

string

120


OutArgsArray 0: CallBackType: Because OnProcess is a general callback that is fired for different events, this specifies the event type. See the callback types for details of the type. 1: Ticket: The ticket returned from the Process API. For example, 974989300. 2: The final result of processing the specified file through a workflow.

1 = The file was allowed. JSON equivalent

is "Allowed" 2 = The file was blocked. JSON equivalent

is "Blocked" 3 = The file is currently being processed.

JSON equivalent is "Processing"

Safearray of variants with the following order 0: UINT32 1: string 2: UINT32

Callback Types

Callback Type

Description Example JSON

2 This callback method will be invoked whenever each engine completes the scan. This callback can be used for a progress report of scanning when more than one engine is used. If engines are not used for any reason such as encrypted archive or scan request on a known file, no progress report will be fired.

{ "type": "ScanProgressReport", "ticket": 974989300, "scan_result": "1", "threat_list": [

"eicar", "eicar" ], "product_name": "Clamwin Scan Engine "scan_start_time": "6/5/2014 2:32 PM", "scan_end_time": "6/5/2014 2:32 PM", "scan_time_(ms)": "1", "file_path": "C:\\some\\file.txt", "process_result": "Processing"

}

121


4 This connection point is fired whenever a scan is completed. This event is not global but specific to the client which makes this scan request. In other words, when scanning is requested by a client, other client objects will not get a callback when the scanning is completed.

{ "type": "OnScanComplete", "ticket": 974989300, "scan_result": "1", "threat_list": [

"eicar", "eicar" ], "scan_start_time": "6/5/2014 2:32 PM", "scan_end_time": "6/5/2014 2:32 PM", "scan_time_(ms)": "2", "file_path": "C:\\some\\file.txt", "process_result": "Processing"

}

7 This callback method will be invoked when Process' archive handling is enabled and an archive was successfully extracted. This callback can be used to determine if a processed file is an archive.

{ "type": "ArchiveFileInfo", "ticket": 783676241, "file_path": "2files_dirty.zip", "process_result": "Processing"

}

122


8 This is fired after a file has been fully processed through each stage of a workflow. FTC Details If FTC is enabled and copy/move is disabled, the converted file will appear next to the original file. If FTC and copy/move are enabled, the converted file location will be reported in "post_processing.copy/move_destination" Collisions are handled by incrementing the file name: file_name.txt , file_name_1.txt , file_name_2.txt , .. Possible Blocked Reasons • Mismatch detected: "Mismatch" • File type disallowed: "Filtered" • Scan Result: "Known | ("Dirty" or

"Infected") | Suspicious | Failed | Cleaned | Unknown | ("Skipped Dirty" or "Skipped Infected") | Not Scanned | Aborted | Password Protected Document"

• Archive: "Encrypted Archive | Missing File During Extraction | Empty Archive | Insufficient Space For Archive Extraction | Exceeded Archive Size | Exceeded Archive File Number | Archive Extraction Error | Exceeded Archive Depth | Archive Error"

Possible Process Results • "Allowed": the file is allowed • "Blocked": the file is blocked • "Processing": the file is currently

being processed

Possible Action Ran Results • Sanitized • Copied • Moved • Quarantined

{ "type": "ProcessComplete", "ticket": "974989300", "process_result": "Allowed", "file_path": "C:\\some\\file.txt", "user_agent": "metascan_rest", "profile": "Default", "file_type_skipped_scan": false, "blocked_reason": ""

}

If Post Processing has run:

{ "type": "ProcessComplete", "ticket": "974989300", "process_result": "Allowed", "file_path": "C:\\some\\toConvert.docx", "user_agent": "metascan_rest", "profile": "Default", "file_type_skipped_scan": false, "blocked_reason": "", "post_processing": {

"actions_ran": "Converted | Quaran "actions_failed": "Convert Failed | Q "converted_to": "pdf", "copy_destination": "C:\\toConvert

} }

123


• 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

124


9 This callback is fired for AnalyzeFileType. It will be fired for a single file as well as for individual files within an archive. For a single file it will be a fully qualified path, such as: "C:\\level1\\file.txt" For a file inside an archive it will be prefixed with \\, such as: "\\level1\\file.txt"

{ "type": "FileTypeAnalyze", "ticket": "974989300", "file_path": "C:\\some\\toConvert.docx", "file_size": 5134 "file_type_category" : "E", "file_type_description" : "Win64 Executa "file_type_extension" : "EXE/DLL", "md5": "20A2DFB5EC69BCEA66203CF "sha1": "6D5052FC0ED06C0D975F19D "sha256":"4A7C7077F929041D2D2A18 "process_result": "Processing"

}

ScanEx

This method is an extensible scan API which replaces previous the APIs - PutToScan(AndClean)Queue and Scan(AndClean). It allows the setting of various scan options that can be configured for each scan request. HRESULT ScanEx (

[in] VARIANT ContentsToScan, [in] VARIANT* InArgsArray, [out, retval] VARIANT* OutArgsArray

) Arguments Argument Description Data Type ContentsToScan

This argument may hold one of four types: a file path to be scanned, a file signature to be scanned, a boot sector to be scanned, or a memory buffer to be scanned, based on the data type of this parameter and input argument (InArgsArray) value

- A file path: if the type of this parameter is a string and the fifth argument of InArgsArray is set to 0 or the size of InArgsArray is 3

- A file signature: if the type of this parameter is a string and the fifth argument of InArgsArray is

File name: string Buffer: byte array

125


set to 1 - A boot sector scan: if the type of this

parameter is a string and the fifth argument of InArgsArray is set to 2

- A memory buffer: if the type of this parameter is a byte array(byte[])

- Virtual Machine image folder path InArgsArray A list of input arguments in following order:

1. (boolean) Sync flag (true: synchronous scan , false or invalid value: asynchronous scan)

2. (boolean) Clean flag (true: Action on dirty file, false: keep)

3. (UINT32) Custom ticket #

- maximum 9 digits from 1-999999999 or 0 for not using custom ticket #

4. (UINT32) Analyze before scan

0: disable analyze file before scan 1: enable analyze file before scan 2: use global setting

(“analyze_before_scan”)

5. (UINT32) Contents Type

0: ContentToScan argument holds file path or memory buffer

1: ContentToScan argument holds SHA1-based signature.

2: ContentToScan argument holds driver letter for a boot sector scan

4: ContenToScan argument holds Virtual Machine image folder path (Virtual machine disk must contain a Windows based filesystem)

6. (UINT32) Clean Action Type

0: take no action 1: quarantine (ignore global setting,

“clean_action”) 2: delete (ignore global setting, “clean

action”) 3: follow global setting

Array of variants

126


7. (UINT32) Caching option

0: disable to cache for this scan request 1: enable to cache for this scan request 2:rescan (disregard existing cache and

update with new scan result) 3: use global setting(“enable_cache_scan”)

8. (String) Password for encrypted archive.

- Use empty string to when no password is required.(“enable_cache_scan”)

9. (String) User agent

- This is used to associate scan history with the source of scan request. Empty string is allowed.

10. (String) User description

- This will be logged along with scan request for the caller’s purpose. Empty string is allowed.

- Pass the following JSON formatted string to control the file name and file path to be logged:

{"file_info.original_file_path":"<original file path not including file name", "file_info.display_name":"<original file name>"}

11. (UINT32) Configure logging

0: disable logging this particular scan request

1: enable logging this particular scan request

2: use global setting (omsConfig.ini)

12. (UINT32) Archive File Handling

0: do not extract archive file for this particular request

1: extract archive file for this particular scan

127


request 2: use global setting

(“internal_archive_lib_enable”)

OutArgsArray A list of outputs with the following order:

1. (UINT32) Ticket number (if custom ticket # is specific in InargsArray, same ticket number is returned

2. (UINT32) Scan result as described in ScanOutCome Return Type

3. (Array of strings) List of threats 4. (String) Scan detail per engine

<scan_details> <objects > <object name="[object name]">

<engine_result> <engine_name>[engine name]</name> <scan_result>[scan outcome for the engine]</scan_result>

</engine_result> </object>

</scan_details> [object_name]: file name or signature depends on type of scan requested. [scan outcome for the engine]: Scan result per engine as described in ScanOutCome Return Type

5. (String) File type information

this is returned only if analyze_before_scan is enabled or the third argument of InArgsArray is set to 1 <file_type> <objects size=""> <object> <sha1></sha1>

Safearray of variants

128


<type_infos size=""> <type_info> <long></long> <short></short> <extension></extension> </type_info> </type_infos> </object> </objects> </file_type>

UpdateAntiViruses

This method is called to initiate an update of all anti-malware engines at the same time on the local machine. It is recommended to perform updates via automatic periodic update which is performed at predetermined intervals as configured in “Update Interval” property. HRESULT UpdateAntiViruses ( ) Note: The result of this call is provided via the OnUpdateCompleteconnection point.

UpdateEngine

This method is called to initiate an update of a specific anti-malware engine on the local machine. HRESULT UpdateEngine (

[in] VARIANT EngineName, [in] VARIANT ReservedArg

) Arguments Argument Description Data

Type EngineName The name of the anti-malware product that needs to be

updated (case in-sensitive) string

129


ReservedArg Reserved. Any type of Variant is allowed except NULL pointer.

Note: The result of this call is provided via the OnUpdateCompleteconnection point.

GetProperty

Read one of Metadefender Core's internal properties. HRESULT GetProperty (

[in] VARIANT PropertyName, [out, retval] VARIANT* PropertyValue


Type PropertyName The name of the requested property. For valid names,

please refer to the Metadefender Core Configuration Guide

string

PropertyValue The value of the property string

SetProperty

Modify one of Metadefender Core's internal properties. HRESULT SetProperty (

[in] VARIANT PropertyName, [in] VARIANT PropertyValue


Type PropertyName The name of the requested property. For valid names,

please refer to the Metadefender Core Configuration Guide

string

130


PropertyValue New value of the property string

GetUpdateStatusEx

This method returns information about the virus definition files of the requested product. HRESULT GetUpdateStatusEx (

[in] VARIANT ProductNamePart, [out] VARIANT * ProductDescription, [out] VARIANT * VirusDefinitionDate, [out] VARIANT * VirusDefinitionVersion, [out] VARIANT * VirusDefinitionSignature, [out] VARIANT * ProductEngineVersion


Type ProductNamePart A part of the product name of the desired

package. Definition file information of the product containing this value will be returned

string

ProductDescription The description of the product that matched ProductNamePart

string

VirusDefinitionDate The dates of virus definition files for the product. 0 will be returned if the data file time is unavailable, for example when the product does not support the data file time

date

VirusDefinitionVersion The virus definition file version of the product string VirusDefinitionSignature The virus definition file signature of the product string ProductEngineVersion The product (engine) version string

AnalyzeFileTypeEx

This method returns information about the virus definition files of the requested product. HRESULT AnalyzeFileTypeEx2 (

[in] VARIANT FileName, [out] VARIANT * SuggestedExtension, [out] VARIANT * FileTypeLong, [out, retval] VARIANT * FileTypeShort

131


) Arguments Argument Description Data Type FileName If FileNameOrBuffer is of type string then it is

treated as a file name to be analyzed. Otherwise, if it is a byte array it is treated as a memory buffer that should be analyzed

String (file) OR Byte array (buffer)

FileTypeLong If the pointer that is passed to the method is not null then the VARIANT will be filled with a string describing the file type in detail.

string

SuggestedExtension If the pointer that is passed to the method is not null then the VARIANT will be filled with the suggested extension type of the file.

string

FileTypeShort A series of letters that summarize the file type. More details are described in UOther Important Return Types.

string

The string returned in SuggestedExtension is the three letter extension of the filename. The AnalyzeFiletypeEx detection is based on the FileTypeLong returned from the AnalyzeFileType. The SuggestedExtension returns the actual extension of the file, even if it has been altered before scanning the file. If the file comprises of more than one extension, such as executable plus archive, the function returns only the first extension type detected.

AnalyzeFileTypeEx2

This method analyzes a file (or buffer) and attempts to guess its type, detect files of which the file extensions may have been altered and recursively analyze contents of archive files. HRESULT AnalyzeFileTypeEx2 (

[in] VARIANT FileNameOrBuffer, [out] VARIANT * InArgsArray, [out, retval] VARIANT * OutArgsArray

) Arguments

132


Argument Description Data Type FileNameOrBuffer If FileNameOrBuffer is of type string then it is

treated as a file name to be analyzed. Otherwise, if it is a byte array it is treated as a memory buffer that should be analyzed

String (file) OR Byte array (buffer)

InArgsArray A list of input arguments in the following order: [0] Detect file extension mismatches. Result can be read from OutArgsArray. Set this to one of the following: a. True - detect mismatches if the input

file’s extension doesn’t match any of our suggested extensions

b. False - do not detect mismatches [1] If mismatch detection and recursive analysis is enabled, stop analyzing upon a mismatch and return immediately with results up until the file that contained the mismatch. Set this to one of the following: a. True – stop analyzing on the first

mismatch b. False – analyze all the files within an

archive [2] Analyze the full contents of archive files along with the archive file itself. Set this to one of the following: a. True – recursively analyze archive

files b. False – only analyze the input file

******************* Variant Array [0] Boolean [1] Boolean [2] Boolean *******************

OutArgsArray A list of output arguments in the following order: [0] If detection of file extension mismatch is enabled, this flag will indicate whether a mismatch was detected. This will be set to one of the following: a. 0 – no mismatch is detected b. 1 – a file extension mismatch was

found while analyzing the input file or the contents of the archive

c. 2 –unknown because of no detection of file type and / or the input was a buffer

[1] Array containing the analyzed file(s) and file type information – consisting of the file name, file description, a short type,

******************* Variant Array [0] UINT32 (mismatch flag) [1] Variant Array (files) ---------------------- Variant Array (files) [0][0] String (file name) [0][1] Variant Array (file info) [0][2] UINT32

133


suggested extension, and extension mismatch flag

(mismatch flag) ---------------------- Variant Array (file info) [0][0] Long type [0][1] Short type [0][2] Suggested Extension *******************

Comparison with AnalyzeFileTypeEx()…

In addition to returning similar results as AnalyzeFileTypeEx, this method will analyze a file and the contents if it is an archive file. It will also give one or more suggestions for the file type information (description, category, and suggested extension) when available. It can also raise a flag if the extension of a file does not match any of our suggested extensions. The caller can specify to abort further analysis on the first mismatch. There are three levels of VARIANT arrays, the last two levels consisting of 2-dimensional SafeArrays Upon analysis with AnalyzeFileTypeEx(), if specific details of the file type could be not retrieved, the ‘FileTypeShort’ result will be set to the letter ‘O’, basically throwing it into the “others” category. In contrast, AnalyzeFileTypeEx2() will return an empty array, indicating that details could not be retrieved for the file

AnalyzeEx

This method is an extensible file type analysis API which allows the user to set various analyze file type options that can be configured for each file type analysis request. It can be used as a wrapper of the other file type analysis APIs. It also supports specifying custom ticket ID and session ID to associate file type analysis and scan. HRESULT AnalyzeEx (

[in] VARIANT ContentsToScan, [in] VARIANT * InArgsArray, [out, retval] VARIANT * OutArgsArray

) Arguments Argument Description Data Type ContentsToScan This argument may hold one of two types, a

file path to be scanned or a memory buffer to be scanned based on the data type of this


134


parameter and input argument (InArgsArray) value • A file path: if the type of this parameter

is a string • Memory buffer: if the type of this

parameter is a byte array(byte[]) InArgsArray A list of input arguments in the following

order. 0. File Type Library choice

• 0: Use default • 1: Magic File Type

• 2: TriD (Not supported for now)

1. Custom ticket # (maximum 9 digits from 1-999999999) or (0 for not using custom ticket #)

2. Session ID a. To associate multiple file scan as

a group (e.g., multiple requests for single folder)

array of variants with following order:

1. UINT32

1. UINT32 2. String

OutArgsArray A list of outputs with the following order: 0: Ticket number (if custom ticket # is specific in InargsArray, same ticket number is returned). 1: Suggested File Type Extension 2: File Type Long 3: File Type Short

Safearray of variants with the following order: 0: UINT32 1: String 2: String 3: String

ConvertFileType

This method converts the specified input file into a different format. HRESULT ConvertFileType (

[in] VARIANT ContentsToConvert, [in] VARIANT ConvertTo, [in] VARIANT TargetFolderPath, [in] VARIANT * ReservedInArgsArray, [out] VARIANT * ReservedOutArgsArray, [out, retval] VARIANT * ConvertedFilePath

)

135


Arguments Argument Description Data Type ContentsToConvert UNC of the input file to convert String

ConvertTo Identifier for targeted conversion Usually file extension (e.g., pdf, docx…)

String

TargetFolderPath UNC of the destination folder path. The converted file will be created in that folder

String

ReservedInArgsArray Reserved ReservedOutArgsArray Reserved ConvertedFilePath Path to the converted file if conversion was

successful String

CheckLicense

This method checks if the license installed on the machine is valid and when it is expired. Metadefender Core will process scan and update requests only if LicenseType is one of the “valid” types below. HRESULT CheckLicense (

[out] VARIANT * LicenseType, [out] VARIANT * ExpiredDate, [out, retval] VARIANT * IsValid

) Arguments Argument Description Data Type LicenseType The type of license

- 0: Expired (invalid) - 1: Activated (valid) - 2: Trial (valid) - 3: Activate Required (invalid) - 4: Activated but expires in 30 days (valid)

UINT32

ExpiredDate The date when the license is expired in the following format MM/DD/YYYY (MM: month, DD: day, YYYY: year)

string

IsValid True: if the license is valid False: if the license is invalid

bool

136


StopScan

This method purges all scan requests and ongoing scan. Method returns only when all requests are purged. HRESULT StopScan (

[in] VARIANT Reserved ) Arguments Argument Description Data Type Reserved Reserved

ScanExWorking

This method is an extensible scan API which replaces previous the APIs - PutToScan(AndClean)Queue and Scan(AndClean). It allows the setting of various scan options that can be configured for each scan request. HRESULT ScanEx (

[in] VARIANT ContentsToScan, [in] VARIANT* InArgsArray, [out, retval] VARIANT* OutArgsArray

) Arguments Argument Description Data Type ContentsToScan

This argument may hold one of four types: a file path to be scanned, a file signature to be scanned, a boot sector to be scanned, or a memory buffer to be scanned, based on the data type of this parameter and input argument (InArgsArray) value

- A file path: if the type of this parameter is a string and the fifth argument of InArgsArray is set to 0 or the size of InArgsArray is 3

- A file signature: if the type of this parameter is a string and the fifth argument of InArgsArray is


137


set to 1 - A boot sector scan: if the type of this

parameter is a string and the fifth argument of InArgsArray is set to 2

- A memory buffer: if the type of this parameter is a byte array(byte[])

- Virtual Machine image folder path InArgsArray A list of input arguments in following order:

1. (boolean) Sync flag (true: synchronous scan , false or invalid value: asynchronous scan)

2. (boolean) Clean flag (true: Action on dirty file, false: keep)

3. (UINT32) Custom ticket #

- maximum 9 digits from 1-999999999 or 0 for not using custom ticket #

4. (UINT32) Analyze before scan

0: disable analyze file before scan 1: enable analyze file before scan 2: use global setting

(“analyze_before_scan”)

5. (UINT32) Contents Type

0: ContentToScan argument holds file path or memory buffer

1: ContentToScan argument holds SHA1-based signature.

2: ContentToScan argument holds driver letter for a boot sector scan

4: ContenToScan argument holds Virtual Machine image folder path (Virtual machine disk must contain a Windows based filesystem)

6. (UINT32) Clean Action Type

0: take no action 1: quarantine (ignore global setting,

“clean_action”) 2: delete (ignore global setting, “clean

action”) 3: follow global setting

array of variants

138


7. (UINT32) Caching option

0: disable to cache for this scan request 1: enable to cache for this scan request 2:rescan (disregard existing cache and

update with new scan result) 3: use global setting(“enable_cache_scan”)

8. (String) Password for encrypted archive.

- Use empty string to when no password is required.(“enable_cache_scan”)

9. (String) User agent

- This is used to associate scan history with the source of scan request. Empty string is allowed.

10. (String) User description

- This will be logged along with scan request for the caller’s purpose. Empty string is allowed.

- Pass the following JSON formatted string to control the file name and file path to be logged:

{"file_info.original_file_path":"<original file path not including file name", "file_info.display_name":"<original file name>"}

11. (UINT32) Configure logging

0: disable logging this particular scan request

1: enable logging this particular scan request

2: use global setting (omsConfig.ini)

12. (UINT32) Archive File Handling

do not extract archive file for this particular request

1: extract archive file for this particular scan

139


request 2: use global setting

(“internal_archive_lib_enable”)

OutArgsArray A list of outputs with the following order: 1. (UINT32) Ticket number (if custom ticket # is

specific in InargsArray, same ticket number is returned

2. (UINT32) Scan result as described in ScanOutCome Return Type

3. (array of strings) List of threats 4. (String) Scan detail per engine

<scan_details> <objects > <object name="[object name]">

<engine_result> <engine_name>[engine name]</name> <scan_result>[scan outcome for the engine]</scan_result>

</engine_result> </object>

</scan_details> [object_name]: file name or signature depends on type of scan requested. [scan outcome for the engine]: Scan result per engine as described in ScanOutCome Return Type

5. (String) File type information - this is returned only if analyze_before_scan is enabled or the third argument of InArgsArray is set to 1 <file_type> <objects size=""> <object> <sha1></sha1> <type_infos size=""> <type_info> <long></long> <short></short>

Safearray of variants

140


<extension></extension> </type_info> </type_infos> </object> </objects> </file_type>

Note: When the Metadefender Core server is too busy, the HRESULT value returned will be E_OUTOFMEMORY

Metadefender Core Deprecated Methods

Metadefender Core Deprecated Methods

This section lists all the deprecated methods of Metadefender Core. We highly encourage that you use newer methods available in latest version.

InitEx (deprecated)

This method can still be used for the purpose of initializing an instance of a Metascan object. However, with more flexible and extensive DB controller, the ability to have its own log writer per instance is disabled. HRESULT InitEx (

[in] VARIANT * argsArray, [in] VARIANT argXML, [out, retval] VARIANT *UsableAntiViruses

) Arguments Argument Description Data Type argsArray empty argXML This parameter is reserved for later use. Please pass

null as its value empty

UsableAntiViruses The list of AVs will be used for this instance of Metascan client

Array of strings

Scan (deprecated)

141


This method is called to scan a file or a memory buffer. This is done in a synchronous (blocking) fashion - the method will only return after the scan is complete. Note: This is a deprecated method and we suggest using ScanEx instead. HRESULT Scan (

[in] VARIANT FileNameOrBuffer, [out] VARIANT* ThreatList, [out, retval] VARIANT* ScanOutcome


Type FileNameOrBuffer If FileNameOrBuffer is of type string then it is treated as

a file / directory name to scan. Otherwise, if it is a byte array (Byte []) it is treated as a memory buffer that should be scanned


ThreatList A threat list found on the scanned object, otherwise null array of strings

ScanOutCome 1: Scan result as described in Other Important Return Types

UINT32

ScanAndClean (deprecated)

This method is called to scan and clean a file. This is done in a synchronous (blocking) fashion - the method will only return after the scan is complete. Note: This is a deprecated method and we suggest using ScanEx instead. HRESULT ScanAndClean (

[in] VARIANT FileName, [out] VARIANT* ThreatList, [out, retval] VARIANT* ScanOutcome

) Arguments

142


Argument Description Data

Type FileName If FileNameOrBuffer is of type string then it is treated as a file /

directory name to scan. Otherwise, if it is a byte array (Byte []) it is treated as a memory buffer that should be scanned


ThreatList A threat list found on the scanned object, otherwise null Array of strings

ScanOutCome 1: Scan result as described in Other Important Return Types

UINT32

PutToScanQueue (deprecated)

This method is called to place a file to the scan-queue. In other words, the scan request will be processed asynchronously. Note: This is a deprecated method and we suggest using ScanEx instead. HRESULT PutToScanQueue (

[in] VARIANT FileNameOrBuffer, [out, retval] VARIANT* Ticket

) Arguments Argument Description Data Type FileNameOrBuffer If FileNameOrBuffer is of type string then it is

treated as a file / directory name to be scanned. Otherwise, if it is a byte array (Byte []) it is treated as a memory buffer that should be scanned


Ticket A ticket for this scan job. This ticket will be passed to the callback methods registered via the OnScanComplete connection point

UINT32

Note: To get the result of this call, you must implement the OnScanComplete connection point.

143


PutToScanAndCleanQueue (deprecated)

This method places a file to the scan-and-clean-queue. In other words, the scan request will be processed asynchronously. Note: This is a deprecated method and we suggest using ScanEx instead. HRESULT PutToScanAndCleanQueue (

[in] VARIANT FileNameOrBuffer, [out, retval] VARIANT* Ticket

) Arguments Argument Description Data Type FileNameOrBuffer If FileNameOrBuffer is of type string then it is

treated as a file / directory name to be scanned. Otherwise, if it is a byte array (Byte []) it is treated as a memory buffer that should be scanned


Ticket A ticket for this scan job. This ticket will be passed to the callback methods registered via the OnScanComplete connection point

UINT32

Note: To get the result of this call, you must implement the OnScanComplete connection point.

GetUpdateStatus (deprecated)

This method returns information about the virus definition files of the requested product. HRESULT GetUpdateStatus (

[in] VARIANT ProductNamePart, [out] VARIANT * ProductDescription, [out] VARIANT * VirusDefinitionDate, [out] VARIANT * VirusDefinitionVersion

) Arguments

144


Argument Description Data Type ProductNamePart A part of the product name of the desired

package. Definition file information of the product containing this value will be returned.

string

ProductDescription The description of the product that matched ProductNamePart

string

VirusDefinitionDate The dates of virus definition files for the product. 0 will be returned if the data file time is unavailable for example when the product does not support the data file time.

Date

VirusDefinitionVersion The virus definition file version of the product. string

AnalyzeFileType (deprecated)

This method analyzes the contents of a file and attempts to guess its type. HRESULT AnalyzeFileType (

[in] VARIANT FileNameOrBuffer, [out] VARIANT * FileTypeLong, [out, retval] VARIANT * FilteTypeShort

) Arguments Argument Description Data Type FileNameOrBuffer If FileNameOrBuffer is of type string then it is treated

as a file name to be analyzed. Otherwise, if it is a byte array (Byte []) it is treated as a memory buffer that should be analyzed


FileTypeLong If the pointer that is passed to the method is not null then the VARIANT will be filled a string describing the file type in detail

string

FileTypeShort A series of letters that summarize the file type. More details are described in Other Important Return Types

string

The string returned in FileTypeLong is a series of types that match the file. If the file matches more than one type (sometimes it’s impossible to tell the difference), the returned string will contain all the possible file types separated by ‘,’.

145


The string returned in FileTypeShort is a string comprised of letters that give the rough classification of the file. The possible classifications of file types are described in the Other Important Return Types section.

SubscribeGlobalEvents (Deprecated)

If you want to get global callbacks such as OnLogAvailable, you must subscribe to global events with appropriate event type through this call. If you subscribe to a specific type of event, you must unsubscribe to that type of event. For example, if you subscribe to a scan event type and update event type, you must unsubscribe to both scan event type and update event type. HRESULT SubscribeGlobalEvents (

[in] VARIANT EventType [out, retval] VARIANT * Reserved

) Arguments Argument Description Data Type EventType Determines the type of events to subscribe.

0 all events 1 update events 2 log events 3 scan events

UINT32

Reserved Reserved

UnsubscribeGlobalEvents (Deprecated)

This method is called to unsubscribe to specific or all events. If you subscribe to specific type of event, you must unsubscribe to that type of event. For example, if you subscribe to scan event type and update event type, you must unsubscribe to both scan event type and update event type. Calling to unsubscribe to events which is not subscribed has no effect. HRESULT UnsubscribeGlobalEvents (

[in] VARIANT EventType [out, retval] VARIANT * Reserved

) Arguments

146


Argument Description Data Type Reserved Reserved

COM Connection Points

COM Connection Points

Metadefender Core server provides callback methods by allowing client objects to register connection points. In order to use Metadefender Core API in C/C++ development, it is required to implement all connection points. For other languages such as C# or ASP.net, only desired methods can be implemented.

OnScanComplete

This connection point is fired whenever a scan is completed. This event is not global but specific to the client which makes this scan request. In other words, when scanning is requested by a client, other client objects will not get a callback when the scanning is completed. void MyOnScanComplete (

VARIANT ticket, VARIANT * result, VARIANT * threatList, VARIANT * scanStartTime VARIANT * scanEndTime

) Arguments Argument Description Data Type ticket The ticket which is generated when this scan has

been requested UINT32

result A UINT32 value that specifies the scan outcome UINT32 threatList An array of strings (String []). Each string element in

the array is the name of the virus which has been detected

Array of strings

scanStartTime The time when the scan is started Date scanEndTime The time when the scan is finished Date

ScanProgressReport

147


This callback method will be invoked whenever each engine completes the scan. This callback can be used for a progress report of scanning when more than one engine is used. If engines are not used for any reason, such as encrypted archive or scan request on a known file, no progress report will be fired. void MyScanProgressReport (

VARIANT ticket, VARIANT result, VARIANT threatList, VARIANT productName, VARIANT productNum, VARIANT totalNumberOfProducts, VARIANT scanStartTime VARIANT scanEndTime

) Arguments Argument Description Data Type ticket The ticket which is generated when this scan

has been requested UINT32

result A UINT32 value that specifies the scan outcome

UINT32

threatList An array of strings(String []). Each string element in the array is the name of the virus which has been detected

Array of strings

productName The description of the product string productNumber The order of scan completion among the

usable AVs UINT32

totalNumberOfProducts The number of products scan is requested for this ticket

UINT32

scanStartTime The time when the scan is started date scanEndTime The time when the scan is finished date

ScanProgressReportEx

This callback method will be invoked when each engine completes the scan. This callback can be used for a scan progress report when more than one engine is used. If an engine is not used for any reason such as encrypted archive or scan request on a known file in side of the folder, no progress report will be fired for the particular file.

148


void MyScanProgressReport (

VARIANT ticket, VARIANT result, VARIANT threatList, VARIANT productName, VARIANT scanStartTime VARIANT scanEndTime VARIANT filePath

) Arguments Argument Description Data Type ticket The ticket which is generated when this scan has


result A UINT32 value that specifies the scan outcome UINT32 threatList An array of strings(String []). Each string element in

the array is the name of the virus which has been detected

Array of strings

productName The description of the product string scanStartTime The time when the scan is started date scanEndTime The time when the scan is finished date filePath The path to the file which is scanned string

OnUpdateProgressReport

This callback method will be invoked when an update for each engine completes. This callback is fired to the Metadefender Core client object which initiates the update. void MyOnUpdateProgressReport (

VARIANT productName, VARIANT updateState, VARIANT updateReport, VARIANT productNum, VARIANT totalNumberOfProducts, VARIANT startTime, VARIANT elapsedMiliSec, VARIANT reserved

)

149


Arguments Argument Description Data

Type productName The description of the product

updateState The progress in percentage for update with the specified engine (0 indicates update start while 100 indicates update complete)

updateReport XML-formatted string consisting of engine names and engine update results. Engine update result is one of following.

- updateOk - updateUpToDate - updateFailed - updateUnknown - updateNetworkProblem - updateTimeOut - updateNotImplemented - updateNotSupported - updateAlreadyInProgress

string

productNum The order of update among the current AVs totalNumberOfProducts The number of products scan is requested for this

ticket

startTime Time when update for the engine is initiated elapsedMiliSec Time elapsed for update complete in milliseconds reserved Reserved * updateAlreadyInProgress: If any update on the antivirus product is already running, no additional updates will be queued. This means that the update which has previously been started will return the UpdateResult through the connection point after this.

OnUpdateComplete

This callback method will be invoked when an update completes. This callback is fired to ALL Metadefender Core client objects which are registered to this connection point. However, if there is already an update request which has not completed, only the Metadefender Core client which requested the update will get a callback with the update result of “updateAlreadyRequested(2)”. void MyOnUpdateComplete (

150


VARIANT updateResult, VARIANT updateReport

) Arguments Argument Description Data Type updateResult A UINT32 value which contains the update result

- 0: updateFinished - 1: updateFailed - 2: updateAlreadyRequested - 3:updateUnknown

UINT32

updateReport XML-formatted string consisting of engine names and engine update results. Engine update result is one of following

- updateOk - updateUpToDate - updateFailed - updateUnknown - updateNetworkProblem - updateTimeOut - updateNotImplemented - updateNotSupported - updateAlreadyInProgress

string

* updateAlreadyInProgress: If any update on the antivirus product is already running, no additional updates will be queued. This means that the update which has previously been started will return the UpdateResult through the connection point after this.

ScanStartReport

This callback method will be invoked when each engine begins the scan. This callback can be used when a scan request begins. This callback is fired on if “report_on_scan_start” is set to “1” (true). void MyScanStartReport (

VARIANT ticket, VARIANT productName, VARIANT filePath

)

151


Arguments Argument Description Data Type ticket The ticket which is generated when this scan has


productName The description of the product string filePath The path to the file which is scanned string

OnFileInArchiveInfoAvailable

This callback method will be invoked when Metadefender Core's archive library is enabled and a file from within an archive is scanned. This callback can be used to obtain more discrete information of a file contained within an archive. void MyOnFileInArchiveInfoAvailable ( VARIANT SessionID, VARIANT Ticket, VARIANT FileName, VARIANT MD5, VARIANT SHA1, VARIANT SHA256, VARIANT FileSize, VARIANT FileTypeDesc, VARIANT Reserved) Arguments Argument Description Data Type

SessionID Reserved for future usage

Ticket The ticket which is generated when this scan has been requested

UINT 32

FileName The name of the file contained in the archive with the file path of the root archive preceding it

string

MD5 MD5 signature of the file string

152


SHA1 SHA1 signature of the file string

SHA256 SHA256 signature of the file string

FileSize Reserved for future usage

FileTypeDesc Reserved for future usage

Reserved Requested reserved for future usage

Metadefender Core Web API

REST API

Overview of the Metadefender Core REST API

Beginning with Metascan 3.8.1, OPSWAT recommends using the JSON-based (v2) REST API. The available methods are documented below.

Using REST API Keys

Metadefender Core allows you to limit access to the REST API only to users that have a defined API key. If no such API keys are defined then the 'apikey' parameter should be excluded from the REST API calls. If one or more API keys are defined, the 'apikey' parameter is required. To define API keys, the following registry key should be set to a '|' delimited list of API keys.

HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OPSWAT\Metascan\rest_api_keys

For example, setting this value to '|abcd|efgh|' would create two API keys, 'abcd' and 'efgh'.

Basic API Methods

Scanning a File

Initiate scan request and retrieve scan results. Scan is done asynchronously and each scan request is tracked by data id.

153


Initiate scan request http://localhost:8008/metascan_rest/file Retrieve scan results http://localhost:8008/metascan_rest/file/{data_id*} URL to Initiate scan request: Initiate scan request http://localhost:8008/metascan_rest/file

HTTP header parameters: user_agent A string to identify the user. Used for

mapping to a specific workflow. If the string does not match any defined in Metadefender Core the default workflow will be used.

RECOMMENDED, if not specified no workflow will be used and files will be processed according to the ScanEx configuration

filename Name of files to preserve extension during scan and meta data. File name should be URL encoded and should not contain the characters '>' or '<'.

RECOMMENDED

archivepwd If submitted file is password protected archive

OPTIONAL

apikey API key defined by the Metadefender Core Administrator

REQUIRED if API keys are defined by the Metadefender Core Administrator

X-File-Size If the file is being uploaded in chunks, this needs to be set to the total size of the file. Metadefender Core will not start scanning the file until this file size has been reached.

OPTIONAL

X-File-ID If the file is being uploaded in chunks, for all file chunks after the first chunk, this needs to be set to the data_id value returned from the upload of the first chunk of the file.

OPTIONAL

Method: POST HTTP request must include the contents of file as HTTP body. HTTP body Contents of the file for scan

Request Error (HTTP status: 40x)

154


400: Bad request Not supported HTTP method or invalid http request (e.g., empty body) 401: Invalid API key/ Exceeded usage Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when scan request is successful: {

"data_id": "4f84e3b096d54908963d037b5457bf27" } Description

data_id Data ID used for retrieving scan results. Since there are potentially multiple scans for same files when any engine has different definition time or when there is an additional engine, this is the identifier per scan rather than per file. If chunk upload is being used, this value must be included in the X-File-ID header of POST requests for subsequent file chunks (see above).

Retrieving Scan Results Using Data ID

You can retrieve scan results using the Data ID. The scan is done asynchronously and each scan request is tracked by the ID. You need to use two separate API calls to initiate a file scan and retrieve the scan results. This request needs to be made multiple times until the scan is complete. You can trace the scan completion using the “scan_results.progress_percentage” value from the response. Use the following URL to initiate the scan request: http://localhost:8008/metascan_rest/file Use the following URL to retrieve scan results: http://localhost:8008/metascan_rest/file/{data_id*}

HTTP header parameters

Parameter Description Required/Optional

apikey API key assigned by user. Optional

GET method parameters

155

https://api.metascan-online.com/v1/file

https://api.metascan-online.com/v1/file/%7bdata_id*%7d


Parameter Description Required/Optional

URL path /hash/{hash_value} Required

data_ID You can get this by scanning a file. You can also use the ticket number if scanning from the command line.

Required

Response status codes

Error Description Notes

200 OK Found the scan result for given data_id.

400 Bad request Not supported HTTP method or invalid HTTP request.

401 Invalid API key Either missing API key or invalid API is passed.

404 Not found The scan result for the given data_id was not found.

500 Internal error Server temporarily unavailable. Try again later.

Example of when the result is not found

When scan results are not found, a 404 response status code appears. {

"56a80962c736465b9fd8f6fc4614bd00": "Not Found" }

Scan Results Descriptions

Name Description

Data id The submitted ID.

Example of when the result is found

{ "extracted_files": { "data_id": "b3a0949e833840128a346fdd7ec42477",

156


"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": null, "scan_results": { "scan_details": { "Ahnlab": { "threat_found": "EICAR_Test_File", "scan_result_i": 1, "def_time": "2015-07-02T07:00:00Z", "scan_time": 2 }, "Avira": { "threat_found": "Eicar-Test-Signature", "scan_result_i": 1, "def_time": "2015-07-02T07:00:00Z", "scan_time": 23 }, "ClamAV": { "threat_found": "Eicar-Test-Signature", "scan_result_i": 1, "def_time": "2015-07-02T07:00:00Z", "scan_time": 93

157


}, "ESET": { "threat_found": "Eicar test file", "scan_result_i": 1, "def_time": "2015-07-02T07:00:00Z", "scan_time": 10 } }, "rescan_available": false, "data_id": "b3a0949e833840128a346fdd7ec42477", "scan_all_result_i": 0, "start_time": "2015-08-06T23:09:46.006Z", "total_time": 93, "total_avs": 4, "progress_percentage": 100, "in_queue": 0, "scan_all_result_a": "Clean", "last_file_scanned": "\\Printout.pdf" }, "file_info": { "file_size": 227973, "upload_timestamp": "2015-08-06T23:09:46.006Z", "md5": "A1A63E31911FEF7F9DF6D183535AD0E8", "sha1": "25B7A560186274DEE054FE528D3E37F0B68374D9", "sha256": "0DDAB22473E5D6F9994B1CF0979CDF062203D60DEAA54C68821836C2AAB349FA", "file_type_category": "A", "file_type_description": "7-Zip compressed archive", "file_type_extension": "7Z", "display_name": "demo_process.7z", "original_file_path": "c:\\\\users\\\\wzhao\\\\desktop" }, "process_info": { "post_processing": { "actions_ran": "Sanitized", "actions_failed": "", "converted_to": "pdf", "copy_move_destination": "", "converted_destination": "<metascan_install_dir>\\REST\\Data\\FileTypeConversion\\<data_id>\\toConvert_[sanitized].pdf" }, "progress_percentage": 100, "user_agent": "cactus",

158


"profile": "default", "result": "Blocked", "blocked_reason": "Dirty", "file_type_skipped_scan": false }, "data_id": "b3a0949e833840128a346fdd7ec42477", "source": "10.0.50.115", "scanned_on": "10.0.50.34" }


Top level Attribute Description

file_id Populated when files are configured to be stored (not the default).

scan_result Global scan results, metadata, and scan reports from all engines.

file_info File metadata, hash value, and analyzed file types.

data_id Used for retrieving scan results.

Additional levels for scan_results

Attribute Description

scan_details Array of scan results for engines.

scan_result_i* See table below (Description of scan_result_i / scan_all_result_i) for descriptions.

threat_found Name of threat if detected by engine.

def_time Definition time of engine at the time of scan.

scan_time Elapsed scan time in milliseconds.

159


rescan_available This value will be set to true if the engine definition has changed, and/or any engine is missing scan results such as "failed to scan" or "not scanned."

scan_all_result_i See table below (Description of scan_result_i / scan_all_result_i) for descriptions.

total_time Total elapsed time for scan by all engines.

total_avs Number of antiviruses used for scan.

progress_percentage Indicator of scan being in progress.

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

Additional levels for file_info level Attribute Description

upload_timestamp The first time the file is uploaded to the server. Even if the file is rescanned this value will be preserved.

file_type_category High-level categorization of file type (see table below for descriptions). Archive scan attributes These are only applied when scanning archive files. Attribute Description

original_file Includes basic information and reference to the data_id of the original archive file, not the extracted contents.

extracted_files Basic information about the included files in the archive can be found in the files_in_archive attribute. This attribute only contains a maximum of 50,000 results, and No Threat Detected results will be on the top. The data_id references the engine's summary results for the archive, which can be different from the scan_results in the archive root object.

parent_data_id References the parent id, which is used for the files inside an archive to point to the archive and also for the original file to point to the archive.

Process info attributes These are only applied when scanning with user_agent.

160



process_info The process node. This is only applicable if the user scanned with user_agent.

progress_percentage The percentage of processing completed.

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 result of processing the file. Possible values include:

• Allowed: The file is allowed. • Blocked: The file is blocked. • Processing: The file is currently being processed. • Not processed: Default value set in REST before the file is processed by

Metadefender Core.

blocked_reason Why the file is being blocked. Possible values include:

• Failed to request a process: "Process Failed" • Mismatch detected: "Mismatch" • File type disallowed: "Filtered" • Scan Result: Known ("Dirty" or "Infected"), Suspicious, Failed, Cleaned,

Unknown ("Skipped Dirty" or "Skipped Infected"), Not Scanned, Aborted, Password Protected Document

• Archive: Encrypted Archive, Missing File During Extraction, Insufficient Space for Archive Extraction, Exceeded Archive Size, Exceeded Archive File Number, Archive Extraction Error, Exceeded Archive Depth, Archive Error

• Null: Default value set in REST before the file is processed by Metadefender Core.

file_type_skipped_scan Indicates if the input file's detected type was configured to skip scanning. Value is a JSON Boolean type.

post_processing The post processing node. This only appears if post processing was configured.

actions_ran List of post processing actions that ran. Possible values include: Sanitized, Copied, Moved, Quarantine, 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. Possible values include: Sanitization

161


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 The extension to which the file was converted. If the string contains a file type, the converted file can be downloaded.

copy_move_destination Destination where the file was copied/moved.

converted_destination Location where the converted file exists. Interpreting Process API JSON A process_info field is necessary for processing JSON messages.

• Use process_info.progress_percentage to know whether the process is finished or is still in process.

• Use process_info.result to check whether the file processed is allowed or blocked. • While a file is allowed, process_info.blocked_reason is an empty string. If the file is blocked, use

the field to retrieve detailed blocked reasons. • Use process.profile to retrieve the profile used for processing. • Use process.file_type_skipped_scan to determine if the input file's detected type is configured

to skip scanning. If post processing is configured and applied, the process.post_processing field appears in the JSON result. You can check whether this field exists to find out if post_processing has been applied or not.

• If process.post_processing exists, use process.post_processing.action_ran to check what actions have been applied. See details in [Description of Response].

• If process.post_processing exists, use process.post_processing.action_failed to check which post_processing failed.

• If "Move" is in "action_ran", check process.post_processing.converted_to to retrieve information about the target file type. Call /file/converted/{data_id} to retrieve the link to download converted files.

• If "Copied" or "Moved" is in "action_ran", check process.post_processing.copy_or_move_destination for the target directory information.

Description of scan_result_i / scan_all_result_i Metadefender Core categorizes files as 'blocked' or 'allowed' based on the scan result. The following scan results causes a file to be labeled as 'blocked': Infected/Known, Suspicious, Failed To Scan, Cleaned, Unknown, Quarantined, Skipped Dirty, Not Scanned, Aborted, Encrypted. Value Short Description Long Description

162


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 (e.g., invalid file or no read permission).

4 Cleaned/Deleted Threat is found and file is repaired or deleted.

5 Unknown Unknown scan result.

6 Quarantined File is quarantined.

7 Skipped Clean Scan is skipped because this file type is whitelisted.

8 Skipped Infected Scan is skipped because this file type is blacklisted.


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 the scan is disabled, this is the result.

11 Aborted All ongoing scans are purged.

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 Metadefender Core scan progress callbacks since the engines do not perform any scan operations. If the Internal Archive Library is OFF, Metadefender Core will pass the encrypted files to the engines directly, bypassing the detection.


The extracted archive is too large to scan.


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

15

Password Protected Document

Password-protected document (e.g., Office documents or PDFs that require a password to view content).

16

Exceeded Archive Timeout

The archive process reached the given timeout value. This result is supported from Metadefender Core version 4.4.0.

Scan is not carried out If scanning is disabled, or a file is blocked and not configured to scan, a scan_results object will be generated. Information about this object is below.

163


Metadefender Core Version Object Value

Metadefender Core 3.11.2+ scan_results.scan_all_result_i 10

scan_results.scan_all_result_a "Not Scanned"

Metadefender Core 3.11.0 and 3.11.1 scan_results.scan_all_result_i -1

scan_results.scan_all_result_a ""

Metadefender Core 3.11.0 and 3.11.1 scan_results.scan_all_result_i 1000

scan_results.scan_all_result_a "No Scan Result" Scan is partially completed The accumulated result at the time the scan result was queried. Description of file_type_category Value Description

“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, BMP, …)

“T” Text

“P” PDF format

“M” Audio or video format

“Z” Mail messages (MSG, …)

“I” Disk image

“O” Other (anything that is not recognized as one of the above)

Retrieve Scan Results Using Hash

You can use the following URL for retrieving scan results using a hash lookup: http://localhost:8008/metascan_rest/hash/{hash value *}


Parameter Description Required?

164


apikey API key defined by the Metadefender Core administrator.

Required if API keys are defined the Metadefender Core administrator.

GET method parameters

Parameter Example Required?

URL path /hash/{hash_value} Yes.

You can use any of the following as the hash value: • SHA1 • MD5 • SHA256

Response status codes

Error Description Notes

200 OK Found the scan result for given data_id.

400 Bad request Not supported HTTP method or invalid HTTP request.

401 Invalid API key Either missing API key or invalid API is passed.

404 Not found The scan result for the given data_id was not found.

503 Internal server error Server temporarily unavailable. Try again later.

Example of when scan results are not found

When scan results are not found, a 200 response status code appears. {

"BED12FDA073BB386B54700138FB47EEA": "Not Found" }

Example of when scan results are found

{ "extracted_files": { "data_id": "b3a0949e833840128a346fdd7ec42477", "scan_result_i": 0,

165


"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": null, "scan_results": { "scan_details": { "Ahnlab": { "threat_found": "EICAR_Test_File", "scan_result_i": 1, "def_time": "2015-07-02T07:00:00Z", "scan_time": 2 }, "Avira": { "threat_found": "Eicar-Test-Signature", "scan_result_i": 1, "def_time": "2015-07-02T07:00:00Z", "scan_time": 23 }, "ClamAV": { "threat_found": "Eicar-Test-Signature", "scan_result_i": 1, "def_time": "2015-07-02T07:00:00Z", "scan_time": 93 },

166


"ESET": { "threat_found": "Eicar test file", "scan_result_i": 1, "def_time": "2015-07-02T07:00:00Z", "scan_time": 10 } }, "rescan_available": false, "data_id": "b3a0949e833840128a346fdd7ec42477", "scan_all_result_i": 0, "start_time": "2015-08-06T23:09:46.006Z", "total_time": 93, "total_avs": 4, "progress_percentage": 100, "in_queue": 0, "scan_all_result_a": "Clean", "last_file_scanned": "\\Printout.pdf" }, "file_info": { "file_size": 227973, "upload_timestamp": "2015-08-06T23:09:46.006Z", "md5": "A1A63E31911FEF7F9DF6D183535AD0E8", "sha1": "25B7A560186274DEE054FE528D3E37F0B68374D9", "sha256": "0DDAB22473E5D6F9994B1CF0979CDF062203D60DEAA54C68821836C2AAB349FA", "file_type_category": "A", "file_type_description": "7-Zip compressed archive", "file_type_extension": "7Z", "display_name": "demo_process.7z", "original_file_path": "c:\\\\users\\\\wzhao\\\\desktop" }, "process_info": { "post_processing": { "actions_ran": "Sanitized", "actions_failed": "", "converted_to": "pdf", "copy_move_destination": "", "converted_destination": "<metascan_install_dir>\\REST\\Data\\FileTypeConversion\\<data_id>\\toConvert_[sanitized].pdf" }, "progress_percentage": 100, "user_agent": "cactus", "profile": "default",

167


"result": "Blocked", "blocked_reason": "Dirty", "file_type_skipped_scan": false }, "data_id": "b3a0949e833840128a346fdd7ec42477", "source": "10.0.50.115", "scanned_on": "10.0.50.34" }


Top level Attribute Description

scan_result Global scan results, metadata, and scan reports from all engines.

file_info File metadata, hash value, and analyzed file types.

Additional levels for scan_results


scan_details Array of scan results for engines.

scan_result_i* See table below (Description of scan_result_i / scan_all_result_i) for descriptions.

threat_found Name of threat if detected by engine.

def_time Definition time of engine at the time of scan.

scan_time Elapsed scan time in milliseconds.

scan_all_result_i See table below (Description of scan_result_i / scan_all_result_i) for descriptions.

total_time Total elapsed time for scan by all engines.

168


total_avs Number of antiviruses used for scan.

progress_percentage Indicator of scan being in progress.

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

Additional levels for file_info level Attribute Description

upload_timestamp The first time the file is uploaded to the server. Even if the file is rescanned this value will be preserved.

file_type_category High-level categorization of file type (see table below for descriptions). Archive scan attributes These are only applied when scanning archive files. Attribute Description

original_file Includes basic information and reference to the data_id of the original archive file, not the extracted contents.

extracted_files Basic information about the included files in the archive can be found in the files_in_archive attribute. This attribute only contains a maximum of 50,000 results, and No Threat Detected results will be on the top. The data_id references the engine's summary results for the archive, which can be different from the scan_results in the archive root object.

parent_data_id References the parent id, which is used for the files inside an archive to point to the archive and also for the original file to point to the archive.

Process info attributes These are only applied when scanning with user_agent. Attribute Description

process_info The process node. This is only applicable if the user scanned with user_agent.

progress_percentage The percentage of processing completed.

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

169


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

result The result of processing the file. Possible values include:

• Allowed: The file is allowed. • Blocked: The file is blocked. • Processing: The file is currently being processed. • Not processed: Default value set in REST before the file is processed by

Metadefender Core.

blocked_reason Why the file is being blocked. Possible values include:

• Failed to request a process: "Process Failed" • Mismatch detected: "Mismatch" • File type disallowed: "Filtered" • Scan Result: Known ("Dirty" or "Infected"), Suspicious, Failed, Cleaned,

Unknown ("Skipped Dirty" or "Skipped Infected"), Not Scanned, Aborted, Password Protected Document

• Archive: Encrypted Archive, Missing File During Extraction, Insufficient Space for Archive Extraction, Exceeded Archive Size, Exceeded Archive File Number, Archive Extraction Error, Exceeded Archive Depth, Archive Error

• Null: Default value set in REST before the file is processed by Metadefender Core.

file_type_skipped_scan Indicates if the input file's detected type was configured to skip scanning. Value is a JSON Boolean type.

post_processing The post processing node. This only appears if post processing was configured.

actions_ran List of post processing actions that ran. Possible values include: Sanitized, Copied, Moved, Quarantine, 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. Possible values include: 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.

170


converted_to The extension to which the file was converted. If the string contains a file type, the converted file can be downloaded.

copy_move_destination Destination where the file was copied/moved.

converted_destination Location where the converted file exists. Description of scan_result_i / scan_all_result_i Metadefender Core categorizes files as 'blocked' or 'allowed' based on the scan result. The following scan results causes a file to be labeled as 'blocked': Infected/Known, Suspicious, Failed To Scan, Cleaned, Unknown, Quarantined, Skipped Dirty, Not Scanned, Aborted, Encrypted. 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 (e.g., invalid file or no read permission).

4 Cleaned/Deleted Threat is found and file is repaired or deleted.

5 Unknown Unknown scan result. This is only used in multiple hash lookup. For single hash lookup, scan_result_* are not returned as a response.

6 Quarantined File is quarantined.

7 Skipped Clean Scan is skipped because this file type is whitelisted.

8 Skipped Infected Scan is skipped because this file type is blacklisted.


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 the scan is disabled, this is the result.

11 Aborted All ongoing scans are purged.

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 Metadefender Core scan progress callbacks since the engines do not perform any scan operations. If the Internal Archive Library is OFF, Metadefender Core will pass the encrypted files to the engines directly, bypassing the detection.


The extracted archive is too large to scan.

171



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

15

Password Protected Document

Password-protected document (e.g., Office documents or PDFs that require a password to view content).

16

Exceeded Archive Timeout

The archive process reached the given timeout value. This result is supported from Metadefender Core version 4.4.0.

Scan is not carried out If scanning is disabled, or a file is blocked and not configured to scan, a scan_results object will be generated. Information about this object is below.

Metadefender Core Version Object Value

Metadefender Core 3.11.2+ scan_results.scan_all_result_i 10

scan_results.scan_all_result_a "Not Scanned"

Metadefender Core 3.11.0 and 3.11.1 scan_results.scan_all_result_i -1

scan_results.scan_all_result_a ""

Metadefender Core 3.11.0 and 3.11.1 scan_results.scan_all_result_i 1000

scan_results.scan_all_result_a "No Scan Result" Description of file_type_category Value Description

“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, BMP, …)

“T” Text

“P” PDF format

“M” Audio or video format

“Z” Mail messages (MSG, …)

“I” Disk image

“O” Other (anything that is not recognized as one of the above)

172


Retrieving Sanitized Files Using Data ID

Retrieve files that have been sanitized as part of a Metadefender Core workflow. Metadefender Core administrators have the option of defining a workflow that includes data sanitization for allowed and/or blocked files. If a file is processed by such a workflow, the sanitized copy of the file can be retrieved using the data id of the process request. If the request is successful, the result will be the contents of the sanitized file. URL to retrieve process results: Retrieve process status http://localhost:8008/metascan_rest/process/converted/{data_id*}

http://localhost:8008/metascan_rest/file/converted/{data_id*}

POST parameters: user_agent A string to identify the user. REQUIRED if file was scanned with

Metadefender Core workflows


REQUIRED if API keys are defined the the Metadefender Core Administrator

Method: GET e.g., http://localhost:8008/metascan_rest/process/download/56a80962c736465b9fd8f6fc4614bd00 Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request (e.g., empty body). Request Error (HTTP status: 401/403) Invalid API key Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the result is not found: {

"56a80962c736465b9fd8f6fc4614bd00": "Not Found"

173

https://api.metascan-online.com/v1/hash/BED12FDA073BB386B54700138FB47EEA


}

Advanced Scanning API Methods

Advanced Scanning API Methods

Download Previously Scanned File

Downloading file scanned from database using file_id. Request URL

http://localhost:8008/metascan_rest/file/download/<file_id> e.g. http://localhost:8008/metascan_rest/file/download/528049058c14f610d4896016

HTTP header parameters apikey API key defined by the

Metadefender Core Administrator REQUIRED if API keys are defined the the Metadefender Core Administrator

file_id file_id of file download REQUIRED

Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request (e.g., empty body). 401: Invalid API key/ Exceeded usage Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the request is not successful: { "err" : "file not found in database" } Example of when the request is successful: It will return the content of that file if using REST client tool.

174

http://localhost:8008/metascan_rest/file/download/%3cfile_id%3e

http://localhost:8008/metascan_rest/file/download/528049058c14f610d4896016


0000: 73 66 64 73 66 31 32 33 31 32 33 61 73 64 0D 0A | sfdsf123123asd.. | 0010: 61 64 73 61 64 61 73 64 0D 0A 61 73 64 61 73 64 | adsadasd..asdasd | 0020: 73 61 64 0D 0A 61 73 64 61 73 64 73 61 64 0D 0A | sad..asdasdsad.. | 0030: 61 73 64 61 73 64 73 61 64 | asdasdsad | If using a web browser, a pop-up save file will appear with the file name “display_name” in database (see the picture below):

Retrieve Queue Size

Getting the number of files in the queue. Request URL

http://localhost:8008/metascan_rest/file/inqueue



REQUIRED if API keys are defined the Metadefender Core Administrator

Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid HTTP request. 401: Invalid API key/ Exceeded usage Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error

175

http://localhost:8008/metascan_rest/file/inqueue


Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the request is successful: { "in_queue" : "0" }

Rescan a File

Request URL http://localhost:8008/metascan_rest/rescan/<file_id>

e.g. http://localhost:8008/metascan_rest/rescan/528049058c14f610d4896016

HTTP header parameters apikey API key defined by the Metadefender Core Administrator REQUIRED if API

keys are defined the Metadefender Core Administrator

filename Name of files to preserve extension during scan and meta data OPTIONAL

archivepwd If submitted file is password protected archive OPTIONAL

source IP address or identifier of host machine OPTIONAL

forcerescan 1: Rescan even if rescan_available flag is marked as true. This is useful for sanity check scan

RECOMMENDED

sample_sharing Only working to paid user, allow file scanned to be shared or not, by default is 1 1: Enable sharing file scanned when done 0: Disable sharing file

OPTIONAL

Method: GET HTTP request must include the parameter: file_id Get from retrieving scan results REQUIRED

Request Error (HTTP status: 40x) 400: Bad request

176

http://localhost:8008/metascan_rest/rescan/%3cfile_id%3e

http://localhost:8008/metascan_rest/rescan/528049058c14f610d4896016


Not supported HTTP method or invalid http request. 401: Invalid API key/ Exceeded usage Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. 503: Service Unavailable Server temporary unavailable. There are too many unfinished files in the pending queue. Try again later. Response (HTTP status: 200) Example of when rescan request is failed {

"528049058c14f610d48196016": "Not Found" } Example of when rescan request is successful: {

"data_id": "ed3f536f7b384b11bd8285d4cce4d88f" } Description data_id Data ID used for retreiving scan result

Scanning a Metadefender Core Server Local File

You can improve Metadefender Core's performance if the client is on the same machine that Metadefender Core is installed on. The scan is done asynchronously and each scan request is tracked by data id. Initiate scan request http://localhost:8008/metascan_rest/file

Retrieve scan results http://localhost:8008/metascan_rest/file/{data_id*}

URL to Initiate scan request: Initiate scan request http://localhost:8008/metascan_rest/file


177


https://api.metascan-online.com/v1/file/%7bdata_id*%7d



apikey API key defined by the Metadefender Core

Administrator. REQUIRED if API keys are defined the Metadefender Core Administrator

filename The filename to be logged with the scan result for this file. This must be set with the correct file extension for file type analysis to be effective.

OPTIONAL

user_agent A string identifying the user, which determines which Metadefender Core workflow is used to process this file.

OPTIONAL - if not defined, the default workflow is used

source Set only to 127.0.0.1 or localhost. OPTIONAL - if not defined, file is copied to the Metadefender temp directory for scanning

original_file_path Local path of scanned file, including the file name.

OPTIONAL - if not defined, file is copied to the Metadefender temp directory for scanning

Method: POST HTTP body HTTP request must include the contents of file as HTTP body unless the fie is being

scanned locally and original_file_path header is defined.

Request Error (HTTP status: 40x) 400: Bad request - File not found. Example of when the result is not found:

{ "5280490958c14f610d4896016": "Not Found"

}

Statistics API Methods

Statistics API Methods

Metadefender Core Info

This is an overview of the Metadefender Core info with REST server API version. Request URL

http://localhost:8008/metascan_rest/stat

178

http://localhost:8008/metascan_rest/stat



Metadefender Core Administrator


Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request. 401: Invalid API key/ Exceeded usage Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the request is successful: { "server_started" : "11/10/2013 11:05:55 PM", "num_cur_avs" : 4, "rest_ver" : "3.7.0.21135", "metascan_ver" : "3.7.0.21166" } Description num_cur_avs Number of current anti-virus of

Metadefender Core rest_ver REST version

metascan_ver Metadefender Core version

Scan History

Retrieve scan history from the last X hours

179


Request URL

http://localhost:8008/metascan_rest/stat/scanhistory/<X>

HTTP header parameters apikey Metadefender Core Management Console password REQUIRED if set in the Management

Console

Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request. 401: Permission Denied for statistic Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when request is successful: [ { "total_scanned_files" : 101, "total_infected" : 0, "avg_scan_time" : 19.712871287128714, "localtime" : "2013-11-11T11:00:00+07:00" }, { "total_scanned_files" : 3, "total_infected" : 0, "avg_scan_time" : 113.66666666666667, "localtime" : "2013-11-11T10:00:00+07:00" }, { "total_scanned_files" : 5, "total_infected" : 0, "avg_scan_time" :25.455566656565212, "localtime" : "2013-11-11T09:00:00+07:00" } ] Description avg_scan_time Average scanning time

180

http://localhost:8008/metascan_rest/stat/scanhistory/%3cX%3e


Client History

Retrieve scan info of clients from the last X hours Request URL

http://localhost:8008/metascan_rest/stat/clients/<X>

HTTP header parameters apikey Metadefender Core Management Console password REQUIRED if

set in the Management Console

Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request. 401: Permission Denied for statistic Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the request is successful: [ { "ip" : "localhost", "total_scanned_files" : 104, "total_infected" : 0 } ] Description ip ip address of client calls rest

File Upload Information

Retrieve the number of uploaded files in the last X days Request URL

181

http://localhost:8008/metascan_rest/stat/clients/%3cX%3e


o Get the file upload records in the 7 days http://localhost:8008/metascan_rest/stat/fileuploads

o Get the file upload records from the last X days http://localhost:8008/metascan_rest/stat/fileuploads/<X> e.g. http://localhost:8008/metascan_rest/stat/fileuploads/2



Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request. 401: Permission Denied for statistic Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when request is successful: [ { "date" : "2013-11-09T17:00:00Z", "total_file_scan" : 12, "total_file_upload" : 12, "unique_ips" : 1 }, { "date" : "2013-11-08T17:00:00Z", "total_file_scan" :0, "total_file_upload" : 0, "unique_ips" : 0 }, { "date" : "2013-11-07T17:00:00Z", "total_file_scan" : 5, "total_file_upload" : 5, "unique_ips" : 1 }]

182

http://localhost:8008/metascan_rest/stat/fileuploads

http://localhost:8008/metascan_rest/stat/fileuploads/%3cX%3e

http://localhost:8008/metascan_rest/stat/fileuploads/2


The records returned should not include today's record. E.g. Today is 2013-11-12 but the date of latest record returned should be 2013-11-11. Description ip IP address of client calls rest

stat/fileuploads/last Request URL

http://localhost:8008/metascan_rest/stat/fileuploads/last

Similar with stat/fileuploads, but only returns last record, no other info. Example of when the request is successful: [ { "date" : "2013-11-11T00:00:00", "total_file_scan" : 7, "total_file_upload" : 7, "unique_ips" : 1 } ] The records returned should not include today's record. E.g. Today is 2013-11-12 but the date of latest record returned should be 2013-11-11.

File Type Information

Request URL o Get the last 30 days’ stats

http://localhost:8008/metascan_rest/stat/filetypes

o Get the statistics from the last X days http://localhost:8008/metascan_rest/stat/filetypes/<X> E.g. http://localhost:8008/metascan_rest/stat/filetypes/10


183

http://localhost:8008/metascan_rest/stat/fileuploads/last

http://localhost:8008/metascan_rest/stat/filetypes

http://localhost:8008/metascan_rest/stat/filetypes/%3cX%3e

http://localhost:8008/metascan_rest/stat/filetypes/10



Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request. 401: Permission Denied for statistic Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the request is successful: [ { "date" : "2013-11-10T00:00:00", "file_type_short" : "A", "file_type_long" : "Archive", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "Z", "file_type_long" : "Email", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "E", "file_type_long" : "Executable", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "I", "file_type_long" : "Disc Image", "total_files" : 0, "clean_files" : 0,

184


"infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "D", "file_type_long" : "Document", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "G", "file_type_long" : "Graphics", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "M", "file_type_long" : "Media", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "N", "file_type_long" : "Not Analyzed", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "P", "file_type_long" : "PDF", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "T", "file_type_long" : "Text", "total_files" : 0, "clean_files" : 0, "infected_files" : 0 }, { "date" : "2013-11-10T00:00:00", "file_type_short" : "O", "file_type_long" : "Uncategorized",

185


"total_files" : 0, "clean_files" : 0, "infected_files" : 0 } ]

Server Health

Request URL http://localhost:8008/metascan_rest/stat/serverhealth



Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request. 401: Permission Denied for statistic Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the request is successful: [ { "usage_check_localtime" : "2013-11-11T15:00:00+07:00", "avg_ram_usage" : 25.2051264444987, "avg_cpu_usage" : 15.52880859375, "avg_disk_q_len" : 3.3068783523049206E-5 } ] Description avg_ram_usage average of RAM usage of Metascan server avg_cpu_usage average of CPU usage of Metascan server

avg_disk_q_len ?

186

http://localhost:8008/metascan_rest/stat/serverhealth


Recent Threats

Request URL o Get all threats

http://localhost:8008/metascan_rest/stat/threats

o Get the n of last threats http://localhost:8008/metascan_rest/stat/threats/<n> e.g. http://localhost:8008/metascan_rest/stat/threats/10



Method: GET Request Error (HTTP status: 40x) 400: Bad request Not supported HTTP method or invalid http request. 401: Permission Denied for statistic Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the request is successful: [ { "data_id" : "ebf9bc7b204d433eb63167d1e2511798", "detected_at" : "2013-11-11T09:45:52.309Z", "last_queried" : "2013-11-11T09:45:55.724Z", "threat_name" : "Worm.Bagle.AT", "logging_source" : "REST" }, { "data_id" : "7ebdf2fbc345459cacfcfc297aaf2ae1", "detected_at" : "2013-11-11T09:43:43.702Z",

187

http://localhost:8008/metascan_rest/stat/threats

http://localhost:8008/metascan_rest/stat/threats/%3cn%3e

http://localhost:8008/metascan_rest/stat/threats/10


"last_queried" : "2013-11-11T09:45:12.798Z", "threat_name" : "Eicar-Test-Signature", "logging_source" : "REST" } ] Description data_id data_id of infected file contains threat logging_source Source logs that threat to database

Engine Info

Request URL http://localhost:8008/metascan_rest/stat/engines


Metadefender Core Administrator


Method: GET Request Error (HTTP status: 40x) 400: Bad request Unsupported HTTP method or invalid HTTP request. 401: Invalid API key/ Exceeded usage Either missing API key or invalid API is passed. Request Error (HTTP status: 50x) 500: Internal server error Server temporary unavailable. Try again later. Response (HTTP status: 200) Example of when the request is successful: [ { "eng_name" : "ClamAV scan engine", "eng_ver" : "0.97.8",

188

http://localhost:8008/metascan_rest/stat/engines


"def_time" : "11/10/2013 12:00:00 AM", "eng_type" : "Bundled engine", "active" : true }, { "eng_name" : "ESET NOD32 Antivirus", "eng_ver" : "4.2.71.2", "def_time" : "11/11/2013 12:00:00 AM", "eng_type" : "Customer licensed engine", "active" : false }, { "eng_name" : "ESET scan engine", "eng_ver" : "1412 (20131023)", "def_time" : "6/1/2012 12:00:00 AM", "eng_type" : "Bundled engine", "active" : true }, { "eng_name" : "Norman scan engine", "eng_ver" : "7.2.6", "def_time" : "10/13/2013 12:00:00 AM", "eng_type" : "Bundled engine", "active" : true }, { "eng_name" : "Total Defense scan engine", "eng_ver" : "37.0.1.55", "def_time" : "11/8/2013 12:00:00 AM", "eng_type" : "Bundled engine", "active" : true } ] Description def_time The last time the engine updated active True: Engine is used to scan file

Using Sample Code

PHP Sample Code for IIS 7

1. Install IIS 7 by adding a role to the server.

2. Add CGI/Fast CGI as an IIS feature (from cmd.exe): dism /online /enable-feature /featurename:IIS-CGI

3. Download the latest PHP 5 from http://www.php.net/downloads.php

189

http://www.php.net/downloads.php


4. Install PHP as IIS FastCGI to “C:\PHP” (make sure to select script executable option to associate *.php with PHP)

5. Edit C:\PHP\php.ini short_open_tag = On cgi.force_redirect = 0

6. Configure IIS on the system. Go to Start -> Control Panel -> Administrative Tools -> Internet Information Services (IIS) Manager Choose Sites->Default Web Site Double-click on Handler Mappings in the right pane Double-click on PHP_via_FastCGIModule Click Request Restrictions Flip to the Verbs tab Select radial button One of the following verbs, enter “GET,POST,HEAD” Flip to the Access tab Select Script radio button Click OK all the way out and accept changes.

7. Place scan.php, userInput.html and uploads folder into C:\Inetpub\wwwroot folder.

8. Allow necessary security permission to both the files and the folder (for testing please allow to everyone).

9. Configure Metadefender Core COM settings to allow IIS_USRS and IUSR to launch, access, and configure Metadefender Core (local permissions only).

10. Restart Metadefender Core service.

11. Go to http://localhost/userInput.html

12. Upload the file to be scanned and HTML should call PHP script and prints the scan results on the web page.

ASP Sample

1. Install IIS.

2. Install Web Development support for Visual Studio.

3. Enable web sharing on the sample dir - Go to sample dir -> [Right click] Properties -> Web Sharing -> Share this folder -> give all permissions to folder (including Execute for scripts.

190

http://localhost/userInput.html


4. Enable advanced file sharing options – Open an explorer window -> Tools -> Folder Options -> View -> uncheck “Use simple file sharing”.

5. Make sure the following ASP accounts have permissions on the project folder: - ASP.Net machine account - Internet guest account (IUSR) - Launch IIS Process account (IWAM) In order to change the permissions, right-click the folder -> Properties -> Security -> add the accounts, and for each account add Read + Execute permissions).

6. Open Internet Explorer, and change security settings to custom. Reset them to Medium low, and change the “Download unsigned ActiveX controls” and “Initialize and script ActiveX controls not marked as safe” options to “prompt”.

7. Open the project.

8. You may get the following message "The specified Web server is not running ASP.NET version 1.1 ..." if so follow the steps in: http://support.microsoft.com/kb/817267/en-us.

9. In the IIS make sure access is allowed to the sample folder (by setting the folder's "Directory Security".)

10. Assign "Launch and Activation" permission on the Metascan to the account running ASP.Net in DCOM Configuration (DCOMCNFG).

Java Sample

Here are some steps to use the Java sample with Eclipse IDE or running on the command line. Java sample is not installed with Metadefender Core. You must download this separately from the OPSWAT portal. Go to https://portal.opswat.com/, Products->Metadefender Core->Resources->Sample Code-> For Metadefender Core. With the Eclipse IDE running:

1. Create new Java project from existing source code. (Choose the Java sample code folder you have downloaded).

2. Add Metasscan_java_interface.jar to the build path of the project (By default, Metascan_java_interface.jar file is installed in the directory where Metadefender Core is installed under the JNI folder).

3. Set java argument of Native library path to the “omsJInterfaceImple.dll”

191



Example: -Djava.library.path=C:/Program Files (x86)/OPSWAT/Metadefender Core 8/JNI (in vm arguments of “Run Configuration”)

Running on the Command Line:

1. Go to bin directory.

2. Run the following command: Java.exe -cp .;<absolute path to Metascan_java_interface.jar file> -Djava.library.path=<absolute path to omsJInterfaceImpl.dll> com.opswat.metascan.Sample

Building Custom Engines for Metadefender Core

How to Deploy or Enable Custom Engine

What You Need to Do

1. Install Metadefender Core 3.8.0 or newer. 2. Obtain custom engine template package. - Template for C custom engine(vc10) - Template for C# custom engine(vc10) - Template for VB .NET custom engine(vc10) 3. Obtain Metadefender Core custom engine handler (omsCEHandler.exe). 4. Implement the custom engine interface. 5. Build custom engine library (DLL). 6. Deploy the custom engine library (DLL) with the Metadefender Core custom engine handler (omsCEHandler.exe). 7. Configure Metadefender Core to load and use your custom engine. 8. Additional steps for C# and VB.NET custom engines.

Installation/Configuration

This section covers the configuration of Metadefender Core in order to load and use your custom engine. The following properties must be defined and configured in the omsConfig.ini, located in the Metadefender Core installation directory.

Section or attribute Value Description

192


[custom_engine_***]

Replace *** with a unique identifier for your engine. (e.g. [custom_engine_myav] or [custom_engine_mycompany]

A unique section name to group the settings for your custom engine. This section must be unique and begin with “custom_engine”. If you do not name the section appropriately, Metadefender Core will not detect your custom engine.

custom_engine_dir

Absolute path to the directory. This path should not end with a trailing separator. e.g., c:\my Custom Engine AV

The directory where your custom engine binaries reside. (At a minimum, omsCEHandler.exe and the C interface DLL).

custom_unique_id 4~10 characters starting with “ce” prefix e.g., ce01

This is used for communication between Metadefender Core and the omsCEHandler processes. This must be unique for each custom engine, if you have multiple custom engines.

custom_dll_name Custom engine DLL name e.g., sampleCustomEng.DLL

The sample custom engine project generates “sampleCustomEng.DLL” by default, but you can modify as you wish.

custom_engine_type Numerical value 0 – Indicates the engine is a scan engine

support_multithread Numerical Value. 0 – No 1 – Yes

You must set this attribute to 0 if your custom engine is not thread-safe. If you are not sure, set to 0.

Complete Example

[custom_engine_myav] custom_engine_dir= c:\my Custom Engine AV custom_dll_name=sampleCustomEng.dll custom_engine_type=0 support_multithread=0 custom_unique_id=ce01

C Interface

InitCE

193


This is the first method called. It allows you to initialize your engine. Metadefender Core will only recognize your engine if this method returns success (returns 0). int InitCE (

void ** reserved ) Arguments Argument Description

reserved Reserved for future usage.

Return Value Value Description

0 To indicate that the engine initialized correctly.

1 To indicate that initialization failed and the engine should not be used.

Deinit CE

This is called when Metadefender Core is shut down. Any resources acquired by your engine should be released and any unsaved data should be stored. int DeinitCE ( ) Arguments No arguments are required for this function.

FreeString

This is called to free allocated memory for wchar **. Metadefender Core will call this when Metadefender Core is done with the values allocated by your functionality. void FreeString

194


( wchar ** stringToFree

) Arguments

Argument Description Other

stringToFree Double pointer to wchar.

Must be de-allocated in the same way that memory is allocated.

GetProductName

This method provides the name of the custom engine. Metadefender Core will use this for display purposes. int GetProductName (

wchar_t ** productName void ** reserved

) Arguments Argument Description Other

productName The name of the custom engine.

Implementer must allocate the memory required.



0 To indicate that product name is successfully returned.

Other value Not supported. Reserved for future usage.

Scan

195


This is the main function of the custom engine. The scan result returned from this function call will be used by Metadefender Core's scan-related API. (For more details, please refer to the Metadefender Core COM API section in the Software Developer Guide). int Scan ( int dataType, const void * data, int * scanResult, wchar_t ** threatName,


dataType 0: If data is a file path string (wide characters) Other dataType values are not supported with 3.2.5.

data

When dataType indicates a file path, you must cast to a const wchar_t pointer. e.g., wstring filePathToScan = (const wchar_t *)data;

scanResult

Scan result to be returned. 0: clean 1: found threat 2: suspicious 3: failed to scan 10: not scanned (during update)

threatName Threat name to be returned.

reserved Reserved for future.

IMPORTANT: threatName is a double pointer to wchar_t. It must be allocated by the custom engine in a way that can be deallocated by the FreeString function. Return Value Value Description

0 Scan completed successfully.

196


1 Failed to start or finish scanning.

PeformUpdate

This is called in order to initiate an update of the custom engine. This call should be a synchronous call and wait until the update completes. int PerformUpdate (



Return Value Value Description 0 Update completed successfully. 1 Failed to start or finish updating. 2 Engine is already up to date. 3 Failed to update due to network problem. 4 Engine is already updating. 5 Failed downloading update. 6 Failed reloading database.

GetDefinitionTime

This is used to retrieve the timestamp of the definition files currently in use by the custom engine. Memory will be allocated by Metadefender Core. int GetDefinitionTime ( int * defYear, int * defMon, int * defDay, int * defHour,

197


int * defMin, void** reserved

) Arguments Argument Description

defYear Year portion of definition time.

defMon Month portion of definition time.

defDay Day portion of definition time.

defHour Hour portion of definition time.

defMin Minute portion of definition time.


0 Information successfully retrieved.

1 Information unavailable.

GetDefinitionInfo

This method is used to retrieve additional attributes about the definition files in use by the custom engine. int GetDefinitionTime ( wchar_t** reserved, wchar_t** defVer, wchar_t** defSig, wchar_t** engVer, void** reserved2 ) Arguments

198


Argument Description Others

defVer Definition version you would like to report. Metadefender Core does not utilize this information for any logic. It is used only for display purposes.


defSig Definition signature count you would like to report. Metadefender Core does not utilize this information for any logic. It is used only for display purposes.


engVer Engine version you would like to report. Metadefender Core does not utilize this information for any logic. It is used only for display purposes.


reserved, reserved2 Reserved for future use.

IMPORTANT: defVer, defSig, engVer are double pointers to wchar_t or NULL. They must be allocated by the custom engine in a way that can be deallocated by the FreeString function unless NULL pointer is passed. Return Value

Value Description



ReloadDatabase

This method provides a way for Metadefender Core to explicitly reload the definition database of the engine, especially for a malware engine. During this call any requests to scan should return “Not Scanned’’. If there is no specific step required for reloading the database, it should still return 0 to indicate that the engine is ready. int ReloadDatabase (

const wchar_t * srcDir, void ** reserved

) Arguments

199


Argument Description

srcDir If specified, path to the folder where new definition files are placed.


IMPORTANT: If srcDir is used, the folder and its contents must be consumed and deleted by the engine. Return Value

Value Description

0 Database is successfully reloaded or nothing needs to be done to reload database.

1 Fail to reload database (same result as fail to init).

ReloadConfig

This is used to reload any/all specific engine configurations. If there is no specific engine configuration, this needs to be reloaded, this function should return 0 without any re-initialization of engines. int ReloadConfig ( const wchar_t * reservedI,

void** reservedIO ) Return Value Value Description

0 Successfully reloaded configuration.

1 Failed to reload configuration.

VB NET C Interface with C wrapper

NInitCE

200


This is the first method called. It allows you to initialize your engine. Metadefender Core will only recognize your engine if this method returns success (returns 0). public int NInitCE ( ) Arguments No argument. Return Value Value Description

0 To indicate that the engine initialized correctly.

1 To indicate initialization failed and the engine should not be used.

NDeinitCE

This is called when Metadefender Core is shut down. Any resources acquired by your engine should be released and any unsaved data should be stored. int NDeinitCE ( ) Arguments No arguments are required for this function.

NGetProductName

This method provides the name of the custom engine. Metadefender Core will use this for display purposes. int GetProductName (

ref string productName )

201


Arguments

Argument Description

productName The name of custom engine.


0 To indicate that product name is successfully returned.

Other value Not supported. Reserved for future usage.

NScan

This is the main function of the custom engine. The scan result returned from this function call will be used by Metadefender Core's scan-related API. (For more details, please refer to the Metadefender COM API section in the Software Developer Guide). int NScan ( int reserved, string filepath, ref int scanResult, ref string threatName, ) Arguments Argument Description

reserved Reserved for future.

filepath Path to the file needed to scan.

202


scanResult

Scan result to be returned. 0: clean 2: suspicious 1: found threat 3: failed to scan 10: not scanned (during update)

threatName Threat name to be returned.

Return Value

Value Description

0 Scan completed successfully.

1 Failed to start or finish scanning.

NPerformUpdate

This is called in order to initiate an update of the custom engine. This call should be a synchronous call and wait until the update completes. int PerformUpdate ( ) Return Value Value Description 0 Update completed successfully. 1 Failed to start or finish updating. 2 Engine is already up to date. 3 Failed to update due to network problem. 4 Engine is already updating. 5 Failed downloading update. 6 Failed reloading database.

NGetDefinitionTime

203


This is used to retrieve the timestamp of the definition files currently in use by the custom engine. Memory will be allocated by Metadefender Core. int NGetDefinitionTime ( ref int defYear, ref int defMon, ref int defDay, ref int defHour, ref int defMin, ) Arguments Argument Description

defYear Year portion of definition time.

defMon Month portion of definition time.

defDay Day portion of definition time.

defHour Hour portion of definition time.

defMin Minute portion of definition time.




NGetDefinitionInfo

This method is used to retrieve additional attributes about the definition files in use by the custom engine. int NGetDefinitionTime ( ref string reserved, ref string defVer, ref string defSig, ref string engVer,

204


) Arguments Argument Description

defVer Definition version you would like to report. Metadefender Core does not utilize this information for any logic. It is used only for display purposes.

defSig Definition signature count you would like to report. Metadefender Core does not utilize this information for any logic. It is used only for display purposes.

engVer Engine version you would like to report. Metadefender does not utilize this information for any logic. It is used only for display purposes.

reserved Reserved for future use.




NReloadDatabase

This method provides a way for Metadefender Core to explicitly reload the definition database of the engine, especially for a malware engine. During this call any requests to scan should return ‘Not Scanned.’ If there is no specific step required for reloading the database, it should still return 0 to indicate that the engine is ready. int ReloadDatabase (

ref string srcDir, ) Arguments Argument Description

205


srcDir If specified, path to the folder where new definition files are placed.


0 Database is successfully reloaded or nothing needs to be done to reload database.

1 Fail to reload database (same result as fail to init).

Additional Steps for VB C custom engine

Additional Steps for VB/C# Custom Engine

1. Register your custom engine library on the system: If you are using regasm.exe, run the following command. regasm.exe <DLL name>

2. Place C wrapper DLL with the custom engine dlls. If you compile the VB sample solution or C# solution, you will get 2 DLLs (one for the cwrapper provided by OPSWAT and the other for your custom engine).

When you uninstall or upgrade Metadefender Core

When You Uninstall/Upgrade Metadefender Core

Any configuration pertaining to the custom engines will NOT be preserved if you uninstall and re-install Metadefender Core. You MUST backup and then restore the following changes once your installation or upgrade is complete:

• omsConfig.ini (changes made pertaining to the custom engines) • Any custom engine directories located under the Metadefender Core

installation folder

206


Metadefender® Core Release Notes General ======== Please refer to the Metadefender Core documentation for more information on Metadefender Core - Metadefender Core 1, 4, and 8 come with a trial license good for 15 days after installation - Metadefender Core 12, 16, and 20 do not come with a trial license. To obtain a trial license, please contact OPSWAT sales ([email protected]) - Metadefender Core should be restarted whenever a new license has been applied - Metadefender Core was previously called Metascan - Metadefender Core categorizes files as 'blocked' or 'allowed' based on the scan result. The following scan results causes a file to be labeled as 'blocked': Infected/Known, Suspicious, Failed To Scan, Cleaned, Unknown, Quarantined, Skipped Dirty, Not Scanned, Aborted, Encrypted, File Mismatch, Filtered - Beginning with version 3.11.2 Metadefender Core is only supported on Windows 64 bit operating systems Known Issues ============= - Metadefender Core embedded engines should not be installed on a system which has an alternate product provided by the same vendor, for example, installation of the Norman Scan Engine with Norman Security Suite. This configuration is not supported by Metadefender Core . - Metadefender Core license allows up to 10 Remote Desktop (RDP) sessions to a server running Metadefender Core . Please contact OPSWAT if you need more than ten connections via RDP. - Scanning boot sector is only supported by Total Defense/Quick Heal scan engine. Other engines will fail to scan for bootsector scan request. - REST Web Service installation may fail to install if UAC (User Access Control) is enabled. Turn off UAC and run the installation with Administrator privileges. - If logging all scan history is enabled, the Metadefender Core Management console dashboard may cause high load on mongoDB. - ICAP server does not block traffic if server is overloaded by default - Metadefender Core does not support installation to directory paths that include non-ASCII characters. - Metadefender Core must have archive handling enabled in order to correctly scan GZIP content through the ICAP interface. - When Metadefender Core is configured to use a local instance of MongoDB (the default configuration) the HKEY_LOCAL_MACHINE\SOFTWARE\Wow6432Node\OPSWAT\Metascan\db_instan

207


ce (or HKEY_LOCAL_MACHINE\SOFTWARE\OPSWAT\Metascan\db_instance for 32 bit systems) key must be set to 'localhost' or '127.0.0.1'. The local system can not be referred to by IP address. - Metadefender Core does not support installation on systems where the TEMP environment variable contains more than one path - In Metadefender Core 20 packages, the Sophos engine must have its definitions updated before scans will complete successfully - Archives scanned through the COM interface do not have their scan results logged - The setting 'Maximum File Size for files scanned through the web interface' found on the Configuration->Scan Configuration page in the Metadefender Core Management Console cannot currently be imported or exported through the Backup/Restore feature. - Disabling the 'support_custom_engine' property will disable all engines in Metadefender Core - Threats found within archives will not be removed even if Metadefender Core is configured to delete or quarantine files that contain threats. - Stopping the Metadefender Core service may not stop all engine handlers (omsAMEHandler.exe and omsCEHandler.exe processes) if there are engine updates in progress. Engine handlers will terminate after the update has completed or they can be terminated manually. - For Metadefender Core 20 packages, Vir.IT eXplorer fails to scan file paths longer than 260 characters. The following are only applicable if the Metadefender Mail functionality is being used ============================================================================ - Metadefender Email agent will be installed as part of Metadefender Core. Before installing Metadefender Core, please uninstall mail agent before installing Metadefender Core. - A separate SMTP server is required for notification - Exchange (malware agent configuration) may block release from quarantine. - Email sanitization to HTML may be blocked and attachment may be replaced with text "This attachment was removed because it contains data that could pose a security risk." - An attachment that has been sanitized may be larger than the original attachment. As a result, it may be necessary to increase the maximum attachment size setting on your mail server Version 3.12.2 ============= New Features ------------ - The Vir.IT eXplorer engine has been added to the Metadefender Core 20 installer Other changes ------------

208


- Updated the McAfee, FProt, AVG, and ClamAV engines to the latest versions - The length of time to retain scan history and application logs is now configurable - Source IP address is now listed on the file scan history page - Fixed minor bugs in file scan history page - ICAP: added support for retrieving file name from Content-Disposition header - Mail: added support for exporting mail agent configuration - JPG sanitization (JPG to JPG) Version 3.12.1 ============= New Features ------------ - The NANO engine has been added to the Metadefender Core 20 installer Other changes ------------ - New functionality to scan all e-mail message HTML bodies - Settings for the data sanitization, Metadefender Mail Agent and Metadefender Quarantine are not included in configuration backup/restore and need to be restored manually - 'High Security' default workflow added - 'Client' default workflow added - 7zip component updated to 16.02 to address vulnerability - Updated UX for file scan history page Version 3.12.0 ============= New Features ------------ - Zillya! is now part of Metadefender Core 8 and above, replacing ThreatTrack - Ikarus is now part of Metadefender Core 12 and above, replacing Agnitum - File scanning by path through the REST API - File scanning through ICAP now uses Metadefender Core workflows Other changes ------------- - Files are blocked if data sanitization fails - Password protected documents are now flagged as a scan result type - Data sanitization for Office documents supports output to original file type - Links are now removed as part of Data sanitization - Improved error handling and alert for mail agent - Added additional e-mail header (x-metadefender-core-result) - Improved logging for failed to scan result - Upgraded Avira and Bitdefender integrations

209


Version 3.11.2 ============= New Features ------------ - Data sanitization now supports TIF to TIF and RTF to RTF options Other changes ------------- - Updated Avira engine - Metadefender Core is only supported on Windows 64 bit operating systems - Enhanced file type detection of DOCX and SVG file types - Resolved issue with non-English file names in the quarantine - Archives within Office files are treated as archives - Metadefender Mail will now detect error messages from the destination mail server and log them Version 3.11.1 ============= New Features ------------ - Metascan is now called Metadefender Core Other changes ------------- - Caching is disabled by default Version 3.11.0 ============= New Features ------------ - The Metascan Mail Agent is now installed with Metascan Other changes ------------- - IIS Express component has been upgraded to version 8.0 - The Metascan quarantine service is now installed under the Metascan installation directory - Fixed how average scan time is calculated on the Management Console Dashboard - The Metascan Mail Agent configuration in the Management Console has been updated Version 3.10.1 ============= New Features

210


------------ - None Other changes ------------- - Minor bug fixes in Metascan workflows Version 3.10.0 ============= New Features ------------ - Metascan 20 Package, including McAfee, Sophos, Ikarus, and Zillya! engines - Release of Metascan workflows (previously in beta release) Other changes ------------- - The Metascan ICAP server can be configured to not scan files over a certain size - The Metascan Web Scan interface now uses Metascan workflows - Support for Metascan Central Management Console (installed separately) - The Metascan REST server is no longer an optional component - SQL server is no longer supported for logging scan results Version 3.9.5 ============= New Features ------------ - Sanitization of e-mail attachments is now available with the Metascan Mail Agent. Sanitization can be enabled or disabled by updating the 'Mail Agent' workflow in the Metascan Management Console. - Metascan REST API keys can now be specified when generating Metascan Client packages so that Metascan Client can be used with Metascan servers that have REST API keys enabled Other changes ------------- - Fixed issue where Microsoft Office files were being detected as archives - The Metascan Mail Agent can now send notifications if an infected attachment is found even if the e-mail is not quarantined Version 3.9.4 ============= New Features ------------ - Metascan administrators can now choose whether or not to quarantine e-mails flagged as threats by the Metascan Mail Agent

211


- E-mails quarantined by Metascan can now trigger e-mail notifications to the sender and receiver of the quarantined e-mail Other changes ------------- - MP4 and M4V files are now classified as the same file type for file type detection - Additional debug information collected in verbose log package - The Metascan Mail Agent is now only supported for use as an SMTP relay for all mail servers, included Microsoft Exchange - Metascan's data sanitization technology no longer wraps the output files in an archive if the output is a single file - Hash calculation can now be disabled for large files to improve performance Version 3.9.3 ============= New Features ------------ - A Beta version of configurable workflows has been added to Metascan and can be used through the 'process' REST API. Please refer to the Metascan Developer Guide section of the Metascan documentation for more information on using this and related APIs. - Archive handling, file type analysis, quarantine/delete, file type conversion and 'copy to' post actions can all now be configured per workflow profile - A customized Automatic Definition Update Download Utility package can now be downloaded from the Metascan Management Console Other changes ------------- - The archive handling functionality has been updated to support more types of ISO and tar.bz2 archive extraction - The security and compatibility of the Metascan Management Console and web interface has been improved by replacing the PHP component with JavaScript - The ClamWin engine included in all Metascan packages has been replaced with the ClamAV engine Version 3.9.2 ============= New Features ------------ - Updated Linux version of Metascan Client including RedHat and CentOS support - Metascan Mail Agent now supports scanning e-mails on any SMTP servers in addition to Microsoft Exchange servers Other changes -------------

212


- The OESIS library used to utilize customer licensed engines has been updated to V4 - Archive handling and quarantine options are now configured on the 'Scan Configuration' page under the ScanEx Configuration page - Removed the option to disable reporting on asynchronous scan progress from the Management Console. Option can still be disabled from the Metascan command line. Version 3.9.1 ============= Known limitations for the Metascan Mail Agent ------------ - Mail Agent has only been tested on Exchange Server 2013 and 2010 - Each Metascan server can only scan mail from one Mail Agent on one Exchange Server - E-mail formatting is lost when downloaded from Quarantine page - Quarantined files are not properly listed in the Quarantine Manager when there are too many files in the quarantine New Features ------------ - Metascan Mail Agent for Exchange is included in all Metascan packages - Quarantine Manager is now available through the Metascan Management Console - Configuration settings can be exported and imported through the Management Console Other changes ------------- - The number of Remote Client Licenses included with each Metascan package has been increased to 25 - Significant performance improvements have been made when scanning large volumes of files - The Metascan service will now start automatically after installation - The ClamWin embedded engine has been updated to the latest version Version 3.9.0 ============= New Features ------------ - Metascan packages have been updated. Metascan 4 now includes the Avira and AhnLab engines and Metascan 16 now includes Kaspersky - Metascan Zero has been changed to Metascan 1, and now includes the ClamWin engine - F5 BIG-IP LTM proxies are now supported by the Metascan ICAP server - Management Console look and feel has been updated Other changes -------------

213


- Metascan documentation is now accessible through the Management Console - Improvements have been made in Metascan's queueing mechanism, improving performance when the Metascan server is under high load - Management Console pages now load faster - Metascan service now starts automatically after installation - 7zip library has been upgraded to 9.20 - The Metascan ICAP server can now be configured through the 'Sources' page in the Management Console - Additional information is now logged for scan requests through the ICAP interface - OESIS component has been updated to the latest version - OPSWAT is discontinuing Windows 2003 support in Metascan 3.9.0 Version 3.8.3 ============= Changes ------------- - Remote MongoDB access disabled when authentication is disabled - PHP updated to latest version (5.5.15) - Customer Licensed Engines are disabled by default Version 3.8.2 ============= New Features ------------ - Configuration of Windows Event Log and Syslog logging in the Management Console - Option for Metascan ICAP server to show overloaded web page (for details, refer to Using ICAP Server guide) - Troubleshooting logs available for download through the Metascan Management Console - Updated Metascan Client Linux to Beta2 - Added .NET to installer Other changes ------------- - Enhanced handling database connection usages with high load logging - Enhanced ICAP server to better handle HTTP header with invalid characters - Fixed failure of applying offline update when multiple temporary directories is configured - Better recovery of REST server after an unexpected restart Version 3.8.1 ============= New Features ------------

214


- Support scanning of VMware virtual machines (for details, refer to Software Developer Guide) - More detailed scan results for files inside of archives (for details, refer to Software Developer Guide) - Support scanning original unextracted archive even after extracting (for details, refer to Metascan Configuration Guide) - File type conversions now supported from the Metascan command line interface (for details, refer to Software Developer Guide) - Handle too many scan requests more gracefully on REST API and Metascan COM API - Support for upgrading custom engines from the Metascan command line interface (BETA) - Enhanced logging in the Metascan Management Console - Debug report available through the Metascan Management Console - Metascan Client 3.0.5 - Beta release of Metascan Client for Linux and Mac (BETA) Other changes ------------- - Updated version of AVG - Heuristic scan for ESET enabled by default - Updated version of Bitdefender - Support adjust_non_english_filenames property for files inside of archive - File upload limit on web scan is configurable via Metascan Management Console - Enhanced handling of temporary files - Storing files (scanned via v2 REST API or web scan) is disabled by default. - Minor bug fixes Version 3.8.1 Beta ================== New Features ------------ - Support scanning of VMware virtual machines (for details, refer to Software Developer Guide) - More detailed scan results for files inside of archives (for details, refer to Software Developer Guide) - Support scanning original unextracted archive even after extracting (for details, refer to Metascan Configuration Guide) - File type conversions now supported from the Metascan command line interface (for details, refer to Software Developer Guide) - Handle too many scan requests more gracefully on REST and Metascan COM - Support for upgrading custom engines from the Metascan command line interface (BETA) - Enhanced logging in the Metascan Management Console

215


- Debug report available through the Metascan Management Console - Metascan Client 3.0.5 - Beta release of Metascan Client for Linux and Mac (BETA) Other changes ------------- - Updated version of AVG - Heuristic scan for ESET enabled by default - Updated version of Bitdefender - Support adjust_non_english_filenames property for files inside of archive - File upload limit on web scan is configurable via GUI - Enhanced handling temporary files - Storing file (via v2 REST or web scan) is disabled by default. - Many minor bug fixes Version 3.8.0 ============= New Features ------------ - Metascan 4 package now includes AVG - Logging to Syslog - Scanned files downloadable from Management Console log - Beta version of new REST API Other changes ------------- - Remove service restart requirement for some configuration changes - Client licensing now measured over 24 hour period - Default daily scan limit set to 10,000,000 scans/day - Added RAM drive support to Windows 7, 8, 2008 R2, 2012. - Discontinued REST server logging/API key authentication (v1 REST API) Version 3.7.6 ============= New Features ------------ - Beta release of REST v2 API (for more details, please contact OPSWAT) - Original file name now displayed as part of scan logging page in Management Console - Updated Java sample code/documentation - Ability to clear scan history from Management Console - Metascan events from the Windows event log displayed in Management Console - Proxy configuration added to Management Console - JAVA interface syncscan now returns scan details, including per engine results

216


Other changes ------------- - Minor ICAP server bug fixes - Minor REST server bug fixes - Minor logging bug fixes Version 3.7.5 ============= New Features ------------ - Added system information to debug command - Upgrades to K7, AVG, Norman, Emsisoft, and GFI engines - Full Blue Coat ProxySG Support for Metascan ICAP server - Better messaging in Metascan ICAP server for archives that exceed defined limits - New web-based Metascan Management Console - Support for remote scanning of large (>2GB) files - Support for centralized logging in MongoDB Version 3.7.4 ============= NOTE: Metadefender 3.x MUST not be used with Metascan 3.7.3 or older version New Features ------------ - Support compatibility with Metadefender 3.x - Metascan Web-based Management Console (configuration for Scan/Engines/Metascan Client) - Metascan Web-based Management Console (deploy offline update) Other changes ------------- - Enhanced logging of scan results - Updated Metascan Web Management Console to use latest PHP 5.5 - Upgraded mongodb to the latest version (2.4) Version 3.7.3 ============= New Features ------------ - New customizable web pages for cases when Metascan ICAP server identifies a potential threat - Enhanced configurability of scan results logging (by default, only infected files will be logged)

217


Other changes ------------- - Enhanced stability of Metascan ICAP server - Fixed bug where customer-licensed engines were not being detected Version 3.7.2 ============= New Features ------------ - Included ICAP Server(BETA) supporting Squid Proxy - Updated Metascan 8 Package to include BitDefender engine - Web-based Management Console Dashboard - Enhanced error messages for black/white lists - Generation and download pages for 64bit version of Metascan Client - Renamed VirusBuster to Agnitum Other changes ------------- - Enhanced BitDefender engine integration to handle multi-thread scanning Version 3.7.1 ============= New Features ------------ - Added support of configurable hash (for more details, refer to Metascan Configuration Guide) - High performance built-in db (mongoDB) for Metascan - More comprehensive logging of scan results - More comprehensive logging of client information with remote scanning - Update cache to be based on SHA256 instead of SHA1 - On-demand generation of Metascan Client deployed with Metascan (for more details, refer to Using REST server) Version 3.7.0 ============= New Features ------------ - New REST server running under IIS Express (For more details, refer to Using REST Server documentation) Other changes -------------

218


- Fixed bug where the Metascan license information displayed "trial" even after successful activation of a Metascan license - Enhanced Java Interface to handle massive file scanning - Improved handling of password encrypted RAR archive files - Fixed bug where the Metascan Management Console displayed out-of-date engine information for updates done through offline update Version 3.6.4 ============= New Features ------------ - Support for extraction of self-extracting archives created in 7-Zip and WinRAR - Configurable scan result consolidation for 'failed to scan' results from individual engines - Enhanced scan logging Other changes ------------- - Minor bug fixes Version 3.6.2 ============= New Features ------------ - Updated CA scan engine - Updated AVG scan engine - More efficient offline updates for Metascan 8 with more logging Other changes ------------- - Fixed Bug where Bitdefender engine would return multiple threats on a single file - Other minor bug fixes Version 3.6.1 ============= New Features ------------ - Upgraded GFI engine(VIPRE 5.0) - Scan hang detection and automatic recovery - Update hang detection and automatic recovery - Multiple temporary directories for extracting archive library - MMC does not need to restart when Metascan service restarts - Metascan Command Line Utility to return scan result as process exit code

219


- Concurrent license for Remote Clients Other changes ------------- - Updated offline update download utility - Other minor bug fixes Version 3.6.0 ============= New Features ------------ - Added 8 new engines as embedded engines; Avira, BitDefender, Emsisoft, Frisk/F-Prot, Inca/nProtect, K7, VirusBlokAda, Zillya - Enhanced archive library to handle the number of files and file size inside of an archive file - Enhanced update report when update is already request so that engine name which is currently updating is part of update report - Added new COM API, CheckLicenseEx (For more details, refer to Software Developer Guide) - Enhanced license activation to support rollback mechanism in case of activation failure - Updated MMC with various changes such as engines and license page - Updated Metascan Connector timeout value from 30 seconds to 5 minutes Other changes ------------- - Fixed Metascan Configurator failing to create a database instance on Postgres - Other minor bug fixes Version 3.5.1 ============= New Features ------------ - Updated CA engine - Updated AVG engine - Updated ESET engine - Improved offline update mechanism Other changes ------------- - Other minor bug fixes Version 3.4.2 =============

220


New Features ------------ - Improved handling large files with Metascan REST server Version 3.4.0 ============= New Features ------------ - Added support of logging to PostgreSQL - Added logging of engine definition info - Added logging file type information - Updated ScanEx API to retrieve file type information (For more details, refer to "Software Developer Guide") - Upgraded Clamwin to 0.97 Other changes ------------- - Other minor bug fixes Version 3.3.2 ============= New Features ------------ - Added support of 64bit Java application (64bit JNI). Other changes ------------- - Fixed handing file names with comma inside of archive file. - Added warning to Windows System Event Log as license expiration date gets closer Version 3.3.0 ============= New Features ------------ - Added support of license activation using MMC - Added user-interactive license activation using command prompt Version 3.2.8 ============= Engines -------- - Improved handling scanning non-English files name with VirusBuster scan engine

221


- Fixed update failure of CA scan engine with proxy configuration Other changes ------------- - Added support of auto detection of the proxy setting on IE with Metascan Connector - Updated licensing of Remote Clients during evaluation period - Enhanced handling of invalid engine names during on-demand update (UpdateAntiriruses and UpdateEngine) Version 3.2.5 ============= New Features ------------ - Added support of custom engine. (For more details, refer to the Building Custom Engine Guide) Other changes ------------- - Returns "encrypted archive" instead of "clean" as scan results of nested encrypted archive files. Version 3.2 ============= New Features ------------ - Added ability to run custom script as post action based on scan results. (For more details, refer to "Post Action" section in Metascan Configuration Guide) - Added sample code for Metascan Connector (for REST server) - Added proxy support on Metascan Connector - Added connection_timout_secs on ICAP server configuration New API or Changes ------------------ - Added new property "post_action" (For more details, refer to "Post Action" section in Metascan Configuration Guide) Engines -------- - Updated CA scan engine to 1.4.1 Other changes ------------- - Fixed issue with too many asynchronous scan requests - Added "addtoblack" and "addtowhite" commands to omsFilterCLI.exe.

222


- Removed Microsoft Visual C++ dependency from Metascan Connector binaries. - Fixed issue with REST server installation where it broke existing handler mapping rules (IIS 7 or newer) Version 3.1 ============= New Features ------------ - RESTful Web API (For more details, refer to "Metascan Web API" section in Software Developer Guide) New API or Changes ------------------ - Updated JNI to support Java 1.4 Engines -------- - Added support of updating engines' definition files via http proxy Other Major Changes ------------------- - Optimized scanning archive file with Distributed Remote Engines Other changes ------------- - Fixed issue with "net start" command - Fixed offline activation failure at 2nd time Version 3.0.0 ============= New Features ------------ - Enhanced licensing activation and management - Added support for Distributed Remote Engine - Added support for custom scan rules through whitelist/blacklist New API or Changes ------------------ - Added support for reporting scan details per engine for synchronous scan File Types and Archive Handling ------------------------------- - Added File Type Category for mail messages - Enhanced detection of encrypted archive file

223


- Added support of extracting encrypted archive file Engines -------- - Updated CA scan engine - Updated ClamWin scan engine (0.96) - Enhanced scanning speed with AVG scan engine - Enhanced scanning speed with CA scan engine Other Major Changes ------------------- - Updated Embedded Engines to be out of process - Updated File Type engines to be out of process - Improved capability of recovery from failure by Watchdog Other changes ------------- - Added option to resetting cache with manual update - Improved handling of foreign file names by Quarantine Manager - Enhanced Quarantine Manager to allow restoring files to a custom path - Added configuration guide to MMC help - Improved logging scan history with user agent and user description Version 2.7.5 ============= - Fixed failure in scanning signature with pre-installed engine on Windows 2008 and Windows 7 Version 2.7.4 ============= - Enhanced file type detection (mostly on text-based files) - Fixed Remote Client returning hyphen with threat name - Added new file type short, "Z" for mail messages. (For more details, "Other Important Return Types" section in Software Developer Guide) - Added sample codes for Remote Client (C#, ASP .net, and C++) - Added support of retrieving definition info from Remote Client - Expanded error codes for Remote Client Version 2.7.3 ============= - Updated ClamWin engine to 0.95 - Fixed license activation bug on Windows 2008 and Windows 7 - Added support of Manual Updater on Windows 2008 and Windows 7

224


- Added sample codes for Remote Client (C#, ASP .net, and C++) - Added support of retrieving definition info from Remote Client - Expanded error codes for Remote Client Version 2.7.1 ============= - Improved scanning speed with McAfee Virus Scan Enterprise (8.5) - Fixed minor bugs on Remote Client - Fixed minor bugs on VirusBuster scan engine update Version 2.7.0 ============= - Updated VirusBuster engine - Added support of scan details with caching mechanism - Expanded non-English support with Metascan kernel - Added support of file type analysis for files inside of archive files (For more details, "AnalyzeFileTypeEx2" API in Software Developer Guide) - Added support of file type mismatch (For more details, "AnalyzeFileTypeEx2" API in Software Developer Guide) - Added support of Remote Client C API (For more details, refer to "Metascan Remote Client") - Added configuration of caching mechanism (For more details, refer to "keep_cache_for" and "reset_on_update", under the "Properties" section in Software Developer Guide) - Added logging capability of Metascan ICAP server. (Configure through omsConfig.ini) - Added support of non-English file name input with Metascan Command Line Utility

225

software.opswat.comsoftware.opswat.com/metascan/Documentation/Metascan/documen… · File Scan...

Documents

Transcript of software.opswat.comsoftware.opswat.com/metascan/Documentation/Metascan/documen… · File Scan...