Работа с VRL-песочницей

Данный раздел описывает процесс работы с VRL-песочницей в системе R-Vision SIEM. Работа осуществляется в разделе Инструменты → VRL-песочница веб-интерфейса системы.

Раздел доступен администраторам, пользователям, которые имеют соответствующее разрешение в составе своих ролей, а также учетным записям со статусом Суперадминистратор.

О VRL-песочнице

VRL-песочница — инструмент системы R-Vision SIEM, предназначенный для тестирования VRL-программ, используемых для работы с элементами экспертизы и ресурсами системы.

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

Интерфейс раздела

Панель инструментов раздела содержит кнопку Запустить, которая позволяет выполнить VRL-программу.

Рабочая область раздела состоит из четырех панелей:

  • Программа — панель для ввода кода программы на языке VRL.

  • Событие — панель для указания события, которое будет обрабатываться программой, в формате JSON.

  • Мета — панель для указания вспомогательных метаданных в формате JSON при их наличии. Может быть пустой.

  • Результат — панель для вывода результата выполнения программы. Доступны следующие форматы результата:

    • Target — результат обработки события.

    • Metadata — результат обработки метаданных.

    • Expression — результат выполнения последнего выражения программы. Применяется для проверки фильтров.

    Если программа содержит ошибки или для выбранного формата результата заданы некорректные исходные данные, то при выполнении программы на панели Результат отображается значение null.

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

Результат выполнения программы можно скопировать, используя кнопку copy, расположенную в верхнем правом углу панели Результат.

Работа с редактором кода

В разделе VRL-песочница доступен редактор для кода программ, событий и метаданных, расположенный на панелях Программа, Событие и Мета соответственно.

В редакторах кода реализованы дополнительные возможности, повышающие удобство работы с ними:

  • Нумерация строк — каждая строка в редакторе кода имеет свой номер, начиная с 1.

  • Подсветка синтаксиса — ключевые слова, функции и константы визуально выделяются благодаря цветовой дифференциации.

  • Подстановка функций — система предлагает автоматическое дополнение кода при вводе, что экономит время на написание стандартных конструкций.

  • Валидация кода — автоматическая проверка кода на ошибки с моментальным подсказками для их исправления.

Поиск и подстановка функций

В разделе Инструменты → VRL-песочница при работе на панелях Программа, Событие и Мета предусмотрена функция быстрого поиска и подстановки встроенных VRL-функций в код.

Для подстановки функции:

  1. Откройте панель с перечнем встроенных функций одним из следующих способов:

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

    • Используйте сочетание клавиш CTRL+SPACE для отображения списка всех доступных функций.

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

    Вы можете дополнительно уточнить поиск, дописывая символы в название функции.

  3. Для вставки функции в код нажмите ENTER. Выбранная функция будет вставлена в код.

Просмотр и устранение ошибок

В разделе VRL-песочница происходит автоматическая валидация кода на панелях Программа, Событие и Мета. Система выделяет ошибки в коде и предлагает способы их исправления.

Для подробного просмотра ошибки:

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

  2. Чтобы получить детальное описание, кликните на кнопку View Problem. Отобразится панель с подробным описанием ошибки.

    На этой панели также отображается общее количество обнаруженных ошибок и порядковый номер текущей ошибки.

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

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

Обработка специальных символов

При работе с VRL-песочницей может возникнуть необходимость обработки событий, содержащих специальные символы. Для корректной передачи таких строк в VRL-песочницу, вместо использования стандартных двойных кавычек, необходимо применять конструкцию s'<string_value>', где <string_value> — это строка, содержащая специальные символы.

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

{
  "raw": "CEF:0|Example|Test|1.0|Event|Test Event|1|src=192.168.0.1 dst=192.168.0.2 suser=example_user request=GET /api/test?param=1 HTTP/1.1\\r\\nHost: example.com\\r\\nUser-Agent: test-agent\\r\\nContent-Type: application/json\\r\\n\\r\\n{\"key\":\"value with spaces\", \"another_key\":\"value_with_special_characters_!@#$%^&*()\"}"
}

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

{
  "raw": s'CEF:0|Example|Test|1.0|Event|Test Event|1|src=192.168.0.1 dst=192.168.0.2 suser=example_user request=GET /api/test?param=1 HTTP/1.1\\r\\nHost: example.com\\r\\nUser-Agent: test-agent\\r\\nContent-Type: application/json\\r\\n\\r\\n{"key":"value with spaces", "another_key":"value_with_special_characters_!@#$%^&*()"}'
}

Тестирование VRL-программ

Для тестирования VRL-программ следуйте указанному алгоритму:

  1. Перейдите в Инструменты → VRL-песочница.

  2. Загрузите исходное событие в формате JSON на панели Событие.

  3. Если требуется, добавьте метаданные в формате JSON на панели Мета.

  4. Введите код программы на языке VRL на панели Программа.

  5. Выберите требуемый тип объекта из выпадающего списка на панели Результат.

  6. Запустите выполнение программы, нажав кнопку Запустить.

    После запуска, результаты выполнения программы отобразятся на панели Результат в выбранном формате.

Рассмотрим применение VRL-песочницы для тестирования следующих типов программ:

Тестирование нормализации

При выполнении нормализации происходит преобразование полей исходного события. Формат исходного события и правила преобразования задаются на панелях Событие и Программа соответственно.

Для тестирования нормализации:

  1. Перейдите в раздел Инструменты → VRL-песочница.

  2. Введите исходное событие в формате JSON на панели Событие.

  3. Введите правило преобразования исходного события на языке VRL на панели Программа.

  4. Выберите тип объекта Target из выпадающего списка на панели Результат.

  5. Нажмите на кнопку Запустить для запуска выполнения программы.

    Если выполнение программы прошло успешно, обработанное событие отобразится на панели Результат.

Пример программы

Example 1. VRL-программа (панель Программа)
# Добавим временную метку.
.timestamp = now()

# Сохраним HTTP-код статуса в локальную переменную.
http_status_code = parse_int!(.http_status)

# Удалим HTTP-код статуса.
del(.http_status)

# Добавим поле статуса.
if http_status_code >= 200 && http_status_code <= 299 {
    .status = "success"
    .message = "error {{http_status_code}}"
} else {
.status = "error"
}
Example 2. Исходное событие (панель Событие)
{
"http_status": "200",
"message": "Test event"
}
Example 3. Пример результата (панель Результат, тип объекта Target)
{
  "message": "Test event",
  "status": "success",
  "timestamp": "2023-12-15T08:27:30.561242360Z"
}

В результате выполнения примера:

  • Из исходного события будет удалено поле http_status_code.

  • В исходное событие будет добавлено поле status, значение которого зависит от значения, хранившегося в поле http_status_code.

  • В исходное событие будет добавлено поле timestamp, в котором хранится временная метка запуска выполнения программы.

Тестирование корреляции

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

  • Формат исходного события задается на панели Метаданные.

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

  • Анализ и обработка событий происходит на панели Программа.

Чтобы протестировать выполнение корреляции:

  1. Перейдите в раздел Инструменты → VRL-песочница.

  2. Введите исходное событие в формате JSON на панели Мета.

  3. Введите корреляционное событие в формате JSON на панели Событие.

  4. Введите правило обработки исходного события и создания корреляционного события на языке VRL на панели Программа.

  5. Выберите тип объекта из выпадающего списка на панели Результат:

    • Target — для вывода созданного корреляционного события.

    • Metadata — для вывода обработанного исходного события.

  6. Нажмите на кнопку Запустить для запуска выполнения программы.

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

Пример программы

Example 4. VRL-программа (панель Программа)
# Сохраним поля из исходного события в локальную переменную.
dhost = to_string(%dhost) ?? ""
duser = to_string(%duser) ?? ""
dproc = to_string(%dproc) ?? ""

# Запишем значения полей в корреляционное событие.
.dhost = dhost
.duser = duser
.dproc = dproc

# Добавим поле с сообщением в корреляционное событие.
.message = "На хосте {{dhost}} под пользователем {{duser}} была запущена программа {{dproc}}"
Example 5. Корреляционное событие (панель Событие)
{
"id": "1",
}
Example 6. Исходное событие (панель Метаданные)
{
"dhost": "arm",
"dproc": "ipconfig.exe",
"duser": "user",
"id": "1"
}
Example 7. Результат (панель Результат, тип объекта Target)
{
  "dhost": "arm",
  "dproc": "ipconfig.exe",
  "duser": "user",
  "id": "1",
  "message": "На хосте arm под пользователем user была запущена программа ipconfig.exe"
}
В VRL-программе для доступа к данным корреляционного события (панель Событие) используется символ точки (.), а для доступа к данным из исходного события (панель Мета) — символ процента (%).

В результате выполнения программы корреляции:

  • В корреляционное событие будут добавлены значения полей dhost, dproc, и duser, взятые из исходного события.

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

Проверка условий фильтрации

Проверка условий фильтрации в VRL-песочнице осуществляется на основе данных, введённых в панели Событие и/или Мета. Условие фильтрации задаётся на панели Программа на языке VRL.

Чтобы проверить условие фильтрации:

  1. Перейдите в раздел Инструменты → VRL-песочница.

  2. Введите требуемое событие в формате JSON на панели Событие.

  3. Введите требуемые метаданные в формате JSON на панели Мета при их наличии.

  4. Введите условие фильтрации на языке VRL на панели Программа.

  5. Выберите тип объекта Expression из выпадающего списка на панели Результат.

  6. Нажмите на кнопку Запустить для запуска выполнения программы.

    Если условие фильтрации выполнено, на панели Результат отобразится значение true, если не выполнено — false.

Пример программы

Example 8. Условие фильтрации (панель Программа)
.act == "login_failed"
Example 9. Исходное событие (панель Событие)
{
"act": "login_failed",
"dvendor": "Linux",
"message": "Test event"
}
Example 10. Результат (панель Результат, тип объекта Expression)
true

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

Использование горячих клавиш

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

Table 1. Горячие клавиши VRL-песочницы
Сочетание клавиш Действие Область применения

CTRL+Z

Отмена последнего изменения

Панели Программа, Событие и Мета

CTRL+Y

Повтор последнего отмененного действия

Панели Программа, Событие и Мета

CTRL+SPACE

Открытие панели со списком встроенных функций

Панели Программа, Событие и Мета

ALT+F8

Открытие панели детального описания ошибок

Панели Программа, Событие и Мета, где есть ошибки

SHIFT+ENTER

Запуск выполнения программы

Любое место песочницы
+7 (499) 322 80 40 sales@rvision.ru

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