[Topic 179679]

About Kaspersky Scan Engine

Kaspersky Scan Engine is a server-side security solution that provides anti-virus protection, HTTP traffic scanning, and file and URL reputation checking for third parties’ client-side solutions.

Kaspersky Scan Engine delivers comprehensive protection for a wide range of devices from malware, trojans, worms, rootkits, spyware, and adware. It can be used with various products and services including desktop applications, server solutions, proxy servers, and mail gateways.

Based on Kaspersky Anti-Virus Software Development Kit 8 Level 3 (KAV SDK) and the award-winning Kaspersky Anti-Virus Engine, Kaspersky Scan Engine employs the newest methods of detection and removing various types of malware.

You can request the KAV SDK documentation or purchase KAV SDK together with the documentation from your Technical Account Manager (TAM).

[Topic 179689]

Key functions of Kaspersky Scan Engine

Kaspersky Scan Engine can work in one of two modes:

• HTTP mode

  In this mode, Kaspersky Scan Engine works as a REST-like service that receives HTTP requests from client applications, scans objects passed in these requests, and sends back HTTP responses with scan results.

• ICAP mode

  This mode is available only for Linux operating systems.

  In this mode, Kaspersky Scan Engine works as an ICAP server that scans HTTP traffic that passes through a proxy server and URLs that are requested by users and filters out web page that contain malicious content.

Kaspersky Scan Engine also includes a graphical user interface that allows you to easily configure the behavior of Kaspersky Scan Engine, review its service events, and scan results.

Usage scenarios:

Threat Protection

Kaspersky Scan Engine can scan files and blocks of random access memory (RAM) by using the Kaspersky anti-virus database and the advanced heuristics module. Scanning of compressed executables, archives, Microsoft Office macros, email messages, and email databases is supported.

Web Filtering

Kaspersky Scan Engine can scan specific URLs (in HTTP mode) or URLs that users request from a proxy server (in ICAP mode). In ICAP mode, Kaspersky Scan Engine can return a user-specified HTML page instead of malicious web pages.

File and URL Reputation Checking

Kaspersky Scan Engine can receive information about reputation of the scanned files and URLs from Kaspersky Security Network (KSN).

Graphical User Interface

The graphical user interface (GUI) allows you to configure Kaspersky Scan Engine, check the status of a Kaspersky Scan Engine key file or activation code, review service events, and scan results.

Key functionality:

• Award-wining Kaspersky anti-malware technology provides the best-in-class malware detection rates and can instantaneously react to emerging threats.
• Kaspersky Security Network provides information about the reputation of files and Internet resources, ensures that Kaspersky applications react to threats faster without waiting for an application database update, and reduces the likelihood of false positives.
• Filters out malicious, phishing, and adware URLs.
• Detection of multi-packed objects and objects packed using “grey” compression utilities (frequently used for hiding malicious programs from anti-virus software).
• Advanced heuristics analyzer and machine learning-based detection technologies.
• Disinfection of infected files, archives, and encoded objects.
• Updatable Anti-Virus engine: detection technologies and processing logic can be upgraded or modified through regular updates of the anti-virus database.
• Kaspersky Scan Engine natively supports multithreading and can process several tasks simultaneously. You can adjust the number of scanning processes and threads to increase performance of Kaspersky Scan Engine.
• Additional filtering layer is made possible by the Format Recognizer component. You can use this component to recognize and skip files of certain formats during the scanning process. Dozens of formats are supported, including executable, office, media files, and archives.
• Graphical user interface (GUI) for management and monitoring:
  • Lets you configure application settings and manage the application.
  • Lets you monitor the application operating status, status of the used key file or activation code, and the number of scanned and detected objects.
  • Provides information about all scanned objects on a dashboard. Scan results can be imported in CSV format.
• Ease of installation and configuration, and no development is needed with out-of-the box installation. The solution will be running within minutes.
• Reporting features:
  • Important application events are sent to Syslog in CEF format.
  • All service events are visible on the GUI dashboard.
• Maintenance features:
  • Anti-virus database updates are automatic. Kaspersky Scan Engine automatically restores corrupted databases.
  • Easy collection of product traces with the GUI.
  • Option to use online activation. With online activation, licensing information for Kaspersky Scan engine is updated automatically.
• Fault-tolerant and resilient architecture.
• Source code for HTTP client and ICAP service are provided in the distribution kit for customization.
• Comprehensive documentation and cross-platform API support. Similar APIs for Linux/UNIX and Windows versions.
• Option to minimize external traffic by creating local mirror server for the anti-virus database (additional tool needed).

[Topic 179821]

Kaspersky Scan Engine detection technologies

This section describes detection technologies that are implemented in Kaspersky Scan Engine.

Signature analysis

This detection method is based on searching for a predefined string in scanned files. Signature analysis also includes detection based on the hash of the entire malicious file. Traditional signatures allow for the detection of specific objects with high precision. Other signature-based technologies, such as structure heuristics signatures and SmartHash, can detect unknown and polymorphic malware.

Signature analysis can detect specific attacks with high precision and few false positives. However, this detection method is ineffective against polymorphic malware and different versions of the same malware. Effective signature analysis also requires frequent signature updates.

The frequently updated and comprehensive anti-virus database of Kaspersky Scan Engine ensures the highest level of protection from known malware, trojans, worms, rootkits, spyware, and adware.

Advanced heuristics

When scanning a script or an executable file, Kaspersky Anti-Virus Engine emulates its execution in a secure artificial environment. If a suspicious activity is discovered during analysis of the behavior of the emulated object, it is considered malicious. This method helps detect new and unknown malware.

The emulator component of Kaspersky Scan Engine emulates a functional execution environment for the object, including functions and different subsystems of the target operation system. No real functions or subsystems are used during emulation.

Machine learning technologies

SmartHash is a Kaspersky Lab patented algorithm for building intelligent, locality-sensitive hashes. Locality-sensitive hashes are static file features that can be extracted and quantized. SmartHashes can be calculated for each file and different files can have the same SmartHash when they are functionally similar. Because of this, a single SmartHash allows for the identification of clusters of similar files and the effective detection of unknown malware from known malware families.The SmartHash technology utilizes several precision levels, a feature that allows for the detection of even highly polymorphic malware. Simultaneously, with a very high level of confidence, it minimizes the risk of false postive detection.

SmartHash benefits:

• Strength against new, evasive, and polymorphic malware.
• Detection within minutes.
• Works offline and online.
• Flexible model with several similarity levels that allows for detection of uninfected and malicious files.
• Resilient technology: mathematical model is updated by machine learning techniques and is constantly revised by experts. Using SmartHash results in minimal false positives and yields a high detection rate.

Besides detection functionality, SmartHash online improves the power of Kaspersky Lab whitelisting capabilities. SmartHash calculated on the client side can be compared against billions of known good files in the Kaspersky Lab database through global Kaspersky Security Network.

Kaspersky Lab uses machine learning to boost the detection rate of existing scanning technologies. It deploys machine learning for automated analysis of internal sandbox execution logs. Both known malicious files and unknown files are executed in internal behavioral sandbox systems. Some of these sandboxes mimic user systems running standard products. The most powerful sandboxes make use of granular logging capabilities, allowing for extremely fine-tuned detection.

Robots process the sandbox logs line by line. The execution logs of new malicious samples’ are studied by using Machine Learning, to find new detection indicators. These new indicators enrich mathematical models of non-signature-based detection methods as well as heuristic behavioral records created by Kaspersky Lab experts.

Processing of Compressed Executables And Archives

Kaspersky Scan Engine includes technology that allows for detection of viruses and other objects inside compressed executables and archives. With this technology, infected archives and compressed executables can be safely disinfected or deleted.

Kaspersky Scan Engine supports approximately 4000 different formats of compressed executables and archives.

Disinfection of Archives

This technology is designed to disinfect archived files. With this technology, infected objects inside archives are successfully disinfected or deleted, depending on user-defined settings. You do not have to use any other archiving utilities.

The Kaspersky Anti-Virus Engine is currently capable of removing viruses from ARJ, CAB, RAR, and ZIP archives.

Kaspersky Security Network

Kaspersky Security Network (KSN) is an infrastructure of cloud services that provides access to the online Knowledge Base of Kaspersky Lab which contains information about the reputation of files, web resources, and software. The use of data from Kaspersky Security Network ensures faster responses to threats, improves the performance of some protection components, and reduces the likelihood of false positives.

KSN can block new malware seconds after it appears, by using automatic rules that are generated from data provided by Kaspersky Lab users.

Kaspersky Lab hosts KSN servers in data centers all around the world providing minimal latency for cloud checks. KSN database contains terabytes of information that is constantly updated by security analysts and automatic methods.

When using KSN, you provide Kaspersky Lab with information about the installed copy of Kaspersky Scan Engine and detected objects. This information does not contain any personal or confidential information of the user. The information obtained is protected by Kaspersky Lab in accordance with statutory requirements. For the full list of information that is transferred to Kaspersky Lab when using KSN, see section "Data transferred to Kaspersky Lab during File and URL Reputation Checking".

Kaspersky Scan Engine is compliant with the General Data Protection Regulation (GDPR).

To learn about use cases for working with KSN, see section "File and URL Reputation Checking in KSN".

Notice to users in the U.S.

Malicious and phishing URL detection

Kaspersky Scan Engine includes an offline database of malicious and phishing URLs. In addition, you can check the reputation of the scanned URLs in Kaspersky Security Network.

[Topic 179681]

Kaspersky Scan Engine architecture

Kaspersky Scan Engine is an implementation of Kaspersky HTTP Daemon and Kaspersky ICAP Plugin, which are parts of Kaspersky Anti-Virus SDK.

When Kaspersky Scan Engine is running as Kaspersky HTTP Daemon, it is working in HTTP mode. When Kaspersky Scan Engine is running as Kaspersky ICAP Plugin, it is working in ICAP mode.

Following are descriptions of the modes:

• HTTP mode

  In this mode, Kaspersky Scan Engine works as a REST-like service that receives HTTP requests from client applications, scans files and URLs passed in these requests, and sends back HTTP responses with scan results.

• ICAP mode

  This mode is available only for Linux operating systems.

  In this mode, Kaspersky Scan Engine works as an ICAP server that scans HTTP traffic that passes through a proxy server, scans URLs that are requested by users, and filters out web pages that contain malicious content.

Kaspersky Scan Engine consists of the following components:

• The service that processes client requests. The services are different in HTTP and ICAP modes.
• Kaspersky Scan Engine GUI

  The user interface that the user can access over a browser. Its functionality is implemented in the klScanEngineUI executable file.

• Kaspersky Anti-Virus Engine

  The executable file that scans objects passed to it.

[Topic 179822]

HTTP mode

In HTTP mode, Kaspersky Scan Engine consists of an HTTP service called kavhttpd, Kaspersky Anti-Virus Engine, and Kaspersky Scan Engine GUI.

When you use Kaspersky Scan Engine in HTTP mode, the interaction between the components occurs in the following order:

1. Files and URLs for scanning are sent to kavhttpd in HTTP requests.

   You can send objects to kavhttpd in two ways:

   • By using an HTTP client, such as the sample HTTP client from the distribution kit
   • By making HTTP requests manually
2. The kavhttpd service sends objects to Kaspersky Anti-Virus Engine.
3. Kaspersky Anti-Virus Engine scans the objects.

   If you are using File and URL Reputation Checking, the objects are also sent to KSN for reputation checking.

4. After scanning, Kaspersky Anti-Virus Engine returns the results to the kavhttpd service.
5. The kavhttpd service sends scan results to the HTTP client or another application that sent objects for scanning.

   If you are using Kaspersky Scan Engine GUI, the scan results are displayed on the Scan results page.

The diagram below shows the interaction between the components of Kaspersky Scan Engine.

Interaction between HTTP clients and the Kaspersky Scan Engine working in HTTP mode

Page top

[Topic 179823]

ICAP mode

In ICAP mode, Kaspersky Scan Engine consists of an ICAP server called kavicapd, Kaspersky Anti-Virus Engine, and Kaspersky Scan Engine GUI.

When you use Kaspersky Scan Engine in ICAP mode, the interaction between the components occurs in the following order:

1. An ICAP client (for example, a proxy server) sends ICAP requests to kavicapd.
2. The kavicapd service sends files to Kaspersky Anti-Virus Engine for scanning.
3. Kaspersky Anti-Virus Engine scans the contents of HTTP messages and URLs that are encapsulated in these ICAP requests.

   If you are using File and URL Reputation Checking, the contents of HTTP messages and URLs are also sent to KSN for reputation checking.

4. After scanning, Kaspersky Anti-Virus Engine returns the results to the kavicapd service.
5. The kavicapd service sends ICAP responses with scan results to the ICAP client.

   If you are using Kaspersky Scan Engine GUI, the scanning results are displayed on the Scan results page.

Kaspersky Scan Engine can work with several ICAP clients at once.

The following example shows the interaction between a proxy server and Kaspersky Scan Engine working in ICAP mode.

Interaction between a proxy server and the Kaspersky Scan Engine working in ICAP mode

Page top

[Topic 179824]

Kaspersky Scan Engine usage scenarios

This section describes common usage scenarios of Kaspersky Scan Engine.

[Topic 180130]

Threat Protection

Kaspersky Scan Engine helps you protect your network and data by detecting malware and legitimate software that can be used by intruders.

Before you start using Kaspersky Scan Engine, decide on your use case, in the following order:

1. Decide what data you want to scan:
   • Data uploaded to your network by your users.
   • Data created inside your organization, such as documents.
   • Data uploaded from sources outside your network. This can prevent supply chain attacks.

   You can also use Kaspersky Scan Engine to add scanning functionality to your own applications and security services. Kaspersky Scan Engine scans objects of any format, including packed objects.

2. Decide whether HTTP or ICAP mode is better for your environment.

   For information about the two modes of Kaspersky Scan Engine, see section "Key functions of Kaspersky Scan Engine".

3. Decide where you want to deploy Kaspersky Scan Engine.
4. Decide how you will gain access to scan results:
   • In Kaspersky Scan Engine GUI
   • In a client application
5. Decide which features of Kaspersky Scan Engine you will use:
   • Decide whether you want to use Kaspersky Security Network (KSN) for checking the reputation of files and URLs
   • Decide what level of heuristics you want to use
   • Decide what actions Kaspersky Scan Engine must perform after detecting malware or legitimate software that can be used by intruders
   • Decide whether you want to scan packed executables
   • Decide whether you want to scan archives
   • Decide whether you want to scan email
   • Decide whether you want to scan email databases

After determining your use case for Kaspersky Scan Engine, proceed to section "Getting started with Kaspersky Scan Engine".

Below you can find instructions for typical tasks that Kaspersky Scan Engine performs in HTTP mode and in ICAP mode.

Scanning files with the sample HTTP client (HTTP mode)

This instruction assumes that you have already installed and configured Kaspersky Scan Engine by using the configuration file or the GUI.

To scan files with Kaspersky Scan Engine:

1. Start the kavhttpd service.
2. Start the sample HTTP client. The client is located in the /bin/kavhttp_client directory of the distribution kit.
3. Pass the files that you want to scan to the sample HTTP client:
   • Scan files that are larger than 4 megabytes (MB) in scanfile mode. Use the -f option and pass the local paths to the files to the sample HTTP client.

     The example below shows how to scan two files in scanfile mode:

   ./kavhttp_client -f /usr/dir1/example1.zip /usr/dir2/example2.iso

   • Scan files that are smaller than 4 MB in scanmemory mode. Pass the paths (network or local) to the sample HTTP client. To do this, use the -s option.

     The example below shows how to scan a file in scanmemory mode:

   ./kavhttp_client -s 192.0.2.0:888 /usr/dir/example.txt

4. Review the scan results.

Scanning traffic that passes through a proxy server (ICAP mode)

This instruction assumes that you have already installed and configured Kaspersky Scan Engine by using the configuration file or the GUI.

To scan traffic that passes through a proxy server:

1. Configure your proxy server to work with Kaspersky Scan Engine. See section "Using Kaspersky Scan Engine in ICAP mode with Squid" for an example.
2. Create a response template that you want to display or script to execute when malware or legitimate software that can be used by intruders is detected.
3. Configure ICAP service rules for a situation when Kaspersky Scan Engine detects malware or legitimate software that can be used by intruders. You can do it either manually or by using the GUI.
4. Start the kavicapd service.

Kaspersky Scan Engine will automatically detect malware or legitimate software that can be used by intruders, and process it according to the ICAP service rules.

[Topic 180131]

Web Protection from malicious and phishing websites

This section describes common scenarios where you can use Kaspersky Scan Engine to check websites.

The instructions provided in this section assume that you have already installed Kaspersky Scan Engine.

Scanning URLs (HTTP mode)

To scan a URL with Kaspersky Scan Engine:

1. In the ServerSettings > Flags element of the kavhttpd.xml configuration file, specify the settings you want:
   • KAV_SHT_ENGINE_KSN—For checking the reputation of websites by KSN.
   • KAV_SHT_ENGINE_WMUF—For detecting malicious websites.
   • KAV_SHT_ENGINE_APUF—For detecting phishing websites.

   You can also specify settings by means of the GUI.

2. Start the kavhttpd service.
3. Send the URL that you want to check to the kavhttpd service.

   For example, you can use the sample HTTP client %service_dir%/bin/kavhttp_client for this purpose, as follows:

   ./kavhttp_client -u http://example.com

   Also you can send an HTTP POST request to the kavhttpd service.

4. Review the scan results.

   You can block URLs for which the DETECTED result is returned.

Checking URLs that users request through proxy server (ICAP mode)

To check URLs that pass through a proxy server:

1. In the kavicapd.xml configuration file, specify the settings you want:
   • In the SDKSettings > ScanningMode element, specify KAV_O_M_PHISHING for detecting phishing websites.
   • In the KSNSettings > UseKSN element, specify 1 for checking the reputation of websites by KSN.

   You can also specify settings by means of the GUI.

2. Configure your proxy server to work with Kaspersky Scan Engine. See section "Using Kaspersky Scan Engine in ICAP mode with Squid" for an example.
3. Create a response template if you want to display it instead of phishing web pages.
4. Create ICAP service rules for cases when Kaspersky Scan Engine returns PHISHING and DETECTED scan results.

   You can do it either manually or by using the GUI.

5. Start the kavicapd service.

Kaspersky Scan Engine will automatically check URLs and process them according to the ICAP service rules.

[Topic 180133]

File and URL reputation checking in KSN

This section describes common scenarios where you can use Kaspersky Scan Engine together with Kaspersky Security Network (KSN) to check files and websites.

The instructions provided in this section assume that you have already installed Kaspersky Scan Engine.

Checking files and websites with reputation checking (HTTP mode)

To check files and websites by means of reputation checking:

1. In the ServerSettings > Flags element of the kavhttpd.xml configuration file, specify the KAV_SHT_ENGINE_KSN setting.

   You can also use the GUI to turn on reputation checking.

2. Start the kavhttpd service.
3. Send URLs and files that you want to check to the kavhttpd service.

   For example, you can use the sample HTTP client %service_dir%/bin/kavhttp_client.

   Also, you can send HTTP POST requests to the kavhttpd service.

4. Review the scan results.

   The scan results will depend on the reputation of the URLs and files.

Checking URLs that users request through proxy server (ICAP mode)

To check URLs that pass through a proxy server:

1. In the KSNSettings > UseKSN element of the kavicapd.xml configuration file, specify 1 for checking the reputation of files and websites by KSN.

   You can also turn on reputation checking by using the GUI.

2. Configure your proxy server to work with Kaspersky Scan Engine. See section "Using Kaspersky Scan Engine in ICAP mode with Squid" for an example.
3. Create ICAP service rules for scan results returned by Kaspersky Scan Engine.

   You can create the rules either manually or by using the GUI.

4. Start the kavicapd service.

Kaspersky Scan Engine will return the results of checking files and URLs on the basis of their reputation in KSN and will respond according to the ICAP service rules you have specified.

[Topic 179690]

Hardware and software requirements

This section describes the Kaspersky Scan Engine system requirements.

Supported operating systems

Kaspersky Scan Engine runs on 64-bit Linux and 64-bit Microsoft Windows operating systems.

Software requirements

Kaspersky Scan Engine GUI can be used with the following web browsers:

• Google Chrome 60 or later
• Microsoft Internet Explorer 11 or later
• Mozilla Firefox 55 or later
• Microsoft Edge 38 or later

Kaspersky Scan Engine GUI requires PostgreSQL 10.7 or later to be installed. For more information, see section "Preparing to install Kaspersky Scan Engine GUI".

The Kaspersky Scan Engine distribution kit does not contain the Boost and OpenSSL sources. If you want to customize the HTTP service or ICAP service by editing and recompiling their sources shipped in the Kaspersky Scan Engine distribution kit, download the Boost and OpenSSL sources from the official websites and use them in your system. If you make changes in the sources of the HTTP or ICAP service and want to use Kaspersky Scan Engine GUI, get approval for the changes from your technical account manager (TAM) so that the HTTP or ICAP service can still work with Kaspersky Scan Engine GUI.

For compiling the HTTPD and ICAP services, use the following software:

• Boost 1.60
• OpenSSL (latest version)
• GCC 6.1 or later
• PostgresSQL libraries. It is recommenced to install the libpqxx-devel package.

Hardware requirements

Kaspersky Scan Engine requires 1 gigabyte (GB) of available hard disk space. If you use Kaspersky Scan Engine GUI, you also must allocate space for the PostgreSQL database that stores service events. You can keep the PostgreSQL database on the same computer as Kaspersky Scan Engine or on a different computer. The size of the database depends on the number of the events and can reach several gigabytes. The database stores events that occurred in the last six months.

The table below lists minimum processors and the RAM requirements for Kaspersky Scan Engine depending on the operating system that you use.

Page top

[Topic 179691]

Distribution kit contents (Linux)

The Kaspersky Scan Engine distribution kit for Linux contains the following files and directories.

Distribution kit contents (Linux)

Page top

[Topic 184779]

Distribution kit contents (Windows)

The Kaspersky Scan Engine distribution kit for Windows contains the following files and directories.

Distribution kit contents (Windows)

Page top

[Topic 180558]

Getting started with Kaspersky Scan Engine

This section explains how to start using Kaspersky Scan Engine quickly and easily.

[Topic 179865]

Getting started with Kaspersky Scan Engine in HTTP mode

This section explains how to start using Kaspersky Scan Engine in HTTP mode.

Before you start using Kaspersky Scan Engine, we strongly recommend that you restrict access to Kaspersky Scan Engine files, including logs, with built-in tools provided by your operating system. This measure will help make your information more secure.

To start using Kaspersky Scan Engine in HTTP mode:

1. Install Kaspersky Scan Engine.

   Kaspersky Scan Engine starts automatically after installation is complete.

2. Optionally, configure Kaspersky Scan Engine for use in HTTP mode.

   For example, you can configure Format Recognizer to increase the processing speed of Kaspersky Scan Engine in HTTP mode.

3. If you configure HTTP mode manually (without using the install installation script), and you are using offline licensing mode, you have to put the license file in the directory that is specified in the LicensePath element of the configuration file. If you are using online licensing mode, you have to specify the activation code. For more information about online and offline licensing modes, see sections "Activating Kaspersky Scan Engine in offline licensing mode", "Activating Kaspersky Scan Engine in online licensing mode".
4. Optionally, configure the init script or systemd unit file to manage Kaspersky Scan Engine in HTTP mode.
   • For information on how to configure the init script, see section "Changing variables in the HTTP mode init script".
   • For information on how to configure the systemd unit file, see section "Changing variables in the HTTP mode unit file".

   For Linux systems only.

5. Optionally, configure logging.

   Notice that logging decreases performance of Kaspersky Scan Engine. Usually you need to enable logging only during the integration or for debugging.

6. Update the anti-virus database or configure the update frequency.

   To keep track of the update process and make sure that you get the latest updates, send an HTTP request to the /api/v3.0/update/status address. For more information, see section "Updating the database in HTTP mode", subsection "Getting the database update status".

7. Verify the detection capabilities of Kaspersky Scan Engine.
8. Make requests to Kaspersky Scan Engine:
   • Run the sample HTTP client from the command line to scan files.

     For more information about using the sample HTTP client, see section "Using the HTTP client".

   • Use a REST-like protocol for making HTTP requests.
   • Use the source code of the sample HTTP client as an example for creating your own client.

Page top

[Topic 179890]

Getting started with Kaspersky Scan Engine in ICAP mode

This section explains how to start using Kaspersky Scan Engine in ICAP mode.

Before you start using Kaspersky Scan Engine, we strongly recommend that you restrict access to Kaspersky Scan Engine files, including logs, with built-in tools provided by your operating system. This step will help make your information more secure.

To start using Kaspersky Scan Engine in ICAP mode:

1. Install Kaspersky Scan Engine.

   Kaspersky Scan Engine starts automatically after installation is complete.

2. Optionally, configure Kaspersky Scan Engine for use in ICAP mode.
3. If you configure ICAP mode manually (without using the install installation script), and you are using offline licensing mode, you have to put the license file in the directory that is specified in the LicensePath element of the configuration file. If you are using online licensing mode, you have to specify the activation code. For more information about online and offline licensing modes, see sections "Activating Kaspersky Scan Engine in offline licensing mode", "Activating Kaspersky Scan Engine in online licensing mode".
4. Optionally, configure service rules.
5. Optionally, configure logging.

   Notice that logging decreases performance of Kaspersky Scan Engine. Usually you need to enable logging only during the integration or for debugging.

6. Optionally, configure environment variables.
7. Update the anti-virus database or configure the update frequency.
8. Verify the detection capabilities of Kaspersky Scan Engine.
9. Run Kaspersky Scan Engine in ICAP mode.

[Topic 179682]

Installing Kaspersky Scan Engine

This section explains how to install Kaspersky Scan Engine.

[Topic 181508]

Preparing to install Kaspersky Scan Engine GUI

Kaspersky Scan Engine GUI uses the PostgreSQL object-relational database management system to store scan statistics, scan results, service events, and service status. For this reason, if you want to use Kaspersky Scan Engine GUI, you must install PostgreSQL first.

You can use one of two integration schemes:

• Install Kaspersky Scan Engine on the same computer as PostgreSQL.
• Install Kaspersky Scan Engine on a different computer that has access to the computer with PostgreSQL.

[Topic 184772]

Installing and configuring PostgreSQL (Linux)

Kaspersky Scan Engine GUI requires PostgreSQL 10.7 or later. The following procedure covers installation and configuration of PostgreSQL 10.7. The procedure for a later version may vary.

To install and configure PostgreSQL:

1. Download and install PostgreSQL.

   You can install PostgreSQL in one of the following ways:

   • Install the package downloaded from the PostgreSQL website.

     Visit https://www.postgresql.org/download/ to see a list of supported operating systems and installation instructions for each of them.

   • Install PostgreSQL from source code.

     Visit https://www.postgresql.org/docs/10/installation.html for installation instructions.

2. Open the postgresql.conf configuration file. The location of this file varies depending on your operating system:
   • In Debian-based Linux distributions postgresql.conf is located at /etc/postgresql/10/main/.
   • In RedHat-based Linux distributions postgresql.conf is located at /var/lib/pgsql/data/.

   If you use another operating system, the location of postgresql.conf may be different.

3. Specify the IP address that Kaspersky Scan Engine must use to connect to PostgreSQL in the listen_addresses setting of postgresql.conf.
4. Specify the port on which the PostgreSQL is to listen for connections from Kaspersky Scan Engine in the port setting of postgresql.conf.
5. Save and close postgresql.conf.
6. Open the pg_hba.conf configuration file. This file is located in the same directory as postgresql.conf.
7. Specify that PostgreSQL must require an MD5-encrypted password for authentication from all of its clients:
   1. Find the following line in pg_hba.conf:

      host all all 127.0.0.1/32 peer

   2. Change this line to:

      host all all 127.0.0.1/32 md5

8. If PostgreSQL and Kaspersky Scan Engine are installed on different computers, add the following line to pg_hba.conf:

   host all all %IP%/32 md5

   Here %IP% is the IP address of the computer on which Kaspersky Scan Engine is installed.

9. Save and close pg_hba.conf.
10. Restart PostgreSQL by running the following command from the command line:

    service postgresql restart

11. Set the password for the default PostgreSQL user.

    During installation PostgreSQL creates a superuser called postgres. By default, this user does not a have a password.

    To set the password for the postgres user:

    1. From the command line, change the currect user to the postgres user:

       su postgres

    2. Under the postgres user account, start the psql utility by running the following command in the command line:

       psql

    3. In psql, change the password of the postgres user by running the following command:

       alter user postgres with password '%PASSWORD%';

       Here %PASSWORD% is the new password for the postgres user.

    4. Quit the psql utility by running the following command in psql:

       \q

You can now install Kaspersky Scan Engine GUI.

To install Kaspersky Scan Engine GUI, you need a PostgreSQL user that has permissions for creating new databases and users. You can use the postgres user for that, or create a new user.

After installing PostgreSQL and setting the password for the postgres user, you can proceed to section Installation using script (Linux) or Manual installation (Linux).

All data is stored in a single database called kavebase. Kaspersky Scan Engine does not use any other databases.

[Topic 184729]

Installing and configuring PostgreSQL (Windows)

To install and configure PostgreSQL:

1. Download and install PostgreSQL.

   Visit https://www.enterprisedb.com/downloads/postgres-postgresql-downloads to see a list of supported operating systems and download the installer.

2. Open the postgresql.conf configuration file. This file is located at %postgresql_dir%\data. Here %postgresql_dir% (for example, C:\Program Files\PostgreSQL\11) is the folder that PostgreSQL was installed in.
3. Specify the IP address that Kaspersky Scan Engine must use to connect to PostgreSQL in the listen_addresses setting of postgresql.conf.
4. Specify the port on which the PostgreSQL is to listen for connections from Kaspersky Scan Engine in the port setting of postgresql.conf.
5. Save and close postgresql.conf.
6. Open the pg_hba.conf configuration file. This file is located in the same folder as postgresql.conf.
7. Make sure that PostgreSQL requires an MD5-encrypted password for authentication from all of its clients. Find the following line in pg_hba.conf:

   host all all 127.0.0.1/32 md5

   If the authentication method specified on this line is other than md5, change it to md5.

8. If PostgreSQL and Kaspersky Scan Engine are installed on different computers, add the following line to pg_hba.conf:

   host all all %IP%/32 md5

   Here %IP% is the IP address of the computer on which Kaspersky Scan Engine is installed.

9. Save and close pg_hba.conf.
10. Restart PostgreSQL by running the following command from the command line:

    sc stop postgresql-x64-11 sc start postgresql-x64-11

You can now install Kaspersky Scan Engine GUI.

To install Kaspersky Scan Engine GUI, you need a PostgreSQL user that has permissions for creating new databases and users. You can use the postgres user for that, or create a new user.

After installing PostgreSQL, you can proceed to section Installation using installer (Windows) or Manual installation (Windows).

All data is stored in a single database called kavebase. Kaspersky Scan Engine does not use any other databases.

[Topic 180797]

Installation using script (Linux)

This section explains how to install Kaspersky Scan Engine using the install installation script. You can use the install installation script if Kaspersky Scan Engine is not installed on your computer (there is no /opt/kaspersky/ScanEngine directory).

If you want to use Kaspersky Scan Engine together with Kaspersky Scan Engine GUI, you must have PostgreSQL installed on a computer that is accessible from the computer on which you install Kaspersky Scan Engine. Kaspersky Scan Engine GUI does not work without PostgreSQL.

To install Kaspersky Scan Engine using the installation script:

1. Make sure you have root (administrator) privileges.
2. Run install.
3. Read the End User License Agreement (EULA) for Kaspersky Scan Engine.

   If you agree with the terms of the EULA, accept it. If you decline to accept the terms of the EULA, the installation will be canceled.

4. Choose whether to use Kaspersky Scan Engine GUI.
5. If you choose to use Kaspersky Scan Engine GUI, do the following:
   1. Perform the actions described in section "Preparing to install Kaspersky Scan Engine GUI".
   2. Specify the IP and port for connecting to PostgreSQL.
   3. Provide credentials for a user that has permissions for creating new databases and users. The credentials are not recorded anywhere.

      With these credentials, Kaspersky Scan Engine will create a new database called kavebase in which Kaspersky Scan Engine will store its data, and a new PostgreSQL user called scanengine. From this moment on, Kaspersky Scan Engine will use the scanengine user to make changes to the database.

6. Choose the mode for Kaspersky Scan Engine.

   The following modes are available:

   • HTTP
   • ICAP
7. For the HTTP mode, specify the IP address and port or the UNIX socket that Kaspersky Scan Engine will listen on for incoming requests to scan objects.

   For the ICAP mode, specify the port whose traffic Kaspersky Scan Engine will scan.

8. Specify whether Kaspersky Scan Engine must use Kaspersky Security Network (KSN).
9. If you choose to use KSN, read the EULA for KSN and the Privacy Policy.

   If you agree with the terms of the EULA and the Privacy Policy, accept it. If you decline the terms of the EULA for KSN or the Privacy Policy, you will not be able to use KSN, but the installation will continue. You can enable KSN later by using Kaspersky Scan Engine GUI or the Kaspersky Scan Engine configuration file (HTTP or ICAP).

10. If you choose to use Kaspersky Scan Engine GUI, specify the port on which Kaspersky Scan Engine GUI will be available, if necessary.
11. Specify whether to use a proxy server.
12. If you choose to use a proxy server, specify the proxy settings.
13. Specify the directory for storing temporary files.

    The installation script will create the scanengine subdirectory in this directory; Kaspersky Scan Engine will use this subdirectory for storing temporary files.

14. Specify the licensing mode to be used in Kaspersky Scan Engine.
    • For simplified licensing mode, specify the key file.
    • For online licensing mode, specify the activation code.
15. At the prompt, check the settings you have specified and modify them if necessary.

After you specify necessary data, the install script installs Kaspersky Scan Engine and then starts it. Finally, the script prints the summary information about the installation to the command line.

[Topic 180652]

Manual installation (Linux)

This section describes how to manually install Kaspersky Scan Engine on Linux systems.

To install Kaspersky Scan Engine manually:

1. Make sure that you have root (administrator) privileges.
2. Create the /opt/kaspersky/ScanEngine directory. This directory is called %service_dir% in this Help document.
3. Unpack the distribution kit contents to the %service_dir% directory on your system.
4. Read the End User License Agreement (EULA) for Kaspersky Scan Engine. The EULA is located at %service_dir%/doc/license.txt.

   If you agree to the terms of the EULA, proceed to the next step. If you decline the terms of the EULA, cancel the installation.

5. Open file %service_dir%/etc/klScanEngineUI.xml.
6. Accept the EULA. Change <Common>rejected</Common> to <Common>accepted</Common> in the klScanEngineUI.xml file.
7. If you want to use Kaspersky Security Network (KSN), read the EULA for KSN and the Privacy Policy. This EULA is also located at %service_dir%/doc/ksn_license.txt and contains the link to the Privacy Policy.

   If you agree to the terms of the EULA for KSN and the Privacy Policy, proceed to the next step. If you decline the terms of the EULA for KSN or the Privacy Policy, proceed to step 9.

8. Accept the EULA for KSN. Change <KSN>rejected</KSN> to <KSN>accepted</KSN> in klScanEngineUI.xml.
9. Save and close %service_dir%/etc/klScanEngineUI.xml.
10. Create a symbolic link to %service_dir%/etc/klScanEngineUI.xml from the /etc/ directory:

    ln -s %service_dir%/etc/klScanEngineUI.xml /etc/klScanEngineUI.xml

11. If you want to use Kaspersky Scan Engine GUI, read subsection "Enabling Kaspersky Scan Engine GUI" below.
12. Make a symbolic link to the proper Kaspersky Scan Engine configuration file from the /etc/ directory:
    • For HTTP mode, copy the %service_dir%/etc/kavhttpd.xml file to the /etc/ directory.
    • For ICAP mode, copy the %service_dir%/etc/kavicapd.xml file to the /etc/ directory.

    For example, in HTTP mode you have to run the following command:

    ln -s %service_dir%/etc/kavhttpd.xml /etc/kavhttpd.xml

13. Make a symbolic link to the proper Kaspersky Scan Engine init script from the /etc/init.d dirctory:
    • For HTTP mode, copy the %service_dir%/etc/init.d/kavhttpd file to the /etc/init.d directory.
    • For ICAP mode, copy the %service_dir%/etc/init.d/kavicapd file to the /etc/init.d directory.

    For example, in HTTP mode you have to run the following command:

    ln -s %service_dir%/etc/init.d/kavhttpd /etc/init.d/kavhttpd

14. If you want Kaspersky Scan Engine to start automatically on system bootup, do the following:
    1. Go to the /etc/init.d/ directory.
    2. Add the proper Kaspersky Scan Engine service to the system startup.
       • For HTTP mode, run the following command:
         • Red Hat-based distributions:

         chkconfig --add kavhttpd

         • Debian-based distributions:

         update-rc.d kavhttpd defaults

       • For ICAP mode, run the following command:
         • Red Hat-based distributions:

         chkconfig --add kavicapd

         • Debian-based distributions:

         update-rc.d kavicapd defaults

15. Go to the next step of your "Getting started" section:
    • For HTTP mode, see step 2 in section "Getting started with Kaspersky Scan Engine in HTTP mode".
    • For ICAP mode, see step 2 in section "Getting started with Kaspersky Scan Engine in ICAP mode".

Enabling Kaspersky Scan Engine GUI

To enable Kaspersky Scan Engine GUI:

1. Make sure that you have root (administrator) privileges.
2. Perform the actions described in section "Preparing to install Kaspersky Scan Engine GUI".
3. On the computer that has PostgreSQL installed, perform the actions listed below under a user that can create new users and databases. To perform these actions, you can use either the psql utility or pgAdmin.
   1. Create a new PostgreSQL user called scanengine:

      CREATE USER scanengine;

   2. Set the password for the scanengine user:

      ALTER USER scanengine WITH PASSWORD '%PASSWORD%';

   3. Using PostgreSQL, create a database called kavebase:

      CREATE DATABASE kavebase OWNER scanengine;

   4. In the kavebase database run the queries described in %service_dir%/samples/tables.sql.

      psql -d kavebase -a -f tables.sql

4. Open /etc/klScanEngineUI.xml.
5. In the <Mode> element, specify the mode that Kaspersky Scan Engine will work in:

   For HTTP mode:

   <Mode>httpd</Mode>

   For ICAP mode:

   <Mode>icap</Mode>

6. Change <EnableUI>false</EnableUI> to <EnableUI>true</EnableUI>.
7. In the <ConnectionString> element, specify the address of the Kaspersky Scan Engine GUI web service in %IP%:%port% format.

   For example:

   <ConnectionString>198.51.100.0:443</ConnectionString>

8. Specify the SSL certificate to install in the Kaspersky Scan Engine GUI web service.
   • If you already have an SSL certificate that you want to install in the Kaspersky Scan Engine GUI web service, specify the paths to your certificate and your private key:
     1. In the <SSLCertificatePath> element, specify the path to your SSL certificate.
     2. In the <SSLPrivateKeyPath> element, specify the path to your private key.
   • If you do not have an SSL certificate that you want to install in the Kaspersky Scan Engine GUI web service, generate a new one. Run the %service_dir%/tools/openssl utility as follows:

   /opt/kaspersky/ScanEngine/tools/openssl req -x509 -nodes -days 1825 -subj /C=RU/CN="%СonnectionString%" -newkey rsa:2048 -extensions EXT -config "/opt/kaspersky/ScanEngine/tools/openssl.cnf" -keyout "/opt/kaspersky/ScanEngine/httpsrv/kl_scanengine_private.pem" -out "/opt/kaspersky/ScanEngine/httpsrv/kl_scanengine_cert.pem"

   Here %СonnectionString% is the value that is specified in the <ConnectionString> element.

9. Encrypt the user name and password of the user that you specified in step 3. Kaspersky Scan Engine will use this user name and password to connect to the kavebase database.

   To encrypt the credentials, use the kav_encrypt utility. This utility also automatically writes the encrypted user name and password to klScanEngineUI.xml. The utility is located in the %service_dir%/tools/ directory.

   Run the kav_encrypt utility with the following options:

   -d '%USERNAME%:%PASSWORD%'

10. In the DatabaseSettings > ConnectionString element, specify the address of the kavebase database in format %IP%:%port%.
11. Save and close /etc/klScanEngineUI.xml.
12. Make a symbolic link to %service_dir%/etc/init.d/klScanEngineUI from /etc/init.d:

    ln -s %service_dir%/etc/init.d/klScanEngineUI /etc/init.d/klScanEngineUI

13. If you want Kaspersky Scan Engine to start automatically on system bootup, do the following:
    1. Go to the /etc/init.d/ directory.
    2. Add the Kaspersky Scan Engine GUI service to the system startup. Run the following command:
       • Red Hat-based distributions:

         chkconfig --add klScanEngineUI

       • Debian-based distributions:

         update-rc.d klScanEngineUI defaults

14. Start Kaspersky Scan Engine GUI:

    /etc/init.d/klScanEngineUI start

Page top

[Topic 184732]

Installation using the installer (Windows)

This section explains how to install Kaspersky Scan Engine using the install.exe installer. You can use the install.exe installer if Kaspersky Scan Engine is not installed on your computer.

If you want to use Kaspersky Scan Engine together with Kaspersky Scan Engine GUI, you must have PostgreSQL installed on a computer that is accessible from the computer on which you install Kaspersky Scan Engine. Kaspersky Scan Engine GUI does not work without PostgreSQL.

To install Kaspersky Scan Engine using the installer:

1. Unpack the distribution kit contents to an empty folder on your system.
2. Make sure you have administrator privileges.
3. Run install.exe.
4. Read the End User License Agreement (EULA) for Kaspersky Scan Engine.

   If you agree with the terms of the EULA, accept it. If you decline to accept the terms of the EULA, the installation will be canceled.

5. Choose whether to use Kaspersky Scan Engine GUI.
6. If you choose to use Kaspersky Scan Engine GUI, do the following:
   1. Perform the actions described in section "Installing and configuring PostgreSQL (Windows)".
   2. Specify the IP and port for connecting to PostgreSQL.
   3. Provide credentials for a user that has permissions for creating new databases and users. The credentials are not recorded anywhere.

      With these credentials, Kaspersky Scan Engine will create a new database called kavebase in which Kaspersky Scan Engine will store its data, and a new PostgreSQL user called scanengine. From this moment on, Kaspersky Scan Engine will use the scanengine user to make changes to the database.

7. Specify the IP address and port that Kaspersky Scan Engine will listen on for incoming requests to scan objects.
8. Specify whether Kaspersky Scan Engine must use Kaspersky Security Network (KSN).
9. If you choose to use KSN, read the EULA for KSN and the Privacy Policy.

   If you agree with the terms of the EULA and the Privacy Policy, accept it. If you decline the terms of the EULA for KSN or the Privacy Policy, you will not be able to use KSN, but the installation will continue. You can enable KSN later by using Kaspersky Scan Engine GUI or the Kaspersky Scan Engine configuration file.

10. If you choose to use Kaspersky Scan Engine GUI, specify the port on which Kaspersky Scan Engine GUI will be available, if necessary.
11. Specify whether to use a proxy server.
12. If you choose to use a proxy server, specify the proxy settings.
13. Specify the directory for storing temporary files.

    The installer will create the scanengine subdirectory in this directory; Kaspersky Scan Engine will use this subdirectory for storing temporary files.

14. Specify the licensing mode to be used in Kaspersky Scan Engine.
    • For simplified licensing mode, specify the key file.
    • For online licensing mode, specify the activation code.
15. At the prompt, check the settings you have specified and modify them if necessary.

After you specify necessary data, install installs Kaspersky Scan Engine and then starts it. Kaspersky Scan Engine is installed to the %ProgramW6432%\Kaspersky Lab\ScanEngine folder.

Finally, the installer prints the summary information about the installation to the command line.

[Topic 184719]

Manual installation (Windows)

This section describes how to manually install Kaspersky Scan Engine on Windows systems.

To install Kaspersky Scan Engine manually:

1. Make sure that you have administrator privileges.
2. Create the %ProgramW6432%\Kaspersky Lab\ScanEngine folder. This folder is called %service_dir% in this Help document.
3. Unpack the distribution kit contents to the %service_dir% folder on your system.
4. Read the End User License Agreement (EULA) for Kaspersky Scan Engine. The EULA is located at %service_dir%\doc\license.txt.

   If you agree to the terms of the EULA, proceed to the next step. If you decline the terms of the EULA, cancel the installation.

5. Open file %service_dir%\bin\klScanEngineUI.xml.
6. Accept the EULA. Change <Common>rejected</Common> to <Common>accepted</Common> in the klScanEngineUI.xml file.
7. If you want to use Kaspersky Security Network (KSN), read the EULA for KSN and the Privacy Policy. This EULA is also located at %service_dir%\doc\ksn_license.txt and contains the link to the Privacy Policy.

   If you agree to the terms of the EULA for KSN and the Privacy Policy, proceed to the next step. If you decline the terms of the EULA for KSN or the Privacy Policy, proceed to step 9.

8. Accept the EULA for KSN. Change <KSN>rejected</KSN> to <KSN>accepted</KSN> in klScanEngineUI.xml.
9. Save and close %service_dir%\bin\klScanEngineUI.xml.
10. Open file %service_dir%\bin\kavhttpd.xml.
11. At the BasesPath and the TempPath element specify the full path to the %service_dir%\bin\bases directory and to the directory that contains temporary files used by Kaspersky Scan Engine, respectively. Save and close the file.
12. If you want Kaspersky Scan Engine to start automatically on system bootup, do the following:
    1. In Windows, open a Command Prompt window as Administrator.
    2. Run the following command:

    sc create "Kaspersky ScanEngine" binpath= "%service_dir%\bin\kavhttpd.exe -c %service_dir%\bin\kavhttpd.xml" start= auto DisplayName= "Kaspersky ScanEngine"

    Note that if the full path to the configuration file contains a space character, you have to add a quote mark (") after the slash (\) mark. Example: C:\Program Files\Kaspersky Lab\ScanEngine\bin>sc create "Kaspersky ScanEngine" binpath= "C:\Program Files\Kaspersky Lab\ScanEngine\bin\kavhttpd.exe -c \"C:\Program Files\Kaspersky Lab\ScanEngine\bin\kavhttpd.xml\""

13. Go to step 2 in section "Getting started with Kaspersky Scan Engine in HTTP mode".

Enabling Kaspersky Scan Engine GUI

To enable Kaspersky Scan Engine GUI:

1. Make sure that you have administrator privileges.
2. Perform the actions described in section "Installing and configuring PostgreSQL (Windows)".
3. On the computer that has PostgreSQL installed, perform the actions listed below under a user that can create new users and databases. To perform these actions, you can use either the psql utility, or pgAdmin. If you use the psql utility, specify a space character and a user name after the -U parameter.
   1. Create a new PostgreSQL user called scanengine:

      CREATE USER scanengine;

   2. Set the password for the scanengine user:

      ALTER USER scanengine WITH PASSWORD '%PASSWORD%';

   3. Using PostgreSQL, create a database called kavebase:

      CREATE DATABASE kavebase OWNER scanengine;

   4. In the kavebase database run the queries described in %service_dir%\samples\tables.sql.

      psql -d kavebase -a -f tables.sql

4. Open %service_dir%\bin\klScanEngineUI.xml.
5. Change <EnableUI>false</EnableUI> to <EnableUI>true</EnableUI>.
6. In the <ConnectionString> element, specify the address of the Kaspersky Scan Engine GUI web service in %IP%:%port% format.

   For example:

   <ConnectionString>198.51.100.0:443</ConnectionString>

7. Specify the SSL certificate to install in the Kaspersky Scan Engine GUI web service.
   • If you already have an SSL certificate that you want to install in the Kaspersky Scan Engine GUI web service, specify the paths to your certificate and your private key:
     1. In the <SSLCertificatePath> element, specify the path to your SSL certificate.
     2. In the <SSLPrivateKeyPath> element, specify the path to your private key.
   • If you do not have an SSL certificate that you want to install in the Kaspersky Scan Engine GUI web service, generate a new one. Run the %service_dir%\tools\openssl utility as follows:

   %service_dir%\tools\openssl.exe req -x509 -nodes -days 1825 -subj /C=RU/CN="%СonnectionString%" -newkey rsa:2048 -extensions EXT -config "%service_dir%\tools\openssl.cnf" -keyout "%service_dir%\httpsrv\kl_scanengine_private.pem" -out "%service_dir%\httpsrv\kl_scanengine_cert.pem"

   Here %СonnectionString% is the value that is specified in the <ConnectionString> element.

8. Encrypt the user name and password of the user that you specified in step 3. Kaspersky Scan Engine will use this user name and password to connect to the kavebase database.

   To encrypt the credentials, use the kav_encrypt utility. This utility also automatically writes the encrypted user name and password to klScanEngineUI.xml. The utility is located in the %service_dir%\tools\ folder.

   Run the kav_encrypt utility with the following options:

   -d %username%:%password%

9. In the DatabaseSettings > ConnectionString element, specify the address of the kavebase database in format %IP%:%port%.
10. Save and close %service_dir%\bin\klScanEngineUI.xml.
11. If you want Kaspersky Scan Engine GUI to start automatically on system bootup, do the following:
    1. Open a Command Prompt window as Administrator.
    2. Run the following command:

    sc create "Kaspersky ScanEngine UI" binpath= "%service_dir%\bin\klScanEngineUI.exe --svc" start= auto DisplayName= "Kaspersky ScanEngine UI"

12. Start Kaspersky Scan Engine GUI

    sc start "Kaspersky ScanEngine UI"

[Topic 179707]

Using Kaspersky Scan Engine in HTTP mode

This chapter contains information about using Kaspersky Scan Engine in HTTP mode.

[Topic 179864]

Kaspersky Scan Engine and HTTP mode

Hypertext Transfer Protocol (HTTP) is the standard communication protocol in the client-server computer model. In HTTP mode, Kaspersky Scan Engine operates as a REST-like service that receives HTTP requests in JSON or plain text format from client applications. The service scans objects passed in these requests, and sends back HTTP responses with scan results in JSON or plain text format.

In additional, a sample HTTP client source code is shipped in the distribution package. This sample HTTP client demonstrates how to make requests to Kaspersky Scan Engine in HTTP mode. You can also use the compiled sample to scan files from the command line.

Connection types

Kaspersky Scan Engine supports two connection types:

• TCP connection
• UNIX socket connection

  For Linux systems only.

Scanning capabilities

Kaspersky Scan Engine supports the following scan modes:

• scanfile

  In this mode, the sample HTTP client passes file paths to Kaspersky Scan Engine, which reads the files and scans them.

• scanmemory

  In this mode, the sample HTTP client passes file contents to Kaspersky Scan Engine, which scans the contents.

• checkurl

  In this mode, the sample HTTP client passes URLs to Kaspersky Scan Engine, which checks them for malicious and phishing addresses.

For more information, see section "Making requests in HTTP mode".

[Topic 179866]

Configuring Kaspersky Scan Engine in HTTP mode

This section explains how to manually configure Kaspersky Scan Engine for use in HTTP mode without using Kaspersky Scan Engine GUI.

[Topic 179867]

HTTP mode configuration file

The HTTP mode configuration file (hereinafter, also configuration file) is an XML file that specifies general settings for Kaspersky Scan Engine.

HTTP mode configuration file (Linux)

The Kaspersky Scan Engine distribution kit for LInux contains a %distr_kit%/etc/kavhttpd.xml configuration file.

After installing Kaspersky Scan Engine, you can copy kavhttpd.xml to your preferred location:

• If you copy kavhttpd.xml to the /etc/ directory, Kaspersky Scan Engine automatically finds and parses this file.
• If you copy kavhttpd.xml to a different location, you must set the path to this location when you start Kaspersky Scan Engine:
  • If you want to use the init script to start Kaspersky Scan Engine, see section "Running Kaspersky Scan Engine in HTTP mode with init script"
  • If you want to use the systemd unit file to start Kaspersky Scan Engine, see section "Running Kaspersky Scan Engine in HTTP mode with systemd unit file"
  • If you want to start Kaspersky Scan Engine from the command line manually, see section "Running Kaspersky Scan Engine in HTTP mode manually"

HTTP mode configuration file (Windows)

The Kaspersky Scan Engine distribution kit for Windows contains a %distr_kit%\bin\kavhttpd.xml configuration file.

Parameters of the HTTP mode configuration file

Most elements of the configuration file have default values that are used when the element is absent. Elements that are present in the configuration file must not be empty, unless stated otherwise.

ServerSettings

The following parameters specify Kaspersky Scan Engine settings:

• MaxIncomingConnectionsNum—Specifies the maximum number of pending TCP connections to Kaspersky Scan Engine in HTTP mode. Extra connections may be dropped. This value must be an unsigned integer and cannot be 0.

  The default value is 100. For more information about MaxIncomingConnectionsNum, see section "Setting up the connection queue in HTTP mode".

• MaxHTTPSessionsNum—Specifies the maximum number of active TCP connections that Kaspersky Scan Engine can maintain simultaneously. This value must be an unsigned integer.

  The default value is 10. If you set MaxHTTPSessionsNum to 0, the default value is used. For more information about MaxHTTPSessionsNum, see section "Setting up the connection queue in HTTP mode".

• MaxTCPFileSize—Specifies the maximum allowed size (in bytes) of the headers and bodies of the HTTP messages that are passed to Kaspersky Scan Engine. This value must be an unsigned integer.

  It is recommended to specify at least 100 KB for the headers.

  The default value is 104857600 (100 MB). If you set MaxTCPFileSize to 0, the default value is used.

• ConnectionString—Specifies the IP address and the port for Kaspersky Scan Engine, or a path to the UNIX socket used by Kaspersky Scan Engine. This is a string value.

  ConnectionString—Mandatory parameter. The default value is /tmp/.kavhttpd in Linux and 127.0.0.1:9999 in Windows. You can specify an IP address and a port for a TCP connection in the following format: ip_addr:port.

• SessionTimeout—Specifies the timeout for processing the request and sending the response, in milliseconds (ms). This value must be an unsigned integer.

  The default value is 1000. If you set SessionTimeout to 0, the default value is used. For more information on setting the session timeout, see section "Setting the session timeout".

• Flags—Specifies the initialization options for Kaspersky Scan Engine. Initialization options are defined by a combination of flags separated by pipes (|).

  This is a string value.

  Possible values:

  • KAV_SHT_ENGINE_KLAV

    Enable KLAV anti-virus engine.

    If you set this flag, you do not have to specify the KAV_SHT_ENGINE_KLAVEMU flag. Enabling the KLAV Engine automatically turns on the KLAV emulator.

  • KAV_SHT_ENGINE_KLAVEMU

    Enable the advanced heuristic anti-virus engine (KLAV emulator). Add this flag if you want to use heuristics.

  • KAV_SHT_ENGINE_WMUF

    Enable detection of malicious websites.

  • KAV_SHT_ENGINE_APUF

    Use phishing protection.

  • KAV_SHT_ENGINE_KSN

    Use KSN to check the reputation of files and URLs.

    Before specifying the KAV_SHT_ENGINE_KSN flag, make sure that your key file allows you to use this functionality and that you accepted the terms of the EULA for KSN.

    Notice to users in the U.S.

    Updates functionality (including providing anti-virus signature updates and codebase updates), as well as KSN functionality will not be available in the software in the U.S. territory from 12:00 AM Eastern Daylight Time (EDT) on September 10, 2024 in accordance with the restrictive measures.

  • KAV_SHT_ENGINE_STATISTIC_MAIL

    Submit statistical information to KSN in Linux.

    Before specifying the KAV_SHT_ENGINE_STATISTIC_MAIL flag, make sure that your key file allows you to use this functionality.

  • KAV_SHT_ENGINE_STATISTIC

    Submit statistical information to KSN in Windows.

    Before specifying the KAV_SHT_ENGINE_STATISTIC flag, make sure that your key file allows you to use this functionality.

  Notice that by enabling the KAV_SHT_ENGINE_KSN, KAV_SHT_ENGINE_STATISTIC_MAIL, or KAV_SHT_ENGINE_STATISTIC flags, you agree to transfer data, described in the corresponding About data provision*.txt file to Kaspersky Lab. For more information about the procedure of data provisioning, see section "About data provisioning". For information about statistics that can be submitted to KSN, see section "Statistics submitted to KSN".

KSNSettings

The following parameters specify KSN settings:

• UrlCheckTimeoutMs—Specifies the maximum time that Kaspersky Scan Engine waits for a response from KSN when running reputation checks for URLs (in milliseconds). This value must be an unsigned integer and cannot be 0.

  The default value is 20000.

  Notice that this parameter only sets the timeout for reputation checks in KSN. This timeout does not include the time required for sending a scan request and receiving a reputation status from KSN.
  This timeout can be exceeded if KSN finds that the reputation status of the scanned file is Danger.

• ObjectCheckOnDemandTimeoutMs—Specifies the timeout for a response from KSN when running reputation checks for files (in milliseconds). This value must be an unsigned integer and cannot be 0.

  The default value is 10000.

  Notice that this parameter only sets the timeout for reputation checks in KSN. This timeout does not include time required for sending a scan request and receiving a reputation status from KSN.
  This timeout can be exceeded if KSN finds that the reputation status of the scanned file is Danger.

• CacheSizeKb—Specifies the maximum size of the KSN status cache (in kilobytes). This cache is used by Kaspersky Scan Engine to store scan results obtained from KSN.

  This value must be an unsigned integer. If the value of this parameter is 0, the KSN status cache is not used. The maximum value is 262143. The default value is 30720.

Notice to users in the U.S.

KAVScanningSettings

The following parameters specify scanning settings for KAV SDK, which is a part of Kaspersky Scan Engine:

• ScannersCount—Specifies the number of scanning processes. You can have up to 256 scanning processes. This value must be an unsigned integer and cannot be 0.

  The default value is 16.

• ThreadsCount—Specifies the maximum number of simultaneously running scanning threads. You can have up to 256 scanning threads. This value must be an unsigned integer and cannot be 0.

  The default value is is 16.

• QueueLen—Specifies the maximum length of the queue for scan tasks. This value must be an unsigned integer and cannot be 0.

  The default value is 1024.

• Flags—Specifies a scanning mode.

  A scanning mode is defined by a combination of flags separated by pipes (|). This is a string value.

  Possible values:

  • KAV_O_M_PACKED

    Scan compressed executable files.

  • KAV_O_M_ARCHIVED

    Scan archived files.

  • KAV_O_M_MAILBASES

    Scan email database files.

  • KAV_O_M_MAILPLAIN

    Scan email messages.

  • KAV_O_M_HEURISTIC_LEVEL_SHALLOW

Set the scanning level of the advanced heuristic code analyzer to shallow (the Low level in the graphical user interface).

• KAV_O_M_HEURISTIC_LEVEL_MEDIUM

  Set the scanning level of the advanced heuristic code analyzer to medium (the Medium level in the graphical user interface).

• KAV_O_M_HEURISTIC_LEVEL_DETAIL

  Set the scanning level of the advanced heuristic code analyzer to detailed (the High level in the graphical user interface).

• KAV_O_M_MSOFFICE_MACRO

  Notify the user if a Microsoft Office document file contains a macro.

This element can be empty. In this case, the value of 0 is used.

The default value is KAV_O_M_PACKED | KAV_O_M_ARCHIVED | KAV_O_M_MAILBASES | KAV_O_M_MAILPLAIN | KAV_O_M_HEURISTIC_LEVEL_DETAIL.

• Mode—Specifies a cleaning mode.

  This is a string value. This is a mandatory parameter.

  Possible values:

  • KAV_SKIP

    If malware is detected while scanning an object, Kaspersky Scan Engine will not try to disinfect or delete the object. The infected object will be skipped.

    Specify this value if you want to use scanmemory mode.

  • KAV_DELETE

    If malware is detected while scanning an object, Kaspersky Scan Engine will try to delete the object. If deletion is not possible, the infected object will be skipped.

  • KAV_CLEAN_DELETE

    If malware is detected while scanning an object, Kaspersky Scan Engine will try to disinfect the object. If the disinfection attempt fails, or disinfection is not possible for specific malware, the object will be deleted. If deletion is not possible, the infected object will be skipped.

  • KAV_CLEAN_SKIP

    If malware is detected while scanning an object, Kaspersky Scan Engine will try to disinfect the object. If the disinfection attempt fails, the infected object will be skipped.

  The default value is KAV_SKIP.

DirectorySettings

The following parameters specify directory settings for KAV SDK, which is a part of Kaspersky Scan Engine:

• BasesPath—Specifies a directory where the database is located. This is a string value.

  This is a mandatory parameter.

  Notice that in Windows systems you have to specify a full path to the directory where the database is located.

• TempPath—Specifies a directory where the files created at runtime are stored. The path must be absolute. This is a string value.

  This is a mandatory parameter.

  Do not delete any files from this directory.

• LicensePath—Specifies a directory where the application ID file, the licensing file, and the key file are stored. This is a string value.

  KAV SDK looks for these files in the following directories:

  • The directory that is specified in LicensePath.
  • The directory that contains the kavhttpd executable file.
  • The %service_dir%/ppl directory. For Linux systems only.

  This is a mandatory parameter.

• LicensingMode—Specifies the licensing mode used in Kaspersky Scan Engine.

  Possible values:

  • 1—Offline licensing mode
  • 2—Online licensing mode

  The default value is 1.

• ScanningPaths—Contains paths to the locations where scanning over TCP socket is allowed when a HTTP client sends scan requests from a remote computer. Specify these locations to prevent a remote HTTP client from accidentally scanning the whole filesystem on the computer where Kaspersky Scan Engine is installed.
  • ScanningPath—Specifies a location where scanning over TCP socket in scanfile mode is allowed.

    Possible values:

    • Absolute paths to a directory

      Allow to scan files that are located inside this directory and all its subdirectories.

      The directory must be located on the same computer as Kaspersky Scan Engine or on a remote hard disk mounted on that computer.

      The path must start from the root directory of the computer that Kaspersky Scan Engine is installed on.

      The kavhttpd service must have permissions to read files in the directory and its subdirectories.

    • Absolute path to a file

      Allow to scan the specified file.

      The file must be located on the same computer as Kaspersky Scan Engine or on a remote hard disk mounted on that computer.

      The path must start from the root directory of the computer that Kaspersky Scan Engine is installed on.

      The kavhttpd service must have permissions to read the file.

    • / (forward slash)

      Allow to scan all files.

      For Linux systems only.

  Each path is specified inside its own <ScanningPath> element.

UseHTTPProxy and HTTPProxy

The following parameters specify proxy server settings for KAV SDK, which is a part of Kaspersky Scan Engine. In the current version of KAV SDK, only the HTTP proxy type is supported.

• UseHTTPProxy—Specifies whether Kaspersky Scan Engine uses a proxy server when connecting to the Internet. This value can be set to 0 or 1.

  The default value is 0 (proxy server is not used). To enable using a proxy server, set this value to 1.

• HTTPProxy—Contains proxy settings.
  • url—Address of the proxy server. This is a string value.

    The value of this parameter can be an IPv4 address, an IPv6 address, or a domain name. Do not specify the protocol (http:// or https://) in this parameter.

    If UseHTTPProxy is set to 1, this parameter is mandatory.

  • port—Port of the proxy server. This value must be an unsigned integer and cannot be 0.

    The default value is 3128.

  • user—Encrypted user name for the proxy server authentication. The user name is encrypted by the kav_encrypt utility. This is a string value.

    If UseHTTPProxy is set to 1, this parameter is mandatory.

  • pass—Encrypted password for the proxy server authentication. The password is encrypted by the kav_encrypt utility. This is a string value.

    If UseHTTPProxy is set to 1, this parameter is mandatory.

UpdateSettings

The following parameters specify update settings for Kaspersky Scan Engine. For more information, see section "Configuring updating in HTTP mode".

• DisableBackup—Defines whether the database backup is disabled. This value can be set to 0 or 1.

  If this parameter is 1, database backup is disabled.

  The default value is 0.

• UpdatePeriodMinutes—Specifies automatic update interval (in minutes). This value must be an unsigned integer.

  The maximum value is 44640.

  If this parameter is 0, Kaspersky Scan Engine does not perform automatic updates.

  The default value is 0.

• UseOnlyCustomSources—Specify whether the default update sources are used. This value can be set to 0 or 1.

  If this parameter is 1, only the custom update sources are used.

  The default value is 0.

• UpdateSources—Contains custom update sources.
  • Source—Specifies a custom update source. This is a string value.

  Each update source is specified inside its own <Source> element. For an example of this, see section "Configuring updating in HTTP mode", subsection "Specifying custom database update sources".

FormatRecognizerSettings

The following parameters specify Format Recognizer settings.

• FormatsToSkipScanning—Specifies which file formats must not be scanned by Kaspersky Scan Engine in HTTP mode.

  To disable the format skipping functionality, remove the FormatRecognizerSettings section from the configuration file or leave the FormatsToSkipScanning list empty.

Structure of the configuration file

Following is an example of the HTTP mode configuration file.

Page top

[Topic 179868]

Configuring Format Recognizer

Format Recognizer is a component that can be used in Kaspersky Scan Engine to recognize and skip files of certain formats during the scanning process. Skipping files increases the processing speed of Kaspersky Scan Engine in HTTP mode.

Enabling Format Recognizer

To enable Format Recognizer:

1. In the HTTP mode configuration file, locate the FormatRecognizerSettings section.

   If this section is missing, add it manually as follows:

   <FormatRecognizerSettings> ... </FormatRecognizerSettings>

2. Within this section, in the FormatsToSkipScanning list, specify which file formats must not be scanned by Kaspersky Scan Engine, as follows:

   <FormatRecognizerSettings> <FormatsToSkipScanning> <KAV_FF_GENERAL_TXT/> ... <KAV_FF_AUDIO_WMA/> </FormatsToSkipScanning> </FormatRecognizerSettings>

3. For the changes to take effect, restart the kavhttpd service with the following command:
   • On Linux:

     /etc/init.d/kavhttpd restart

   • On Windows:

     net stop "Kaspersky ScanEngine"

     net start "Kaspersky ScanEngine"

Format Recognizer will start recognizing and skipping files of the formats specified in the FormatsToSkipScanning list. Kaspersky Scan Engine will not scan the skipped files, which will increase its processing speed.

Disabling Format Recognizer

To disable Format Recognizer:

1. In the HTTP mode configuration file, remove the FormatRecognizerSettings section or leave the FormatsToSkipScanning list empty.
2. For the changes to take effect, restart the kavhttpd service with the following command:
   • On Linux:

     /etc/init.d/kavhttpd restart

   • On Windows:

     net stop "Kaspersky ScanEngine"

     net start "Kaspersky ScanEngine"

Page top

[Topic 180222]

Recognizable file formats

This group of constants defines file formats that can be recognized by Format Recognizer.

Text formats

• KAV_FF_GENERAL_TXT
• KAV_FF_GENERAL_CSV
• KAV_FF_GENERAL_HTML
• KAV_FF_GENERAL_HTML_STRICT

Multimedia formats

• KAV_FF_VIDEO_FLV
• KAV_FF_VIDEO_F4V
• KAV_FF_VIDEO_AVI
• KAV_FF_VIDEO_3GPP
• KAV_FF_VIDEO_DIVX
• KAV_FF_VIDEO_MKV
• KAV_FF_VIDEO_MOV
• KAV_FF_VIDEO_ASF
• KAV_FF_VIDEO_RM
• KAV_FF_VIDEO_VOB
• KAV_FF_VIDEO_BIK
• KAV_FF_VIDEO_RTMP
• KAV_FF_AUDIO_MP3
• KAV_FF_AUDIO_FLAC
• KAV_FF_AUDIO_APE
• KAV_FF_AUDIO_OGG
• KAV_FF_AUDIO_AAC
• KAV_FF_AUDIO_WMA
• KAV_FF_AUDIO_AC3
• KAV_FF_AUDIO_WAV
• KAV_FF_AUDIO_MKA
• KAV_FF_AUDIO_RA
• KAV_FF_AUDIO_MIDI
• KAV_FF_AUDIO_CDA
• KAV_FF_IMAGE_JPEG
• KAV_FF_IMAGE_GIF
• KAV_FF_IMAGE_PNG
• KAV_FF_IMAGE_BMP
• KAV_FF_IMAGE_TIFF
• KAV_FF_IMAGE_EMF
• KAV_FF_IMAGE_EPS
• KAV_FF_IMAGE_PSD
• KAV_FF_IMAGE_CDR
• KAV_FF_MULTIMEDIA_SWF

Executable formats

Office suite formats

• KAV_FF_OFFICE_OPENXML
• KAV_FF_OFFICE_MSOFFICE_MACRO
• KAV_FF_OFFICE_MSOFFICE
• KAV_FF_OFFICE_RTF
• KAV_FF_OFFICE_PDF
• KAV_FF_OFFICE_MSG
• KAV_FF_OFFICE_EML
• KAV_FF_OFFICE_VSD
• KAV_FF_OFFICE_VDX
• KAV_FF_OFFICE_XPS
• KAV_FF_OFFICE_ONE
• KAV_FF_OFFICE_ONEPKG
• KAV_FF_OFFICE_XSN
• KAV_FF_OFFICE_ODT
• KAV_FF_OFFICE_ODS
• KAV_FF_OFFICE_ODP
• KAV_FF_OFFICE_SXW
• KAV_FF_MSOFFICE_DOC
• KAV_FF_MSOFFICE_DOT
• KAV_FF_MSOFFICE_DOCX
• KAV_FF_MSOFFICE_DOTX
• KAV_FF_MSOFFICE_DOCM
• KAV_FF_MSOFFICE_DOTM
• KAV_FF_MSOFFICE_XLS
• KAV_FF_MSOFFICE_XLSX
• KAV_FF_MSOFFICE_XLTX
• KAV_FF_MSOFFICE_XLSM
• KAV_FF_MSOFFICE_XLTM
• KAV_FF_MSOFFICE_XLAM
• KAV_FF_MSOFFICE_XLSB
• KAV_FF_MSOFFICE_PPT
• KAV_FF_MSOFFICE_PPTX
• KAV_FF_MSOFFICE_POTX
• KAV_FF_MSOFFICE_PPTM
• KAV_FF_MSOFFICE_POTM
• KAV_FF_MSOFFICE_PPSX
• KAV_FF_MSOFFICE_PPSM
• KAV_FF_MSOFFICE_PUB
• KAV_FF_MSOFFICE_SCRAP

Database files

• KAV_FF_DATABASE_MDB
• KAV_FF_DATABASE_ACCDB
• KAV_FF_DATABASE_ACCDC

Archive files

• KAV_FF_ARCHIVE_ZIP
• KAV_FF_ARCHIVE_7Z
• KAV_FF_ARCHIVE_RAR
• KAV_FF_ARCHIVE_ISO
• KAV_FF_ARCHIVE_CAB
• KAV_FF_ARCHIVE_JAR
• KAV_FF_ARCHIVE_BZIP2
• KAV_FF_ARCHIVE_GZIP
• AV_FF_ARCHIVE_ARJ
• KAV_FF_ARCHIVE_DMG
• KAV_FF_ARCHIVE_XAR
• KAV_FF_ARCHIVE_TAR
• KAV_FF_ARCHIVE_ACE

Web archive files

• KAV_FF_TEXT_CHM
• KAV_FF_TEXT_MHT
• KAV_FF_TEXT_REG

Miscellaneous

• KAV_FF_CRYPTO_CAT

[Topic 179869]

Setting up the connection queue in HTTP mode

The connection queue contains pending connections to Kaspersky Scan Engine. By configuring the connection queue, you can influence the performance of Kaspersky Scan Engine in HTTP mode. This section explains how to configure the connection queue.

Three parameters allow you to configure the connection queue: MaxHTTPSessionsNum, MaxIncomingConnectionsNum, and ThreadsCount. These parameters can be set in the HTTP mode configuration file.

MaxHTTPSessionsNum

This parameter specifies the maximum number of active TCP connections that Kaspersky Scan Engine can maintain simultaneously. When a TCP connection with a client closes, Kaspersky Scan Engine can accept another connection in its place.

MaxIncomingConnectionsNum

This parameter specifies the maximum number of pending TCP connections to Kaspersky Scan Engine. If the number of pending connections reaches MaxIncomingConnectionsNum, additional connections may be dropped.

ThreadsCount

This parameter specifies the maximum number of simultaneously running scan threads. When a scan thread completes a scanning task, it picks up another one from the scan queue.

Examples of the connection queue configuration

These examples show how you can use the connection queue to influence the behavior of Kaspersky Scan Engine.

• Kaspersky Scan Engine without a connection queue

  Consider the following example: the value of MaxIncomingConnectionsNum is 16, the value of ThreadsCount is 16, and the value of MaxHTTPSessionsNum is 50. In this example, Kaspersky Scan Engine can accept only 16 connections at a time, but because MaxHTTPSessionsNum is 50, their scan tasks are accepted immediately. Additional connections may be dropped. Sixteen scan threads is usually enough to process scan tasks from 16 clients quickly, so the scan queue will be short.

• Kaspersky Scan Engine with a connection queue

  Consider the following example: the value of MaxIncomingConnectionsNum is 100, the value of ThreadsCount is 16, and the value of MaxHTTPSessionsNum is 50. In this example, Kaspersky Scan Engine can accept 50 connections at a time. Kaspersky Scan Engine starts processing scan tasks from some of these clients in 16 scan threads, and the rest of the scan tasks form the scan queue. Other pending connections form the connection queue and wait to be accepted. Additional connections may be dropped.

[Topic 179870]

Setting the session timeout

There are two parameters that affect the session timeout: the SessionTimeout parameter of the HTTP mode configuration file and the X-KAV-Timeout request header. This section explains how to configure the session timeout for Kaspersky Scan Engine in HTTP mode by using these two values.

SessionTimeout

This parameter of the configuration file sets the maximum time that Kaspersky Scan Engine can spend on receiving a scan request for an object and on processing this request (scanning operation), in milliseconds. This timeout is valid for all objects sent to Kaspersky Scan Engine.

Consider the following example: the value of SessionTimeout is set to 4000 (four seconds), and the request does not contain the X-KAV-Timeout header. Kaspersky Scan Engine spends one second on receiving the request. Then Kaspersky Scan Engine spends the remaining three seconds on scanning.

X-KAV-Timeout

This header sets the time that Kaspersky Scan Engine can spend on a scanning operation (in milliseconds), regardless of the value of the SessionTimeout parameter.

The range of values for this parameter is from 0 to 4294967295 (an unsigned 32-bit integer).

Consider the following example: the value of SessionTimeout is set to 4000 (four seconds), and the value of X-KAV-Timeout is set to 10000 (10 seconds). Kaspersky Scan Engine spends one second on receiving the request. Then Kaspersky Scan Engine spends 10 seconds (which is the value of X-KAV-Timeout) on scanning.

If SessionTimeout is exceeded during the reception of the request, the session is closed, regardless of the value of X-KAV-Timeout.

Consider the following example: the value of SessionTimeout is set to 4000 (four seconds), and the value of X-KAV-Timeout is set to 10000 (10 seconds). Kaspersky Scan Engine spends four seconds on receiving the request, and the session is closed because SessionTimeout is exceeded.

You can choose the value of X-KAV-Timeout on the basis of the size of the files that you want to scan. For example, Kaspersky Scan Engine could require 10 seconds to scan a large file, or 0.1 seconds to scan a small one.

Page top

[Topic 179871]

Changing variables in the HTTP mode init script (Linux)

For Linux systems only.

You can configure Kaspersky Scan Engine by changing one or more variables in the init script located at /etc/init.d/kavhttpd.

• SDKPATH—Specifies the directory where Kaspersky Scan Engine is located. The default value is /opt/kaspersky/ScanEngine.
• CONFILE—Specifies the name and the location of the HTTP mode configuration file. The default value is /etc/kavhttpd.xml.
• PIDFILE—Specifies the name and the location of the PID file. The default value is /var/run/kavhttpd.pid.

  The script adds a -p option to the command line when launching the Kaspersky Scan Engine binary file.

• PROGNAME—Specifies the name of the Kaspersky Scan Engine binary file. The default value is kavhttpd.
• USE_WATCHDOG—Specifies whether monitoring is enabled or disabled. The default value is 0 (monitoring is disabled). To enable monitoring, specify 1.

  For more information about monitoring, see section "Monitoring Kaspersky Scan Engine in HTTP mode".

Page top

[Topic 179872]

Changing variables in the HTTP mode unit file (Linux)

For Linux systems only.

You can configure Kaspersky Scan Engine by changing one or more variables in its unit file, %distr_kit%/etc/kavhttpd.service.

Changing the path to the Kaspersky Scan Engine PID file

You can change this variable if you want to create a PID file of Kaspersky Scan Engine in a directory other than /var/run/kavhttpd.pid.

The following example shows how this variable is set in the unit file:

Changing environment variables

You must change these environment variables if Kaspersky Scan Engine is located in a directory other than /opt/kaspersky/ScanEngine.

The unit file uses the following environment variables:

• SDKPATH—Specifies the directory where Kaspersky Scan Engine is located. The following example shows how this variable is set in the unit file:

  Environment=SDKPATH=/opt/kaspersky/ScanEngine

• KL_PLUGINS_PATH—Specifies the path to the directory containing the PPL plugin files used by Kaspersky Scan Engine. The following example shows how this variable is set in the unit file:

  Environment=KL_PLUGINS_PATH=/ppl

• LD_LIBRARY_PATH—Specifies the path to the directory containing shared libraries used by Kaspersky Scan Engine. The following block shows how this variable is set in the unit file:

  Environment=LD_LIBRARY_PATH=/lib:/ppl

Changing paths in the command executed on kavhttpd startup

You must change paths in the command executed on kavhttpd startup if you put the kavhttpd executable file or the HTTP mode configuration file in directories different from the ones specified in the unit file, or if you want to create a PID file of Kaspersky Scan Engine in a directory other from /var/run/kavhttpd.pid.

The following example shows how this command is set in the unit file:

Page top

[Topic 179873]

Configuring updating in HTTP mode

This section explains how to configure updating in Kaspersky Scan Engine.

Specifying the update settings

Kaspersky Scan Engine uses update settings stored in the HTTP mode configuration file. Set the necessary update settings in kavhttpd.xml before starting Kaspersky Scan Engine. For descriptions of all configuration file elements, see section "HTTP mode configuration file".

Specifying custom database update sources

Kaspersky Scan Engine updates the anti-virus database from database update sources. A database update source used by Kaspersky Scan Engine can be either default or custom. The default update sources are Kaspersky Lab update servers.

You can use the default update sources, custom update sources, or both.

To specify custom update sources:

1. Specify custom update sources in the UpdateSources element of the kavhttpd.xml configuration file. Use a separate Source element for each source.

   To use a local directory, specify an absolute path. To use a network location, specify a URL, including the protocol. The supported protocols are HTTP and FTP.

   The following example shows two update sources:

   <UpdateSources> <Source>http://example1.com/updates/</Source> <Source>http://example2.com/updates/</Source> </UpdateSources>

2. If you want to use only custom sources, set the UseOnlyCustomSources parameter of kavhttpd.xml to 1.

   If UseOnlyCustomSources is 0, Kaspersky Scan Engine uses default sources together with custom sources. In this case, Kaspersky Scan Engine first looks for updates in custom update sources.

The settings that you specified will be used after the kavhttpd service is started or restarted.

Configuring database backup

Database backup is a mechanism that protects Kaspersky Scan Engine from possible faults caused by the database update process.

By default, database backup is enabled. Kaspersky Scan Engine creates database backup copies automatically during updates. Make sure that your hard disk has enough free space for a full copy of the database.

To disable database backup,

Set the DisableBackup parameter in kavhttpd.xml to 1.

The setting that you specified will be used after the kavhttpd service is started or restarted.

Establishing connections to update sources

Kaspersky Scan Engine uses the connection settings defined in kavhttpd.xml to connect to update sources. For more information about how to configure connection settings, see section "HTTP mode configuration file".

Scheduling automatic database updates

If you want to update the database at regular intervals, use automatic updates.

By default, automatic updates are disabled.

To set up automatic updates:

1. Set the UpdatePeriodMinutes parameter in kavhttpd.xml to the required update interval (in minutes).
2. Restart the kavhttpd service.

Kaspersky Scan Engine will perform updates automatically.

For information on how to manually update the database, see section "Updating the anti-virus database in HTTP mode".

[Topic 179874]

Running Kaspersky Scan Engine in HTTP mode

This section explains how to run Kaspersky Scan Engine in HTTP mode.

[Topic 179876]

Running Kaspersky Scan Engine in HTTP mode manually

You can run the kavhttpd service by manually executing the kavhttpd binary file.

The following options are available when the kavhttpd service is run manually:

Options for running the kavhttpd binary file

Page top

[Topic 179877]

Running Kaspersky Scan Engine in HTTP mode with init script (Linux)

For Linux systems only.

The init script is located at %distr_kit%/etc/init.d/kavhttpd. You can run it from the command line to manage Kaspersky Scan Engine.

Starting Kaspersky Scan Engine automatically

To start Kaspersky Scan Engine automatically, add kavhttpd to the service startup list.

To add kavhttpd to the service startup list:

1. If you use Security-Enhanced Linux (SELinux) in enforcing mode, change the mode before proceeding:
   1. Open /etc/selinux/config for editing.
   2. Locate the line that contains the SELINUX variable:

      SELINUX=enforcing

   3. Set the value of the SELINUX variable to permissive or disabled:

      SELINUX=permissive

   4. Save and close the /etc/selinux/config configuration file.
2. Copy the HTTP mode init script to the directory that contains init scripts. The location of this directory may vary depending on the operating system, but usually it is /etc/init.d.
3. If necessary, edit the init script.
4. Add the kavhttpd service to the service startup list. The exact method may vary depending on the operating system.
5. Verify that kavhttpd has been added successfully.
6. Restart the system for the configuration to take effect.

Starting Kaspersky Scan Engine

To start Kaspersky Scan Engine, run the init script with the start parameter, as follows:

After Kaspersky Scan Engine is started, it listens for incoming requests from client applications.

Stopping Kaspersky Scan Engine

To stop Kaspersky Scan Engine, run the init script with the stop parameter:

Restarting Kaspersky Scan Engine

To restart Kaspersky Scan Engine, run the init script with the restart parameter:

Reloading the anti-virus database used by Kaspersky Scan Engine

To reload the anti-virus database used by Kaspersky Scan Engine, run the init script with the reloaddb parameter.

Updating the anti-virus database used by Kaspersky Scan Engine

To update the anti-virus database used by Kaspersky Scan Engine, run the init script with the updatedb parameter.

Getting the Kaspersky Scan Engine status

To get the status of Kaspersky Scan Engine, run the init script with the status parameter.

Page top

[Topic 179878]

Running Kaspersky Scan Engine in HTTP mode with systemd unit file (Linux)

For Linux systems only.

You can run the Kaspersky Scan Engine by using the kavhttpd service unit file for systemd. The unit file allows you to add the kavhttpd service to the service startup list and to manage the service manually from the command line.

This section assumes that you want to add the kavhttpd service for all users. For information on how to add and manage a service under a specific user, please see the official documentation for systemd and systemctl.

Starting Kaspersky Scan Engine automatically

To start Kaspersky Scan Engine automatically, add kavhttpd to the service startup list.

To add kavhttpd to the service startup list:

1. Place the kavhttpd unit file in the /etc/systemd/system/ directory.
2. If necessary, edit the unit file.
3. Reload systemd by running the following command:

   systemctl daemon-reload

4. Make sure that the kavhttpd unit file is installed by running the following command:

   systemctl list-unit-files

5. Enable kavhttpd to launch when the system starts by running the following command:

   systemctl enable kavhttpd.service

Remove Kaspersky Scan Engine from the service startup list

To remove kavhttpd from the service startup list, run the following command:

Managing Kaspersky Scan Engine with systemd from the terminal

To start kavhttpd without rebooting the computer, run the following command:

After this command is executed, the script prints the [OK] message and immediately returns control to the terminal, but it will take the kavhttpd service some time to start.

To stop kavhttpd without rebooting the computer, run the following command:

To reload the anti-virus database, run the following command:

Page top

[Topic 184964]

Running Kaspersky Scan Engine in HTTP mode as service (Windows)

If you registered the kavehttpd as a Windows service, you can start it from the command line by using the following commands:

• If you installed Kaspersky Scan Engine by using the installer or registered kavehttpd as a service manually:

  net start "Kaspersky ScanEngine"

• If you registered kavehttpd by using the kavehttpd binary file:

  net start kavhttpd

Page top

[Topic 186032]

Running Kaspersky Scan Engine in HTTP mode with a BAT script (Windows)

Kaspersky Scan Engine dIstribution kit includes a BAT script that allows you to manage the kavhttpd service and the klScanEngineUI service.

This script will not work if you manually added the kavhttpd service to the list of Windows services.

The script is run from the command line.

Syntax:

kl_control.bat start | stop | restart | status | help

The table below describes the kl_control.bat options. If you specify more than one option, the script will execute the first one and exit.

The kl_control.bat options

The kl_control.bat script prints an error message if an error occurred when you tried to stop or start the kavhttpd service. If you receive an error message, you can check the state of the kavhttpd service or the klScanEngineUI service by using Windows Task Manager.

[Topic 179880]

Monitoring Kaspersky Scan Engine in HTTP mode

Monitoring Kaspersky Scan Engine in Linux

When monitoring is enabled, the kavhttpd service automatically restarts if it freezes or crashes.

If logging is enabled along with monitoring, the monitoring process writes log messages to a separate file.

To enable monitoring:

1. Set the USE_WATCHDOG parameter in the HTTP mode init script to 1.
2. Restart Kaspersky Scan Engine.

For more information about editing the init script, see section "Changing variables in the HTTP mode init script".

Monitoring Kaspersky Scan Engine in Windows

The watchdog functionality is not supported in the service mode in Windows systems, but you can enable Windows to automatically restart the kavhttpd service after a crash.

To enable Windows to automatically restart the kavhttpd service process after a crash:

1. Log in to a user account that has local administrator rights.
2. Open the Services system utility. The exact way to do this depends on the operating system.
3. Right-click the kavhttpd service. The service is called Kaspersky ScanEngine if you installed Kaspersky Scan Engine by using the installer, or KAV HTTP for Windows if you registered it as a service manually.

   A context menu appears.

4. Select the Properties item.

   The Properties window opens.

5. Select the Recovery tab.
6. Select the Restart the Service option in the First failure, Second failure, and Subsequent failures drop-down lists.

[Topic 181165]

Making requests in HTTP mode

This section explains how to make requests to Kaspersky Scan Engine when working in HTTP mode.

[Topic 181167]

About KAV protocol

A client application uses the KAV protocol to interact with Kaspersky Scan Engine by means of HTTP requests. The current KAV protocol version is 3, but versions 1 and 2 are also supported.

Choose the protocol version that works best for your solution:

• KAV protocol version 3

  In version 3 of the protocol, the bodies of request messages and response messages are in JSON format. Version 3 supports more API methods than versions 1 and 2.

  This is the recommended version of the protocol.

  Note that on Windows systems, only KAV protocol version 3 is used.

• KAV protocol versions 1 and 2

  In versions 1 and 2 of the protocol, the bodies of request messages and response messages are in plain text format.

  Use these versions of the protocol if plain text format is necessary for your solution.

[Topic 179875]

Making requests in HTTP mode via KAV protocol version 3

This section explains how to make HTTP requests to Kaspersky Scan Engine by using KAV protocol version 3.

[Topic 181169]

Supported API methods in KAV protocol version 3

The following table lists the API methods that Kaspersky Scan Engine supports in HTTP mode when using KAV protocol version 3. The format of the requests does not depend on whether the client uses TCP or UNIX sockets for interaction with Kaspersky Scan Engine.

API methods supported in HTTP mode in KAV protocol version 3

Page top

[Topic 181045]

Format of a scan POST request

Scan POST requests have the following format:

where:

• timeout is the object scan timeout in milliseconds (ms). This field is optional.
• omitCleanSubobjectResults is a binary flag that specifies whether the subObjectsScanResults array returned in the response must contain objects with the CLEAN scan result. If the value is true, such objects are omitted; if the value is false, such objects are retained. The default value is true. This field is optional

  For more information on the structure of the subObjectsScanResults array, see section "Format of a response to a scan POST request".

• url is the URL to use as the scan task context. This field is optional.

  This field can be used for increasing the detection rate. For more information, see section "Increasing the detection rate".

• requestHeaders specifies the text of the HTTP request headers extracted from the HTTP transaction message. This field is optional.

  This field can be used for increasing the detection rate. For more information, see section "Increasing the detection rate".

• responseHeaders specifies the text of the HTTP response headers extracted from the HTTP transaction message. This field is optional.

  This field can be used for increasing the detection rate. For more information, see section "Increasing the detection rate".

• object is the full path to the file to scan (if a request is made to /api/v3.0/scanfile) or a Base64-encoded string (if a request is made to /api/v3.0/scanmemory). This field is mandatory.

If the request body contains any special characters, they must be escaped in accordance with Standard ECMA-404 (The JSON Interchange Syntax).

[Topic 181047]

Format of a response to a scan POST request

If a scan POST request is successfully processed, the response body contains a JSON object with the following fields:

where:

• object contains the full path to the scanned file (if a request is made to /api/v3.0/scanfile) or to a "memory" string (if a request is made to /api/v3.0/scanmemory).
• scanResult is the scan result and can have the following values:
  • CLEAN
  • DETECTED
  • DISINFECTED
  • DELETED
  • NON_SCANNED
  • SERVER_ERROR
• detectionName is the name of the detected malicious object in the Kaspersky Lab classification system.
• containsOfficeMacro is the binary flag that has a value of true if a macro was detected in the object and false otherwise.
• subObjectsScanResults is an array of scan results for each sub-object nested in the object that was scanned. This field with all of its sub-fields is only included in the response body if the scanned object contains nested sub-objects.
  • subObjectsScanResults/object is the path to the nested sub-object. Note that the path to the sub-object is separated from the path to its parent object by a double slash (//), for example:

    /home/user/archive.tar//folder/subobject

  • subObjectsScanResults/scanResult is the scan result for the nested sub-object.
  • subObjectsScanResults/detectionName is the name of the detected malicious object in the Kaspersky Lab classification system.
  • subObjectsScanResults/containsOfficeMacro is the binary flag that has a value of true if a macro was detected in the nested sub-object and false otherwise.

If a POST scan request is processed with an error, the response body contains a JSON object with a single error field:

where error contains the description of the error that occurred during the request processing.

[Topic 181065]

Increasing the detection rate

When an HTTP request is made to scan a file or a block of memory, there are two ways to increase the detection rate by specifying an optional scan task context:

• Provide the origin of the object to scan in the url field of the POST request body:
  • If the object to scan was received from the web, specify the web address of origin, including the protocol, for example:

    http://example.com

    The supported protocols are HTTP, HTTPS, and FTP.

    If the URL is unknown, we recommend that you use http://example.com as the scan task context.

  • If the object to scan was received by email, specify the sender's email address in the following format: [from:%sender_address%], for example:

    [from:example@example.com]

    If the sender's email address is unknown, we recommend that you use [from:test@relay.example] as the scan task context.

  Below is an example of an HTTP request to scan a local file received from the web. Note the use of the url field to specify the web address of origin:

  POST /api/v3.0/scanfile HTTP/1.0 Content-Type: application/octet-stream Content-Length: 22   { "timeout": "10000", "object": "\/home\/user\/eicar", "url": "http:\/\/example.com" }

  The response is the same as in section "Example of an HTTP request to scan a local file".

• Provide request and response headers gathered from HTTP traffic related to the object to scan in the requestHeaders and responseHeaders fields of the POST request body.

  Note that you can combine the two types of scan task context to further boost the detection rate. In the example below, the request and response headers are specified along with the web address of origin.

  POST /api/v3.0/scanfile HTTP/1.0 Content-Type: application/octet-stream Content-Length: 22   { "object": "\/home\/user\/eicars.tar", "requestHeaders": ": authority: example.com\r\n: method: GET\r\n path:\/ \r\n:scheme: https\r\naccept: text\/html,application\/xhtml+xml,application\/xml;q=0.9,image\/webp,image\/apng,*\/*;q=0.8\r\naccept-encoding: gzip, deflate, br\r\naccept-language: ru-RU,ru;q=0.9,en-US;q=0.8,en;q=0.7,mt;q=0.6\r\ncache-control: no-cache\r\npragma: no-cache\r\nupgrade-insecure-requests: 1\r\nuser-agent: Mozilla\/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit\/537.36 (KHTML, like Gecko) Chrome\/71.0.3578.98 Safari\/537.36", "responseHeaders": "accept-ranges: bytes\r\ncache-control: max-age=604800\r\ncontent-type: text\/html; charset=UTF-8\r\ndate: Thu, 31 Jan 2019 18:51:11 GMT\r\netag: \"1541025663\"\r\nexpires: Thu, 07 Feb 2019 18:51:11 GMT\r\nlast-modified: Fri, 09 Aug 2013 23:54:35 GMT\r\nserver: ECS (dca\/532C)\r\nstatus: 200\r\nvary: Accept-Encoding\r\nx-cache: HIT", "url": "http:\/\/example.com" }

  The successfully processed request will result in the following response:

  HTTP/1.0 200 Ok Connection: close Content-Type: text/plain Server: KAVHTTPD/1.0 X-KAV-ProtocolVersion: 3 Date: Wed, 30 Jan 2019 15:46:29 GMT Content-Length: 75   { "object": \/home\/user\/eicars.tar", "scanResult": "DETECTED", "detectionName": "multiple", "subObjectsScanResults": [ { "object": "\/home\/user\/eicars.tar\/\/eicar1", "scanResult": "DETECTED", "detectionName": "EICAR-Test-File" }, { "object": "\/home\/user\/eicars.tar\/\/eicar2", "scanResult": "DETECTED", "detectionName": "EICAR-Test-File" } ] }

Page top

[Topic 181041]

Example of an HTTP request to scan a local file

The following example shows an HTTP request to scan a local file:

For a description of all possible fields in the request body, see section "Format of a scan POST request". For recommendations on how to increase the detection rate, see section "Increasing the detection rate".

The following block shows the corresponding response:

For description of all possible fields in the response body, see section "Format of a response to a scan POST request".

[Topic 181043]

Example of an HTTP request to scan a block of memory

The following example shows an HTTP request to scan a block of memory:

For a description of all possible fields in the request body, see section "Format of a scan POST request". For recommendations on how to increase the detection rate, see section "Increasing the detection rate".

The following example shows the corresponding response:

For a description of all possible fields in the response body, see section "Format of a response to a scan POST request".

Page top

[Topic 181049]

Example of an HTTP request to check a URL

The following example shows an HTTP request to check a URL:

The following example shows the corresponding response:

where:

• url is the URL that was checked.
• scanResult is the scan result and can have the following values:
  • CLEAN
  • DETECTED
  • DISINFECTED
  • DELETED
  • NON_SCANNED
  • SERVER_ERROR
• detectionName is the name of the detected malicious object in the Kaspersky Lab classification system. It can have one of the following values:
  • PHISHING_URL
  • MALICIOUS_URL
  • ADWARE_URL
  • RISKWARE_URL

Page top

[Topic 181051]

Example of an HTTP request to get the release date of the anti-virus database

This release date request is usually made after a database update to make sure that the anti-virus database has been updated to the latest version.

The following example shows an HTTP request to get the release date of the anti-virus database:

The following example shows the corresponding response:

where databaseVersion contains the current version of the anti-virus database in the following format: DD.MM.YYYY hh:mm GMT.

[Topic 181053]

Example of an HTTP request to get the current KAV SDK version

The following example shows an HTTP request to get the current KAV SDK version:

The following example shows the corresponding response:

where KAVSDKVersion contains the current KAV SDK version in the following format: MajorVersion.MinorVersion.BuildNumber.Revision.

[Topic 181055]

Example of an HTTP request to get licensing information

The following example shows an HTTP request to get licensing information:

The following example shows the corresponding response that contains licensing information when offline licensing mode is used:

where:

• licenseName is the name of the current key file.
• licenseExpirationDate is the expiration date of the key file or activation code in the following format: DD.MM.YYYY.

The following block shows the corresponding response, which contains licensing information when online licensing mode is used. In this example, the license ticket has expired:

where:

• activationCode is the online activation code.
• licenseExpirationDate is the expiration date of the key file or activation code in the following format: DD.MM.YYYY.
• ticketExpired contains a message that is included in the response body only if the license ticket has expired.

[Topic 181057]

Example of an HTTP request to get accumulated statistics

The following example shows an HTTP request to get accumulated statistics:

The following example shows the corresponding response:

where statistics is an object containing the following accumulated statistics:

• total_requests is the total number of requests to scan a file or a block of memory or to check a URL.
• infected_requests is the number of requests for which Kaspersky Scan Engine returned a DETECTED, DISINFECTED, or DELETED scan result.
• protected_requests is the number of requests for which Kaspersky Scan Engine returned a DISINFECTED or DELETED scan result.
• error_requests is the number of requests for which Kaspersky Scan Engine returned a NOT_SCANNED scan result (due to errors related to the scanned object).
• engine_errors is the number of requests for which Kaspersky Scan Engine returned a SERVER_ERROR scan result (due to errors not related to the scanned object).
• processed_data is the total amount of scanned data in bytes.
• infected_data is the amount of scanned data, in bytes, passed in requests for which Kaspersky Scan Engine returned a DETECTED, DISINFECTED, or DELETED scan result.
• processed_urls is the total number of checked URLs.
• infected_urls is the number of URLs recognized by Kaspersky Scan Engine as malicious, phishing, adware, or legitimate programs that can be used by intruders to damage computers and data.

[Topic 181059]

Example of an HTTP request to clear accumulated statistics

The following example shows an HTTP request to clear accumulated statistics:

The following example shows the corresponding response:

Page top

[Topic 181061]

Example of an HTTP request to update the anti-virus database

This request can be made only if the client and Kaspersky Scan Engine are installed and running on the same computer. If you send this request from a different computer, Kaspersky Scan Engine will throw a 405 Method Not Allowed error.

The following example shows an HTTP request to update the anti-virus database:

The following example shows the corresponding response that is returned if the database update has been successfully initiated:

The following example shows the corresponding response that is returned if an update is already in progress:

The following example shows the corresponding response that is returned if an error occurred when launching the update:

Page top

[Topic 181063]

Example of an HTTP request to get the database update status

This request can be made only if the client and Kaspersky Scan Engine are installed and running on the same computer. If you send this request from a different computer, Kaspersky Scan Engine will throw a 405 Method Not Allowed error.

The following example shows an HTTP request to get the database update status:

The following example shows the corresponding response:

For a description of all the fields that can be included in the response body, see section "Updating the anti-virus database in HTTP mode", subsection "Getting the database update status".

[Topic 181038]

Making requests in HTTP mode via KAV protocol versions 1 and 2

This section explains how to make HTTP requests to Kaspersky Scan Engine by using KAV protocol versions 1 and 2.

[Topic 181170]

Supported API methods in KAV protocol versions 1 and 2

In addition to using KAV protocol version 3, you can make POST and GET requests to Kaspersky Scan Engine by means of KAV protocol versions 1 and 2.

The following table lists the API methods that Kaspersky Scan Engine supports in HTTP mode in KAV protocol versions 1 and 2.

API methods supported in HTTP mode in KAV protocol versions 1 and 2

Page top

[Topic 181073]

Request headers

An HTTP request, using the POST method, to Kaspersky Scan Engine must include the Content-Length header.

When making an HTTP request, there are three request headers specific to Kaspersky Scan Engine that you can set:

• X-KAV-ProtocolVersion

  This header specifies the KAV protocol version used. This header is mandatory.

• X-KAV-Timeout

  This header specifies a scanning operation timeout in milliseconds (but not a session timeout). This header is optional.

  This header takes values ranging from 0 to 4294967295 (unsigned 32-bit integer value). Set the value based on the characteristics of the object to scan (for example, its size or whether it is multipart or not; Kaspersky Scan Engine takes longer to scan a large multipart object).

  For more information about a scanning timeout and a session timeout, see section "Setting the session timeout".

• X-KAV-ObjectURL

  This header contains the scan task context that Kaspersky Scan Engine uses to increase the detection rate. This header is optional.

  The use of this header does not affect scanning performance.

  We recommend that you use the scan task context in gateway integrations.

  Use the following format for the context:

  • If the object to scan is received from the web, specify the web address of origin, including the protocol, for example:

    http://example.com

    The supported protocols are HTTP, HTTPS, and FTP.

    If the URL is unknown, we recommend to use http://example.com as the scan task context.

  • If the object to scan was received by email, specify the sender's email address in the following format: [from:%sender_address%], for example:

    [from:example@example.com]

    If the sender's email address is unknown, we recommend that you use [from:test@relay.example] as the scan task context.

  Scan task context is only applicable to file and memory scanning. If you specify scan task context for a URL, it will be ignored.

Page top

[Topic 181074]

Example of an HTTP request to scan a local file

The following example shows an HTTP request to scan a local file:

If the file to scan is large, consider specifying the X-KAV-Timeout header.

The following example shows the corresponding response:

Page top

[Topic 181076]

Example of an HTTP request to scan a block of memory

The following example shows an HTTP request to scan a block of memory:

If the file to scan is large, consider specifying the X-KAV-Timeout header.

The following examole shows the corresponding response:

For information on how to make a multipart scan request, see section "Example of a multipart HTTP request to scan a block of memory".

[Topic 181078]

Example of a multipart HTTP request to scan a block of memory

To make multipart HTTP requests, use the KAV protocol version 2 by specifying it in the X-KAV-ProtocolVersion request header.

When making a multipart HTTP request, you can specify request and response headers that were gathered from HTTP traffic related to the object being scanned. This data improves the detection rate.

The body of a multipart HTTP request must contain no more than three parts. These parts contain the following data:

• Request headers (optional)

  This part must begin with the "Request headers" string followed by \r\n characters. These characters must be followed by request headers from HTTP traffic related to the object that is being scanned.

• Response headers (optional)

  This part must begin with the "Response headers" string followed by \r\n characters. These characters must be followed by response headers from HTTP traffic related to the object that is being scanned.

• Object for scanning.

  This part can contain the full path to the file to scan (if a request is made to /scanfile) or a string (if a request is made to /scanmemory).

The following example shows a multipart HTTP request to scan a block of memory:

The following example shows the corresponding response:

Page top

[Topic 181080]

Example of an HTTP request to check a URL

The following example shows an HTTP request to check a URL:

The following example shows the corresponding response:

Page top

[Topic 181082]

Example of an HTTP request to get the release date of the anti-virus database

The following example shows an HTTP request to get the release data of the anti-virus database:

The following example shows the corresponding response:

Page top

[Topic 181084]

Example of an HTTP request to get the current KAV SDK version

The following example shows an HTTP request to get the current KAV SDK version:

The following example shows the corresponding response:

Page top

[Topic 181086]

Example of an HTTP request to get licensing information

The following example shows an HTTP request to get licensing information:

The following example shows the corresponding response that contains licensing information when offline licensing mode is used:

The following example shows the corresponding response that contains licensing information when the online licensing mode is used. In this example, the license ticket has expired:

Page top

[Topic 181088]

Example of an HTTP request to get accumulated statistics

The following example shows an HTTP request to get accumulated statistics:

For a description of the statistics returned in the HTTP response, see the example of making this request in KAV protocol version 3.

[Topic 181090]

Example of an HTTP request to clear accumulated statistics

The following example shows an HTTP request to clear accumulated statistics:

The following example shows the corresponding response:

Page top

[Topic 179883]

Using the sample HTTP client

This section explains how to use the sample HTTP client from the command line. The sample HTTP client is located in %service_dir%/bin.

This section explains how to use the executable file of the sample HTTP client. Explaining the implementation of the sample HTTP client is beyond the scope of this documentation. The source code of the sample HTTP client is located in the /samples/kavhttp directory of the Kaspersky Scan Engine distribution package.

About the sample HTTP client

The sample HTTP client is a console application that demonstrates how to implement a client for Kaspersky Scan Engine in HTTP mode. You can also use it to scan files from the console.

The sample HTTP client makes HTTP requests to Kaspersky Scan Engine. It supports TCP connections and UNIX socket connections and can pass file paths or file contents to Kaspersky Scan Engine.

When Kaspersky Scan Engine finishes scanning files, it sends a response to the sample HTTP client. The sample HTTP client prints the scan result to the standard output. For more information about the scan results, see section "Scan results for the HTTP client".

[Topic 179884]

Syntax and options for the HTTP client

You can supply one or more options to the sample HTTP client.

Options

The following options are available in the sample HTTP client:

Options for running the sample HTTP client

Connection type

Connections of two types are supported by the sample HTTP client:

• TCP connection

  To use a TCP connection, specify an IP address in the -s option in the following format: "ip_addr:port".

• UNIX socket connection

  For Linux systems only.

  To use a UNIX socket connection, specify the path to the socket in the -s option.

  This is the default option. The default socket file is /tmp/.kavhttpd.

Timeout

The sample HTTP client uses the value specified in the -t option to determine the scan timeout, similarly to the X-KAV-Timeout header.

The default timeout value is 2000.

If 0 is specified in this option, the timeout is infinite.

Scan mode

The sample HTTP client support two scan modes, which you can specify by using the -f option:

• scanfile mode (-f).

  In this mode, the sample HTTP client passes file paths to Kaspersky Scan Engine, which reads and scans the files.

  To send a scan request to a remote computer over a TCP socket, you must specify the paths to the files that you want to scan or the directories that contain these files. For more information, see "Scanning files over TCP socket in scanfile mode". You do not have to do that if the sample HTTP client and Kaspersky Scan Engine are located on the same computer.

• scanmemory mode (default).

  In this mode, the sample HTTP client passes file contents to Kaspersky Scan Engine, which scans the contents.

  Use only the KAV_SKIP cleaning mode with scanmemory scan mode. Kaspersky Scan Engine cannot disinfect or delete files in scanmemory mode.

Scan task context

Kaspersky Scan Engine uses the scan task context to increase the detection rate. Using this option does not affect scanning performance.

It is recommended to use the scan task context in gateway integrations.

Use the following format for the context:

• If the object to scan is received from the Internet, specify the web address of the source, including the protocol.

  Example: http://example.com

  The supported protocols are HTTP, HTTPS, and FTP. If the source URL is unknown, it is recommended to use http://example.com as the scan task context.

• If the object to scan is received by email, specify the sender's email address. Use the following format: [from:%sender_address%].

  Example: [from:example@example.com]

If the object is received by email, but the sender's email address is unknown, it is recommended to use [from:test@relay.example] as the scan task context.

The scan task context is applicable to file scanning only. If you specify the scan task context for a URL, it will be ignored.

Request and response headers

Specifying request and response headers that were gathered from HTTP traffic related to the scanned object improves the detection rate. It is recommended to use the request and response headers in gateway integrations.

Information messages

The -b, -v, and -l options can only be used together with the -s, -j, and -t options. If you use them with any other option, kavhttp_client returns an error.

You can use the -b, -v, and -l options to check whether kavhttpd is running.

Scanning files

You can specify one or more files to scan, separating them by a white space. Depending on the scan mode, the sample HTTP client then passes the paths to these files or their contents to Kaspersky Scan Engine.

Use the following syntax to scan files in scanfile mode:

Use the following syntax to scan the contents of files in scanmemory mode:

Scanning URLs

You can specify a URL to scan. If the URL contains spaces or tabs, enclose the URL in quotation marks, or make these characters percent-encoded. Similarly, if the URL contains quotation marks ("), make them percent-encoded.

Simultaneous scanning of multiple URLs is not supported. If you specify more than one URL, only the first one will be scanned.

Files cannot be scanned when the -u option is specified. The -u and -f options cannot be used together.

Use the following syntax to scan a URL:

Page top

[Topic 182976]

Scanning files over TCP socket in scanfile mode

You can send scan requests in both scanmemory mode and scanfile mode from the HTTP client on a remote computer to the computer on which the kavhttpd service runs.

In scanmemory mode, the content of the scanned object is sent in the HTTP request message and is scanned in the system memory of the computer that the kavhttpd service runs on.

In scanfile mode, the HTTP client sends to the kavhttpd service the path to the object that is located on the same computer as the kavhttpd service, or on a remote hard disk successfully mounted on that computer. The kavhttpd service reads the object from the hard disk and scans it.

However, when Kaspersky Scan Engine receives a scan request from a client on remote computer in scanfile mode, it scans only those files that are placed at locations specified in the <ScanningPath> elements of the HTTP mode configuration file. This restriction is necessary to prevent the HTTP client from accidentally scanning the whole file system from the remote computer.

To scan a file by using a TCP socket in scanfile mode:

1. In a <ScanningPath> element of the configuration file, specify the location of the file that you want to scan.

   For information about possible values of the <ScanningPath> element, see section "HTTP mode configuration file", subsection "DirectorySettings".

   The following example shows how to specify a directory that contains files to scan:

   <ScanningPaths> <ScanningPath>/mnt/to_scan/</ScanningPath> </ScanningPaths>

2. Connect to Kaspersky Scan Engine on a remote computer by using a TCP socket and scan the file in scanfile mode.

   The following example shows how to scan the eicar.txt file that is located in the /mnt/to_scan/ directory on the computer the kavhttpd service runs on:

   user@computer:/opt/kaspersky/ScanEngine/bin# ./kavhttp_client -f -s 192.0.2.42:9999 /mnt/to_scan/eicar.txt

Page top

[Topic 179885]

Syntax examples

This section contains examples of using the sample HTTP client application from the Linux command line. To run these example in Windows, call kavhttp_client.exe and add the -j option.

Use the default UNIX socket to scan one file by passing the file contents:

Use the default UNIX socket to scan one file by passing the path to the file:

Connect to Kaspersky Scan Engine over a TCP socket and scan two files by passing their contents:

Connect to Kaspersky Scan Engine over a TCP socket and scan two files by passing their contents with a 10-second timeout:

Connect to Kaspersky Scan Engine over a TCP socket and scan by passing the file path:

Connect to Kaspersky Scan Engine over a TCP socket and scan a URL:

Connect to Kaspersky Scan Engine over a TCP socket and scan a URL with the IP of the host referred to by the URL:

Connect to Kaspersky Scan Engine over a TCP socket and request the release date of the anti-virus database:

Page top

[Topic 179886]

Scan results for the HTTP client

For each scanned file, the sample HTTP client prints a scan result that specifies whether a scanned object is considered uninfected or malicious.

The following scan results are possible:

• CLEAN

  Scanned object is considered uninfected.

• DETECTED

  Scanned object is considered malicious. This scan result is followed by the name of the detected object or the type of the detected URL.

  Kaspersky Scan Engine detects URLs of the following types:

  • Malicious URLs. When such a URL is detected, Kaspersky Scan Engine returns DETECTED MALICIOUS_URL. The priority of this type is 1 (highest priority).
  • Phishing URLs. When such a URL is detected, Kaspersky Scan Engine returns DETECTED PHISHING_URL. The priority of this type is 2.
  • Adware URLs. When such a URL is detected, Kaspersky Scan Engine returns DETECTED ADWARE_URL. The priority of this type is 3.

    A URL of this type can only be detected when Cloud Protection is enabled.

  • URLs leading to legitimate software that can be used by intruders to damage computers or users' personal data). When such a URL is detected, Kaspersky Scan Engine returns DETECTED RISKWARE_URL. The priority of this type is 4 (lowest priority).

    A URL of this type can only be detected when Cloud Protection is enabled.

  A URL can belong to several types simultaneously. In this case, Kaspersky Scan Engine returns the DETECTED scan result of the highest priority.

• DISINFECTED

  Scanned object has been successfully disinfected.

• DELETED

  Scanned object was deleted.

If the scanned object contains macros, the scan result of this file is appended with "AND CONTAINS OFFICE MACRO".

Below is an example of the output produced by the sample HTTP client:

If the scanning operation failed, the scan result will contain one of the following error codes:

• NOT_SCANNED

  Specified object was not scanned. The reason for it is provided as well.

• SERVER_ERROR

  An error occurred in Kaspersky Scan Engine.

• CONNECTION_CLOSED

  Connection was closed by Kaspersky Scan Engine.

• CLIENT_TIMEOUT

  Operation timed out. This happens when the client timeout is exceeded.

• CONNECTION_FAILED

  Failed to establish a connection to Kaspersky Scan Engine.

• HTTP_ERROR

  The server has responded with an HTTP status code that is not equal to 200. The HTTP status code and its description are provided as well.

[Topic 179887]

HTTP client connection error messages

When a connection error occurs, the HTTP client prints an error message to the console.

• Invalid response

  The connection was broken when the client was waiting for a response from the server. The client exits after this error.

• Invalid response followed by CONNECTION_CLOSED

  The connection was broken when the client was transmitting a file to scan to the server.

• Invalid response followed by CLIENT_TIMEOUT

  Client timeout (defined by the -t option) was exceeded.

• HTTP_ERROR 408 Request Timeout

  The processing timeout (defined by the SessionTimeout parameter) was exceeded.

Page top

[Topic 179881]

Using a proxy server

Kaspersky Scan Engine can use a proxy server to connect to Kaspersky Lab cloud services.

If a proxy server is specified in the HTTP mode configuration file, Kaspersky Scan Engine does the following:

1. Kaspersky Scan Engine tries to establish a direct connection to the destination.

   Note that this happens even if a proxy server is specified.

2. If a direct connection cannot be established, Kaspersky Scan Engine tries to establish a connection by using the specified proxy server.
3. If a proxy server connection cannot be established, Kaspersky Scan Engine uses offline technologies only.

   Note that this also happens when network problems prevent a proxy server connection from being established. In this case, at regular intervals Kaspersky Scan Engine tries to establish a connection to the proxy server. If a connection is established before a certain timeout, Kaspersky Scan Engine uses online technologies.

You must restart Kaspersky Scan Engine to use the new proxy server settings.

Kaspersky Scan Engine does not print information about using online and offline technologies to the command line. You must analyze log files to get this information. For more information about enabling logging, see section "Logging".

For more information about specifying a proxy server, see section "HTTP mode configuration file".

Page top

[Topic 179882]

Updating the anti-virus database in HTTP mode

With default configuration, Kaspersky Scan Engine uses the anti-virus database from the ./bin/bases directory. You can update the anti-virus database by sending a signal or an HTTP request to Kaspersky Scan Engine.

When the anti-virus database is updated, the encrypted user agent string of Kaspersky Scan Engine is transferred to Kaspersky Lab. For the list of transferred data, see section "Data transferred to Kaspersky Lab during an update".

Updating the database on demand

If you want to update the database manually, use updating on demand.

To update the database on demand in Linux by using signals:

1. Before starting the kavhttpd service, specify the update setting in kavhttpd.xml.
2. Start the kavhttpd service.
3. Send a SIGUSR2 signal to the kavhttpd service.

   If the client and Kaspersky Scan Engine are installed and running on the same computer, you can send an HTTP request to the /api/v3.0/update/start address to update the database. Note that if you send this request from a different computer, Kaspersky Scan Engine will throw a 405 Method Not Allowed error. If the database update has been successfully initiated, the HTTP response will contain the following JSON object:

   { "status": "update started" }

   To learn how to track the database update status, see subsection "Getting the database update status" below.

To update the database on demand in Linux by using the sample HTTP client,

Call the sample HTTP client with the -d option:

kavhttp_client.exe -j -d

To update the database on demand in Windows,

Call the sample HTTP client with the -d option:

kavhttp_client.exe -j -d

For details on scheduling automatic database updates, see section "Configuring updating in HTTP mode", subsection "Scheduling automatic database updates".

Getting the database update status

If you want to obtain the database update status, send a GET request to the /api/v3.0/update/status address.

You can only send this request if the client and Kaspersky Scan Engine are installed and running on the same computer.

When Kaspersky Scan Engine receives the request, it returns a response in the following format:

where:

• status is the current status of the database update. It can have one of the following values:
  • "in progress"
  • "not started"
• progress is the progress, in percent, of the database update.

  This element is only included in the response if the database update is being performed at present (that is if the status element has the value of "in progress").

• last_update_result is the result of the last database update. It can have one of the following values:
  • "success"
  • "all components are up to date"
  • "invalid update sources"
  • "not all components are updated"
  • "download error"
  • "error while updating"
  • "error %ERROR_CODE% occurred", where %ERROR_CODE% is the error code received from Kaspersky Scan Engine

  This element is only included in the response if the database update is not in progress at present (that is if the status element has the value of "not started").

• last_update_time is the date and the time of the last database update in the following format: %hh%:%mm%:%ss% %DD%.%MM%.%YYYY%.

  This element is only included in the response if the database update is not in progress at present (that is if the status element has the value of "not started").

[Topic 186768]

Logging in HTTP mode

This section explains how to work with logs in HTTP mode.

[Topic 179879]

Configuring logging in HTTP mode

For instructions on how to enable logging, see section "Manually enabling logging in Kaspersky Scan Engine", subsection "Enabling logging in HTTP mode".

Configuring logging

To configure logging, change the parameters in the httpdkavlog.ini logging configuration file (hereinafter referred to as the logging configuration file) located in the %service_dir%/bin directory. The configuration file consists of several sections.

The [DebugLogging] section

• LogLevel—Specifies the logging level.

  Possible values:

  • 0

    Disables logging. This is the default value.

  • 1

    Enables full logging mode. Use this mode for debugging purposes.

    In HTTP mode, Kaspersky Scan Engine does not automatically remove log files from previous initializations. If necessary, you can remove these log files manually.

• LogFolder—Specifies the path to a directory where log files are stored.

  The path can be absolute or relative. A relative path is calculated relative to the directory that contains the kavhttpd binary file.

The [SyslogLogging] section

The settings below are available only for Linux operating systems.

• SyslogEnabled—Specifies whether the Kaspersky Scan Engine sends syslog messages.

  Possible values:

  • 0

    Disables sending of syslog messages.

  • 1

    Enables sending of syslog messages.

• SyslogFormat—Specifies the format of syslog messages.

  Possible values:

  • cef—Specifies the CEF format of syslog messages.
  • raw—Specifies the RAW format of syslog messages. The raw value is used when the value specified in this element is not cef or raw, or no value is specified in this element, or if the logging configuration file does not contain the SyslogFormat parameter.
• SyslogDestination—Specifies the destination address for syslog messages.

  Possible values:

  • %PROTOCOL%%IP%:%PORT%, where:
    • %PROTOCOL% is a network protocol (use tcp:// or udp:// for this value).
    • %IP% is an IPv4 address that receives syslog messages.
    • %PORT% is a port that receives syslog messages.

    If you do not specify a protocol as described above, Kaspersky Scan Engine will use the UDP protocol.

  • localhost—Indicates that syslog messages are redirected to syslogd.
  • Absolute or relative path to a directory where log files with syslog messages are stored.

    The directory contains the httpd_kav_syslog.log file. Log files with syslog messages created by previous sessions are not removed. If the directory contains an old file, Kaspersky Scan Engine writes new information to this file without deleting the old data.

Kaspersky Scan Engine can write debug logs and send syslog messages at the same time or separately.

Sending syslog messages is available starting from Kaspersky Scan Engine version 1.0.1.51.

Structure of the logging configuration file

Following is an example of a logging configuration file:

Page top

[Topic 186767]

Format of CEF logs in HTTP mode

If Kaspersky Scan Engine is configured to write syslog messages in CEF format, the log records about events appears as follows:

CEF:0|Kaspersky Lab|Kaspersky HTTP Service|%VERSION%|%EVENT_CLASS_ID%|%EVENT_NAME%|%SEVERITY%| msg=%EVENT_MSG% src=%CLIENT_IP% dvcpid=%HTTP_SERVICE_PID% sproc=unix_socket dvc=%HTTP_SERVICE_IP% start=%EVENT_TIME% fileHash=%SCANNED_FILE_MD5_HASH% fname=%SCANNED_FILE_NAME% request=%SCANNED_URL% act=%ACTION_MADE% cs1=%SCAN_RESULT% cs1Label=Scan result cs2=%VIRUS_NAME% cs2Label=Virus name\n

A record has the following fields:

• %VERSION%

  Version of KAV SDK that Kaspersky Scan Engine is based on.

• %EVENT_CLASS_ID%

  Class of the event. Possible values:

  • 1

    Service event (not related to scanning).

  • 2

    Event related to errors.

  • 3

    Event related to scanning (for example, a scan result).

• %EVENT_NAME%

  Name of the event. Possible values:

  • Initializing—Kaspersky Scan Engine initialized.
  • Deinitializing—Kaspersky Scan Engine deinitialized.
  • Service event—Service event occurred.
  • Service error—Error occurred in the kavhttpd service .
  • Core error—Error occurred in Kaspersky Anti-Virus Engine.
  • Scan result—Kaspersky Scan Engine finished scanning an object.
• %SEVERITY%

  Importance level of the event. The higher the level, the more important the event. Possible values:

  • 5

    This value is specified for service events, when the scanning starts, or if the scan result is CLEAN.

  • 7

    This value is specified for initialization, deinitialization, and errors.

  • 8

    This value is specified if the scan result is something other than CLEAN.

• %EVENT_MSG%

  Description of the event, for example, the text of an error message.

• %CLIENT_IP%

  IP address of the HTTP client that sent the scan request to Kaspersky Scan Engine. This field appears only if the request is sent over a TCP socket and is related to scanning.

• %HTTP_SERVICE_PID%

  PID of Kaspersky Scan Engine.

• %HTTP_SERVICE_IP%

  IP address that Kaspersky Scan Engine uses to receive scan requests from clients. This field appears only if Kaspersky Scan Engine receives scan requests over a TCP socket.

• %EVENT_TIME%

  Time and date of the event. The time and date are taken from the computer that Kaspersky Scan Engine runs on.

• sproc=unix_socket

  This field appears only if Kaspersky Scan Engine receives scan requests over a UNIX socket.

• %SCANNED_FILE_MD5_HASH%

  Hash of the object that was passed for scanning to Kaspersky Scan Engine. This field appears only if a client sent a scan request and Kaspersky Scan Engine has finished scanning.

• %SCANNED_FILE_NAME%

  Name of the scanned file. If the client sent a request to scan a part of RAM, the value of this field is MEMORY_BLOCK. This field appears only if a client sent a scan request and Kaspersky Scan Engine has finished scanning.

• %SCANNED_URL%

  URL specified in the X-KAV-ObjectURL header of the scan request. This field appears only if a client sent a scan request and Kaspersky Scan Engine has finished scanning.

• %ACTION_MADE%

  Action that was performed on the detected threat or a threat or legitimate software that can be used by intruders. This field appears only in events that contain scan results.

• %SCAN_RESULT%

  Scan result. This field appears only in events that contain scan results.

• cs1Label=Scan result

  This field appears only in events that contain scan results.

• %VIRUS_NAME%

  Name of the detected threat or legitimate software that can be used by intruders. This field appears only if a threat or legitimate software that can be used by intruders was detected.

• cs2Label=Virus name

  This field appears only if a threat or legitimate software that can be used by intruders was detected.

Writing syslog messages in CEF format is available starting from Kaspersky Scan Engine version 1.0.1.51.

Page top

[Topic 186769]

Format of RAW logs in HTTP mode

If Kaspersky Scan Engine is configured to write syslog messages in RAW format, the log records about events appear as follows:

<%PRIORITY%>1 %TIMESTAMP% %HTTP_SERVICE_IP% KasperskyHTTPService %HTTP_SERVICE_PID% %MESSAGE_ID% [KL_HTTPD@23668 md5="%SCANNED_FILE_MD5_HASH%"] BOM %MESSAGE%\n

A record has the following fields:

• %PRIORITY%

  Severity level of the event. Possible values:

  • 163

    This value is specified for errors.

  • 165

    This value is specified if the the scan result is something other than CLEAN.

  • 166

    This value is specified for service events or if the the scan result is CLEAN.

• %TIMESTAMP%

  Date and time of the event in the Coordinated Universal Time (UTC) time zone.

• %HTTP_SERVICE_IP%

  IP address that Kaspersky Scan Engine uses to receive scan requests from clients. If Kaspersky Scan Engine receives scan requests over a UNIX socket, the field contains the host name of the computer that Kaspersky Scan Engine runs on.

• %HTTP_SERVICE_PID%

  PID of Kaspersky Scan Engine.

• %MESSAGE_ID%

  Class of the event. Possible values:

  • SERVICE_MESSAGE

    Service event.

  • ERROR_MESSAGE

    Error.

  • SCAN_RESULT_MESSAGE

    Scan result.

• %SCANNED_FILE_MD5_HASH%

  MD5 hash of the object that was passed for scanning to Kaspersky Scan Engine. This field appears only when Kaspersky Scan Engine returns the scan result.

• %MESSAGE%

  Description of the event, for example, the text of an error message.

Writing syslog messages in RAW format is available starting from Kaspersky Scan Engine version 1.0.1.51.

[Topic 179888]

Building executable files for the HTTP service and the HTTP client

You can compile the kavehttpd service and the sample HTTP client from the source code located in the %service_dir%/samples/kavhttp/ directory.

Software requirements

To compile kavehttpd service and the sample HTTP client, you must install the following software on you computer:

• Boost 1.60 or later. The kavehttpd service source files are liked with Boost dynamically, which requires the boost-devel package.

  The boost libraries must be compiled statically. You can find a list of the necessary boost libraries in %service_dir%/samples/kavhttp/Makefile.

• OpenSSL library. It is recommended to install the openssl-devel package.
• PostgresSQL libraries. It is recommenced to install the libpqxx-devel package.

Compiling Kaspersky Scan Engine and the sample HTTP client in Linux

To compile Kaspersky Scan Engine and the sample HTTP client in Linux:

1. Navigate to the %service_dir%/samples/kavhttp/ directory.
2. Run make.

   The compiled client executable files will be placed in the %service_dir%/bin directory. The compiled service executable files will be placed in the %service_dir%/opt/kaspersky/ScanEngine/sdk8l3/bin/ directory.

The following example demonstrates building the executable files:

Kaspersky Scan Engine and the sample HTTP client in Windows

To compile Kaspersky Scan Engine and the sample HTTP client in Windows:

1. Navigate to the %service_dir%/samples/kavhttp/http_service/windows folder.
2. Do the following:
   • If you want to compile the kavehttpd service, open the kavhttpd.vcxproj file in Microsoft Visual Studio.
   • If you want to compile the sample HTTP client, open the kavhttp_client.vcxproj file in Microsoft Visual Studio.
3. Right-click the project in Solution Explorer and select Properties.
4. In the properties window that opens, in the left navigation tree, select Configuration Properties > Linker > Input, and for the Additional Dependencies property add the paths to the Boost, OpenSSL, and PostgresSQL libraries.
5. In the left navigation tree, select Configuration Properties > С/C++, and for the Additional Include Directories property add the headers of the Boost, OpenSSL, and PostgresSQL libraries.
6. Right-click the project in Solution Explorer and select Build.

If you use Kaspersky Scan Engine GUI and intend to modify the provided binaries, please make sure to get prior approval for all changes from your technical account manager (TAM).

[Topic 179708]

Using Kaspersky Scan Engine in ICAP mode

This chapter contains information about using Kaspersky Scan Engine in ICAP mode.

The ICAP mode is available only for Linux operating systems.

[Topic 179889]

Kaspersky Scan Engine and ICAP mode

Internet Content Adaptation Protocol (ICAP) is the standard for communication between proxy servers and service providers. In ICAP mode, Kaspersky Scan Engine works with ICAP-compliant proxy servers. Kaspersky Scan Engine scans HTTP traffic that passes through a proxy server, and URLs requested by users.

In ICAP mode, Kaspersky Scan Engine consists of the kavicapd service, configuration files, and libraries, and has the following features:

• URL scan

  Kaspersky Scan Engine allows you to scan URLs that users request from a proxy server. This function is available in both the request modification (REQMOD) mode and response modification (RESPMOD) mode of ICAP.

• HTTP traffic scan

  Kaspersky Scan Engine allows you to scan incoming and outgoing HTTP traffic that passes through a proxy server. This function is available in both the request modification (REQMOD) mode and response modification (RESPMOD) mode of ICAP.

  Scanning of multipart objects is supported.

• Support for the 204 No Content HTTP status code

  The kavicapd service can be configured to reply with this status code if the message sent by a client does not require modification.

• Configuring the kavicapd service behavior with service rules
• Partial mode

  In this mode, the ICAP plugin scans files as a whole, and then divides them into batches, and sends the batched files to the user. The plugin continues to scan files at the same time that it is sending the first batches of files to the user. This function allows users to receive large scanned files quickly.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

• Preview mode

  In this mode, the ICAP client sends preview requests to the ICAP plugin. The preview requests allow you to skip objects that the plugin does not consider malicious.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

Page top

[Topic 179891]

Configuring Kaspersky Scan Engine in ICAP mode

This section explains how to manually configure Kaspersky Scan Engine for use in ICAP mode without using Kaspersky Scan Engine GUI.

[Topic 179892]

ICAP mode configuration file

The ICAP mode configuration file, kavicapd.xml, consists of several sections that specify settings for the kavicapd service and KAV SDK.

Preparing the ICAP mode configuration file

The Kaspersky Scan Engine distribution kit contains a %distr_kit%/etc/kavicapd.xml configuration file.

After installing Kaspersky Scan Engine, you can copy kavicapd.xml to your preferred location:

• If you copy kavicapd.xml to the /etc/ directory, Kaspersky Scan Engine automatically finds and parses this file.
• If you copy kavicapd.xml to a different location, you need to set the path to this location when you start Kaspersky Scan Engine:
  • If you want to use the init script to start Kaspersky Scan Engine, see section "Running Kaspersky Scan Engine in ICAP mode with the init script".
  • If you want to start Kaspersky Scan Engine from command line manually, see section "Running Kaspersky Scan Engine in ICAP mode manually".

Parameters of the ICAP mode configuration file

Following are the sections of the ICAP mode configuration file, kavicapd.xml. An example configuration file is at the end.

Some sections of the configuration file are optional. However, if a section exists in the configuration file, all of its child elements must be present. Elements must not be empty, unless stated otherwise.

SDKSettings

The following parameters specify KAV SDK settings.

• ScannersCount—Specifies the number of scanning processes. You can have up to 256 scanning processes.

  The default value is 16.

• ThreadsCount—Specifies the total number of scanning threads in all processes. You can have up to 256 scanning threads.

  The default value is 16.

• QueueLen—Specifies the length of the scan task queue.

  The default value is 1024.

• ScanTimeout—Specifies the scanning timeout, in milliseconds (ms). If the value of this parameter is 0, the timeout is disabled.

  The default value is 10000 (10 seconds).

• LicensePath—Specifies an absolute path to a directory where the application ID file, licensing file, and key file are stored.

  Kaspersky Scan Engine looks for these files in the following directories:

  • The directory specified in LicensePath.
  • The directory that contains the kavicapd executable file.
  • The %service_dir%/ppl directory.

  The default value is /opt/kaspersky/ScanEngine/bin.

• BasesPath—Specifies an absolute path to a directory where the anti-virus database is located.

  The default value is /opt/kaspersky/ScanEngine/bin/bases.

• TempPath—Specifies an absolute path to a directory where the files created at runtime are stored.

  The default value is /tmp/kavicapd.

  Do not delete any files from this directory.

• DiskUsageLimit—Specifies the maximum amount of disk space (in kilobytes) that can be allocated for unpacking a packed object.

  Limiting disk space allocated for an unpacked object helps protect the server from zip bombs (malicious archive files).

  If the value of this parameter is 0, the zip bomb protection is disabled.

  The default value is 102400.

• ScanningMode specifies a file scanning mode.

  A scanning mode is defined by a combination of flags separated by pipes (|).

  Possible values:

  • KAV_O_M_PACKED

    Scan compressed executable files.

  • KAV_O_M_ARCHIVED

    Scan archived files.

  • KAV_O_M_MAILBASES

    Scan files that contain email databases.

  • KAV_O_M_MAILPLAIN

    Scan email messages.

  • KAV_O_M_HEURISTIC_LEVEL_SHALLOW

    Set the scanning level of the advanced heuristic code analyzer to shallow (the Low level in the graphical user interface).

  • KAV_O_M_HEURISTIC_LEVEL_MEDIUM

    Set the scanning level of the advanced heuristic code analyzer to medium (the Medium level in the graphical user interface).

  • KAV_O_M_HEURISTIC_LEVEL_DETAIL

    Set the scanning level of the advanced heuristic code analyzer to detail (the High level in the graphical user interface).

  • KAV_O_M_MSOFFICE_MACRO

    Notify the user if a Microsoft Office document file contains a macro.

  • KAV_O_M_PHISHING

    Enable Phishing protection.

  The default value is KAV_O_M_PACKED | KAV_O_M_ARCHIVED | KAV_O_M_MAILPLAIN | KAV_O_M_MAILBASES | KAV_O_M_HEURISTIC_LEVEL_SHALLOW.

• LicensingMode—Specifies the licensing mode used in Kaspersky Scan Engine.

  Possible values:

  • 1—Offline licensing mode
  • 2—Online licensing mode

  The default value is 1.

KSNSettings

The following parameters specify Kaspersky Security Network (KSN) settings.

This is an optional section. If this section is absent from the configuration file, KSN is not used.

Note that by using KSN you agree to transfer data described in the About data provision.txt file to Kaspersky Lab. For more information about the procedure of data provisioning, see section "About data provisioning".

• UseKSN—A Boolean value that defines whether KSN is enabled.

  If the value of this parameter is 1, KSN is enabled. It also automatically enables the KAV_O_M_COMPOSITE_SCAN_KSN flag. If the value of this parameter is 0, KSN is disabled.

  The default value is 0.

• ObjectCheckOnDemandTimeoutMs—Specifies the KSN scanning timeout, in milliseconds (ms).

  This value cannot be 0.

  The default value is 10000 (10 seconds).

• CacheSizeKb—Specifies the maximum size, in kilobytes (KB), of the KSN status cache.

  This cache is used by Kaspersky Scan Engine to store scan results obtained from KSN.

  The default value is 30720.

Notice to users in the U.S.

ProxySettings

The following parameters specify proxy server settings for Kaspersky Scan Engine. Kaspersky Scan Engine uses these settings when it connects to the Internet.

This is an optional section. If this section is absent from the configuration file, Kaspersky Scan Engine does not use a proxy server when connecting to the Internet.

• UseProxy—A Boolean value that defines whether Kaspersky Scan Engine uses a proxy server when connecting to the Internet.

  If the value of this parameter is 1, Kaspersky Scan Engine uses a proxy server. If the value of this parameter is 0, Kaspersky Scan Engine does not use a proxy server.

  The default value is 0.

• Host—Specifies the proxy server IP address (IPv4 or IPv6) or a domain name.

  If a proxy server is used, this parameter is mandatory.

  Do not specify the protocol (http:// or https://) in this parameter.

• Port—Specifies the port number of the proxy server.

  The default value is 3128.

• User—Specifies the encrypted user name that is used for authenticating on a proxy server. The user name is encrypted by the kav_encrypt utility.

  If a proxy server is used, this parameter is mandatory.

  If the User parameter and the Pass parameter are empty, an anonymous proxy server is used.

• Pass—Specifies the encrypted password used for authenticating on a proxy server. The password is encrypted by the kav_encrypt utility.

  If this element and the User element are empty, an anonymous proxy server is used.

UpdateSettings

The following parameters specify update settings for Kaspersky Scan Engine.

This is an optional section. If this section is absent from the configuration file, updating is disabled.

• DisableBackup—A Boolean value that defines whether anti-virus database backup is enabled.

  If the value of this parameter is 0, anti-virus database backup is enabled. If the value of this parameter is 1, anti-virus database backup is disabled.

  The default value is 0.

• UpdatePeriodMinutes—Specifies the interval between automatic updates (in minutes).

  The maximum value is 44640.

  If this parameter is 0, Kaspersky Scan Engine does not perform automatic updates.

  The default value is 30.

• UseOnlyCustomSources—Specifies whether Kaspersky Lab update servers are used as a source of updates.

  If the value of this parameter is 1, only custom update sources are used. If the value of this parameter is 0, Kaspersky Lab update servers are used along with custom update sources.

  The default value is 0.

• UpdateSources—Contains custom update sources.
  • Source specifies a custom update source.
• USRSignalAction—Specifies an action that must be performed on receiving a signal specified in the USRSignalToHandle parameter.

  Possible values:

  • reload

    Reloads the database without updating it. It is assumed that the files in the database directory are already up to date and must be reloaded.

  • update

    Updates and reloads the database.

  The default value is update.

• USRSignalToHandle—Specifies the signal that must be received to update or reload the database (this action is specified in the USRSignalAction parameter).

  Possible values:

  • USR1

    Only the SIGUSR1 signal must be handled.

  • USR2

    Only the SIGUSR2 signal must be handled.

  • all

    Both the SIGUSR1 and SIGUSR2 signals must be handled.

  • None

    Signals must not be handled (database update is performed according to a pre-defined schedule).

ICAPSettings

The following parameters specify Kaspersky Scan Engine settings.

• Port—Specifies the port number of Kaspersky Scan Engine.

  The default value is 1344.

• MaxIcapSessionsCount—Specifies the maximum number of simultaneous connections to Kaspersky Scan Engine.
• RAMUsageLimit—Specifies the maximum amount of system memory, in kilobytes (KB) that can be allocated by Kaspersky Scan Engine.

  This measure prevents the operating system from running out of memory. Excessive use of system memory (in this case, RAM) can occur when Kaspersky Scan Engine scans large files or receives a lot of simultaneous scan requests. When the RAMUsageLimit limit is reached, Kaspersky Scan Engine stops processing the object that caused excessive consumption of memory.

  Set the value of RAMUsageLimit as high as possible, but keep in mind that you have to leave enough system memory for the proper functioning of Kaspersky Scan Engine. The anti-virus database and libraries used by Kaspersky Scan Engine occupy about 300 megabytes (MB)—and this amount doubles during reloading of the database. Kaspersky Scan Engine also requires memory resources for all of its components.

  Do not set the value of RAMUsageLimit lower than 7 MB. This is the minimum amount of system memory required to ensure the proper functioning of Kaspersky Scan Engine.

  If the value of this parameter is 0, the amount of system memory that can be allocated by Kaspersky Scan Engine is not limited.

  The default value is 0.

  Note that if the value of this parameter is set to 0, the operating system may run out of memory. If Kaspersky Scan Engine uses too much system memory, the operating system may stop the service.

• Exclusions

  Specifies the rules for the preview request mode (REQMOD). This feature enables the ICAP client to send preview requests to the ICAP plugin, which then skips scanning of objects that are not considered malicious.

  Possible parameters:

  • ContentSize

    The exclusion rule for the object size, in kilobytes (KB), that is specified in the Content-Length field of the HTTP header. If the Content-Length value is greater than or equal to the ContentSize value, the ICAP plugin does not scan this object. You can set this parameter only once.

    This parameter may be absent if you explicitly omitted it.

  • ContentType

    The exclusion rule for the object type that is specified in the Content-Type field. If the Content-Type field contains the value, which is specified in the ContentType element field, the ICAP plugin does not scan this object. You can set this parameter one or more times. The ICAP plugin will check all of these parameters.

    This parameter may be absent if you explicitly omitted it.

  • RequestURL

    The exclusion rule for sending the request to a URL. The URL is contained in the Host field (from the HTTP header) and in the URI field (from the HTTP starting line). If the RequestURL element contains the requested URL, the ICAP plugin does not scan the object. Before comparing the requested URL with the rule value from the RequestURL field, the ICAP plugin applies normalizing rules to this URL.

    The RequestURL parameter may contain masks.

    You can specify the asterisk (*) wildcard character from the third level of the domain and above. For example, *.domain.com: this value includes all subdomains of this domain. The asterisk (*) wildcard character can be used as a substitute for any sequence of characters.

    On the URI field, you can specify the asterisk (*) and question mark (?) wildcard characters, which can be used to substitute for any sequence of characters, or a single character, respectively. For example, domain.com/test/page=*: this value includes all pages that contain the /test/page= path (such as domain.com/test/page=123).

    You can set this parameter one or more times. The ICAP plugin will check all of these parameters.

    This parameter may be absent if you explicitly omitted it.

  If the object to scan complies with at least one of the rules, the ICAP plugin returns the code 204, regardless of the value that the Allow204 parameter of the kavicapd.xml file contains. If the object to scan does not comply with any of the rules, the ICAP plugin returns error code 100 and then waits for the ICAP client to send this object.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

• ScanMaxFileSize—Specifies the maximum size (in kilobytes) of a file that can be scanned by Kaspersky Scan Engine.

  If the value of this parameter is 0, Kaspersky Scan Engine will scan files of any size. If the ContenSize exclusion rule is specified, the value of the ScanMaxFileSize parameter is equal to the value of this rule.

  The default value is 0.

• Allow204—A Boolean value that defines whether Kaspersky Scan Engine sends a 204 No Content HTTP status code instead of unchanged data to the proxy server.

  If the value of this parameter is 1, Kaspersky Scan Engine returns a 204 No Content HTTP status code instead of unchanged data. If the value of this parameter is 0, Kaspersky Scan Engine returns unchanged data.

• ScanInReqMode—Specifies the types of content that Kaspersky Scan Engine must scan in request modification (REQMOD) mode.

  This is an optional element. If this element is absent from the configuration file, the All value is used.

  Possible values:

  • Content

    Only scan the HTTP message body.

  • Url

    Only scan the requested URL.

  • All

    Scan the HTTP message body and the requested URL.

  • Empty value

    Do not scan HTTP messages in request modification (REQMOD) mode.

  The default value is All.

• ScanInRespMode—Specifies the types of content that Kaspersky Scan Engine must scan in response modification (RESPMOD) mode.

  This is an optional element. If this element is absent from the configuration file, the All value is used.

  Possible values:

  • Content

    Only scan the HTTP message body.

  • Url

    Only scan the requested URL.

  • All

    Scan the HTTP message body and the requested URL.

  • Empty value

    Do not scan HTTP messages in response modification (RESPMOD) mode.

  The default value is All.

• RulesFilePath—Specifies an absolute path to a file that contains service action rules.

  The default value is /opt/kaspersky/ScanEngine/icap_data/kavicapd_gui_rules.conf.

• CmdPath—Specifies an absolute path to a directory containing scripts that can be executed when the corresponding rules are triggered.

  The default value is /opt/kaspersky/ScanEngine/icap_data/scripts.

• ResponsesPath—Specifies an absolute path to a directory containing response templates that can be executed when the corresponding rules are triggered.

  The default value is /opt/kaspersky/ScanEngine/icap_data/templates.

• HTTPClientIpICAPHeader—Specifies the name of the header field in which the IP address of the HTTP client is specified.

  This element is optional. It can have an empty value.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

• HTTPUserNameICAPHeader—Specifies the name of the header field in which the name of the HTTP client is specified.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.This element is optional. It can have an empty value.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

• TransferBeforeScanEnding

  Specifies Partial mode for files that are sent to the proxy server.

  This element has the following attributes:

  • Delay specifies the delay(s) between the start of receiving the object and sending the first batch of files to the proxy server.

    The range of possible values is from 1 to 3600. This element may be absent if you explicitly omitted it.

    The preset value is 10.

  • ChunkSize specifies the data rates (kilobytes per second (KB/s)) of the file that is being scanned while the scan is in progress.

    The range of possible values is from 1 to 1024. This element may be absent if you explicitly omitted it.

    The preset value is 4.

  You can specify one of two values for the element.

  Possible values:

  • 0

    The file is sent only after the scanning ends.

  • 1

    The file can be sent before the scanning ends.

  The preset value is 0.

  This element is available starting from Kaspersky Scan Engine version 1.0.1.51.

Structure of the configuration file

Following is an example ICAP mode configuration file.