Содержание

API для проверки объектов внешних систем

API для проверки объектов внешних систем

Kaspersky Anti Targeted Attack Platform предоставляет HTTPS REST интерфейс проверки объектов, хранящихся во внешних системах.

Для проверки объектов, хранящихся во внешних системах, рекомендуется использовать следующий сценарий взаимодействия с Kaspersky Anti Targeted Attack Platform:

Создание запроса на проверку объектов HTTP-методом POST
Создание запроса на получение результатов проверки HTTP-методом GET
Интерфейс API является асинхронным, то есть Kaspersky Anti Targeted Attack Platform выполняет проверку объектов не в момент обращения внешней системы, а в фоновом режиме. Поэтому для получения результатов проверки требуется периодически отправлять запрос от внешней системы HTTP-методом GET. Рекомендуемая периодичность отправки запроса 1 раз в минуту.

Вы также можете настроить отправку уведомлений об обнаруженных объектах в веб-интерфейсе Kaspersky Anti Targeted Attack Platform.
Создание запроса на удаление результатов проверки HTTP-методом DELETE
Вы можете удалить результаты проверки указанного объекта или всех объектов.

Работа с кластером

Если внешняя система представляет собой несколько серверов, объединенных в кластер, рекомендуется использовать один идентификатор (sensorId) для всех серверов. В этом случае в веб-интерфейсе Kaspersky Anti Targeted Attack Platform будет отображаться один запрос на интеграцию для всей системы. При необходимости разграничить получение результатов проверки по отдельным серверам вы можете назначить каждому серверу уникальный идентификатор экземпляра (sensorInstanceId).

Ограничения

В конфигурационном файле Kaspersky Anti Targeted Attack Platform установлены максимально допустимое количество запросов на проверку объектов от внешних систем и максимально допустимый размер проверяемого объекта.

Если превышено максимально допустимое количество одновременных запросов на проверку объектов, Kaspersky Anti Targeted Attack Platform перестает обрабатывать дальнейшие запросы до тех пор, пока количество запросов на проверку объектов не станет меньше максимально допустимого. До этого времени выдается код возврата 429. Необходимо повторить запрос на проверку позже.

Если превышен максимально допустимый размер объекта, Kaspersky Anti Targeted Attack Platform не проверяет этот объект. При создании запроса HTTP-методом POST выдается код возврата 413. Вы можете узнать максимально допустимый размер объекта, просмотрев список ограничений приложения на проверку объектов с помощью метода GET.

В начало

Запрос на проверку объектов

Для создания запроса на проверку объектов используется HTTP-метод POST. Создать запрос можно, например, с помощью утилиты командной строки cURL.

Вы можете задавать параметры выполнения команды cURL с помощью дополнительных ключей (см. таблицу ниже).

Подробную информацию о ключах команд cURL см. в документации cURL.

Синтаксис команды

curl --cert <путь к файлу TLS-сертификата> --key <путь к файлу закрытого ключа> -X POST "<URL-адрес сервера с компонентом Central Node>:<порт, по умолчанию 443>/kata/scanner/v1/sensors/<идентификатор sensorId>/scans?sensorInstanceId=<идентификатор sensorInstanceId>" -F "content=<путь к файлу, который вы хотите проверить>" -F scanId=<идентификатор запроса на проверку> -F "objectType=file"

При успешной обработке запроса отобразится статус "OK".

Параметры

Параметр	Тип	Описание
`sensorId`	string	Уникальный идентификатор внешней системы, используемый для авторизации в Kaspersky Anti Targeted Attack Platform.
`content`	file	Содержимое проверяемого объекта.
`scanId`	string	Уникальный идентификатор запроса на проверку. Должен быть сформирован на стороне внешней системы. Не может содержать пробелы и специальные символы. Не используйте имена файлов в качестве идентификатора запроса на проверку. Если этот параметр не указан, просмотр результатов проверки недоступен.
`objectType`	string	Тип проверяемого объекта. Возможное значения параметра: `file`.
`sensorInstanceId`	string	Уникальный идентификатор экземпляра внешней системы. Экземплярами внешней системы считаются также серверы, объединенные в кластер. Параметр не является обязательным.

Возвращаемое значение

Код возврата	Описание
`200`	Проверка выполнена успешно.
`401`	Требуется авторизация.
`429`	Превышено количество запросов. Повторите запрос позднее.
`500`	Внутренняя ошибка сервера. Повторите запрос позднее.

Пример ввода команды с параметрами

curl --cert /root/cert.pem --key /root/server.key -X POST "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/scans?sensorInstanceId=instance1" -F "content=@/tmp/test" -F scanId=1 -F "objectType=file"

В начало

Запрос на получение результатов проверки

Для создания запроса на получение результатов проверки используется HTTP-метод GET. Создать запрос можно, например, с помощью утилиты командной строки cURL.

Вы можете задавать параметры выполнения команды cURL с помощью дополнительных ключей (см. таблицу ниже).

Подробную информацию о ключах команд cURL см. в документации cURL.

Синтаксис команды

curl --cert <путь к файлу TLS-сертификата> --key <путь к файлу закрытого ключа> -X GET<URL-адрес сервера с компонентом Central Node>:<порт, по умолчанию 443>/kata/scanner/v1/sensors/<идентификатор sensorId>/scans/state?sensorInstanceId=<идентификатор sensorInstanceId>&state=<один или несколько статусов проверки, которые вы хотите отобразить в результатах проверки>"

При успешной отправке запроса отобразится список запросов на проверку объектов и результаты проверки этих объектов. Результаты проверки будут отфильтрованы по статусам, которые вы указали в параметре state. Например, если в запросе на получение результатов проверки вы указали статусы state=processing,detect, отобразятся только запросы на проверку объектов, которые находятся в обработке или в которых приложение обнаружило угрозу.

Параметры

Параметр	Тип	Описание
`sensorId`	UUID	Уникальный идентификатор внешней системы, используемый для авторизации в Kaspersky Anti Targeted Attack Platform.
`state`	array (тип элементов string)	Статус проверки объекта. При указании этого параметра результаты проверки будут отфильтрованы по статусу. Указывайте один или несколько статусов через запятую. Возможны следующие значения параметра: `detect`; `not detected`; `processing`; `timeout`; `error`.
`sensorInstanceId`	string	Уникальный идентификатор экземпляра внешней системы. Экземплярами внешней системы считаются также серверы, объединенные в кластер. Параметр не является обязательным.

Параметр

Тип

Описание

sensorId

UUID

Уникальный идентификатор внешней системы, используемый для авторизации в Kaspersky Anti Targeted Attack Platform.

state

array (тип элементов string)

Статус проверки объекта. При указании этого параметра результаты проверки будут отфильтрованы по статусу.

Указывайте один или несколько статусов через запятую.

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

detect;
not detected;
processing;
timeout;
error.

sensorInstanceId

string

Уникальный идентификатор экземпляра внешней системы. Экземплярами внешней системы считаются также серверы, объединенные в кластер. Параметр не является обязательным.

Ответ

HTTP-код: 200

Формат: JSON

type Response []Scans

type Scans struct {

ScanID integer `json:"scanId"`

State array `json:"state"`

}

Возвращаемое значение

Код возврата	Описание
`204`	Нет содержимого.
`404`	Не найдены результаты проверки по указанному идентификатору.
`500`	Внутренняя ошибка сервера. Повторите запрос позднее.

Пример ввода команды с параметрами, если вы хотите отобразить все статусы проверки объектов в результатах проверки

curl --cert /root/cert.pem --key /root/server.key -X GET "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/scans/state?sensorInstanceId=instance1&state=detect,not%20detected,processing,error,timeout"

В начало

Запрос на удаление результатов проверки

Для создания запроса на удаление результатов проверки одного или нескольких объектов используется метод DELETE. Создать запрос можно, например, с помощью утилиты командной строки cURL.

Синтаксис команды

curl --cert <путь к файлу TLS-сертификата> --key <путь к файлу закрытого ключа> -X DELETE "<URL-адрес сервера с компонентом Central Node>:<порт, по умолчанию 443>/kata/scanner/v1/sensors/<идентификатор sensorId>/scans/<идентификатор scanId>"

При успешной обработке запроса результаты проверки объекта будут удалены. Отобразится статус "OK".

Параметры

Параметр	Тип	Описание
`sensorId`	string	Уникальный идентификатор внешней системы, используемый для авторизации в Kaspersky Anti Targeted Attack Platform.
`scanId`	string	Уникальный идентификатор запроса на проверку объекта. Если этот параметр не задан, будут удалены результаты проверки всех объектов.

Возвращаемое значение

Код возврата	Описание
`200`	Проверка выполнена успешно.
`401`	Требуется авторизация.
`404`	Не найдены результаты проверки по указанному идентификатору.
`500`	Внутренняя ошибка сервера. Повторите запрос позднее.

Пример ввода команды

curl --cert /root/cert.pem --key /root/server.key -X DELETE "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/scans/1"

В начало

Запрос на вывод ограничений приложения на проверку объектов

Для создания запроса на вывод ограничений приложения на проверку объектов (например, по размеру) используется HTTP-метод GET. Создать запрос можно, например, с помощью утилиты командной строки cURL.

Синтаксис команды

curl --cert <путь к файлу TLS-сертификата> --key <путь к файлу закрытого ключа> -X GET "<URL-адрес сервера с компонентом Central Node>:<порт, по умолчанию 443>/kata/scanner/v1/sensors/<идентификатор sensorId>/scans/filters"

При успешной обработке запроса отобразятся ограничения приложения на проверку объектов. Например, ограничение maxObjectSize – максимально допустимый размер объекта, который вы можете отправить на проверку.

Параметры

Параметр	Тип	Описание
`sensorId`	string	Уникальный идентификатор внешней системы, используемый для авторизации в Kaspersky Anti Targeted Attack Platform.

Ответ

HTTP-код: 200

Формат: JSON

type Response struct {

MaxObjectSize integer `json:"maxObjectSize"`

Version string `json:"version"`

}

Возвращаемое значение

Код возврата	Описание
`401`	Требуется авторизация.
`500`	Внутренняя ошибка сервера. Повторите запрос позднее.

Пример ввода команды

curl --cert /root/cert.pem --key /root/server.key -X GET "https://10.10.10.1:443/kata/scanner/v1/sensors/dd11a1ee-a00b-111c-b11a-11001b1f1111/scans/filters"

В начало