Триггер плейбука

Триггер плейбука – это фильтр, позволяющий выбрать алерты или инциденты, для которых необходимо запустить плейбук. Фильтр (триггер) применяется к каждому объекту (алерту или инциденту) индивидуально и принимает одно значение: true или false. Триггер состоит из выражений на языке jq, обрабатывающих структурированные данные в формате JSON. Для получения дополнительной информации о выражениях jq см. Руководство по jq.

В Open Single Management Platform используется gojq. Это реализация jq, написанная на языке go, которая имеет следующие отличия от jq:

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

Дополнительные сведения о различиях между gojq и jq см. на сайте GitHub.

Как написать триггер

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

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

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

Чтобы избежать перегрузки системы не рекомендуется указывать в триггере данные OriginalEvents, Observables, Extra и Alerts.

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

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

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

Обратите внимание, что стандартные статусы (Новый и Закрыт) имеют одинаковые идентификаторы в разных рабочих процессах. Это означает, что триггер будет запускаться для всех инцидентов с указанным идентификатором статуса. Чтобы ограничить количество инцидентов, для которых будет запущен плейбук, в триггере вам нужно указать идентификатор статуса инцидента и тип инцидента.

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

При написании триггера используются базовые синтаксические правила.

Чтобы обратиться к свойствам структуры, вам нужно использовать точку "." и указать атрибут, например:

.MITRETactics[] – для просмотра массива тактик MITRE, связанных со всеми сработавшими IOA-правилами в алерте.
.MITRETactics[0] – для просмотра первого элемента из массива тактик MITRE.

Чтобы обратиться к дочерним свойствам, вы можете использовать вертикальную черту (|) или ту же комбинацию без вертикальной черты, например:

.Assignee[0].Name или Assignee[0] | .Name – выражение выводит имя пользователя, которому назначен алерт.
.MITRETactics[0].ID или .MITRETactics[0] | .ID – выражение выводит идентификатор первой тактики MITRE.

Чтобы получить значение, необходимо использовать следующие операторы: ==, >, <, >=, <=, !=, например:

.Assignee[0] | .Name == "user" – выражение возвращает значение true, если алерт назначен пользователю.
(.Serverity == "high") and (.DetectSource == "KES") – выражение возвращает значение true, если уровень важности алерта высокий и источником данных является Kaspersky Endpoint Security.
[ .DetectionTechnologies[] | . == "IOC" ] | any – выражение возвращает значение true, если срабатывает технология обнаружения IOC.
.DetectionTechnologies | length > 1 – выражение возвращает значение true, если срабатывает более одной технологии обнаружения.

Для перечисления значений в массиве объектов можно использовать метод any, например:

[.Assets[] | .Name == "W21H2-X64-3160"] | any – выражение фильтрует алерты, в которых любой элемент массива Assets имеет значение W21H2-X64-3160 в поле Name.
[.Observables[] | .Value == "127.0.0.1"] | any – выражение фильтрует алерты, в которых любой элемент массива Observables имеет значение 127.0.0.1 в поле Value.
[.Assets[].ID] – для вывода массива идентификаторов.
[.Assets[] | select(.AttackerOrVictim=="attacker") | .ID] – для отображения массива идентификаторов активов, отфильтрованных по полю AttackerOrVictim.

Если вы хотите повторно использовать вычисления, укажите переменную с помощью $. Например, выражение event.manual != true as $not_manual | [ .DetectionTechnologies[] | . == "IOC" ] | any and $not_manual определяет и использует переменную $not_manual, которая содержит флаг, показывающий, внесено ли изменение вручную или нет.

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

now – чтобы получить текущее время Unix в секундах, например, now == 1690541520.537496.
todate – чтобы получить текущее время Unix в секундах, например, now | todate == "2023-07-28T10:47:36Z".
fromdate – чтобы преобразовать дату в секунды, например:
- .CreatedAt | split(".")[0] + "Z" – эта команда удаляет миллисекунды и преобразует строку в формат 2023-07-15T07:49:51Z.
- (.CreatedAt | split(".")[0] + "Z") | fromdate == 1689407391 – преобразование в секунды завершено.

Jq использует итераторы – интерфейс, который обеспечивает доступ к элементам набора, например к массиву, и позволяет вам перемещаться по ним. Итераторы всегда являются результатом расчета. Разница в количестве элементов, которые содержит итератор. В Open Single Management Platform итератор должен иметь только один элемент. Остальные случаи считаются ошибкой.

Чтобы написать правильный триггер, вам нужно заключить итератор в квадратные скобки ([...]). Например, триггер .DetectionTechnologies[] == "IOC" вызовет ошибку, так как возвращает итератор с двумя элементами. Правильный триггер должен иметь следующий вид: [ .DetectionTechnologies == "IOC" ] | any, где сначала вам нужно использовать [], чтобы обернуть результат сравнения в массив, а затем обработать его с помощью метода any, который возвращает значение true, если хотя бы один элемент массива true. Иначе возвращается false.

Когда запускается триггер

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

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

Поддерживаются следующие типы событий изменения алертов:

Назначение или удаление аналитика.
Изменение статуса алерта.
Изменение базовых событий.
Связывание или удаление связи алерта с инцидентом.
Изменение значения в поле ExternalReference.

Поддерживаются следующие типы событий изменения инцидента:

Назначение или удаление аналитика.
Изменение статуса инцидента.
Изменение базовых событий.
Связывание или удаление связи алерта с инцидентом.
Изменение названия инцидента.
Изменение описания инцидента.
Изменение приоритета инцидента.
Изменение значения в поле ExternalReference.
Объединение инцидентов.

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

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

event.manual and ([ event.updateOperations[] | . == "alertReopened" ] | any) – триггер срабатывает, только если алерт повторно открывается вручную.
[ event.updateOperations[] | . == "alertLinkedWithIncidentBySystem" ] | any – триггер срабатывает, только если алерт автоматически связывается с инцидентом.
event.manual != null and (([ event.updateOperations[] | . == "alertChangedToNew" ] | any) | not) – триггер срабатывает, если статус алерта изменяется на любой статус, кроме Новый, вручную или автоматически.
event == null and .Status == "inIncident" – триггер работает для всех алертов со статусом В инциденте, но только при изменении плейбука, а не алерта.

При необходимости вы можете протестировать примеры jq-выражений, применить фильтры и просмотреть результаты на сервисе Jq playground.

Идентификатор статьи: 273327, Последнее изменение: 18 апр. 2025 г.

В начало