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 control and manage Dr.Web for UNIX Mail Servers via the HTTP protocol (to ensure security, the HTTPS protocol is used).

Version 1.0 of the HTTP protocol is used. The API uses the 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, use the Content-Type: header with application/json as its value.

The format of an HTTP response to an HTTP request

•In responses to all requests, except as otherwise specified, JSON objects are returned. If an error occurs while processing a request, an Error JSON will be returned.

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

•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, an Error JSON object with EC_UNEXPECTED_MESSAGE in the code field will be returned.

•If SCS (Secure Cookie Sessions for HTTP) is used (see below), the responses contain the SCS cookie.

Encoding of strings in JSON objects

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

•Strings in the incoming JSON objects may contain both UTF-8 encoded symbols and escaped sequences like \uXXXX.

General restrictions of data transmission

•In POST-requests with JSON objects in the body any symbols complying with RFC 7159 are allowed.

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

•Symbols 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 means of authorization are provided.

1.Using SCS, according to RFC 6896.

2.Using clients’ SSL certificates that are signed with a special certificate which Dr.Web HTTPD regards as a trusted CA’s certificate. In this case the client is treated as if the client had successfully input root credentials to get authorization (X.509 client certificates are used).

If a SCS is used, the cookies confirming the authentication are transferred in the headers: Cookie: in the request and Set-Cookie: in the response.
When authorizing with an SSL certificate, no cookies are used.

When authorizing with SCS, using the API starts with sending the login command. If this command is executed successfully, an SCS cookie is sent to the client in the response.
When authorizing with a client certificate, you do not need to run the login command. If you try to execute it, an Error JSON object will be returned in the response.

2.1. Via specifying login and password (SCS)

User authentication and authorization commands:

*) Here and below the SCS cookie is given in parentheses, because sending/receiving it is required only if authorization via SCS is used.

Description of used objects

1) AuthOptions—an object that contains the login data of a user that needs to be authenticated and authorized to use the full HTTP API:

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

3) Error—an object that contains Information about an error that has occurred:

Asterisk-marked parameter is optional.

2.2. Authentication using a personal certificate

Authentication with an SSL certificate supposes using the personal certificate is signed by a certificate authority certificate specified in the Dr.Web HTTPD settings as trusted. If you are authenticated with a certicate, all your requests are considered a made on behalf of the root user.

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 (parameter AdminSslCA), specify a path to the authority certificate by which your personal certificate is signed.

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. Managing Dr.Web for UNIX Mail Servers

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

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

•active—the current values of the parameters;

•hardcoded—default values automatically assigned to the parameters whose values are missing or invalid;

•master—the values of configuration parameters set by the client.

Description of JSON objects

1) LexMaps—an object that contains the active, the default and the user-set 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 that contains a lexical map of parameters:

3) LexOption—an object that contains a single parameter or a section of the configuration (a section is a group of parameters):

Asterisk-marked parameters are optional.

The LexOption object represents a section or a single parameter of the Dr.Web for UNIX Mail Servers configuration. It always has a key field that corresponds to the name of the section or to the name of the single parameter. Besides this, depending on what this object describes—a single parameter or a section—the object also contains either a value field (in case it describes a single parameter), or a map field (in case it describes a section). Any section is also an object of the LexMap type; whereas the value of a single parameter is an object of the LexValue type that contains an item field specifying the parameter value in the string format.

4) LexValue—an object that contains the array of values assigned to a parameter:

As its input, the set_lexmap command accepts a LexMap object, which must contain all the parameters whose values you want to change to new ones or want to 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 given by you in the set_lexmap command will not be changed. As a result of its execution, the set_lexmap command returns a SetOptionResult object that will contain the results of changing every parameter that was specified in your command.

5) SetOptionResult—an object with an item field that contains an array of results of parameter changes:

The object contains an array of SetOptionResultItem objects that describe the results of making changes to every parameter specified in your command.

6) SetOptionResultItem—an object that contains information about a making a change to a value of some parameter:

Asterisk-marked parameters 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 the new value was assigned successfully to a parameter, then this field will contain EC_OK. In case of an error (if this field is not equal to EC_OK), this object may optionally contain an lower_limit field and an upper_limit field that hold the maximum and the minimum permitted value for this parameter.

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

8) The ESConnection object contains data on the started update process:

Asterisk-marked parameters are optional.

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

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

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

10) The VirusBaseInfo object contains the information on each virus base:

Asterisk-marked parameter is optional.

11) The IdpassRequest object contains data on the password-protected archive:

Asterisk-marked parameter is optional.

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

4. Object Scanning

API commands for scanning objects:

Description of JSON objects

1) ScanOptions is the object that contains parameters used for creating endpoint for file scanning:

2) ScanPathOptions is the object that contains parameters used for scanning a file or a directory located on the path specified:

Asterisk-marked parameters are optional.

3) ScanPathResult is an object that contains results of the scanning of the object located on the path specified:

Asterisk-marked parameter is optional.

If the scanning is successful, the error string is not included in the response.

4) ScanResult is an object that contains the results of scanning:

Asterisk-marked parameters are optional.

5) ScanReport is an object that contains information about the file in which the threat was found:

Asterisk-marked parameters are optional.

The fields virus and error may be absent if no threats are detected and no errors occur 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 local server file system and containing the data for scanning, sent in the body of the scan_endpoint request.

6) ScanEndpoint is an object that contains data on the endpoint, created for file scanning:

The endpoint string, returned in the object body, is used to launch file scanning with the scan_endpoint command (part of URI).

7) VirusInfo is an object that contains information on the detected threat:

The type field (threat type) is the string SE_XXX:

•SE_KNOWN_VIRUS is a known virus;

•SE_VIRUS_MODIFICATION is a modification of known malware;

•SE_UNKNOWN_VIRUS is an unknown virus (suspicious object);

•SE_ADWARE is adware;

•SE_DIALER is a dialer program;

•SE_JOKE is a joke program;

•SE_RISKWARE is a potentially dangerous program;

•SE_HACKTOOL is a hacktool.

8) Archive is an object that contains information on archives, packed objects, e-mail messaged and other containers:

9) ScanStat is an object that contains the scanning statistics:

5. Managing the list of threats

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

Each threat found in the specified application has a unique numeric integer identifier <threat ID>. The list of all identifiers is returned by the threats command. In the threat_info, cure_threat, delete_threat, ignore_threat, and quarantine_threat commands only the identifiers returned by the threats command are allowed.

All information on the specified threat, including actions 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 that contains the following data:

The report field contains the 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 that contains information about the file in which the threat was found:

Asterisk-marked parameter 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 that contains file statistics:

Asterisk-marked parameters 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 contain a User and a Group object respectively, that have information about the file owner and the group owning the file 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 that contains information on the action applied to the file and the result:

The cure_threat, delete_threat, ignore_threat and quarantine_threat commands return an empty object when executed successfully. If the requested action fails, Error object is returned.

6. Managing Quarantine

To manage quarantined objects the following commands are available in the HTTP API:

Each quarantined object has a unique identifier. The list of identifiers represented as of QuarantineId is returned by the quarantine command. The identifier consists of two parts: chunk_id and entry_id.

Description of JSON objects

1) QuarantineId is an object that contains both parts of the two-part identifier of a quarantined object:

These two fields together make up the identifier of a quarantined object. To apply any action to a quarantined object with the help of the qentry_info, cure_qentry, delete_qentry or restore_qentry commands, you should specify the quarantined object general identifier—<entry ID>—written in the form of <entry_id>@<chunk_id>. 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 that contains information about a quarantined object:

Asterisk-marked parameters 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 isolated object. Each action entry is described by a QEntryOperation object. The optional who field contains information about the deleted user in the form of a RemoteUser object.

3) QEntryOperation is an object that contains data on operations applied to the quarantined object:

Asterisk-marked parameters are optional.

The action field can have the following values:

•QENTRY_ACTION_DELETE is an attempt to remove the quarantined object;

•QENTRY_ACTION_RESTORE is an attempt to restore the quarantined object;

•QENTRY_ACTION_RESCAN is an attempt to rescan the quarantined object;

•QENTRY_ACTION_CURE is an attempt to cure the quarantined object.

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

Asterisk-marked parameters are optional.

The cure_qentry, delete_qentry and restore_qentry commands return an empty object if the command execution was successful. In case the requested operation on a quarantined object finished with an error (for instance, the file could not be restored), then, instead of an empty object, an Error object will be returned.

7. Examples of using the HTTP API

To test the work of the HTTP API, you can use the curl utility. The general format of an API call is given below.

•the -k option specifies curl not to verify the SSL certificate;

•the -X options specifies the HTTP method 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 saved in a text file to the request;

•if an SCS is used to get authorization, the files that contain the sent and received SCS cookies need to be specified with the -b and -c parameters respectively.
 
For the detailed description of the curl options refer to the man page (perform curl --help or man curl command).

1.Authenticate and authorize a client by specifying a user name and a password (for an SCS).

An AuthOptions object in the JSON format must be written in advance to a file named user.json. For example:

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

Request:

Response:

The Set-Cookie header field contains an SCS cookie that should be used in all further requests to the HTTP API. The body of the response contains an empty object, if the authentication and authorization were successful. If the user has not been authorized, an Error object is returned:

2.Get the information about the threat with ID = 1:

Request:

Response:

3.Move to quarantine the threat with ID = 1:

Request:

Response:

4.View the information on the quarantined (isolated) object with the specified ID:

Request:

Response:

5.Change a configuration setting: disable Dr.Web CloudD.

A LexMap object in the JSON format must be written in advance to a file named lexmap_ls_off.json:

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

Request:

Response:

6.Change a configuration setting: enable Dr.Web CloudD.

A LexMap object in the JSON format must be saved in a file named lexmap_ls_on.json:

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

Request:

Response: