Kaspersky MLAD: Исользование внутреннего API

1.            Назначение документа

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

2.внутреннему APIKaspersky MLAD - типы входных данных

Вне зависимости от того, какой тип коннектора или интерфейса вы используете для передачи данных в Kaspersky MLAD, вдля общемполучения данных (значения тегов, информацию об инцидентах и целом,артефакты системаработы предполагает работу с двумя принципиально разными типами входных данных

Во-первых, это непрерывные данные от промышленного оборудования (временные ряды). По сути, речь идет о текущих значениях технологических параметров, которые описывают работу промышленной установки, например, температура, вибрация, давление, расход и прочие. И именно с такими данными работает модуль выявления аномалий Kaspersky MLAD, включая обучение моделей и потоковый инференс. При этом речь не обязательно идет об аналоговых величинах – модуль выявления аномалий также поддерживает работу с дискретными сигналами (например, для разметки или диагностических правил)моделей).

Но2.            вОбщая любом случае, речь выше идет о данных вида «метка времени» - «значение».информация

ЧтоНа еслимомент вамнаписания необходимоданной выявлять аномалии не во временных рядах, но в потоке событий от одного или множества источников? Например, от POS-терминалов, банкоматов, потребителей электроэнергии, систем SIEM и так далее. Очевидно, что в данном случае мы имеем дело уже с другим типом данных, а именно с событийными данными. Такие данные помимо метки времени могут содержать (и обычно содержат) несколько дополнительных параметров и свойств. Например, событие от POS-терминала может содержать идентификатор события, ID терминала, номер транзакции, результат операции, дополнительный контекст и т.д.

Для работы с событийными данными и последовательностями событийинструкции в Kaspersky MLAD естьне отдельныйреализован модуль,официальный внешний API, через который называетсяможно Процессорбыло Событийбы (забирать данные во внешние системы. Тем не менее в системе присутствует EventAPI, используемый внутренними сервисами, к которому так же можно подключиться извне.

ВНИМАНИЕ: Описываемый в данном документе механизм подключения не является официальным функционалом Kaspersky ProcessorMLAD)., Данныйи модульпроизводитель входитне внесет составответственности базовойпри поставки,его ноиспользовании для егокоммуникации работыс требуетсявнешними отдельная лицензия.системами.

3.            Описание работы модуля EPКонфигурация

Как было указано выше, основным предназначением Процессора Событий является работа с событийными данными и последовательностями событий.

Очевидно,Таким чтообразом, для работыподключения снеобходимых типомданных данных,нужно которыеотправить содержатсоответствующий большоезапрос количествона важныхнужный полей и метаданных, не подходят классические нейронные сети, которые применяются в модуле выявления аномалий. Поэтому в Процессоре Событий используется особый тип нейросетей, которые называются нейросемантические сети, а также продвинутые методы статистического анализа. Для их работы не требуется предварительное обучение или загрузка, скажем, всего перечняэндпоинт POSAPI-терминалов из примера выше в систему. Обучение происходит «на лету».

ЗаНиже анализбудут событийприведены ипримеры выявлениескриптов аномалийpython для подобных запросов. Но перед этим потребуется несколько предварительных шагов.

Извлечение хеша пароля

Пароль передается в событийныххешированном данныхвиде, впоэтому Процессоредля Событийего отвечаютполучения такпотребуются называемыедополнительные Мониторыдействия, Данных.но Типтолько используемогоодин Мониторараз зависит(при отусловии, решаемойчто задачи.пароль Основныене типы уже включены в состав модуля.меняется).

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

- Открываем страницу логина в системе,MLAD
- Открываем "инструменты разработчика / developer tools" (F12 или правой кнопкой мыши в любом месте страницы -> "Просмотреть код / Inspect")
- В инструментах разработчика открываем вкладку "Network" / "Сеть"
- Вверху вкладки ставим "галочку" "Preserve log", иначе не увидите нужных запросов
- Авторизуемся под нашим пользователем
- Ищем в логе запрос авторизации (/api/authorize/)
- В "payload" будет искомый нами пароль, который мы можем использовать для авторизации в вызывающем API "скрипте".
- Пароль будет в виде хеша, например: "7DFcwe0I6Ult8w422gQgWg2TPUXKPYXlkRFlWvhkrPKAs8kfWcInbHo7UYiKMVYUa/rHQ7K7GtEvP8S2ZLJQAw=="
- Используем этот хеш в переменной ‘USER_PASSWORD’в основном скрипте

Поиск нужных UUID

Нужные нам UUID моделей и мывообще хотимлюбых выявлятьэлементов входможно пользователейпосмотреть в системувеб-интерфейсе с необычного для них хоста.MLAD.

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

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

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

Теперь каждый раз, когда у нас будет прилетать новое событие с новым для нас значением поля UserHost, мы будем получать срабатывание монитора.

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

Предположим, перед нами стоит задача выявления необычной активности по событиям в разрезе времени суток. Для простоты, пусть это будет выявление активности пользователей некой доменной группы в необычное для них время.

Для решения подобного класса задач существует свой тип монитора:

При работе данного монитора (и большинства других) обычно требуется сфокусироваться на определенном параметре события, например на доменной группе, в разрезе которой мы мониторим активность, или на IP хостов, которые проявляют активность. Также может потребоваться отфильтровать не нужные параметры событий и работать только с важными параметрами.

Для этого в EP существуют дополнительные сущности, которые называются Головы Внимания. Они позволяют задать предмет внимания, на котором будет фокусироваться монитор, и условия по отдельным параметрам события.

На скриншоте выше мы создаем новую голову внимания, которая фокусируется на IP адресе хоста и фильтрует события по вердикту системы контроля доступа. При этом в перечень обрабатываемых параметров события так же попадает IP адрес узла назначения.

Далее при создании Монитора мы указываем голову внимания, с которой он будет работать.

После активацииэтого мониторможно будет мониторить входящий поток событий и выявлять аномалии по времени активности для каждого хоста.

Большая часть мониторов (за исключением разве что монитора, выявляющего эксфильтрацию данных поскопировать DNSUUID) являетсяиз универсальнойадресной и может быть использована для решения широкого спектра задач.

К примеру, Монитор, выявляющий статистические аномалии может быть использован для выявления майнеров в электрической сети.строки:

ДляАналогично, этогочтобы мыузнать создаемномер головунужного внимания, которая фокусируется на потребителях и изучает данные об их электропотреблении.тега:

Запрос значений тегов и предиктов через API

ИНиже далееприведен создаемпример мониторскрипта для выявлениязапроса статистическихзначений аномалийтегов и артефактов работы моделей:

# импортируем нужные модули

import requests

import json

import logging

import time

from datetime import datetime

# учетная запись пользователя, от имени которого происходит подключение

USER_EMAIL = test@admin.com

# пароль в хешированном виде – см. инструкцию по извлечению хеша пароля выше

USER_PASSWORD = "z24y0qIWIn/zfnbI8YJlO3K+E38GcKtY8kRTyU2moNagGLUABgl9HeJrHWWblGdOE9cNmey2s3szM0Iy3v9l4w==" #hashed password

# IP адрес или имя хоста Kaspersky MLAD

MLAD_HOST = "192.168.179.131"

requests.packages.urllib3.disable_warnings()

logging.basicConfig(

    level=logging.INFO,

    format='%(asctime)s - %(levelname)s - %(message)s',

    datefmt='%Y-%m-%d %H:%M:%S'

)

logging.info(f"{20*'-'}START{20*'-'}")

auth_response = requests.post(

url=f'https://{MLAD_HOST}/api/authorize/',

json={

'username': USER_EMAIL,

'password': USER_PASSWORD,

},

verify=False,

)

logging.info(json.dumps(auth_response.json(), indent=4))

# timestamp - момент времени, от которого все будет рассчитываться, задается в миллисекундах

# для отправки запроса в реальном времени можно брать текущую метку времени:

# int(time()*1000)

timestamp_string = '2026-03-12 12:00:00'

timestamp_format = '%Y-%m-%d %H:%M:%S'

timestamp_obj = datetime.strptime(timestamp_string, timestamp_format)

timestamp_ms = int(timestamp_obj.timestamp() * 1000)

logging.info(f'{timestamp_obj} = {timestamp_ms} ms')

# period (ms)- Период, за который планируется достать данные из истории в миллисекундах. На странице истории выбирается из выпадающего списка.

# если мы хотим значение за конкретную метку времени, то можно поставить значение значительно ниже дискретности, с использованиемкоторой даннойприходят головыданные, вниманиянапример, 10мс

# interval (ms) - интервал группировки (ресемпл) данных. Если данные приходят очень часто, то позволит группировать данные по окнам

# Если мы хотим получать одно значение раз в 5 минут, но не знаем точные метки времени, можно отправлять запрос каждые (T<5min) минут и указать период равный T. В таком случае будет возвращаться либо одно значение, либо ни одного.

# timestamp_position - Позиционирование центра времени, т.к. timestamp - обычно `center` т.е. значения будут браться по обе стороны от него.

# Т.е. если мы говорим "дай данные за 1 минуту", значит возьмутся 30 секунд до заданного timestamp и 30 секунд после. В целом можно не менять.

# element_uuid_list - UUID элементов моделей, чьи артефакты необходимо получить наравне с тегами

request_data = {

'period': 300000,

'interval': 150000,

'tag_id_list': [76], # список с номерами тегов – можно посмотреть во вкладке Активы

'timestamp_position': 'center',

'timestamp': timestamp_ms,

# element_uuid_list – список с UID моделей, из которых мы хотим брать предсказания для тегов из списка tag_id_list. Можно посмотреть в адресной строке браузера после выбора соответствующей модели в веб-интерфейсе – см инструкцию выше

'element_uuid_list': [

'ca6e5966-1c7f-11f1-8bb3-72a1019c5619'

],

}

history_data = requests.post(

url=f'https://{MLAD_HOST}/api/trends/',

json=request_data,

verify=False,

headers={

'Token': auth_response.json()['token'],

}

)

logging.info(json.dumps(history_data.json(), indent=4))

# Пример вывода:

# 2026-03-13 13:25:29 - INFO - 2026-03-12 12:00:00 = 1773306000000 ms

# 2026-03-13 13:25:29 - INFO - {

    # "REAL": {

        # "76": [

            # {

                # "timestamp": 1773306080000000000,

                # "y": 997.8019959509448

            # }

        # ]

    # },

    # "PRED": {

        # "ca6e5966-1c7f-11f1-8bb3-72a1019c5619": {

            # "76": [

                # {

                    # "timestamp": 1773306080000000000,

                    # "y": 1002.8917846679688

                # }

            # ]

        # }

    # },

    # "DIFF": {

        # "ca6e5966-1c7f-11f1-8bb3-72a1019c5619": {

            # "76": [

                # {

                    # "timestamp": 1773306080000000000,

                    # "y": 0.002571807693983069

                # }

            # ],

            # "ca6e5966-1c7f-11f1-8bb3-72a1019c5619": [

                # {

                    # "timestamp": 1773306080000000000,

                    # "y": 0.6879152193599999

                # }

            # ]

        # }

    # },

    # "tags_order": [

        # 76

    # ],

    # "tag_independent": [

        # "ca6e5966-1c7f-11f1-8bb3-72a1019c5619"

    # ]

# }

#- REAL - Измеренные (реальные) значения по запрошенным тегам

#- PRED - Предсказания значения тегов, сделанные конкретными элементами модели (сгруппированные по UUID элементам модели)

#- DIFF - Артефакты элементов модели, так же сгруппированы по UUID элемента модели. Могут внутри содержать как артефакты по тегам, так и собственные

#- RULE - Артефакты элементов типа "Правило"

#- tags_order - порядок тегов, нужно для UI.

#- tag_independent - перечисление всех артефактов, нужно для UI.

#Некоторых ключей может не быть, если при заданных параметрах, не окажется данных.

Запрос инцидентов через API

Пример кода для запроса инцидентов:

Послеstart_date активации= данногоdatetime(2024, монитора,1, ему1, на0, вход0, можно0).isoformat()
end_date подавать= получасовыеdatetime(2024, данные12, потребления31, ЭЭ23, по59, десяткам59).isoformat()
incidents или= дажеrequests.get(
 сотням   тысячf'https://mlad/api/incidents/external?start_date={start_date}&end_date={end_date}',
 потребителей,   иverify=False,
 он   будетheaders={
 выявлять       сложные'Token': статистическиеauth_response.json()['token'],
 аномалии   в потреблении ЭЭ по каждому из них.},
)

4.            Заключение

Инструменты процессора событий позволяют решать предметные задачи, стоящие перед пользователями системы. Функционал Мониторов событий и голов внимания не ограничивает их применение определенным кругом задач, так что они могут использоваться в абсолютно разных сценариях. В дальнейшем перечень мониторов внимания будет расширяться, в том числе под требования Заказчиков.