Глобальные функции

В данном разделе представлен обзор структуры, принципов работы и процесса создания глобальных функций в R-Vision SIEM. Управление глобальными функциями в системе осуществляется в разделе Экспертиза.

О глобальных функциях

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

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

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

Работа с глобальной функцией

Доступные операции над глобальной функцией:

создание глобальной функции;
изменение глобальной функции;
удаление глобальной функции.

Создание глобальной функции

Чтобы создать глобальную функцию:

Перейдите в раздел Экспертиза. Система отобразит сведения об имеющихся элементах экспертизы, включая их статус (включен/выключен).

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

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

Заполните поля глобальной функции, чтобы определить ее логику и параметры.

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

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

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

Изменение глобальной функции

Чтобы изменить глобальную функцию:

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

Выберите опцию Изменить в меню Действия ( more vertical ) в верхней части карточки функции. Откроется окно настроек.

Вы также можете открыть окно настроек с помощью кнопки в нижней части карточки:

Для опубликованной версии: нажмите на кнопку Просмотр в нижней части карточки. Система отобразит окно просмотра настроек элемента экспертизы. Нажмите на кнопку Изменить в правом нижнем углу окна.
Для черновика: нажмите на кнопку Изменить в нижней части карточки.

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

При публикации новой версии элемента экспертизы требуется увеличить его текущую версию в поле version.

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

Удаление глобальной функции

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

Удаление недоступно для элементов экспертизы, используемых в других сущностях системы.

Чтобы удалить глобальную функцию:

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

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

Перейдите в раздел Экспертиза. Система отобразит сведения об имеющихся элементах экспертизы, в том числе их текущий статус (включен/выключен).
Установите флажки напротив тех элементов, которые вы хотите удалить, в левом столбце таблицы.
Нажмите на кнопку на панели инструментов. Отобразится окно удаления.
Нажмите на кнопку Удалить. Система удалит выбранные элементы и отобразит уведомление об успешном удалении. Удаленные элементы будет исключены из списка элементов экспертизы.

Структура глобальной функции

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

Поле Описание Тип данных Обязательное поле

Поле	Описание	Тип данных	Обязательное поле
`id`	Уникальный идентификатор глобальной функции. Должен быть уникальным в пределах экспертизы. Можно использовать UUID в качестве значения.	строка	да
`name`	Название глобальной функции. Допустимы латинские буквы, цифры, подчеркивания.	строка	да
`description`	Краткое описание назначения глобальной функции.	строка	нет
`data_source`	Список источников данных, с которыми совместима глобальная функция. Используется для классификации и быстрого поиска элементов экспертизы в системе.	массив строк массив объектов	нет
`status`	Статус разработки текущей версии глобальной функции. Может принимать любые текстовые значения. Примеры значений: `debug` — версия в разработке; `experimental` — экспериментальная версия; `test` — версия для тестирования; `stable` — стабильная версия.	строка	нет
`date`	Дата создания или изменения глобальной функции. Задается в формате `YYYY-MM-DD`, то есть "год-месяц-день". Поле не связано с полями Дата создания и Дата изменения в карточке элемента экспертизы.	строка	нет
`type`	Тип объекта. Для глобальных функций всегда указывается `global_function`.	строка	да
`version`	Версия функции в формате Semantic Versioning.	строка	да
`author`	Имя и контактные данные автора функции.	строка	нет
`source`	Код глобальной функции, реализованный на языке VRL.	строка	да
`arguments`	Набор аргументов, определяющих входные данные функции. Каждый аргумент имеет тип и имя.	массив объектов	да
`tests`	Набор тестов для проверки корректности работы функции.	массив объектов	нет

id

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

строка

да

name

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

строка

да

description

Краткое описание назначения глобальной функции.

строка

нет

data_source

Список источников данных, с которыми совместима глобальная функция. Используется для классификации и быстрого поиска элементов экспертизы в системе.

массив строк

массив объектов

нет

status

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

Примеры значений:

debug — версия в разработке;
experimental — экспериментальная версия;
test — версия для тестирования;
stable — стабильная версия.

строка

нет

date

Дата создания или изменения глобальной функции. Задается в формате YYYY-MM-DD, то есть "год-месяц-день".

Поле не связано с полями Дата создания и Дата изменения в карточке элемента экспертизы.

строка

нет

type

Тип объекта. Для глобальных функций всегда указывается global_function.

строка

да

version

Версия функции в формате Semantic Versioning.

строка

да

author

Имя и контактные данные автора функции.

строка

нет

source

Код глобальной функции, реализованный на языке VRL.

строка

да

arguments

Набор аргументов, определяющих входные данные функции. Каждый аргумент имеет тип и имя.

массив объектов

да

tests

Набор тестов для проверки корректности работы функции.

массив объектов

нет

Структура `data_source`

Поле data_source, представленное массивом строк, имеет структуру:

data_source:
- <platform> # Платформа или информационная система
- <source> # Источник событий.
# События (EventId) или путь к журналу событий:
- <EventID_1>
- <EventID_2>

Поле data_source, представленное массивом объектов, имеет следующую структуру:

Поле Описание Тип данных Обязательное поле

Поле	Описание	Тип данных	Обязательное поле
`platform`	Платформа или информационная система.	строка	нет
`source`	Источник событий.	строка	нет
`events`	События (EventId) или путь к журналу событий.	массив строк	нет

platform

Платформа или информационная система.

строка

нет

source

Источник событий.

строка

нет

events

События (EventId) или путь к журналу событий.

массив строк

нет

Структура `arguments`

Поле Описание Тип данных Обязательное поле

Поле	Описание	Тип данных	Обязательное поле
`keyword`	Имя аргумента, которое используется в коде функции.	строка	да
`kind`	Тип аргумента. Допустимые значения: `bytes`, `integer`, `float`, `boolean`, `object`, `array`, `timestamp`, `regex`.	строка или объект	да

keyword

Имя аргумента, которое используется в коде функции.

строка

да

kind

Тип аргумента. Допустимые значения: bytes, integer, float, boolean, object, array, timestamp, regex.

строка или объект

да

Структура `tests`

Поле Описание Тип данных Обязательное поле

Поле	Описание	Тип данных	Обязательное поле
`name`	Название теста, позволяющее идентифицировать его при проверке работы глобальной функции.	строка	да
`events`	Набор входных данных для тестирования в виде массива событий, передаваемых в функцию.	массив	да
`assertion`	Блок проверок на языке VRL, выполняемых на каждом событии из `events`. Включает `assert` и `assert_eq` для валидации ожидаемых результатов.	строка	да

name

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

строка

да

events

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

массив

да

assertion

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

строка

да

Составление глобальной функции

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

Поля метаданных

Заполните поля метаданных глобальной функции:

id: уникальный идентификатор глобальной функции. Должен быть уникальным в пределах экспертизы. Можно использовать UUID в качестве значения.
name: название глобальной функции. Допустимы латинские буквы, цифры и символы подчеркивания.
type: всегда указывается global_function для элементов экспертизы данного типа.
description (опционально): краткое описание назначения функции.
author (опционально): имя и контактные данные автора глобальной функции.
version: версия глобальной функции согласно стандарту Semantic Versioning.
status (опционально): статус разработки текущей версии глобальной функции. Может принимать текстовые значения, такие как:
- debug: версия в разработке.
- experimental: экспериментальная версия.
- test: версия для тестирования.
- stable: стабильная версия.
date (опционально): дата создания или изменения глобальной функции. Формат значения: YYYY-MM-DD (год-месяц-день). Поле не связано с полями Дата создания и Дата изменения в карточке элемента экспертизы.
tags (опционально): список тегов, присвоенных глобальной функции для классификации и быстрого поиска в системе.

Пример метаданных:

id: a123b456-c789-0def-1112-000000000000
name: multiply_values
type: global_function
description: Функция для умножения двух чисел
author: John Doe <johndoe@example.com>
version: 1.0.0
status: stable
date: 2025-01-23
tags:
  - math
  - operations

В этом примере:

Глобальная функция с уникальным идентификатором a123b456-c789-0def-1112-000000000000 предназначена для выполнения операции умножения.
Название функции multiply_values указывает на ее функциональность.
Поле type имеет значение global_function, что обозначает тип элемента экспертизы.
Версия функции указана как 1.0.0 в соответствии с правилами семантического версионирования.
Поле status имеет значение stable, что указывает на завершение разработки функции.
Поле date содержит дату последнего изменения или создания функции: 2025-01-23.
Автором функции является John Doe, чьи контактные данные указаны в поле author.
Теги math и operations присвоены функции для облегчения поиска и классификации в системе.

Поле `source`

Поле source содержит основной код глобальной функции, написанный на языке VRL. Этот код реализует логику выполнения функции и использует аргументы, указанные в поле arguments. Код функции должен быть валидирован, а возвращаемое значение должно соответствовать ожидаемому типу, заданному в конфигурации функции.

Основные аспекты работы `source`

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

Пример реализации source:

source: !vrl |
  # Умножение значений двух аргументов
  argA * argB

В этом примере:

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

Поддерживаемые элементы в `source`

Поле source поддерживает все возможности языка VRL. Подробное описание доступных выражений и функций приведено в документации по выражениям и функциям.

Основные возможности включают:

Операции с аргументами: работа с переданными данными, такими как арифметические операции, манипуляции со строками и преобразования типов.
Условные конструкции: использование логических выражений и операторов if/else для ветвления логики выполнения.
Встроенные функции VRL: вызов встроенных VRL-функций для обработки данных (например, преобразования, фильтрации, агрегации).
Работа с объектами: доступ к полям сложных объектов, переданных в функцию, через их ключи.

Примеры значений в `source`

Пример 1. Пример 1. Простое арифметическое выражение

source: !vrl |
  argA * argB

Выполняется умножение двух числовых аргументов argA и argB.

Пример 2. Пример 2. Условное ветвление

source: !vrl |
  if arg > 10 {
    "Value is greater than 10"
  } else {
    "Value is 10 or less"
  }

Функция возвращает строку в зависимости от значения аргумента arg.

Пример 3. Пример 3. Использование встроенной функции

source: !vrl |
  to_string(arg)

Функция преобразует числовое значение аргумента arg в строку.

Пример 4. Пример 4. Работа с объектом

source: !vrl |
  substring(arg["field_name"], 0, 5)

Функция извлекает подстроку из значения поля field_name объекта arg.

Поле `arguments`

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

Элементы структуры `arguments`

keyword: уникальное имя параметра, используемое в коде функции для ссылки на аргумент.
kind: тип данных параметра.

Пример структуры `arguments`

arguments:
  - keyword: input_data
    kind: object
  - keyword: multiplier
    kind: integer

В этом примере:

Аргумент input_data имеет тип object, что означает, что он представляет объект с произвольной структурой.
Аргумент multiplier имеет тип integer, что указывает на ожидание целого числа.

Типы данных

Поле kind может принимать следующие значения типов данных:

bytes: бинарные данные.
integer: целые числа.
float: числа с плавающей точкой.
boolean: логические значения (true или false).
object: объект (структура ключ-значение).
array: массив.
timestamp: временные метки в формате RFC 3339.
regex: регулярное выражение.

Дополнительные требования

Имена параметров (keyword) должны быть уникальными в рамках одной функции.
Тип данных (kind) должен быть совместим с ожидаемыми значениями, передаваемыми при вызове функции.
Если аргументу передается объект, каждое поле в его структуре должно быть строго типизировано.

Тестирование глобальной функции

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

Если глобальная функция взаимодействует с внешними данными (например, активными списками или таблицами обогащения), рекомендуется настроить MOCK-данные через поле setup_tests. Это позволяет моделировать работу функции в условиях, близких к продуктивным, без обращения к реальной инфраструктуре.

Поле `tests`

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

Элементы структуры tests:

name: название теста для его идентификации.
events: список входных данных, которые подаются на вход функции в процессе тестирования. Входные данные состоят из следующих обязательных полей:
- $arguments — список передаваемых аргументов.
- $event — массив тестовых событий. Эти события моделируют данные, которые передаются функции при ее реальной работе.
assertion: выражение или набор выражений на языке VRL, проверяющих корректность результата выполнения функции.

Пример структуры `tests`

tests:
  - name: Тест умножения чисел
    events:
      - { "$arguments": { "argA": 50, "argB": 10 }, "$event": {} }
    assertion: !vrl |
      assert_eq!(.[0], 50, "Ожидается произведение 50")

В этом примере:

name: тест называется "Тест умножения чисел".
events: входное событие включает два аргумента, argA и argB.
assertion: проверяется, что вызов функции возвращает значение 50.

Тестовые события

Массив events содержит данные, передаваемые в функцию в процессе тестирования. Каждый элемент массива представляет собой объект, где ключи соответствуют именам аргументов функции, а значения — типам данных, указанным в arguments.

Для работы с временными метками (например, типом TIMESTAMP) значения в событиях должны быть указаны в формате t'<значение>'. Например: t'2024-05-15 06:28:15'. Это гарантирует корректную обработку времени.

Условия проверки

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

Создание и выполнение тестов

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

Описание теста (name): краткое описание цели и ожидаемого результата теста.
События (events): список входных данных, которые подаются на вход функции в процессе тестирования. Для входных данных необходимо заполнить следующие поля:
- $arguments — список передаваемых аргументов.
- $event — массив тестовых событий.
Утверждения (assertions): логика проверки результата работы функции на основе переданных событий и условий.

Пример:

tests:
  - name: Проверка функции деления
    events:
      - { $arguments: { dividend: 10, divisor: 2 }, $event: {}}
    assertion: !vrl |
        assert_eq!(.[0], 5, "Ожидается результат 5")

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

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

Пример глобальной функции

Пример 5. Пример глобальной функции "Multiplication Function", схема RObject

# Универсальный уникальный идентификатор функции.
id: d2f0c404-5cb3-11e7-907b-000000000000

# Название глобальной функции.
# Должно быть уникальным в пределах коллектора.
name: multiplication_example

# Тип элемента экспертизы. Всегда имеет значение `global_function` для глобальных функций.
type: global_function

# Версия функции.
version: 1.0.0

# Краткое описание назначения глобальной функции.
description: Функция умножения двух чисел

# Имя и контактные данные автора глобальной функции.
author: John Doe <johndoe@example.com>

# Статус разработки функции.
# Возможные варианты: `debug`, `experimental`, `test`, `stable`.
status: stable

# Дата создания или последнего изменения функции, формат YYYY-MM-DD.
date: 2025-01-23

# Категории, по которым функции группируются.
tags:
  - math
  - example

# Исполняемый код функции на языке VRL.
source: !vrl |
  # Функция возвращает произведение двух аргументов.
  if is_integer(argA) && (is_integer(argB)) {
    argA * argB
  } else {
    0
  }

# Параметры функции.
arguments:
  # Имя первого аргумента.
  - keyword: argA
    # Тип первого аргумента.
    kind: integer
  # Имя второго аргумента.
  - keyword: argB
    # Тип второго аргумента.
    kind: integer

# Список тестов функции.
tests:
  # Наименование теста, уникальное для каждого теста.
  - name: Multiplication Test 1
    # Тестовые данные.
    events:
      - { $arguments: { argA: 10, argB: 2 }, $event: {}}
    # Проверка для тестовых данных.
    assertion: !vrl |
      assert_eq!(.[0], 20, "Ожидается произведение 20")

  # Наименование теста для проверки обработки ошибок.
  - name: Multiplication Test Invalid Data
    # Тестовые данные с некорректным форматом.
    events:
      - { $arguments: { argA: "invalid", argB: 2 }, $event: {}}
    # Проверка для тестовых данных.
    assertion: !vrl |
      assert_eq!(.[0], 0, "При некорректном вводе ожидается результат 0")

Интерпретация

Метаданные глобальной функции:

id: уникальный идентификатор функции — d2f0c404-5cb3-11e7-907b-000000000000.
name: название функции — multiplication_example.
type: тип объекта экспертизы — всегда global_function для глобальных функций.
version: версия функции — 1.0.0.
description: описание назначения функции — "Функция умножения двух чисел".
author: автор функции — John Doe <johndoe@example.com>.
status: статус разработки функции — stable, что означает завершенную разработку и готовность к использованию.
date: дата создания или последнего изменения функции — 2025-01-23.
tags: категории функции, используемые для классификации — math и example.

Код функции:

source: основной код функции, написанный на языке VRL, реализует умножение значений аргументов argA и argB при условии, что в оба аргумента переданы целые числа. В противном случае в качестве результата функции возвращается значение 0.

Параметры функции:

arguments: список параметров, передаваемых функции.
keyword: имя аргумента. В данном случае это argA и argB.
kind: тип данных аргумента. В данном случае это integer (целое число).

Тесты:

tests: набор тестов для проверки правильности выполнения функции.
Тест 1:
- name: название теста — "Multiplication Test 1".
- events: данные для теста содержат два значения: argA = 10 и argB = 2.
- assertion: проверяется, что функция multiplication_example вернет 20 при переданных аргументах.
- Сообщение об ошибке, возвращаемое в случае несоответствия: "Ожидается произведение 20".
Тест 2:
- name: название теста — "Multiplication Test Invalid Data".
- events: данные содержат некорректное значение argA = "invalid" и корректное argB = 2.
- assertion: проверяется, что функция обрабатывает невалидные данные и возвращает 0, если вход некорректен.
- Сообщение об ошибке, возвращаемое в случае несоответствия: "При некорректном вводе ожидается результат 0".

Глобальные функции

О глобальных функциях

Работа с глобальной функцией

Создание глобальной функции

Изменение глобальной функции

Удаление глобальной функции

Структура глобальной функции

Структура data_source

Структура arguments

Структура tests

Составление глобальной функции

Поля метаданных

Поле source

Основные аспекты работы source

Поддерживаемые элементы в source

Примеры значений в source

Поле arguments

Элементы структуры arguments

Пример структуры arguments

Типы данных

Дополнительные требования

Тестирование глобальной функции

Поле tests

Пример структуры tests

Тестовые события

Условия проверки

Создание и выполнение тестов

Пример глобальной функции

Структура `data_source`

Структура `arguments`

Структура `tests`

Поле `source`

Основные аспекты работы `source`

Поддерживаемые элементы в `source`

Примеры значений в `source`

Поле `arguments`

Элементы структуры `arguments`

Пример структуры `arguments`

Поле `tests`

Пример структуры `tests`