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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

    • Для черновика: нажмите на кнопку Изменить в нижней части карточки.

  4. Внесите требуемые изменения в конфигурацию функции.

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

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

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

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

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

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

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

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

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

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

  4. Нажмите на кнопку Удалить. Система удалит функцию и отобразит соответствующее уведомление. Удаленная функция будет исключена из списка элементов экспертизы.

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

  1. Перейдите в раздел Экспертиза. Система отобразит сведения об имеющихся элементах экспертизы.

  2. Установите флажки напротив тех элементов, которые вы хотите удалить, в левом столбце таблицы.

  3. Нажмите на кнопку trash на панели инструментов. Отобразится окно удаления.

  4. Нажмите на кнопку Удалить. Система удалит выбранные элементы и отобразит соответствующее уведомление. Удаленные элементы будет исключены из списка элементов экспертизы.

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

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

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

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

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

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

да

fallible

Определяет, может ли функция возвращать ошибки. По умолчанию true.

логический

нет

tests

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

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

нет

Структура data_source

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

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

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

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

platform

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

строка

нет

source

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

строка

нет

events

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

массив строк

нет

Структура arguments

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

keyword

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

строка

да

kind

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

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

да

Структура tests

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

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. Простое арифметическое выражение
source: !vrl |
  argA * argB

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

Пример 2. Условное ветвление
source: !vrl |
  if arg > 10 {
    "Value is greater than 10"
  } else {
    "Value is 10 or less"
  }

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

Пример 3. Использование встроенной функции
source: !vrl |
  to_string(arg)

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

Пример 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: регулярное выражение.

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

  1. Имена параметров (keyword) должны быть уникальными в рамках одной функции.

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

  3. Если аргументу передается объект, каждое поле в его структуре должно быть строго типизировано.

Поле fallible

Поле fallible в глобальной функции определяет, может ли функция возвращать ошибки.

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

Если в поле установлено значение false, функция не может возвращать ошибок. При использовании такой функции не следует выполнять присваивание, объединение или вызов ошибки.

Глобальная функция может быть помечена как не возвращающая ошибок (fallible: false), только если в ее коде нет вызова функций с прерыванием !.

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

При обращении к глобальной функции в VRL-песочнице будет возвращено значение null.

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

Если глобальная функция взаимодействует с внешними данными (например, активными списками или таблицами обогащения), рекомендуется настроить искусственные данные через поле 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, которые проверяют результат работы функции. Условия могут включать проверки значений, использование логических операторов, или проверку обработки исключительных ситуаций.

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

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

  1. Описание теста (name): краткое описание цели и ожидаемого результата теста.

  2. События (events): список входных данных, которые подаются на вход функции в процессе тестирования. Для входных данных необходимо заполнить следующие поля:

    • $arguments — список передаваемых аргументов.

    • $event — массив тестовых событий.

  3. Утверждения (assertions): логика проверки результата работы функции на основе переданных событий и условий.

Пример:

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

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

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

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

Поле setup_tests

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

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

Поле setup_tests используется для:

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

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

Процедура настройки setup_tests:

  1. В корне конфигурации укажите секцию setup_tests.

  2. Внутри секции setup_tests через ключ enrichment_tables, active_lists или global_functions задайте искусственные таблицы обогащения, активные списки и глобальные функции, используемые правилом.

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

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

Пример 5. Структура setup_tests для активного списка:
setup_tests:
  active_lists:
    <имя_списка>:
      <поле>:
        - [<значение_поля1>]
        - [<значение_поля2>]
Пример 6. Структура setup_tests для таблицы обогащения:
setup_tests:
  enrichment_tables:
    <имя_таблицы>:
      fields:
        - <поле1>
        - <поле2>
      data:
        - [<значение1_поля1>, <значение1_поля2>]
        - [<значение2_поля1>, <значение2_поля2>]
Пример 7. Структура setup_tests для глобальной функции:
setup_tests:
  global_functions:
    <имя_функции>:
      arguments:
        - keyword: <имя_параметра1>
          kind: <тип_параметра1>
        - keyword: <имя_параметра2>
          kind: <тип_параметра2>
      values_map:
        - argument: <аргументы1>
          event: <событие1>
          return: <результат1>
      default: <результат_по_умолчанию>
      fallible: <логическое значение>

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

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

Пример 8. Пример глобальной функции "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

# Опциональное. Определяет, может ли функция возвращать ошибки. По умолчанию 'true'.
fallible: true

# Список тестов функции.
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".

+7 (499) 322 80 40 sales@rvision.ru

О компании Политика конфиденциальности Пользовательское соглашение