Правила агрегации YAML

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

При создании директивы выберите тип узла Событие и напишите правило агрегации на языке YAML в поле для выражения.

Конфигурация

YAML-конфигурация агрегации состоит из двух основных полей:

• aggregation -- блок, содержащий правило агрегации
• expression -- CEL-выражение для отбора событий, подлежащих агрегации

Поля блока aggregation

Поле	Обязательное	Описание
fields	Нет	Массив полей группировки
window	Да	Размер временного окна агрегации (5m, 1h и т.п.)
max_events	Нет	Максимальное количество событий для мгновенного закрытия окна
min_events	Нет	Минимальное количество событий для создания инцидента при закрытии окна
additional_rules	Нет	Дополнительные правила агрегации
derive	Нет	Блок определения вывода полей для результата агрегации

Пример конфигурации

aggregation:
  fields:
    - name: ECS.Event.Code
    - name: AssetIPs
      unnest: true
  window: 30m
  max_events: 500
  min_events: 50
  additional_rules:
    - window: 1m
      min_events: 25
  derive:
    fields:
      - to: Hashes
        deriving_type: distinct
        deriving_data:
          from: ECS.Event.Hash
    all:
      enable: true
      overwrite: false
      deriving_type: last
expression: "ep['ECS.Event.Code'] > 4650 && ep['ECS.Event.Code'] < 4700"

Поля группировки

Новая агрегация поддерживает три режима группировки:

• Без группировки -- события агрегируются без разделения по полям, исключительно по фильтру
• Одно поле -- аналог поведения предыдущей версии агрегации
• Несколько полей -- события разделяются на основе значений нескольких полей

Для указания полей группировки используется поле aggregation.fields.

Формат объектов группировки

Каждое поле группировки задаётся объектом:

fields:
  - name: "ECS.Event.Code"
    unnest: true

Параметр	Описание
name	Название поля для группировки
unnest	Режим группировки по полям-массивам (по умолчанию false)

Если unnest равен false, группировка проводится целиком по значению массива -- для попадания в одну группу события должны иметь одинаковые значения в массиве. Если unnest равен true, группировка проводится отдельно по каждому элементу массива.

Сокращённый формат

Поля группировки можно задать массивом строк. В этом случае параметр unnest считается равным false для каждого поля:

fields:
  - "ECS.Event.Code"
  - "AssetIPs"

Условия завершения агрегации

Основные условия завершения агрегации определяются значениями max_events и min_events:

max_events	min_events	Поведение
> 0	> 0	Агрегация завершается сразу при достижении max_events событий, либо по окончании окна при наличии минимум min_events событий
0	> 0	Агрегация завершается только при окончании окна при наличии минимум min_events событий
> 0	0	Агрегация завершается при достижении max_events событий в окне
0	0	Невалидная конфигурация (приводит к ошибке)

warning

Хотя бы одно из полей max_events или min_events должно быть указано.

Дополнительные правила агрегации

Блок additional_rules позволяет определить дополнительные условия успешного завершения агрегации. Это полезно для обнаружения всплесков количества событий и ускорения реакции на них.

Каждое дополнительное правило содержит:

Поле	Обязательное	Описание
window	Да	Размер дополнительного временного окна
max_events	Нет	Максимальное количество событий в дополнительном окне
min_events	Нет	Минимальное количество событий в дополнительном окне
immediate_trigger	Нет	Немедленное завершение основной агрегации при срабатывании (по умолчанию false)

Поведение при срабатывании дополнительного правила:

• Если immediate_trigger равен true, основная агрегация незамедлительно завершается успехом
• Если immediate_trigger равен false или не указан, агрегация завершится успехом только при закрытии основного окна

Пример дополнительного правила

additional_rules:
  - window: 1m
    min_events: 25
    immediate_trigger: true

В этом примере, если в течение 1 минуты поступит 25 и более событий, основная агрегация завершится немедленно.

Вывод полей

Блок derive определяет, какие поля и каким образом будут включены в результат агрегации.

Структура блока derive

derive:
  fields:
    - to: "ИмяПоля"
      deriving_type: "способ_вывода"
      deriving_data:
        from: "ИсходноеПоле"
  all:
    enable: true
    overwrite: false
    deriving_type: last

Поле fields

Массив объектов, определяющих вывод отдельных полей:

Параметр	Описание
to	Название поля в результате агрегации
deriving_type	Способ вывода значения поля
deriving_data	Данные для конкретного способа вывода

Поле all

Общее правило вывода полей:

Параметр	Описание
enable	Активация общего вывода полей
overwrite	Перезаписывать ли существующие значения полей
deriving_type	Способ вывода (first или last)

Стандартные способы вывода

Для стандартных способов вывода в блоке deriving_data необходимо указать поле from с названием исходного поля.

Способ	Описание	Типы полей
first	Значение из первого события	Любые
last	Значение из последнего события	Любые
distinct	Все уникальные значения в виде массива	Любые
avg	Среднее значение	Числовые
sum	Сумма значений	Числовые
min	Минимальное значение	Числовые
max	Максимальное значение	Числовые

Пользовательский способ вывода

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

Параметры deriving_data для custom:

Параметр	Описание
init_expr	CEL-выражение, инициализирующее начальное состояние агрегации
state_expr	CEL-выражение функции состояния, вызываемое для каждого события
finalize_expr	CEL-выражение, завершающее агрегацию и возвращающее результат
disable_type_checking	Отключить проверку типов в CEL-выражениях

Алгоритм работы пользовательского вывода:

1. Вызывается init_expr, результат определяет начальное значение состояния
2. Для каждого события в закрытом окне вызывается state_expr. Внутри выражения доступна переменная agg_state с текущим состоянием и все переменные события. Результат становится новым состоянием
3. Вызывается finalize_expr с доступом к agg_state. Результат присваивается целевому полю

Если disable_type_checking равен true, переменная agg_state имеет динамический тип. Если false (значение по умолчанию), тип agg_state определяется результатом init_expr, и типы результатов init_expr и state_expr должны совпадать.

Пример пользовательского вывода

derive:
  fields:
    - to: HasAdminRights
      deriving_type: custom
      deriving_data:
        init_expr: "false"
        state_expr: "agg_state || (has(ep.HasAdminRights) && ep['HasAdminRights'])"
        finalize_expr: "agg_state"

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