Параметры парсинга событий
При создании правил парсинга событий в окне параметров нормализатора на вкладке Схема нормализации вы можете настроить правила приведения поступающих событий к формату KUMA.
Доступные параметры:
- Название (обязательно) – название правил парсинга. Должно содержать от 1 до 128 символов в кодировке Unicode. Название основного правила парсинга будет использоваться в качестве названия нормализатора.
- Тенант (обязательно) – название тенанта, которому принадлежит ресурс.
Этот параметр недоступен для дополнительных правил парсинга.
- Метод парсинга (обязательно) – выпадающий список для выбора типа входящих событий. В зависимости от выбора можно будет воспользоваться преднастроенными правилами сопоставления полей событий или же задать свои собственные правила. При выборе некоторых методов парсинга могут стать доступны дополнительные параметры, требуемые для заполнения.
Доступные методы парсинга:
- json
Этот метод парсинга используется для обработки данных в формате JSON, в которых каждый объект, включая его вложенные объекты, занимает одну строку файла.
При обработке файлов с иерархически выстроенными данными можно обращаться к полям вложенных объектов, поочередно через точку указывая названия параметров. Например, к параметру username из строки "user":{"username":"system:node:example-01"} можно обратиться с помощью запроса user.username.
Файлы обрабатываются построчно. Многострочные объекты с вложенными структурами могут быть нормализованны некорректно.
В сложных схемах нормализации, где используются дополнительные нормализаторы, все вложенные объекты обрабатываются на первом уровне нормализации за исключением случаев, когда условия дополнительной нормализации не заданы и, следовательно, в дополнительный нормализатор передается обрабатываемое событие целиком.
В качестве разделителя строк могут выступать символы \n и \r\n. Строки должны быть в кодировке UTF-8.
Если вы хотите передавать сырое событие для дополнительной нормализации, на каждом уровне вложенности в окне Дополнительный парсинг события выберите в раскрывающемся списке Использовать сырое событие значение Да.
- cef
Этот метод парсинга используется для обработки данных в формате CEF.
При выборе этого метода можно воспользоваться преднастроенными правилами преобразования событий в формат KUMA, нажав на кнопку Применить сопоставление по умолчанию.
- regexp
Этот метод парсинга используется для создания собственных правил обработки данных в формате с использованием регулярных выражений.
В поле блока параметров Нормализация необходимо добавить регулярное выражение (синтаксис RE2) c именованными группами захвата: имя группы и ее значение будут считаться полем и значением "сырого" события, которое можно будет преобразовать в поле события формата KUMA.
Чтобы добавить правила обработки событий:
- Скопируйте в поле Примеры событий пример данных, которые вы хотите обработать. Это необязательный, но рекомендуемый шаг.
- В поле блока параметров Нормализация добавьте регулярное выражение c именованными группами захвата в синтаксисе RE2, например "(?P<name>regexp)". Регулярное выражение, добавленное в параметр Нормализация, должно полностью совпадать с событием. Также при разработке регулярного выражения рекомендуется использовать специальные символы, обозначающие начало и конец текста: ^, $.
Можно добавить несколько регулярных выражений с помощью кнопки Добавить регулярное выражение. При необходимости удалить регулярное выражение, воспользуйтесь кнопкой 
.
- Нажмите на кнопку Перенести названия полей в таблицу.
Имена групп захвата отображаются в столбце Поле KUMA таблицы Сопоставление. Теперь в столбце напротив каждой группы захвата можно выбрать соответствующее ей поле KUMA или, если вы именовали группы захвата в соответствии с форматом CEF, можно воспользоваться автоматическим сопоставлением CEF, поставив флажок Использовать синтаксис CEF при нормализации.
Правила обработки событий добавлены.
- syslog
Этот метод парсинга используется для обработки данных в формате syslog.
При выборе этого метода можно воспользоваться преднастроенными правилами преобразования событий в формат KUMA, нажав на кнопку Применить сопоставление по умолчанию.
- csv
Этот метод парсинга используется для создания собственных правил обработки данных в формате CSV.
При выборе этого метода необходимо в поле Разделитель указать разделитель значений в строке. В качестве разделителя допускается использовать любой однобайтовый символ ASCII.
- kv
Этот метод парсинга используется для обработки данных в формате ключ-значение.
При выборе этого метода необходимо указать значения в следующих обязательных полях:
- Разделитель пар – укажите символ, которые будет служит разделителем пар ключ-значение. Допускается указать любое односимвольное (1 байт) значение при условии, что символ не будет совпадать с разделителем значений.
- Разделитель значений – укажите символ, который будет служить разделителем между ключом и значением. Допускается указать любое односимвольное (1 байт) значение при условии, что символ не будет совпадать с разделителем пар ключ-значение.
- xml
Этот метод парсинга используется для обработки данных в формате XML, в которых каждый объект, включая его вложенные объекты, занимает одну строку файла. Файлы обрабатываются построчно.
Если вы хотите передавать сырое событие для дополнительной нормализации, на каждом уровне вложенности в окне Дополнительный парсинг события выберите в раскрывающемся списке Использовать сырое событие значение Да.
При выборе этого метода в блоке параметров Атрибуты XML можно указать ключевые атрибуты, которые следует извлекать из тегов. Если в структуре XML в одном тэге есть атрибуты с разными значениями, можно определить нужное значение, указав ключ к нему в столбце Исходные данные таблицы Сопоставление.
Чтобы добавить ключевые атрибуты XML,
Нажмите на кнопку Добавить поле и в появившемся окне укажите путь к нужному атрибуту.
Можно добавить несколько атрибутов. Атрибуты можно удалить по одному с помощью значка с крестиком или все сразу с помощью кнопки Сбросить.
Если ключевые атрибуты XML не указаны, при сопоставлении полей уникальный путь к значению XML будет представлен последовательностью тегов.
Нумерация тегов
Начиная с версии KUMA 2.1.3 доступна Нумерация тегов. Опция предназначена для выполнения автоматической нумерации тегов в событиях в формате XML, чтобы можно было распарсить событие с одинаковыми тэгами или неименованными тэгами, такими как <Data>.
В качестве примера мы используем функцию Нумерация тегов для нумерации тегов атрибута EventData события Microsoft Windows PowerShell event ID 800.
Чтобы выполнить парсинг таких событий необходимо:
- Настроить нумерацию тегов.
- Настроить мапинг данных для пронумерованных тегов с полями события KUMA.
Одновременное применение функций Атрибуты XML и Нумерация тегов приведёт к некорректной работе нормализатора. Если атрибут содержит неименованные тэги или одинаковые тэги, мы рекомендуем использовать функцию Нумерация тегов. Если атрибут содержит только именованные тэги, используйте Атрибуты XML.
Чтобы настроить парсинг событий с тэгами, содержащими одинаковое название или тэги без названия:
- Создайте новый нормализатор или откройте существующий нормализатор для редактирования.
- В окне нормализатора Основной парсинг событий в раскрывающемся списке Метод парсинга выберите значение xml и в поле Нумерация тегов нажмите Добавить поле.
В появившемся поле укажите полный путь к тэгу, элементам которого следует присвоить порядковый номер. Например, Event.EventData.Data. Первый номер, который будет присвоен тэгу – 0. Если тэг пустой, например, <Data />, ему также будет присвоен порядковый номер.
- Чтобы настроить мапинг данных, в группе параметров Сопоставление нажмите Добавить строку и выполните следующие действия:
- В появившейся строке в поле Исходные данные укажите полный путь к тэгу и его индекс. Для события Microsoft Windows из примера выше полный путь с индексами будет выглядеть следующим образом:
- Event.EventData.Data.0
- Event.EventData.Data.1
- Event.EventData.Data.2 и так далее
- В раскрывающемся списке Поле KUMA выберите поле в событии KUMA, в которое попадет значение из пронумерованного тэга после выполнения парсинга.
- Чтобы сохранить изменения:
- Если вы создали новый нормализатор, нажмите Сохранить.
- Если вы редактировали существующий нормализатор, нажмите Обновить параметры в коллекторе, к которому привязан нормализатор.
Настройка парсинга завершена.
- netflow5
Этот метод парсинга используется для обработки данных в формате NetFlow v5.
При выборе этого метода можно воспользоваться преднастроенными правилами преобразования событий в формат KUMA, нажав на кнопку Применить сопоставление по умолчанию. Если тип netflow5 выбран для основного парсинга, дополнительная нормализация недоступна.
В правилах сопоставления по умолчанию для типа netflow5 тип протокола не указывается в полях событий KUMA. При парсинге данных в формате NetFlow на вкладке нормализатора Обогащение следует создать правило обогащения данных типа constant, добавляющее значение netflow в целевое поле DeviceProduct.
- netflow9
Этот метод парсинга используется для обработки данных в формате NetFlow v9.
При выборе этого метода можно воспользоваться преднастроенными правилами преобразования событий в формат KUMA, нажав на кнопку Применить сопоставление по умолчанию. Если тип netflow9 выбран для основного парсинга, дополнительная нормализация недоступна.
В правилах сопоставления по умолчанию для типа netflow9 тип протокола не указывается в полях событий KUMA. При парсинге данных в формате NetFlow на вкладке нормализатора Обогащение следует создать правило обогащения данных типа constant, добавляющее значение netflow в целевое поле DeviceProduct.
- sflow5
Этот метод парсинга используется для обработки данных в формате sflow5.
При выборе этого метода можно воспользоваться преднастроенными правилами преобразования событий в формат KUMA, нажав на кнопку Применить сопоставление по умолчанию. Если тип sflow5 выбран для основного парсинга, дополнительная нормализация недоступна.
- ipfix
Этот метод парсинга используется для обработки данных в формате IPFIX.
При выборе этого метода можно воспользоваться преднастроенными правилами преобразования событий в формат KUMA, нажав на кнопку Применить сопоставление по умолчанию. Если тип ipfix выбран для основного парсинга, дополнительная нормализация недоступна.
В правилах сопоставления по умолчанию для типа ipfix тип протокола не указывается в полях событий KUMA. При парсинге данных в формате NetFlow на вкладке нормализатора Обогащение следует создать правило обогащения данных типа constant, добавляющее значение netflow в целевое поле DeviceProduct.
- sql
Нормализатор использует этот метод для обработки данных, полученных с помощью выборки из базы данных.
- Сохранить исходное событие (обязательно) – с помощью этого раскрывающегося списка можно указать, надо ли сохранять исходное событие во вновь созданном нормализованном событии. Доступные значения:
- Не сохранять – не сохранять исходное событие. Это значение используется по умолчанию.
- При возникновении ошибок – сохранять исходное событие в поле
Raw нормализованного события, если в процессе парсинга возникли ошибки. Это значение удобно использовать при отладке сервиса: в этом случае появление у событий непустого поля Raw будет являться признаком неполадок.Если поля с названиями *Address или *Date* не соответствуют правилам нормализации, такие поля игнорируются. При этом не возникает ошибка нормализации и значения полей не попадают в поле Raw нормализованного события, даже если был указан параметр Сохранить исходное событие → При возникновении ошибок.
- Всегда – сохранять сырое событие в поле
Raw нормализованного события.
Этот параметр недоступен для дополнительных правил парсинга.
- Сохранить дополнительные поля (обязательно) – в этом раскрывающемся списке можно выбрать, хотите ли вы сохранять поля и их значения, для которых не настроены правила сопоставления (см. ниже). Эти данные сохраняются в поле события
Extra в виде массива. Нормализованные события можно искать и фильтровать по данным, хранящимся в поле Extra.Фильтрация по данным из поля события Extra
Условия для фильтров по данным из поля события Extra:
- Условие – Если.
- Левый операнд – поле события.
- В поле события вы можете указать одно из следующих значений:
- Поле Extra.
- Значение из поля Extra в следующем формате:
Extra.<название поля>
Например, Extra.app.
Значение этого типа указывается вручную.
- Значение из массива, записанного в поле Extra, в следующем формате:
Extra.<название поля>.<элемент массива>
Например, Extra.array.0.
Нумерация значений в массиве начинается с 0.
Значение этого типа указывается вручную.
Чтобы работать со значением из поля Extra на глубине 3 и ниже, следует использовать кавычки ``. Например, `Extra.lev1.lev2.lev3`.
- Оператор – =.
- Правый операнд – константа.
- Значение – значение, по которому требуется фильтровать события.
По умолчанию дополнительные поля не сохраняются.
- Описание – описание ресурса: до 4000 символов в кодировке Unicode.
Этот параметр недоступен для дополнительных правил парсинга.
- Примеры событий – в это поле можно поместить пример данных, которые вы хотите обработать.
Этот параметр недоступен для методов парсинга netflow5, netflow9, sflow5, ipfix, sql.
Поле Примеры событий заполняется данными, полученными из сырого события, если парсинг события был выполнен успешно и тип полученных из сырого события данных совпадает с типом поля KUMA.
Например, значение "192.168.0.1", заключенное в кавычки не будет отображено в поле SourceAddress, при этом значение 192.168.0.1 будет отображено в поле Примеры событий.
- Блок параметров Сопоставление – здесь можно настроить сопоставление полей исходного события с полями события в формате KUMA:
- Исходные данные – столбец для названий полей исходного события, которые вы хотите преобразовать в поля события KUMA.
Если рядом с названиями полей в столбце Исходные данные нажать на кнопку 
, откроется окно Преобразование, в котором с помощью кнопки Добавить преобразование можно создать правила изменения исходных данных перед тем, как они будут записаны в поля событий KUMA. В окне Преобразования добавленные правила можно менять местами, перетягивая их за значок 
, а также удалять с помощью значка 
.
Доступные преобразования
Преобразования – это изменения, которые можно применить к значению до того, как оно будет записано в поле события. Тип преобразования выбирается в раскрывающемся списке.
Доступные преобразования:
- lower – используется для перевода всех символов значения в нижний регистр
- upper – используется для перевода всех символов значения в верхний регистр
- regexp – используется для преобразования значения с помощью регулярного выражения RE2. Поле, в которое следует добавить регулярное выражение, появляется, когда выбран этот тип преобразования.
- substring – используется для извлечения символов в диапазоне позиций, указанном в полях Начало и Конец. Эти поля появляются, когда выбран данный тип преобразования.
- replace – используется для замены указанной последовательности символов на другую последовательность символов. Когда выбран этот тип преобразования, появляются новые поля:
- Символы на замену – в этом поле вы можете указать последовательность символов, которую следует заменить.
- Чем заменить – в этом поле вы можете указать последовательность символов, которая должна использоваться вместо заменяемой последовательности символов.
- trim – используется для удаления одновременно с начала и с конца значения поля события символов, указанных в поле Символы. Это поле появляется при выборе данного типа преобразования. Например, если для значения
Microsoft-Windows-Sysmon выполнить преобразование trim со значением Micromon, то получается значение soft-Windows-Sys. - append – используется для добавления в конец значения поля события символов, указанных в поле Константа. Это поле появляется при выборе данного типа преобразования.
- prepend – используется для добавления к началу значения поля события символов, указанных в поле Константа. Это поле появляется при выборе данного типа преобразования.
- replace with regexp – используется для замены результатов регулярного выражения RE2 на последовательность символов.
- Выражение – в этом поле вы можете указать регулярное выражение, результаты которого следует заменить.
- Чем заменить – в этом поле вы можете указать последовательность символов, которая должна использоваться вместо заменяемой последовательности символов.
- Конвертация закодированных строк в текст:
- decodeHexString – используется для конвертации HEX-строки в текст.
- decodeBase64String – используется для конвертации Base64-строки в текст.
- decodeBase64URLString – используется для конвертации Base64url-строки в текст.
При конвертации поврежденной строки или при ошибках конвертации в поле события могут быть записаны поврежденные данные.
При обогащении событий, если длина закодированной строки превышает размер поля нормализованного события, такая строка будет обрезана и не будет раскодирована.
Если длина раскодированной строки превышает размер поля события, в которое должно быть помещено раскодированное значение, такая строка будет обрезана до размера этого поля события.
Преобразования при использовании расширенной схемы событий
Возможность использования преобразования зависит от типа используемого поля расширенной схемы событий:
- для дополнительное поле с типом «Строка» доступны все типы преобразований.
- для полей с типами «Число», «Число с плавающей точкой» доступны следующие виды преобразований: regexp, substring, replace, trim, append, prepend, replaceWithRegexp, decodeHexString, decodeBase64String, decodeBase64URLString.
- для полей с типами «Массив строк», «Массив чисел» и «Массив чисел с плавающей точкой» доступны следующие виды преобразований: append, prepend.
- Поле KUMA – раскрывающийся список для выбора требуемых полей событий KUMA. Поля можно искать, вводя в поле их названия.
- Подпись – в этом столбце можно добавить уникальную пользовательскую метку полям событий, которые начинаются с
DeviceCustom* и Flex*.
Новые строки таблицы можно добавлять с помощью кнопки Добавить строку. Строки можно удалять по отдельности с помощью кнопки или все сразу с помощью кнопки Очистить все.
Если вы загрузили данные в поле Примеры событий, в таблице отобразится столбец Примеры с примерами значений, переносимых из поля исходного события в поле события KUMA.
Если размер поля события KUMA оказывается меньше длины помещаемого в него значения, значение обрезается до размера поля события.
Расширенная схема события
При нормализации событий, помимо полей стандартной схемы событий KUMA, могут быть использованы поля расширенной схемы событий. Информация о типах полей расширенной схемы событий приведена в таблице далее.
Использование значительного количества уникальных полей расширенной схемы событий может привести к снижению производительности системы, увеличению объёма дискового пространства, необходимого для хранения событий, сложности восприятия данных.
Мы рекомендуем предварительно продумать и сформировать минимально необходимый набор дополнительных полей расширенной схемы событий и использовать его в нормализаторах и корреляции.
Для использования полей расширенной схемы событий необходимо выполнить следующее:
Префиксы «S.», «N.», «F.», «SA.», «NA.», «FA.» обязательны при создании полей расширенной схемы событий, префиксы должны использовать только заглавные буквы.
Вместо <filed_name> необходимо задать имя поля. В имени поля допустимо использовать символы английского алфавита, числа. Использование символа «пробел» не допускается.
- Нажать кнопку ОК.
- Нажать кнопку Сохранить для заверения редактирования нормализатора событий.
Нормализатор сохранён, дополнительное поле создано. После сохранение нормализатора дополнительное поле может быть использовано в других нормализаторах.
Примечание: в случае, если данные, находящиеся в поля «сырого» события, не соответствуют типу поля KUMA, то в процессе нормализации событий значение не будет сохранено. Например, строка «test» не может быть помещена в числовое поле KUMA DeviceCustomNumber1.
С точки зрения нагрузки на сервер хранения при операциях при операциях поиска событий, подготовки отчётов и иных операциями с событиями в хранилище наиболее предпочтительными являются поля схемы событий KUMA, затем идут поля расширенной схемы событий., затем поля Extra.
В начало
