Содержание

API для получения внешними системами информации о событиях приложения

API для получения внешними системами информации о событиях приложения

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

Вы можете указать в параметрах запроса фильтры, чтобы получить информацию только о тех событиях, которые удовлетворяют требуемым условиям.

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

Информация о новых событиях доступна для получения не более двух часов после их появления в базе Kaspersky Anti Targeted Attack Platform.

Особенности работы в распределенном решении

Если приложение работает в режиме распределенного решения, то вам нужно настроить интеграцию с внешней системой для каждого сервера PCN и SCN, с которого вы хотите получать события, отдельно. Ограничение связано с тем, что в веб-интерфейсе сервера PCN отображается информация обо всех событиях, однако в базе событий хранятся только те события, которые были зарегистрированы на этом сервере.

В начало

Запрос на вывод информации о событиях

Для создания запроса на вывод информации о событиях используется HTTP-метод GET.

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

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

При первом запросе Kaspersky Anti Targeted Attack Platform создает ContinuationToken (далее также "токен"). Приложение передает события, доступные в системе на момент создания токена. При создании нового токена Kaspersky Anti Targeted Attack Platform отправляет события, доступные в системе на момент создания этого токена.

Токен содержит информацию о том, какие данные были переданы последними. Если вы хотите получать события, записанные с момента последнего запроса, вам нужно сохранить созданный токен и использовать его в следующих запросах.

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

Для первого запроса:

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

При успешной обработке запроса отобразится информация о запрошенных событиях и значение токена.

Для следующих запросов:

При успешной обработке запроса отобразится информация о событиях, полученных с момента последнего запроса.

Вы можете создать запрос на вывод информации о событиях, указав максимальные время сбора и количество событий, а также параметры фильтрации событий:

curl --cert <путь к файлу TLS-сертификата> --key <путь к файлу закрытого ключа> -X GET "<URL-адрес сервера с компонентом Central Node>:<порт, по умолчанию 443>/kata/events_api/v1/<идентификатор external_system_id>/events?filter=<фильтр для событий>&max_timeout=<максимальное время сбора событий>&max_events=<максимальное количество событий>&continuation_token=<значение токена, полученное при первом запросе>"

Если при первом запросе вы указали значение параметра filter, при повторном запросе вы можете его не указывать: параметры фильтрации сохраняются от предыдущего запроса и используются в случае, если не указаны новые. Если вы не хотите использовать фильтрацию, не указывайте значение для параметра.

Параметры

Параметр	Тип	Описание
`external_system_id`	UUID	Уникальный идентификатор внешней системы, используемый для авторизации в Kaspersky Anti Targeted Attack Platform.
`filter`	string	Параметры фильтрации событий. Задаются с помощью языка запросов для работы с событиями.
`max_timeout`	int	Максимальное время сбора событий. Указывается в формате PT<значение, выраженное целым числом>S. Например, PT300S. Сервер отправляет информацию о событиях, собранную за указанное время. Значение по умолчанию – 5 минут. Это значение используется, если в запросе не указано другое. Максимальное время сбора событий не должно превышать 5 минут. Если вы укажете значение, превышающее 5 минут, сервер Central Node вернет ошибку. Фактическое полное время ожидания событий может быть увеличено.
`max_events`	int	Максимальное количество событий. Если в запросе не указано значение, Kaspersky Anti Targeted Attack Platform вычисляет его, исходя из количества хостов, на которые установлен компонент Endpoint Agent. Примеры значений для типовых конфигураций: Для 1000 хостов – 64000. Для 5000 хостов – 128000. Для 10000 хостов – 208000. Для 15000 хостов – 288000. Для 30000 хостов – 528000. Указанное в запросе значение не должно их превышать.
`continuation_token`	string	Значение токена.

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

curl --cert <путь к файлу TLS-сертификата> --key <путь к файлу закрытого ключа> -X GET "https://10.10.0.22:443/kata/events_api/v1/c440a37b-5c01-4505-a30e-3d23b20dd609/events?
filter=EventType=='threatdetect' OR EventType=='threatprocessingresult'&max_timeout=PT300S&max_events=64000&continuation_token=
CiQyZDcyNjNiOS0zZmNlLTQxNzktYTdhOC03N2E0ZmUwNjNjMTkSBAgAEAoSBAgBEAMSBAgCEAsSBAgDEAcSBAgEEAgSBAgFEAkSBAgGEAQSBAg
HEAUSBAgIEAcSBAgJEAMYiYyCmvIw"

Если значения параметров содержат специальные символы, вам необходимо в запросах использовать кодирование URL или команду
--data-urlencode.

Пример ввода команд с параметрами c использованием кодирования URL

curl --cert <путь к файлу TLS-сертификата> --key <путь к файлу закрытого ключа> -X GET "https://10.10.0.22:443/kata/events_api/v1/c440a37b-5c01-4505-a30e-3d23b20dd609/events?
filter=EventType=='threatdetect' OR EventType=='threatprocessingresult'&max_timeout=PT300S&max_events=64000&continuation_token=
CiQ%3Dcy%7ENiOS0zZmNlLTQxNzktYTdhOC03N2E0Z40%wNjNjMTkSBAgAEAoSBAgB%5EMSB%3CEAsSBAgDEAcSBAgEEAgSBAgFEAkSBAgGEAQSBAg
HEAUSBAgIEAcSBAgJEAMYiYyCmvIw"

Пример ввода команд с параметрами c использованием команды --data-urlencode

curl --cert <путь к файлу TLS-сертификата> --key <путь к файлу закрытого ключа> --GET -d "max_events=64000" -d "max_timeout=PT300S" -d "filter=EventType=='threatdetect'" --data-urlencode "continuation_token=
CiQ?Dcy~NiOS0zZmNlLTQxNzktYTdhOC03N2E0Z@wNjNjMTkSBAgAEAoSBAgB^MSB?CEAsSBAgDEAcSBAgEEAgSBAgFEAkSBAgGEAQSBAg
HEAUSBAgIEAcSBAgJEAMYiYyCmvIw" https://10.10.0.22:443/kata/events_api/v1/c440a37b-5c01-4505-a30e-3d23b20dd609/events

Ответ

HTTP-код: 200

Формат: JSON

type Response struct {

Events array `json:"events"`

ContinuationToken string `json:"continuationToken"`

}

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

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

В начало

Язык запросов для фильтрации событий

Язык запросов для фильтрации событий поддерживает следующие функции и операторы:

Функции: in.
Операторы сравнения для значений типа String или Boolean:
- ==.
- !=.
Операторы сравнения для чисел и переменных:
- AND.
- OR.
- NOT.
- ==.
- !=.
- >.
- >=.
- <.
- <=.

Вы можете посмотреть список полей, по которым можно отфильтровать события, в разделе Поля для фильтрации событий.

Если вы хотите получить информацию о событиях разного типа, вам нужно создать отдельный запрос для каждого типа событий.

EventType=='threatdetect' OR EventType=='threatprocessingresult'

Поддерживаются константы числового и строкового типа. Строковые константы заключаются в апострофы: 'example'. Для строковых констант поддерживаются метасимволы * и ?. Если вы не хотите использовать метасимволы, вам нужно экранировать их: \*, \?. Также в строковых константах вам нужно экранировать специальные символы.

В начало

Поля для фильтрации событий

Список полей для фильтрации событий приведен в таблице ниже.

Если значения полей содержат специальные символы, вам необходимо в запросах использовать кодирование URL или команду
--data-urlencode.

Список полей для фильтрации событий

Название поля	Тип	Описание
HostName	string	Имя хоста.
HostIp	string	IP-адрес хоста.
EventType	string	Тип события. Может иметь следующие значения: process – запущен процесс. process_terminate – завершен процесс. module – загружен модуль. connection – удаленное соединение. applock – правило запрета. blockdocument – заблокирован документ. filechange – изменен файл. windowsevent – журнал событий ОС. registry – изменение в реестре. portlisten – прослушан порт. driver – загружен драйвер. threatdetect – обнаружение. threatprocessingresult – результат обработки обнаружения. amsiscan – AMSI-проверка. process_interpretated_file_run – интерпретированный запуск файла. process_console_interactive_input – интерактивный ввод команд в консоли.
UserName	string	Имя пользователя.
OsFamily	string	Семейство операционной системы.
OsVersion	string	Версия операционной системы, используемой на хосте.
Ioa.Rules.Id	string	Идентификатор правила TAA (IOA).
Ioa.Rules.Name	string	Информация о результатах исследования файла с помощью технологии Targeted Attack Analyzer: название правила TAA (IOA), по которому было выполнено обнаружение.
Ioa.Rules.Techniques	string	Техника MITRE.
Ioa.Rules.Tactics	string	Тактика MITRE.
Ioa.Severity	string	Степень важности, присвоенная событию, выполненному по этому правилу TAA (IOA). Может иметь следующие значения: Low. Medium. High.
Ioa.Confidence	string	Уровень надежности в зависимости от вероятности ложных срабатываний правила. Может иметь следующие значения: Low. Medium. High.
FileCreationTime	integer	Время создания файла.
DllCreationTime	integer	Время создания библиотеки DLL.
DroppedCreationTime	integer	Время создания измененного файла.
InterpretedFileCreationTime	integer	Время создания интерпретируемого файла.
FileName	string	Имя файла.
DllName	string	Имя библиотеки DLL.
DroppedName	string	Имя измененного файла.
BlockedName	string	Имя заблокированного файла.
InterpretedFileName	string	Имя интерпретируемого файла.
FilePath	string	Путь к директории, в которой располагается файл.
DllPath	string	Путь к директории, в которой располагается библиотека DLL.
DroppedPath	string	Путь к директории, в которой располагается измененный файл.
BlockedPath	string	Путь к директории, в которой располагается заблокированный файл.
InterpretedFilePath	string	Путь к директории, в которой располагается интерпретируемый файл.
FileFullName	string	Полный путь к файлу. Включает путь к директории и имя файла.
DllFullName	string	Полный путь к библиотеке DLL. Включает путь к директории и имя файла.
DroppedFullName	string	Полный путь к измененному файлу. Включает путь к директории и имя файла.
BlockedFullName	string	Полный путь к заблокированному файлу. Включает путь к директории и имя файла.
DetectedName	string	Полный путь к обнаруженному файлу. Включает путь к директории и имя файла.
OriginalFileName	string	Полный путь к исходному файлу. Включает путь к директории и имя файла.
InterpretedFileFullName	string	Полный путь к интерпретируемому файлу. Включает путь к директории и имя файла.
FileModificationTime	integer	Время изменения файла.
DllModificationTime	integer	Время изменения библиотеки DLL.
DroppedModificationTime	integer	Время изменения измененного файла.
InterpretedFileModificationTime	integer	Время изменения интерпретируемого файла.
FileSize	integer	Размер файла.
DllSize	integer	Размер библиотеки DLL.
DroppedSize	integer	Размер измененного файла.
InterpretedFileSize	integer	Размер интерпретируемого файла.
Md5	string	MD5-хеш файла.
DllMd5	string	MD5-хеш библиотеки DLL
DroppedMd5	string	MD5-хеш измененного файла.
InterpretedMd5	string	MD5-хеш интерпретируемого файла.
DetectedMd5	string	MD5-хеш обнаруженного файла.
Sha256	string	SHA256-хеш файла.
DllSha256	string	SHA256-хеш библиотеки DLL.
DroppedSha256	string	SHA256-хеш измененного файла.
BlockedSha256	string	SHA256-хеш заблокированного файла.
InterpretedSha256	string	SHA256-хеш интерпретируемого файла.
DetectedSha256	string	SHA256-хеш обнаруженного файла.
HijackingPath	string	Вредоносная DLL, помещенная в директорию по стандартному пути обхода, чтобы система загрузила ее раньше, чем исходную DLL.
LogonRemoteHost	string	IP-адрес хоста, с которого был выполнен удаленный вход.
RealUserName	string	Имя пользователя, назначенное ему при регистрации в системе.
EffectiveUserName	string	Имя пользователя, которое было использовано для входа в систему.
Environment	string	Переменные окружения.
ProcessType	integer	Тип процесса. Может иметь следующие значения: 1 – exec. 2 – fork. 3 – vfork. 4 – clone.
LinuxOperationResult	string	Результат операции. Может иметь следующие значения: success. failed.
SystemPid	integer	Идентификатор процесса.
ParentFileFullName	string	Путь к файлу родительского процесса.
ParentMd5	string	MD5-хеш файла родительского процесса.
ParentSha256	string	SHA256-хеш файла родительского процесса.
StartupParameters	string	Параметры запуска процесса.
ParentSystemPid	integer	Идентификатор родительского процесса.
ParentStartupParameters	string	Параметры запуска родительского процесса.
Method	string	Метод HTTP-запроса.
Direction	string	Направление соединения. Может иметь следующие значения: inbound. outbound.
LocalIp	string	IP-адрес локального компьютера, с которого была произведена попытка удаленного соединения.
LocalPort	integer	Порт локального компьютера, с которого была произведена попытка удаленного соединения.
RemoteHostName	string	Имя компьютера, на который была произведена попытка удаленного соединения.
RemoteIp	string	IP-адрес компьютера, на который была произведена попытка удаленного соединения.
RemotePort	integer	Порт компьютера, на который была произведена попытка удаленного соединения.
URI	string	Адрес ресурса, к которому произведен запрос HTTP.
KeyName	string	Путь к ключу реестра.
ValueName	string	Имя параметра реестра.
ValueData	string	Значение параметра реестра.
RegistryOperationType	integer	Тип операции с реестром. Может иметь следующие значения: 0 – создан ключ реестра. 1 – удален ключ реестра. 2 – изменен реестр. 3 – переименован ключ реестра.
PreviousKeyName	string	Предыдущий путь к ключу реестра.
PreviousValueData	string	Предыдущее имя параметра реестра.
System.EventID.value	string	Идентификатор типа события безопасности в журнале Windows.
LinuxEventType (поле используется для получения типа события, зафиксированного в журнале событий операционных систем Linux и macOS)	string	Тип события. Может иметь следующие значения: NewUserCreated – создана учетная запись. UserAccountDeleted – учетная запись пользователя удалена. GroupCreated – создана группа. GroupDeleted – изменена группа. MemberAddedToGroup – учетная запись добавлена в группу. UserPasswordChanged – изменен пароль учетной записи. LinuxAuth – выполнена аутентификация в ОС Linux и macOS. LinuxSessionStart – запущена сессия в ОС Linux и macOS. LinuxSessionEnd – завершена сессия ОС Linux и macOS. ServiceStart – запущена служба. ChangeAccountExpirationDate – изменен срок действия учетной записи. OperatingSystemShuttingDown – выключена операционная система. OperatingSystemStarted – запущена операционная система. ModifyPromiscuousMode – изменена работа неразборчивого режима. AuditdConfigurationChanged – изменены настройки аудита.
System.Channel.value	string	Имя журнала.
System.EventRecordID.value	string	Идентификатор записи в журнале
System.Provider.Name.value	string	Идентификатор системы, записавшей событие в журнал.
EventData.Data.TargetDomainName.value	string	Доменное имя удаленного компьютера.
EventData.Data.ObjectName.value	string	Имя объекта, инициировавшего событие.
EventData.Data.PackageName.value	string	Имя пакета, инициировавшего событие.
EventData.Data.ProcessName.value	string	Имя процесса, инициировавшего событие.
VerdictName	string	Имя обнаруженного объекта.
RecordId	integer	Идентификатор сработавшего правила.
ProcessingMode	string	Режим проверки. Может иметь следующие значения: Default – по умолчанию. OnDemand – при запросе. OnAccess – при доступе. OnExecute – при выполнении. OnDownload – при загрузке. OnStartup – при запуске приложений. OnMail – при отправке сообщения. OnPostpone – при отложенной проверке. OnDisinfect – при лечении. OnVulnerability – при поиске уязвимостей. OnFirstLaunch – при первом запуске. OnEngineLoad – при запуске системы. OnQuarantineRescan – при повторной проверке объектов в Хранилище. OnWebRequest – при веб-запросе. OnAmsiScan – при проверке AMSI. OnSystemWatcherScan – при анализе поведения приложений.
DetectedName	string	Имя объекта.
DetectedObjectType	string	Тип объекта. Может иметь следующие значения: Unknown – неизвестно. File – файл. LogicalDrive – логический диск. PhysicalDisk – физический диск. SystemMemory – системная память. MemoryProcess – память процесса. MemoryModule – модуль памяти. MailMsgRef – заголовок References сообщения электронной почты. MailMsgMime – MIME-вложения. MailMsgBody – текст сообщения электронной почты. MailMsgAttach – вложение сообщения электронной почты. StartUp – объекты автозапуска. Folder – директория. Script – скрипт. Url – URL-адрес. AmsiStream – поток проверки AMSI.
ThreatStatus	string	Режим обнаружения. Может иметь следующие значения: Untreated – объект не обработан. Untreatable – объект не поддается обработке. NotFound – объект не найден. Disinfected – объект вылечен. Deleted – объект удален. Quarantined – объект помещен на карантин. AddedByUser – объект добавлен пользователем. Unknown – неизвестно. AddedToExclude – объект добавлен в исключения. Terminated – обработка прервана. Clear – объект не заражен. FalseAlarm – ложное срабатывание. RolledBack – выполнен откат к предыдущему состоянию. IpNotBlocked – IP-адрес не заблокирован. IpBlocked – IP-адрес заблокирован. IpCannotBeBlocked – IP-адрес не может быть заблокирован. IpBlockIsNotRequired – не требуется блокировка IP-адреса.
UntreatedReason	string	Статус обработки объекта. Может иметь следующие значения: None – нет данных. NonCurable – объект невозможно вылечить. Locked – объект заблокирован. ReportOnly – приложение работает в режиме Только отчет. NoRights – нет прав на выполнение действия. Cancelled – обработка отменена. WriteProtect – объект защищен от записи. TaskStopped – задача на обработку прервана. Postponed – действие отложено. NonOverwritable – объект невозможно перезаписать. CopyFailed – не удалось создать копию объекта. WriteError – ошибка записи данных. OutOfSpace – нет места на диске. ReadError – ошибка чтения данных. DeviceNotReady – устройство не готово. ObjectNotFound – объект не найден. WriteNotSupported – запись данных не поддерживается. CannotBackup – не удалось создать резервную копию объекта. SystemCriticalObject – объект является критическим для системы. AlreadyProcessed – объект уже был обработан.
InteractiveInputText	string	Команда интерпретатора.
ObjectContent	string	Содержание скрипта, переданного на проверку.
ObjectContentType	integer	Тип содержимого скрипта. Может иметь следующие значения: 1 – текст. 2 – двоичный код.
FileOperationType	integer	Тип операции с файлом. Может иметь следующие значения: 1 – создан файл. 2 – изменен файл. 3 – переименован файл. 4 – изменены атрибуты файла. 5 – удален файл. 6 – прочитан файл.
PreviousFileName	string	Путь к директории, в которой файл располагался ранее.
PreviousFileFullName	string	Полное имя файла, включающее предыдущий путь к директории, в которой файл располагался ранее, и / или предыдущее имя файла.
DroppedFileType	integer	Тип измененного файла. Может иметь следующие значения: 0 – неизвестно. 1 – другие файлы. 2 – образ PE. 3 – PE DLL. 4 – ресурсы PE. 5 – файл ресурсов .NET. 6 – файл ELF.

В начало