Description of the HTTP API

In this section

•General Information

•User authentication and authorization

•Managing Dr.Web for UNIX Mail Servers

•Managing the list of threats

•Managing Quarantine

•Examples of using the HTTP API

1. General Information

The HTTP API is provided as a means to integrate Dr.Web for UNIX Mail Servers with third-party applications via the HTTP protocol (to ensure security, the HTTPS protocol is used).

Version 1.0 of the HTTP protocol is used to interact with the API. All requests use standard methods of the HTTP protocol: GET and POST. All data is transferred in the form of JSON objects, except as otherwise specified. If you are sending a JSON object in the body of your HTTP POST request, set the Content-Type: header to have the value of application/json.

The format of an HTTP response to an HTTP request

•In response to all requests, except as otherwise specified, the API always returns a JSON object. If an error occurs, the API returns an Error JSON object.

•If the JSON object sent as a response has a field of an Array type, but this array does not contain any elements, this field is omitted in the server response.

•In all responses, except as otherwise specified, the Content-Type: header field has the application/json value.

•If the client requests an endpoint that does not exist, the Error JSON object in which the code field with the EC_UNEXPECTED_MESSAGE value is returned.

•If SCS (Secure Cookie Sessions for HTTP) is used, the responses contain a cookie proving the client authorization (hereinafter referred to as the SCS cookie).

Encoding of strings in JSON objects

•The strings are transmitted in UTF-8 encoding (without BOM). Characters that are not part of the ASCII table are not escaped with sequences like \uXXXX, but are transmitted in UTF-8 encoding.

•JSON objects can contain both UTF-8 encoded characters and escaped sequences like \uXXXX.

General restrictions on data transmission

•In POST requests with JSON objects in their body any characters complying with RFC 7159 are allowed.

•In GET requests any characters complying with RFC 1945 are allowed in the URI.

•Characters complying with RFC 1945 can be used in any other part of the request (either in the headers or in the body).

2. User authentication and authorization

To start using the API, you should be authenticated by the server. Two methods of authorization are provided.

1.Using SCS in accordance with RFC 6896.

2.Using client SSL certificates attested by a trusted CA’s certificate on behalf of Dr.Web HTTPD. In this case the client is considered authorized as a superuser (X.509 client certificates are used).

If SCS is used, SCS cookies are transferred in the following HTTP headers: Cookie:—in the request and Set-Cookie:—in the response.
When authorizing with SSL certificates, SCS cookies are not required.

When authorizing with SCS, using the API starts with sending the login command. If this command is run successfully, the client receives an SCS cookie confirming the authorization.
When authorizing with a client certificate, you do not need to run the login command. If you try to run it, the Error JSON object is returned.

2.1. By specifying login and password (SCS)

User authentication and authorization commands:

*) Here and below the SCS cookie is put in parentheses, because it is required only when authorizing via SCS.

Description of used objects

1) AuthOptions—an object which contains the user login and password:

2) whoami—an object which contains the name of the user who was authorized to use the HTTP API:

3) Error—an object which contains information about the occurred error:

The parameter marked with * is optional.

2.2. Authorization using a personal certificate

This authorization method implies using a personal certificate signed by a certificate authority certificate specified as trusted in the Dr.Web HTTPD settings. If you have authorized with a certicate, all your requests are considered executed as root.

To authorize with a personal user certificate

1.Create a personal certificate signed by a certificate authority certificate.

2.In the Dr.Web HTTPD settings (the AdminSslCA parameter), specify a path to the certificate authority certificate used to sign your personal certificate.

3.Each time you connect to Dr.Web HTTPD, use a signed certificate.

If necessary, refer to the Appendix E. Generating SSL certificates section.

3. Dr.Web for UNIX Mail Servers Management

API commands for viewing and modifying the current values of configuration parameters:

Configuration of the product components is returned and set as the so-called lexical map, i.e. as a sequence of parameter-value pairs. A LexMaps object always contains three nested LexMap objects containing the following lexical maps:

•active—active (valid) parameter values;

•hardcoded—default values (automatically assigned to the parameters which values are not specified or invalid);

•master—map of configuration parameter values specified by the client.

Description of used JSON objects

1)LexMaps—an object containing an active, a predefined and a user-defined lexical maps of parameter values:

Each of these fields is a LexMap object, which in turn contains an array of LexOption objects.

2)LexMap—an object containing a lexical map of parameters:

3)LexOption—an object containing a parameter or a configuration section (a group of parameters):

The parameters marked with * are optional.

The LexOption object represents a section or a parameter of the Dr.Web for UNIX Mail Servers configuration. It always has a key field corresponding to the name of the section or of the parameter, as well as a value field (if the object is a parameter), or a map field (in case it describes a section). A section is also an object of the LexMap type; whereas the parameter value is an object of the LexValue type containing an item field specifying the parameter value in the string format.

4)LexValue—an object containing an array of parameter values:

The set_lexmap command accepts a LexMap object that must contain all the parameters which values you want to change to new ones or reset to their defaults. Those parameters that you want to reset to their default values must not contain the value field. Parameters that are not mentioned in the lexical map passed to the set_lexmap command will not be changed. As a result of its execution, the set_lexmap command returns a SetOptionResult object containing changed values of every parameter passed to the command.

5)SetOptionResult—an object with an item field containing an array of modified parameter values:

The object contains an array of SetOptionResultItem objects containing changed values of every parameter passed to the command.

6)SetOptionResultItem—an object containing information about a change of a parameter value:

The parameters marked with * are optional.

The option field contains the name of the parameter to which your action was applied, and the result field contains the result of an attempt to change the value of this parameter. If a new value was successfully assigned, the field has the EC_OK value. In case of an error, this object may contain a lower_limit field and an upper_limit field that store the maximum and the minimum allowed value for this parameter.

7)The StartUpdate object contains data on the started updating process:

8)The ESConnection object contains data on connection to a centralized protection server:

The parameters marked with * are optional.

The login and password parameters are only specified if newbie = true.
Before connecting, download the certificate file from the centralized protection server and run the command:

The string obtained from running this command is used as the certificate parameter value.

9)The BaseInfoResult object contains data on the downloaded virus bases:

10)The VirusBaseInfo object containing the detailed information about the virus base:

The parameter marked with * is optional.

11)The IdpassRequest object contains information about the password-protected archive:

The parameter marked with * is optional.

If the secret field is not specified, the value of the MailD.RepackPassword configuration parameter is used if the password type is not Plain. If the password type is Plain, then the EC_INVALID_ARGUMENT error (the Error object) is returned.

4. Object Scanning

API commands for scanning objects:

Description of used JSON objects

1)ScanOptions is an object containing parameters used for creating endpoint for file scanning:

2)ScanPathOptions is the object containing parameters for scanning a file or a directory at the specified path:

The parameters marked with * are optional.

3)ScanPathResult is an object containing results of scanning a file or a directory at the specified path:

The parameter marked with * is optional.

If the scanning is successful, the error string will be absent in the response.

4)ScanResult is an object containing scan results:

The parameters marked with * are optional.

5)ScanReport is an object containing information about the file with a threat:

The parameters marked with * are optional.

The fields virus and error may be absent in the response if no threats were detected and no errors occurred during the scan. To call scan_endpoint, the scan_endpoint field always specifies a temporary file created by the Dr.Web Network Checker component in the server local file system and containing the data for scanning sent in the body of the scan_endpoint request).

6)ScanEndpoint is an object containing information about endpoint created for file scanning:

The endpoint identifier returned in the object body. The identifier is used to start file scanning with the scan_endpoint command (as part of URI).

7)VirusInfo is an object containing information about the detected threat:

The type field (threat type) is a string in the form of SE_XXX:

•SE_KNOWN_VIRUS—a known virus;

•SE_VIRUS_MODIFICATION—a modification of known malware;

•SE_UNKNOWN_VIRUS—an unknown virus (suspicious object);

•SE_ADWARE—adware;

•SE_DIALER—a dialer program;

•SE_JOKE—a joke program;

•SE_RISKWARE—a potentially dangerous program;

•SE_HACKTOOL—a hacktool.

8)Archive is an object containing information about an archive, packed objects, email messages and other containers:

9)ScanStat is an object containing scanning statistics:

5. Managing the list of threats

To manage the list of threats that have been detected while scanning or by the SpIDer Guard file system monitor, the following commands are available in the HTTP API:

Each found threat has a unique integer identifier <threat ID>. The list of identifiers for all detected threats is returned by the threats command. The threat_info, cure_threat, delete_threat, ignore_threat, and quarantine_threat commands allow the threat identifiers from this list only.

All information about a specific threat, including action history, can be obtained using the threat_info request. The information is returned as the FileThreat object.

Description of JSON objects

1)FileThreat is an object containing the following information:

The report field contains a ScanReport object; the stat field contains a FileStat object, and the history field contains an array of ActionResult objects (the history of actions applied to the file).

2)ScanReport is an object containing information about the file with a threat:

The parameter marked with * is optional.

The virus field is an array of VirusInfo objects containing information about all detected threats. The error field is only present if an error has occurred.

3)FileStat is an object containing file statistics:

The parameters marked with * are optional.

The xattr field contains an array of Xattr objects. This object contains two string-type fields: name and value. The uid and gid fields represent User and Group objects that store information about a user/owner and an owner group respectively. These objects contain two fields each:

•uid (gid)—the numeric ID of the user (group);

•username (groupname)—name of the user (group) as a string.

4)ActionResult is an object containing information about the action applied to the file and its result:

The cure_threat, delete_threat, ignore_threat and quarantine_threat commands return an empty object when run successfully. If the requested action to be applied to the threat fails (for example, the threat cannot be neutralized), an Error object is returned instead of an empty object.

6. Managing Quarantine

To manage quarantined threats, HTTP API provides the following commands:

The quarantine command returns the array of QuarantineId objects, each of which contains the identifier of a quarantined object. The identifier consists of two parts: chunk_id and entry_id.

Description of used JSON objects

1)QuarantineId is an object containing parts of the compound identifier of a quarantined object:

A combination of these two fields in the form of <entry_id>@<chunk_id> represents the identifier of a quarantined object. This identifier is provided in all requests for performing actions under any quarantined object using the qentry_info, cure_qentry, delete_qentry and restore_qentry commands. The qentry_info command allows to get the detailed information about a quarantined object with a specified identifier. This command returns a QEntry object.

2)QEntry is an object containing information about a quarantined object:

The parameters marked with * are optional.

The report field contains a ScanReport object, the stat field contains a FileStat object, and the history field contains the history of actions applied to the quarantined object. Each action record is described by a QEntryOperation object. The optional who field contains information about the remote user in the form of a RemoteUser object.

3)QEntryOperation is an object containing information about an operation applied to the quarantined object:

The parameters marked with * are optional.

The action field can have the following values:

•QENTRY_ACTION_DELETE—an attempt to remove the quarantined object;

•QENTRY_ACTION_RESTORE—an attempt to restore the quarantined object;

•QENTRY_ACTION_RESCAN—an attempt to rescan the quarantined object;

•QENTRY_ACTION_CURE—an attempt to cure the quarantined object.

4)RemoteUser is an object containing information about the remote user who owns the file (if the file was relocated to quarantine from the server storage):

The parameters marked with * are optional.

The cure_qentry, delete_qentry and restore_qentry commands return an empty object if the command execution was successful. In case the command failed, an Error object will be returned in the response.

7. HTTP API Usage Examples

To test the HTTP API, you can use the curl utility. The structure and format of the request can be provided as follows:

•the -k option indicates that curl does not have to verify the used SSL certificate;

•the -X options specifies the HTTP method being used (GET or POST);

•the -H option is used to add the Content-Type: application/json header;

•the --data-binary (or -d) option is used to add a JSON object read from a text file to the body request;

•if SCS is used for authorization, the files containing the sent and received SCS cookies must be specified in the -b and -с parameters respectively.

The detailed description of the curl utility options can be displayed using the curl --help and man curl commands.

1.Authorize a client by specifying a user name and a password (for SCS).

An AuthOptions object in the JSON format must be stored in advance in the user.json file. For example:

{"user":"<username>","password":"<passphrase>"}.

Request:

Response:

The Set-Cookie header contains an SCS cookie to be used in all further requests to the HTTP API. If the authorization was successful, the body of the response will contain an empty object. If the user has not been authorized, the Error object is returned:

2.Get information about the threat having the ID = 1 identifier:

Request:

Response:

3.Quarantine the threat having the ID = 1 identifier:

Request:

Response:

4.View the information about the quarantined object:

Request:

Response:

5.Change settings: disable Dr.Web CloudD.

A LexMap object in the JSON format must be stored in advance in the lexmap_ls_off.json file:

{"option":[{"key":"Root","map":{"option":[{"key":"UseCloud","value":{"item":["no"]}}]}}]}

Request:

Response:

6.Change settings: disable Dr.Web CloudD.

A LexMap object in the JSON format must be stored in advance in the lexmap_ls_on.json file:

{"option":[{"key":"Root","map":{"option":[{"key":"UseCloud","value":{"item":["yes"]}}]}}]}

Request:

Response: