Правила нормализации

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

О правилах нормализации

Правила нормализации в системе 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. Нажмите на кнопку Удалить. Система удалит выбранные элементы и отобразит соответствующее уведомление. Удаленные элементы будет исключены из списка элементов экспертизы.

Структура правила нормализации

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

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

id

Уникальный идентификатор правила.

строка

Да

name

Название правила, которое обозначает его цель или функцию.

строка

Да

version

Версия правила, представленная в формате Semantic Versioning, указывает на текущую версию правила.

строка

Да

type

Тип правила. Всегда имеет значение normalization_rule для правила этого типа.

строка

Да

author

Имя и контактные данные автора правила нормализации.

строка

Нет

description

Описание правила, где можно указать дополнительную информацию о его назначении и функциональности.

строка

Нет

data_source

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

массив строк

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

нет

tags

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

массив строк

Нет

filter

Блок правил на языке VRL, определяющий условия (фильтр), при которых правило будет применяться к событиям. Фильтр позволяет выбирать определенные события для нормализации на основе заданных критериев.

строка

Нет

normalizer

Блок правил на языке VRL, определяющий правила нормализации события.

строка

Нет

tests

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

объект

Нет

setup_tests

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

объект

нет (если нет внешних зависимостей)

Структура data_source

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

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

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

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

platform

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

строка

нет

source

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

строка

нет

events

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

массив строк

нет

Структура tests

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

name

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

строка

да

events

Поток тестовых событий, обрабатываемых правилом.

массив

да

assertion

Блок правил на языке VRL, который будет вызываться на каждое событие, испускаемое полем events. Используя встроенные функции assert и assert_eq, можно строить проверки на соответствие испускаемого события тестовым условиям.

строка

да

Структура setup_tests

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

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

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

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

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

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

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

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

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

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

Пример 1. Структура setup_tests для активного списка:
setup_tests:
  active_lists:
    <имя_списка>:
      <поле>:
        - [<значение_поля1>]
        - [<значение_поля2>]
Пример 2. Структура setup_tests для таблицы обогащения:
setup_tests:
  enrichment_tables:
    <имя_таблицы>:
      fields:
        - <поле1>
        - <поле2>
      data:
        - [<значение1_поля1>, <значение1_поля2>]
        - [<значение2_поля1>, <значение2_поля2>]
Пример 3. Структура 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.

Составление правила

Для составления правила нормализации в системе R-Vision SIEM необходимо выполнить следующие шаги:

  1. Определите метаданные правила:

    • id: задайте уникальный идентификатор правила.

    • name: задайте название правила.

    • version: укажите версию правила, следуя стандартам Semantic Versioning.

    • type: укажите тип правила как normalization_rule.

    • author (опционально): укажите имя и контактные данные автора.

    • description (опционально): предоставьте краткое описание назначения и функциональности правила.

    • data_source (опционально): укажите список совместимых с правилом источников данных для классификации правила в системе.

    • tags (опционально): добавьте теги для классификации и быстрого поиска правила.

  2. Разработайте логику фильтрации событий:

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

  3. Определите правила нормализации:

    • normalizer: создайте блок правил на языке VRL, который будет применяться для нормализации выбранных событий.

  4. Разработайте тесты для проверки правила (опционально):

    • tests: создайте тесты, включающие различные типы событий и условия, для проверки корректности работы правила нормализации.

Пример правила нормализации

Пример 4. Правило нормализации, схема RObject
# Уникальный идентификатор правила.
id: example/basic_normalization_rule

# Название правила.
name: BasicNormalizationRule

# Имя автора правила.
author: John Doe <johndoe@example.com>

# Версия правила.
version: 1.0.0

# Описание назначения правила.
description: Базовое правило нормализации

# Список совместимых с правилом источников данных.
data_source:
  - platform: Windows
  - source: Sysmon
  - events:
    - logs/default.log
    - logs/somelog.log

# Теги, связанные с правилом.
tags:
  - normalization
  - security

# Тип элемента экспертизы.
type: normalization_rule

# Блок правил на языке VRL c условиями фильтрации событий.
filter: !vrl |
  .event.host == "170.174.42.191"

# Блок с правилами на языке VRL для нормализации полей события.
normalizer: !vrl |
    e = parse_json(.event) ?? {}
    . |= {
      "userId": e."user-identifier",
      "timestamp": parse_timestamp(e.datetime, "%d/%b/%Y:%H:%M:%S") ?? now(),
      "host": e.host,
      "method": e.method,
      "path": e.request,
      "protocol": e.protocol
    }

    if e.status == "404" || e.status == "401" {
      .responseStatus = "Bad request"
    }

    if e.protocol == "HTTP/2.0" {
        .protocol = "HTTP/2"
    }

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

Поле filter:

  • .event.host == "198.51.100.191":

    Сравнения поля host со значением "198.51.100.191" в сыром событии. Если значение поля host в сыром событии совпадает с "198.51.100.191", то событие будет нормализовано согласно правилам в поле normalizer. Если значение поля host не совпадает с указанным IP-адресом, правила нормализации к событию применены не будут.

Поле normalizer:

  • e = parse_json(.event) ?? {}:

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

    Если преобразование не удалось или результатом является null, переменной e будет присвоен пустой объект {}, что достигается с помощью оператора ??.

  • . |= { …​ }:

    Оператор обновления/добавления новых полей к текущему объекту на основе значений из объекта e.

Структура, которая присваивается текущему объекту:

  • userId: присваивает значение поля user-identifier из объекта e к полю userId текущего объекта.

  • timestamp: преобразует строковое значение поля datetime из объекта e в метку времени с использованием указанного формата. Если преобразование не удастся или значение поля datetime равно null, будет использовано текущее время, возвращаемое функцией now().

  • host: присваивает значение поля host из объекта e к полю host текущего объекта.

  • method: присваивает значение поля method из объекта e к полю method текущего объекта.

  • path: присваивает значение поля request из объекта e к полю path текущего объекта.

  • protocol: присваивает значение поля protocol из объекта e к полю protocol текущего объекта.

if e.status == "404" || e.status == "401":

  • Условное выражение проверяет, равно ли значение поля status из объекта e строке "404" или "401".

.responseStatus = "Bad request":

  • Если условие выше выполняется, то поле responseStatus текущего объекта устанавливается в значение "Bad request".

if e.protocol == "HTTP/2.0":

  • Условное выражение проверяет, равно ли значение поля protocol из объекта e строке "HTTP/2.0".

.protocol = "HTTP/2":

  • Если условие выше выполняется, то поле protocol текущего объекта заменяется на значение "HTTP/2".

Обработка событий правилом нормализации "BasicNormalizationRule"

Рассмотрим работу правила на примере разбора базового (сырого) события.

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

Пример 5. Исходное событие, JSON
{
  "event": "{\"host\":\"198.51.100.191\",\"user-identifier\":\"JohnDoe\",\"datetime\":\"31/Jul/2023:06:55:49\",\"method\":\"GET\",\"request\":\"/observability/metrics/production\",\"protocol\":\"HTTP/2.0\",\"status\":\"404\",\"bytes\":22427,\"referer\":\"https://example.url.com\"}"
}

После применения к событию правила "BasicNormalizationRule", оно принимает следующий вид:

Пример 6. Нормализованное событие, JSON
{
  "event": "{\"host\":\"198.51.100.191\",\"user-identifier\":\"JohnDoe\",\"datetime\":\"31/Jul/2023:06:55:49\",\"method\":\"GET\",\"request\":\"/observability/metrics/production\",\"protocol\":\"HTTP/2.0\",\"status\":\"404\",\"bytes\":22427,\"referer\":\"https://example.url.com\"}",
  "host": "170.174.42.191",
  "method": "GET",
  "path": "/observability/metrics/production",
  "protocol": "HTTP/2",
  "referer": "https://example.url.com",
  "responseBytes": 22427,
  "responseStatus": "Bad request",
  "serverIP": "198.51.100.191",
  "timestamp": "2023-07-30T23:55:49Z",
  "userAgent": null,
  "userId": "JohnDoe"
}

Событие удовлетворяет условию из поля filter, следовательно, оно подлежит нормализации и обрабатывается согласно правилам из поля normalizer. В структуре нормализованного события в поле event записывается исходное событие. Прочие поля добавляются к объекту и определяются в соответствии с правилами нормализации, хранящимся в поле normalizer.

Расширение конфигурации существующего правила нормализации

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

Допустим, исходное правило нормализации "BasicNormalizationRule" выглядит следующим образом:

Исходное правило нормализации BasicNormalizationRule, схема RObject 
# Уникальный идентификатор правила.
id: example/basic_normalization_rule

# Название правила.
name: BasicNormalizationRule

# Имя автора правила.
author: John Doe <johndoe@example.com>

# Версия правила.
version: 1.0.0

# Описание назначения правила.
description: Базовое правило нормализации

# Список совместимых с правилом источников данных.
data_source:
  - platform: Windows
  - source: Sysmon
  - events:
    - logs/default.log
    - logs/somelog.log

# Теги, связанные с правилом.
tags:
  - normalization
  - security

# Тип элемента экспертизы.
type: normalization_rule

# Блок правил на языке VRL c условиями фильтрации событий.
filter: !vrl |
  .event.host == "170.174.42.191"

# Блок с правилами на языке VRL для нормализации полей события.
normalizer: !vrl |
    e = parse_json(.event) ?? {}
    . |= {
      "userId": e."user-identifier",
      "timestamp": parse_timestamp(e.datetime, "%d/%b/%Y:%H:%M:%S") ?? now(),
      "host": e.host,
      "method": e.method,
      "path": e.request,
      "protocol": e.protocol
    }

    if e.status == "404" || e.status == "401" {
      .responseStatus = "Bad request"
    }

    if e.protocol == "HTTP/2.0" {
        .protocol = "HTTP/2"
    }

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

Пример 7. Конфигурация расширенного правила, схема RObject
# Уникальный идентификатор правила.
id: example/enhanced_normalization_rule

# Название правила.
name: EnhancedNormalizationRule

# Имя автора правила.
author: John Doe <johndoe@example.com>

# Версия правила.
version: 1.0.0

# Описание назначения правила.
description: Улучшенное правило нормализации JSON-события с определением уровня угрозы в поле `severity`.

# Список совместимых с правилом источников данных.
data_source:
  - platform: Windows
  - source: Sysmon
  - events:
     - logs/default.log
     - logs/somelog.log

# Теги, связанные с правилом.
tags:
  - security
  - normalization

# Тип элемента экспертизы.
type: normalization_rule

# Блок правил на языке VRL c условиями фильтрации событий.
filter: !vrl |
  .event.host == "170.174.42.191"

# Блок с правилами на языке VRL для нормализации полей события.
normalizer: !vrl |
  e = parse_json(.event) ?? {}
  . |= {
    "userId": e."user-identifier",
    "timestamp": parse_timestamp(e.datetime, "%d/%b/%Y:%H:%M:%S") ?? now(),
    "host": e.host,
    "method": e.method,
    "path": e.request,
    "protocol": e.protocol,
    "responseStatus": e.status,
    "responseBytes": e.bytes,
    "referer": e.referer,
    "userAgent": e."user-agent",
    "serverIP": "170.174.42.191",
    "severity": e.severity,
  }

  if e.status == "404" || e.status == "401" {
    .responseStatus = "Bad request"
  }

  if e.status == "404" || e.status == "401" {
    .severity = "High"
  }

Улучшенное правило "EnhancedNormalizationRule" представляет собой расширенную версию исходного правила. Оно разбирает недостающие поля сырого события и добавляет поле severity, которое определяет уровень угрозы в зависимости от статуса события. Если статус события соответствует "404" или "401", в поле severity устанавливается значение "High". В противном случае полю severity будет присвоено "null".

Таким образом, после применения правила "EnhancedNormalizationRule", нормализованное событие принимает следующий вид:

Пример 8. Событие, обработанное правилом "EnhancedNormalizationRule", JSON
= {
  "event": "{\"host\":\"170.174.42.191\",\"user-identifier\":\"JohnDoe\",\"datetime\":\"31/Jul/2023:06:55:49\",\"method\":\"GET\",\"request\":\"/observability/metrics/production\",\"protocol\":\"HTTP/2.0\",\"status\":\"404\",\"bytes\":22427,\"referer\":\"https://example.url.com\"}",
  "host": "170.174.42.191",
  "method": "GET",
  "path": "/observability/metrics/production",
  "protocol": "HTTP/2.0",
  "referer": "https://example.url.com",
  "responseBytes": 22427,
  "responseStatus": "Bad request",
  "serverIP": "170.174.42.191",
  "severity": "High", # Добавлено поле severity, уровень угрозы установлен в значение High.
  "timestamp": "2023-07-31T06:55:49Z",
  "userAgent": null,
  "userId": "JohnDoe"
}

Использование глобальных функций

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

...
# Имя функции.
name: set_severity
...

# Основной исполняемый код.
source: !vrl |
  if status == "404" || status == "401" {
    "High"
  } else {
    null
  }

# Аргументы функции.
arguments:
  - keyword: status
    kind: bytes
...

Тогда в правиле нормализации можно вызывать глобальную функцию так:

...
.severity = set_severity(e.status)
+7 (499) 322 80 40 sales@rvision.ru

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