Описание HTTP API

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

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

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

•Управление Dr.Web для почтовых серверов UNIX

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

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

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

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

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

Для взаимодействия с API используется протокол HTTP версии 1.0. Во всех запросах используются стандартные методы протокола HTTP — GET и POST. Все данные, за исключением особо оговоренных случаев, передаются в виде JSON-объектов. При передаче JSON-объекта в теле запроса HTTP POST заголовок Content-Type: должен быть установлен в значение application/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": string, //Имя пользователя
"password": string //Пароль пользователя
}

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

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

{
"whoami" :
{
"user": string //Имя пользователя
}
}

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

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

Символом * помечен факультативный параметр.

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

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

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

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

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

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

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

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

3. Управление Dr.Web для почтовых серверов UNIX

Команды 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 для почтовых серверов UNIX, а не только тех, которые установлены и работают.

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

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

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

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

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

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

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

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

Символом * помечены факультативные параметры.

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

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

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

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

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

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

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

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

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

Символом * помечены факультативные параметры.

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

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

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

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

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

Символом * помечены факультативные параметры.

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

$ cat certificate.pem | base64

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

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

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

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

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

Символом * помечен факультативный параметр.

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

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

Символом * помечен факультативный параметр.

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

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

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

Символом * помечены факультативные параметры.

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

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

Символом * помечен факультативный параметр.

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

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

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

Символом * помечены факультативные параметры.

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

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

Символом * помечены факультативные параметры.

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

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

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

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

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

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

Поле 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" : string //Тип архива, может принимать одно из значений:
"SE_ARCHIVE" //Архив
"SE_MAIL" //Письмо
"SE_CONTAINER" //Другой тип контейнера
"name" : string //Формат архива
}

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

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

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

Для управления списком угроз, обнаруженных при сканировании или монитором файловой системы SpIDer Guard, доступны следующие команды 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": number, //Идентификатор угрозы
"detection_time": UNIXTime, //Время обнаружения угрозы
"report": ScanReport, //Отчет о проверке файла
"stat": FileStat, //Информация о файле
"origin": string, //Имя компонента, обнаружившего угрозу
"origin_pid": number, //PID компонента, обнаружившего угрозу
"task_id": number, //Идентификатор задачи на проверку в сканирующем ядре
"history": ActionResult[] //История действий с угрозой (массив)
}

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

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

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

Символом * помечен факультативный параметр.

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

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

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

Символом * помечены факультативные параметры.

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

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

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

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

{
"action": string, //Применяемое действие
"action_time": UNIXTime, //Время применения
"result": string, //Результат применения
"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": string,
"entry_id": string
}

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

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

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

Символом * помечены факультативные параметры.

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

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

{
"action": string, //Действие, применявшееся к объекту (см. обозначения ниже)
"action_time": number, //Время применения действия (UNIX Time)
"result": string, //Ошибка применения действия (код вида EC_XXX)
*"restore_path": string, //Путь восстановления объекта из карантина (если 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": string, //IP-адрес пользователя
*"user": string, //Имя пользователя
*"domain": string //Домен пользователя
}

Символом * помечены факультативные параметры.

Команды 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

Ответ: