Описание HTTP API

В этом разделе

•Общие положения

•Авторизация и идентификация пользователя

•Управление Dr.Web Mail Security Suite

•Проверка объектов

•Управление списком угроз

•Управление карантином

•Примеры использования HTTP API

1.Общие положения

HTTP API представляет собой инструмент для интеграции Dr.Web Mail Security Suite со сторонними приложениями через протокол HTTP (для обеспечения безопасности используется защищенный протокол HTTPS).

Для взаимодействия с API используется протокол HTTP версии 1.0. Во всех запросах используются стандартные методы протокола HTTP — GET и POST. Все данные, за исключением особо оговоренных случаев, передаются в виде JSON-объектов. При передаче JSON-объекта в теле запроса HTTP POST заголовок Content-Type: должен быть установлен в значение application/json. Для ясности примеры JSON-объектов, приведенные ниже, снабжены комментариями (начинаются с символов //), которые не поддерживаются форматом JSON и при вставке в код должны быть удалены.

Формат HTTP-ответа на HTTP-запрос

•В ответ на все запросы API всегда (за исключением особо оговоренных случаев) возвращает JSON-объект. В случае возникновения ошибки API возвращает JSON-объект Error.

•Если поле ответного JSON-объекта имеет тип «массив», но этот массив не содержит ни одного элемента, то в ответе сервера такое поле опускается.

•Заголовок Content-Type: в ответе всегда (за исключением особо оговоренных случаев) имеет значение application/json.

•При попытке обращения к несуществующему ресурсу в ответе возвращается JSON-объект Error, в котором поле code имеет значение EC_UNEXPECTED_MESSAGE.

•Если используется SCS (Secure Cookie Sessions for HTTP), то ответы содержат cookie, подтверждающие авторизацию клиента (здесь и далее — SCS-cookie).

Кодировка строк объектов JSON

•Строки передаются в кодировке UTF-8 (без BOM). В запросах символы вне таблицы ASCII не экранируются последовательностями типа \uXXXX, а передаются в кодировке UTF-8.

•В ответах объекты JSON могут содержать как символы, закодированные в UTF-8, так и экранированные последовательности \uXXXX.

Общие ограничения на передачу данных

•В POST-запросах, в теле которых передается JSON-объект, допустимы любые символы, разрешенные RFC 7159.

•В GET-запросах в URI могут использоваться любые символы, разрешенные RFC 1945.

•В любых других частях запроса (заголовки, тела) также могут быть использованы любые символы, разрешенные RFC 1945.

2.Авторизация и идентификация пользователя

Чтобы начать работу с API, клиент должен быть авторизован сервером. Предусмотрены два способа авторизации:

1.Использование SCS согласно RFC 6896.

2.Использование клиентских сертификатов SSL, удостоверенных сертификатом доверенного ЦС на стороне Dr.Web HTTPD. В этом случае клиент считается авторизованным как суперпользователь (используются клиентские сертификаты X.509).

При авторизации с использованием SCS SCS-cookie передаются в следующих HTTP-заголовках: Cookie: — в запросе, Set-Cookie: — в ответе.
При авторизации с использованием SSL-сертификатов SCS-cookie не требуются.

При авторизации по SCS работа с API начинается с отправки команды login. В случае успешного выполнения этой команды клиент получает SCS-cookie, подтверждающий авторизацию.
При авторизации с помощью клиентского сертификата выполнять команду login не требуется; при попытке ее выполнения будет возвращен JSON-объект Error.

2.1. С помощью логина и пароля (SCS)

Команды авторизации и идентификации клиента:

Команда API

Описание

Действие: Выполнить авторизацию клиента по указанным имени пользователя и паролю для дальнейшей работы с HTTP API. В случае успешной аутентификации возвращается SCS-cookie.

URI: /api/10.2/login

Метод HTTP: POST

Входные параметры: объект AuthOptions

Результат успешного исполнения: пустой объект, SCS-cookie

logout

Действие: Отозвать (деактивировать) выданный ранее SCS-cookie. В ответе на запрос с отозванным SCS-cookie будет возвращен объект Error с ошибкой EC_NOT_AUTHORIZED.

URI: /api/10.2/logout

Метод HTTP: GET

Входные параметры: SCS-cookie

Результат исполнения: пустой объект

whoami

Действие: Получить имя авторизованного пользователя.

URI: /api/10.2/whoami

Метод HTTP: GET

Входные параметры: (SCS-cookie)*

Результат исполнения: объект whoami, (SCS-cookie)

*) Здесь и далее SCS-cookie заключен в скобки, поскольку он необходим только при авторизации через SCS.

Команды авторизации login и logout используются только при авторизации через SCS.

Описание используемых объектов

1)AuthOptions — объект, содержащий логин и пароль пользователя:

{
"user": <строка>, //Имя пользователя
"password": <строка> //Пароль пользователя
}

Вы можете указать любого пользователя, входящего в группу администраторов (sudoers — в Debian и Ubuntu, wheel — в CentOS и Fedora, astra-admin — в Astra Linux, и т. п.). Если пользователь не является членом группы sudoers, в ответе на запрос возвращается ошибка EC_NOT_AUTHORIZED.

2)whoami — объект, содержащий имя пользователя, авторизованного для работы с HTTP API:

{
"whoami":
{
"user": <строка> //Имя пользователя
}
}

3)Error — объект, содержащий информацию о произошедшей ошибке:

{
"error":
{
"code": <строка>, //Строковый код ошибки вида EC_XXX
*"what": <строка> //Описание ошибки
}
}

Символом * помечен необязательный параметр.

JSON-объект Error, возвращаемый командами HTTP API при ошибках обработки запросов, в поле code содержит не числовой код ошибки, а внутренний строковый код, использующийся компонентами Dr.Web Mail Security Suite. Этот код представляет собой строку вида EC_XXX. Для уточнения числового кода и получения описания ошибки обратитесь к разделу Приложение Е. Описание известных ошибок).

2.2. Авторизация по личному сертификату

Этот способ авторизации предполагает использование личного удостоверяющего сертификата, подписанного сертификатом удостоверяющего центра, который указан в настройках Dr.Web HTTPD как доверенный. При авторизации по сертификату все запросы считаются выполняемыми от имени суперпользователя (пользователя root).

Чтобы авторизоваться по личному сертификату пользователя

1.Создайте личный сертификат, подписанный сертификатом удостоверяющего центра.

2.В настройках компонента Dr.Web HTTPD (параметр AdminSslCA) укажите путь к файлу сертификата удостоверяющего центра, которым подписан ваш личный сертификат.

3.При каждом подключении к Dr.Web HTTPD при установлении соединения используйте подписанный сертификат.

При необходимости обратитесь к информации в разделе Приложение Д. Генерация сертификатов SSL.

3.Управление Dr.Web Mail Security Suite

Команды API для просмотра и изменения текущих значений параметров конфигурации:

Команда API	Описание
Команды управления конфигурацией
get_lexmap	Действие: Получить значения параметров текущей конфигурации («лексическая карта» параметров). URI: /api/10.2/get_lexmap Метод HTTP: GET Входные параметры: (SCS-cookie) Результат успешного исполнения: объект LexMaps, (SCS-cookie)
set_lexmap	Действие: Установить или сбросить значения указанных параметров текущей конфигурации (переданных в виде «лексической карты» параметров). URI: /api/10.2/set_lexmap Метод HTTP: POST Входные параметры: (SCS-cookie), объект LexMap Результат успешного исполнения: объект SetOptionResult, (SCS-cookie)
Команды обновления
start_update	Действие: Запустить обновление. URI: /api/10.2/start_update Метод HTTP: POST Входные параметры: (SCS-cookie) Результат успешного исполнения: объект StartUpdate, (SCS-cookie)
stop_update	Действие: Остановить активный процесс обновления. URI: /api/10.2/stop_update Метод HTTP: POST Входные параметры: (SCS-cookie) Результат успешного исполнения: пустой объект, (SCS-cookie)
baseinfo	Действие: Просмотреть информацию о загруженных вирусных базах URI: /api/10.2/baseinfo Метод HTTP: GET Входные параметры: (SCS-cookie) Результат успешного исполнения: объект BaseInfoResult, содержащий объект VirusBaseInfo, (SCS-cookie)
Команды управления лицензией
install_license	Действие: Установить указанный ключевой файл. URI: /api/10.2/install_license Метод HTTP: POST Входные параметры: (SCS-cookie), тело ключевого файла (или архива, содержащего ключевой файл) Результат успешного исполнения: пустой объект, (SCS-cookie)
Команды подключения к серверу централизованной защиты
esconnect	Действие: Включить режим централизованной защиты. URI: /api/10.2/esconnect Метод HTTP: POST Входные параметры: (SCS-cookie), объект ESConnection Результат успешного исполнения: пустой объект, (SCS-cookie)
esdisconnect	Действие: Выключить режим централизованной защиты. URI: /api/10.2/esdisconnect Метод HTTP: POST Входные параметры: (SCS-cookie) Результат успешного исполнения: пустой объект, (SCS-cookie)
Прочее
idpass	Действие: Получить пароль для архива с угрозами, перепакованного Dr.Web MailD. URI: /api/10.2/idpass Метод HTTP: POST Входные параметры: (SCS-cookie), объект IdpassRequest Результат успешного исполнения: строка с паролем, (SCS-cookie)

Конфигурация компонентов возвращается и задается в виде так называемой лексической карты, то есть в виде последовательности пар «параметр»/«значение». Объект LexMaps всегда содержит три вложенных объекта LexMap, содержащих следующие лексические карты:

•active — активные (актуальные на текущий момент) параметры;

•hardcoded — значения по умолчанию (применяются для параметров, значения которых не указаны или указаны некорректно);

•master — карта значений параметров конфигурации, заданных клиентом для использования.

Команда get_lexmap всегда возвращает все три набора значений параметров конфигурации для всех компонентов, которые могут присутствовать в составе Dr.Web Mail Security Suite, а не только тех, которые установлены и работают.

Описание используемых объектов JSON

1)LexMaps — объект, содержащий активную, предопределенную и определенную пользователем лексические карты параметров:

{
"active": <LexMap>, //Активные значения параметров конфигурации
"hardcoded": <LexMap>, //Предопределенные значения параметров конфигурации
"master": <LexMap> //Значения параметров конфигурации, заданные пользователем
}

Каждое из указанных полей является объектом LexMap, который, в свою очередь, содержит массив объектов типа LexOption.

2)LexMap — объект, содержащий лексическую карту параметров:

{
"option": [<LexOption>] //Массив опций конфигурации
}

3)LexOption — объект, содержащий параметр или секцию конфигурации (группу параметров):

{
"key": <строка>, //Имя опции (параметра конфигурации или секции)
*"value": <LexValue>, //Если данная опция является параметром
*"map": <LexMap> //Если данная опция является секцией
}

Символом * помечены необязательные параметры.

Объект LexOption представляет собой секцию или параметр конфигурации Dr.Web Mail Security Suite. Он обязательно содержит поле key, соответствующее имени секции или параметра, а также либо поле value (если объект — это параметр), либо поле map (если это секция). Секция также представляет собой объект типа LexMap, а значение параметра — объект LexValue, содержащий поле item, описывающее значение параметра в строковом виде.

4)LexValue — объект, содержащий массив значений параметра:

{
"item": [<строка>] //Массив значений параметра
}

Команда set_lexmap принимает на вход объект LexMap, который должен содержать те параметры, значения которых необходимо заменить на новые или сбросить в значения по умолчанию. Параметры, которые следует сбросить в значения по умолчанию, не должны содержать поля value. Параметры, не упомянутые в лексической карте, переданной команде set_lexmap, останутся без изменений. В результате исполнения команда set_lexmap возвращает объект SetOptionResult, содержащий измененные значения каждого из указанных в команде параметров.

5)SetOptionResult — объект, поле item которого содержит массив c измененными значениями параметров:

{
"item": [<SetOptionResultItem>] //Массив результатов
}

Объект содержит массив объектов SetOptionResultItem, которые содержат измененные значения каждого из указанных в команде параметров.

6)SetOptionResultItem — объект, содержащий информацию об изменении значения параметра:

{
"option": <строка>, //Имя параметра
"result": <строка>, //Результат изменения значения (код ошибки)
*"lower_limit": <строка>, //Нижняя допустимая граница значений
*"upper_limit": <строка> //Верхняя допустимая граница значений
}

Символом * помечены необязательные параметры.

Поле option содержит в себе имя параметра, к которому применялось действие, а result — результат попытки изменить его значение. Если новое значение было успешно применено, поле имеет значение EC_OK. В случае ошибки в объекте могут присутствовать поля lower_limit и upper_limit, содержащие наибольшее и наименьшее допустимые значения параметра.

7)StartUpdate — объект, содержащий информацию о начатом процессе обновления:

{
"start_update":
{
"attempt_id": <число> //Идентификатор запущенного процесса обновления
}
}

8)ESConnection — объект, содержащий информацию о подключении к серверу централизованной защиты:

{
*"server": <строка>, //<Адрес узла>:<порт> (без префикса http/https)
"certificate": <строка>, //Ключ сервера в base64
*"newbie": <булево значение>, //По умолчанию: false
*"login": <строка>, //Имя пользователя
*"password": <строка> //Пароль
}

Символом * помечены необязательные параметры.

Параметры login и password указываются, если newbie = true.
Перед подключением скачайте с сервера централизованной защиты файл сертификата и выполните команду:

$ cat certificate.pem | base64

Строку, полученную в результате выполнения этой команды, и нужно использовать в качестве значения параметра certificate.

9)BaseInfoResult — объект, содержащий информацию о загруженных вирусных базах:

{
"vdb_base_stamp": <число> //Временная метка базы
"vdb_bases": [<VirusBaseInfo>] //Детальная информация о базе
}

10)VirusBaseInfo — объект, содержащий подробную информацию о вирусной базе:

{
"path": <строка> //Путь до файла базы
"virus_records": <число> //Количество записей в базе
"version": <число> //Версия базы
"timestamp": <число> //Временная метка базы
"md5": <строка> //MD5-хеш базы
"load_result": <строка> //Результат загрузки базы (в случае успешной загрузки — EC_OK)
*"sha1": <строка> //SHA1-хeш базы
}

Символом * помечен необязательный параметр.

11)IdpassRequest — объект, содержащий информацию об архиве, для которого нужно получить пароль:

{
"id": <строка>, //Идентификатор письма
*"secret": <строка> //Секретное слово (необязательное поле)
}

Символом * помечен необязательный параметр.

Если поле secret не указано, то используется значение параметра конфигурации MailD.RepackPassword, если тип пароля не Plain. Если тип пароля Plain, то возвращается ошибка (объект Error) EC_INVALID_ARGUMENT.

4.Проверка объектов

Команды API для проверки объектов:

Команда API	Описание
Проверка данных (используется вызов компонента Dr.Web Network Checker)
scan_request	Действие: Запрос на создание подключения (endpoint) для проверки данных с необходимыми параметрами. URI: /api/10.2/scan_request Метод HTTP: POST Входные параметры: (SCS-cookie), объект ScanOptions Результат успешного исполнения: объект ScanEndpoint, (SCS-cookie)
scan_endpoint	Действие: Запуск проверки данных (например, тела файла) на созданном подключении endpoint. URI: /api/10.2/scan_endpoint/<endpoint> Метод HTTP: POST Входные параметры: (SCS-cookie), проверяемые данные Результат успешного исполнения: объект ScanResult, (SCS-cookie)
scan_path	Действие: Сканирование файла или каталога, расположенного по указанному пути. URI: /api/10.2/scan_path Метод HTTP: POST Входные параметры: (SCS-cookie), объект ScanPathOptions Результат успешного исполнения: объект ScanPathResult, (SCS-cookie)
scan_stat	Действие: Получение статистики сканирования. URI: /api/10.2/scan_stat Метод HTTP: GET Входные параметры: (SCS-cookie), формат статистики (JSON или CSV) Результат успешного исполнения: объект ScanStat (если выбран формат JSON), (SCS-cookie) Если выбран формат CSV, в ответ на запрос будет возвращена таблица, столбцы которой соответствуют полям объекта ScanStat.

Описание используемых объектов JSON

1)ScanOptions — объект, содержащий параметры, используемые при создании endpoint для проверки файлов:

{
"scan_timeout_ms": <число>, //Тайм-аут на проверку файла в мс
"cure": <булево значение>, //Применять ли лечение к инфицированному файлу
"heuristic_analysis": <булево значение>, //Использовать ли эвристический анализ
"packer_max_level": <число>, //Максимальный уровень вложенности для запакованных объектов
"archive_max_level": <число>, //Максимальный уровень вложенности для архивов
"mail_max_level": <число>, //Максимальный уровень вложенности для почтовых объектов
"container_max_level": <число>, //Максимальный уровень вложенности для прочих сложных объектов (контейнеров)
"max_compression_ratio": <число> //Максимальная величина коэффициента сжатия архивов
"min_size_to_scan": <число>, //Минимальный размер объекта для сканирования
"max_size_to_scan": <число>, //Максимальный размер объекта для сканирования
"threat_hash": <булево значение> //Получать ли хеши обнаруженных угроз
}

2)ScanPathOptions — объект, содержащий параметры сканирования файла или каталога по указанному пути:

{
"path": <строка> //Абсолютный путь файла или каталога для сканирования
*"exclude_path": [<строка>] //Список путей, исключенных из сканирования (можно использовать маски)
*"scan_timeout_ms": <число> //Тайм-аут сканирования одного объекта
*"archive_max_level": <число> //Максимальный уровень вложенности для архивных объектов
*"packer_max_level": <число> //Максимальный уровень вложенности для запакованных объектов
*"mail_max_level": <число> //Максимальный уровень вложенности для почтовых сообщений
*"container_max_level": <число> //Максимальный уровень вложенности для прочих сложных объектов (контейнеров)
*"max_compression_ratio": <число> //Максимальная величина коэффициента сжатия архивов
*"heuristic_analysis": <булево значение> //Использовать ли эвристический анализ (по умолчанию true)
*"follow_symlinks": <булево значение> //Переходить ли по символическим ссылкам
*"min_size_to_scan": <число> //Минимальный размер объекта для сканирования
*"max_size_to_scan": <число> //Максимальный размер объекта для сканирования
*"timeout_ms": <число> //Тайм-аут сканирования всех объектов
*"threat_hash": <булево значение> //Возвращать ли SHA1- и SHA256-хеши угроз
}

Символом * помечены необязательные параметры.

3)ScanPathResult — объект, содержащий результаты сканирования файла или каталога по указанному пути:

{
ScanPathResult:
"results": [<ScanResult>] //Результаты сканирования
*"error": <строка> //Ошибка, если процесс завершился с ошибкой (например, по тайм-ауту)
}

Символом * помечен необязательный параметр.

Если сканирование завершено успешно, строка error будет отсутствовать в ответе.

4)ScanResult — объект, содержащий результаты сканирования:

{
ScanResult:
"scan_report": <ScanReport> //Отчет о сканировании
*"sha1": <строка> //Хeш SHA1 угрозы
*"sha256": <строка> //Хeш SHA256 угрозы
}

Символом * помечены необязательные параметры.

5)ScanReport — объект, содержащий информацию о файле с обнаруженной угрозой:

{
ScanReport:
"object": <строка> //Строка, имя просканированного объекта
// Для файла: абсолютный путь, для вложенного объекта — имя файла
// Для вызова scan_endpoint будет всегда указывать на временный файл
*"size": <число> //Размер объекта
*"compressed_size": <число> //Размер объекта в сжатом состоянии
*"core_fingerprint": <строка> //Отпечаток движка
*"packer": [<строка>] //Список упаковщиков, которыми был запакован объект
*"compression_ratio": <число> //Коэффициент сжатия архива
*"archive": <Archive> //Сведения о типе архива (контейнера), если объект распознан как таковой
*"virus": [<Virus>] //Угрозы, обнаруженные в объекте (если найдены)
*"item": [<ScanReport>] //Отчеты о сканировании вложенных объектов (если они были)
*"error": <строка> //Ошибка сканирования (если возникла)
*"heuristic_analysis": <булево значение> //Использовался ли эвристический анализ (true — использовался, false — нет)
*"cured": <булево значение> //Вылечен ли объект (true — вылечен, false — нет)
*"cured_by_deletion": <булево значение> //Удален ли объект в ходе лечения (true — удален, false — нет)
*"new_path": <строка> //Новый путь к объекту, переименованному в ходе лечения
*"user_time": <число> //Время, проведенное в пространстве пользователя
*"system_time": <число> //Время, проведенное в системных вызовах во время сканирования
}

Символом * помечены необязательные параметры.

Поля virus и error могут отсутствовать в ответе, если в ходе сканирования не было найдено никаких угроз или не произошло никаких ошибок. Для вызова scan_endpoint поле scan_endpoint всегда указывает на временный файл, созданный компонентом Dr.Web Network Checker в локальной файловой системе сервера (в этот файл помещаются данные для проверки, отправленные в теле запроса scan_endpoint).

6)ScanEndpoint — объект, содержащий информацию о созданном endpoint для проверки файлов:

{
"endpoint": <строка> //Уникальный идентификатор созданного endpoint
}

Возвращенный в теле объекта идентификатор endpoint используется для запуска проверки файла командой scan_endpoint (как часть URI).

7)VirusInfo — объект, содержащий информацию об обнаруженной угрозе:

{
"type": <строка>, //Тип выявленной угрозы
"name": <строка> //Название угрозы
}

Поле type (тип угрозы) — строка вида SE_XXX:

•SE_KNOWN_VIRUS — известная угроза,

•SE_VIRUS_MODIFICATION — модификация известной угрозы,

•SE_UNKNOWN_VIRUS — неизвестная угроза (подозрительный объект),

•SE_ADWARE — рекламная программа,

•SE_DIALER — программа автодозвона,

•SE_JOKE — программа-шутка,

•SE_RISKWARE — потенциально опасное ПО,

•SE_HACKTOOL — программа взлома.

8)Archive — объект, содержащий информацию об архиве, запакованных объектах, почтовых сообщениях и других контейнерах:

{
"type": <строка> //Тип архива, может принимать одно из значений:
"SE_ARCHIVE" //Архив
"SE_MAIL" //Письмо
"SE_CONTAINER" //Другой тип контейнера
"name": <строка> //Формат архива
}

9)ScanStat — объект, содержащий статистику проверок:

{
"origin": <строка> //Приложение, по запросу которого было выполнено сканирование
#Счетчики зараженных объектов:
"known_virus": <число> //Количество зараженных известными угрозами объектов
"virus_modification": <число> //Количество объектов, зараженных модификацией известной угрозы
"unknown_virus": <число> //Количество зараженных неизвестными угрозами объектов
"adware": <число> //Количество объектов с SE_ADWARE
"dialer": <число> //Количество объектов с SE_DIALER
"joke": <число> //Количество объектов с SE_JOKE
"riskware": <число> //Количество объектов с SE_RISKWARE
"hacktool": <число> //Количество объектов с SE_HACKTOOL
"cured": <число> //Количество вылеченных объектов
"quarantined": <число> //Количество объектов, помещенных в карантин
"deleted": <число> //Количество удаленных объектов
}

5.Управление списком угроз

Для управления списком угроз, обнаруженных при сканировании, доступны следующие команды HTTP API:

Команда API	Описание
threats	Действие: Получить перечень идентификаторов всех обнаруженных угроз. URI: /api/10.2/threats/ Метод HTTP: GET Входные параметры: (SCS-cookie) Результат успешного исполнения: массив идентификаторов угроз
threat_info	Действие: Получить информацию об угрозе с идентификатором <threat ID>. URI: /api/10.2/threat_info/<threat ID> Метод HTTP: GET Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), объект FileThreat
cure_threat	Действие: Попытаться вылечить угрозу с идентификатором <threat ID>. URI: /api/10.2/cure_threat/<threat ID> Метод HTTP: POST Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), пустой объект
delete_threat	Действие: Удалить файл, содержащий угрозу с идентификатором <threat ID>. URI: /api/10.2/delete_threat/<threat ID> Метод HTTP: POST Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), пустой объект
ignore_threat	Действие: Проигнорировать угрозу с идентификатором <threat ID>. URI: /api/10.2/ignore_threat/<threat ID> Метод HTTP: POST Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), пустой объект
quarantine_threat	Действие: Переместить в карантин угрозу с идентификатором <threat ID>. URI: /api/10.2/quarantine_threat/<threat ID> Метод HTTP: POST Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), пустой объект

У каждой найденной угрозы имеется уникальный целочисленный идентификатор <threat ID>. Список идентификаторов всех обнаруженных угроз возвращается командой threats. В командах threat_info, cure_threat, delete_threat, ignore_threat и quarantine_threat можно использовать только идентификаторы угроз из этого списка.

Всю информацию об отдельной угрозе из списка, включая историю действий с ней, возвращает запрос threat_info в виде объекта FileThreat.

Описание используемых объектов JSON

1)FileThreat — объект, содержащий в себе следующую информацию:

{
"threat_id": <число>, //Идентификатор угрозы
"detection_time": <Unix-время>, //Дата и время обнаружения угрозы
"report": <ScanReport>, //Отчет о проверке файла
"stat": <FileStat>, //Информация о файле
"origin": <строка>, //Имя компонента, обнаружившего угрозу
"origin_pid": <число>, //PID компонента, обнаружившего угрозу
"task_id": <число>, //Идентификатор задачи на проверку в сканирующем ядре
"history": [<ActionResult>] //История действий с угрозой (массив)
}

Поле report содержит объект ScanReport; поле stat — объект FileStat, а поле history — массив объектов ActionResult (история действий по отношению к файлу).

2)ScanReport — объект, содержащий информацию о файле с обнаруженной угрозой:

{
"object": <строка>, //Объект файловой системы с угрозой
"size": <число>, //Размер файла с угрозой в байтах
"virus": [<VirusInfo>], //Перечень сведений об обнаруженных угрозах
*"error": <строка>, //Сообщение об ошибке
"heuristic_analysis": <булево значение> //Использовался ли эвристический анализ (true — использовался, false — нет)
}

Символом * помечен необязательный параметр.

Поле virus представляет собой массив объектов VirusInfo, содержащих информацию обо всех обнаруженных угрозах. Поле error присутствует, только если произошла ошибка.

3)FileStat — объект, содержащий статистическую информацию о файле:

{
"dev": <число>, //Устройство
"ino": <число>, //Индексный дескриптор (inode)
*"size": <число>, //Размер файла
*"uid": <User>, //Идентификатор пользователя-владельца
*"gid": <Group>, //Идентификатор группы владельцев
*"mode": <число>, //Режим доступа к файлу
*"mtime": <Unix-время>, //Дата и время модификации файла
*"ctime": <Unix-время> //Дата и время создания файла
*"rsrc_size": <число>, //
*"finder_info": <строка>, //
*"ext_finder_info": <строка>, //
*"uchg": <строка>, //
*"volume_name": <строка>, //Имя тома
*"volume_root": <строка>, //Корень (точка монтирования) тома
*"xattr": [<Xattr>] //Расширенная информация о файле
}

Символом * помечены необязательные параметры.

Поле xattr представляет собой массив объектов Xattr. Этот объект содержит два строковых поля name и value. Поля uid и gid представляют собой объекты User и Group, хранящие информацию о пользователе-владельце и о группе владельцев соответственно. Они содержат по два поля:

•uid (gid) — числовой идентификатор пользователя (группы);

•username (groupname) — строковое имя пользователя (группы).

4)ActionResult — объект, содержащий информацию о действии по отношению к файлу и его результате:

{
"action": <строка>, //Применяемое действие
"action_time": <Unix-время>, //Дата и время применения
"result": <строка>, //Результат применения
"cure_report": <ScanReport> //Отчет о применении действия
}

Команды cure_threat, delete_threat, ignore_threat и quarantine_threat возвращают пустой объект в случае успешного выполнения. Если запрошенное действие с угрозой завершилось ошибкой (например, угрозу не удалось нейтрализовать), то вместо пустого объекта будет возвращен объект Error.

6.Управление карантином

Для управления содержимым карантина, хранящего угрозы, доступны следующие команды HTTP API:

Команда API	Описание
quarantine	Действие: Получить перечень идентификаторов объектов, помещенных в карантин. URI: /api/10.2/quarantine/ Метод HTTP: GET Входные параметры: (SCS-cookie) Результат успешного исполнения: (SCS-cookie), массив объектов QuarantineId (объектов в карантине)
qentry_info	Действие: Получить информацию об изолированном в карантине объекте с идентификатором <entry ID>. URI: /api/10.2/qentry_info/<entry ID> Метод HTTP: GET Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), объект QEntry
cure_qentry	Действие: Выполнить попытку лечения объекта c идентификатором <entry ID>, находящегося в карантине. URI: /api/10.2/cure_qentry/<entry ID> Метод HTTP: POST Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), пустой объект
delete_qentry	Действие: Удалить из карантина объект с идентификатором <entry ID>. URI: /api/10.2/delete_qentry/<entry ID> Метод HTTP: POST Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), пустой объект
restore_qentry	Действие: Восстановить (в исходное местоположение) из карантина объект с идентификатором <entry ID>. URI: /api/10.2/restore_qentry/<entry ID> Метод HTTP: POST Входные параметры: (SCS-cookie) Результат исполнения: (SCS-cookie), пустой объект

Команда quarantine возвращает массив объектов QuarantineId, в котором каждый объект содержит идентификатор объекта, находящегося в карантине. Идентификатор состоит из двух частей: chunk_id и entry_id.

Описание используемых объектов JSON

1)QuarantineId — объект, содержащий части составного идентификатора изолированного объекта:

{
"chunk_id": <строка>,
"entry_id": <строка>
}

Комбинация этих двух полей в виде <entry_id>@<chunk_id> представляет собой идентификатор изолированного объекта, находящегося в карантине. Этот идентификатор указывается во всех запросах на выполнение действий с любым объектом в карантине при помощи команд qentry_info, cure_qentry, delete_qentry и restore_qentry. Команда qentry_info используется для получения подробной информации об изолированном объекте по его идентификатору. Она возвращает объект QEntry.

2)QEntry — объект, содержащий информацию об изолированном объекте:

{
"entry_id": <строка>, //Части идентификатора
*"chunk_id": <строка>, //изолированного объекта
*"quarantine_dir": <строка>, //Каталог карантина
"restore_path": <строка>, //Путь, куда будет восстановлен объект
"creation_time": <Unix-время>, //Дата и время помещения в карантин
"report": <ScanReport>, //Отчет о проверке объекта (см. ScanReport выше)
"stat": <FileStat>, //Статистическая информация о файле (см. FileStat выше)
*"history": [<QEntryOperation>], //История манипуляций с объектом
*"who": <RemoteUser>, //Удаленный владелец файла (если файл был изолирован с файлового хранилища с сетевым доступом)
*"detection_time": <Unix-время>, //Дата и время обнаружения угрозы
*"origin": <строка> //Компонент, обнаруживший угрозу
}

Символом * помечены необязательные параметры.

Поле report содержит объект ScanReport, поле stat — объект FileStat, а в поле history хранится история действий по отношению к изолированному объекту. Каждая запись о действии описывается объектом QEntryOperation. Необязательное поле who содержит информацию об удаленном пользователе в виде объекта RemoteUser.

3)QEntryOperation — объект, хранящий информацию об операции по отношению к объекту в карантине:

{
"action": <строка>, //Действие, применявшееся к объекту (см. обозначения ниже)
"action_time": <Unix-время>, //Дата и время применения действия
"result": <строка>, //Ошибка применения действия (код вида EC_XXX)
*"restore_path": <строка>, //Путь восстановления объекта из карантина (если action = "QENTRY_ACTION_RESTORE")
*"rescan_report": <ScanReport> //Отчет о повторной проверке (если action = "QENTRY_ACTION_RESCAN")
}

Символом * помечены необязательные параметры.

Поле action может принимать следующие значения:

•QENTRY_ACTION_DELETE — попытка удаления объекта из карантина;

•QENTRY_ACTION_RESTORE — попытка восстановления объекта из карантина;

•QENTRY_ACTION_RESCAN — попытка повторной проверки объекта в карантине;

•QENTRY_ACTION_CURE — попытка лечения объекта в карантине.

4)RemoteUser — объект, содержащий информацию об удаленном пользователе-владельце файла (если файл был изолирован с сетевого хранилища):

{
*"ip": <строка>, //IP-адрес пользователя
*"user": <строка>, //Имя пользователя
*"domain": <строка> //Домен пользователя
}

Символом * помечены необязательные параметры.

Команды cure_qentry, delete_qentry и restore_qentry возвращают пустой объект в случае успешного выполнения. Если выполнение команды завершилось ошибкой, в ответе возвращается объект Error.

7.Примеры использования HTTP API

Для проверки работы HTTP API можно воспользоваться утилитой curl. Структуру и формат запроса можно представить следующим образом:

$ curl https://<HTTPD.AdminListen>/<HTTP API URI> -k -X <метод HTTP>
[-H 'Content-Type: application/json' --data-binary '@<файл JSON-объекта>']
[-c <cookie-файл> [-b <cookie-файл>]] [> <файл результата>]

•опция -k указывает, что curl может не проверять корректность используемого SSL-сертификата;

•опция -X используется для указания используемого метода HTTP (GET или POST);

•опция -H используется для добавления заголовка Content-Type: application/json;

•опция --data-binary (или -d) используется для присоединения к телу запроса JSON-объекта, взятого из текстового файла;

•если для авторизации используется SCS, файлы, содержащие передаваемый и принимаемый SCS-cookie, указываются в параметрах -b и -с соответственно.

Подробную информацию об опциях утилиты curl можно получить с помощью команд curl --help и man curl.

1.Авторизовать клиента с указанием имени пользователя и пароля (для SCS).

В файл user.json предварительно должен быть записан объект AuthOptions в формате JSON, например:

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

Запрос:

$ curl https://127.0.0.1:4443/api/10.2/login -k -X POST -H 'Content-Type: application/json' --data-binary '@user.json' -c cookie.file

Ответ:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 2
Set-Cookie: DWToken=6QXy4wn_JGov9A1GohWP_kvMK3dN6ccKegjNgKcmHpb_AqSrHg9cNX_yFJhxPDgr|MTQ2Mjg3Mzg4NQ==|cWd4Ow==|GywBUVOhU4w2LF_BKT5frg==|kR_rip5nrpxWjJ2dfZ7Xfmvi3rE=; Secure; HttpOnly; Max-Age: 900; Path=/
Pragma: no-cache

{}

Заголовок Set-Cookie содержит SCS-cookie, который нужно использовать во всех последующих запросах к HTTP API. В теле объекта в случае успешной аутентификации возвращается пустой объект. Если пользователь не авторизован, возвращается объект Error:

HTTP/1.0 403 Forbidden
Content-Type: application/json
Content-Length: 35
Pragma: no-cache

{"error":{"code":"EC_AUTH_FAILED"}}

2.Получить информацию об угрозе с ID = 1:

Запрос:

$ curl https://127.0.0.1:4443/api/10.2/threat_info/1 -k -X GET -c cookie.file -b cookie.file

Ответ:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 574
Set-Cookie: DWToken=<...>;
Secure; HttpOnly; Max-Age: 900; Path=/
Pragma: no-cache

{"threat_id":1,"detection_time":1462881660,
"report":{"object":"/sites/site1/eicar.com.txt","size":68,"packer":[],
"virus":[{"type":"SE_KNOWN_VIRUS","name":"EICAR Test File (NOT a Virus!)"}],
"heuristic_analysis":true,"core_fingerprint":"0D2DD5A869DAB7AE354153A4D5F70F45",
"item":[],"log":[],"user_time":0,"system_time":0},"stat":{"dev":2049,"ino":898,
"size":68,"uid":{"uid":1000,"username":"user"},"gid":{"gid":1000,"groupname":"user"},
"mode":33204,"mtime":1441028214,"ctime":1460738554,"xattr":[]},
"origin":"APP_COMMAND_LINE_TOOL","origin_pid":2726,"task_id":1,"history":[]}

3.Переместить в карантин угрозу с ID = 1:

Запрос:

$ curl -v -c cookie.jar -b cookie.jar -k -X POST -H 'Content-Type:application/json' https://127.0.0.1:4443/api/10.2/quarantine_threat/1

Ответ:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 2
Set-Cookie: DWToken=<...>; Secure; HttpOnly; Max-Age: 900; Path=/
Pragma: no-cache

{}

4.Просмотреть информацию об изолированном объекте:

Запрос:

$ curl -v -k -X GET -c cookie.jar -b cookie.jar https://127.0.0.1:4443/api/10.2/qentry_info/3070d3ce-7b6e-4143-9d9f-89ba3473a781@801:2108d

Ответ:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 781
Set-Cookie: DWToken=<...>; Secure; HttpOnly; Max-Age: 900; Path=/
Pragma: no-cache

{"entry_id":"3070d3ce-7b6e-4143-9d9f-89ba3473a781","chunk_id":"3830313A3231303864",
"quarantine_dir":"2F686F6D652F757365722F2E636F6D2E64727765622E71756172616E74696E65",
"restore_path":"2E2E2F7473742F65696361722E636F6D2E747874","creation_time":1462888884,
"report":{"object":"/home/user/tst/eicar.com.txt","size":68,"packer":[],
"virus":[{"type":"SE_KNOWN_VIRUS","name":"EICAR Test File (NOT a Virus!)"}],
"heuristic_analysis":true,"core_fingerprint":"467CD4C6D423C55448B71CD5B8152776",
"item":[],"log":[],"user_time":0,"system_time":0},"stat":{"dev":2049,"ino":898,
"size":68,"uid":{"uid":1000,"username":"user"},"gid":{"gid":1000,"groupname":"user"},
"mode":33204,"mtime":1441028214,"ctime":1462888421,"xattr":[]},"history":[],
"detection_time":1462888667,"origin":"APP_COMMAND_LINE_TOOL"}

5.Изменить настройки: выключить Dr.Web CloudD.

В файл lexmap_ls_off.json предварительно должен быть записан объект LexMap в формате JSON:

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

Запрос:

$ curl -v -k -c cookie.jar -b cookie.jar -X POST -H 'Content-Type: application/json' --data-binary '@lexmap_ls_off.json' https://127.0.0.1:4443/api/10.2/set_lexmap

Ответ:

HTTP/1.0 200 OK
Content-Type: application/json
Content-Length: 58
Set-Cookie: DWToken=<...>; Secure; HttpOnly; Max-Age: 900; Path=/
Pragma: no-cache

{"item":[{"option":"Root.UseCloud","result":"EC_OK"}]}

6.Изменить настройки: включить Dr.Web CloudD.

В файл lexmap_ls_on.json предварительно должен быть записан объект LexMap в формате JSON:

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

Запрос:

$ curl -v -k -c cookie.jar -b cookie.jar -X POST -H 'Content-Type: application/json' --data-binary '@lexmap_ls_on.json' https://127.0.0.1:4443/api/10.2/set_lexmap

Ответ: