Функции событий и активных списков
В данном разделе при описании функций приняты следующие обозначения:
|
Функции секретов
get_secret
Возвращает значение заданного секрета из события.
Спецификация функции
get_secret(key: <строка>) :: <строка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
строка |
Имя секрета. |
да |
Пример
Получение ключа API Datadog из метаданных события
get_secret("datadog_api_key")
"secret value"
remove_secret
Удаляет секрет из события.
Спецификация функции
remove_secret(key: <строка>) :: <пустое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
строка |
Имя секрета для удаления. |
да |
Пример
Удаление ключа API Datadog из события
remove_secret("datadog_api_key")
null
set_secret
Устанавливает указанный секрет в событие.
Спецификация функции
set_secret(key: <строка>, secret: <строка>) :: <пустое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
строка |
Имя секрета |
да |
|
|
строка |
Значение секрета |
да |
Пример
Установка значения ключа API Datadog
set_secret("datadog_api_key", "abc122")
null
set_semantic_meaning
Устанавливает семантический смысл для события.
Эта функция устанавливает значение при запуске и не выполняется поведения во время работы программы. Рекомендуется размещать все вызовы этой функции в начале программы VRL. Функцию нельзя вызывать внутри условия. Например, нельзя предотвратить присваивание значения с использованием оператора |
Спецификация функции
set_semantic_meaning(target: <путь>, meaning: <строка>) :: <пустое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
путь |
Путь к значению, которому будет назначено семантическое значение. |
да |
|
|
строка |
Имя назначаемого значения. |
да |
Пример
Присваивание полю пользовательского семантического смысла
set_semantic_meaning(.foo, "bar")
null
Функции таблиц обогащения
find_enrichment_table_records
Поиск строк в таблице обогащения, соответствующих предоставленному условию.
Поскольку условие используется при загрузке таблицы для создания индексов в данных, оно должно быть представлено литералом, без использования переменных. |
-
Для таблиц обогащения типа
file
это условие должно быть объектом VRL, в котором ключи и значения указывают на поле для поиска и значение для поиска в этом поле. Эта функция возвращает строки, соответствующие предоставленным условиям. Все поля должны совпадать, чтобы строки были возвращены; если хотя бы одно поле не совпадает, строки не возвращаются.В настоящее время существуют следующие формы критериев поиска:
-
Поиск точного совпадения. Заданное поле должно точно совпадать со значением. Чувствительность к регистру может быть указана с помощью аргумента
case_sensitive
. Точный поиск может использовать индекс прямо в наборе данных, что делает его менее ресурсозатратным с точки зрения производительности. -
Поиск по диапазону дат. Заданное поле должно попадать в диапазон от даты
from
до датыto
включительно.Поиск по диапазону дат включает последовательное сканирование строк, которые были найдены с помощью любых точных критериев. Такая операция может оказаться ресурсозатратной, если много строк возвращается любыми точными критериями. Рекомендуется использовать диапазоны дат как единственные критерии, когда набор данных обогащения очень мал.
-
-
Для таблиц обогащения
geoip
это условие должно быть объектом VRL с одной парой "ключ — значение", значение которой должно быть действительным IP-адресом. Пример:{"ip": .ip }
. Если ожидается поле с результатом без значения, будет использовано значениеnull
.Поля, возвращаемые из таблицы
-
Базы данных ISP:
-
autonomous_system_number
; -
autonomous_system_organization
; -
isp
; -
organization
.
-
-
Базы данных City:
-
city_name
; -
continent_code
; -
country_code
; -
country_name
; -
region_code
; -
region_name
; -
metro_code
; -
latitude
; -
longitude
; -
postal_code
; -
timezone
.
-
-
Базы данных Connection-Type:
-
connection_type
.
-
-
Спецификация функции
find_enrichment_table_records(table: <строка>, condition: <объект>, [select: <массив>,] [case_sensitive: <логическое значение>]) :: <массив>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
строка |
Таблица обогащения для поиска. |
да |
|
|
объект |
Условие для поиска. |
да |
|
|
массив |
Подмножество возвращаемых полей из таблицы обогащения. Если не указано, будут возвращены все поля. |
нет |
|
|
логическое значение |
Определяет, нужно ли точное совпадение текстовых полей. |
|
нет |
Примеры
Точное совпадение
find_enrichment_table_records!("test",
{"surname": "smith",},
case_sensitive: false)
[ { "id": 1, "firstname": "Bob", "surname": "Smith" }, { "id": 2, "firstname": "Fred", "surname": "Smith" } ]
Поиск по диапазону дат
find_enrichment_table_records!("test",
{
"surname": "Smith",
"date_of_birth": {
"from": t'1985-01-01T00:00:00Z',
"to": t'1985-12-31T00:00:00Z'
}
})
[ { "id": 1, "firstname": "Bob", "surname": "Smith" }, { "id": 2, "firstname": "Fred", "surname": "Smith" } ]
get_enrichment_table_record
Функция ищет строку в таблице обогащения, которая соответствует указанному условию. Должна быть найдена одна строка. Если строка не найдена или найдено более одной строки, возвращается ошибка.
Поскольку условие используется при загрузке таблицы для создания индексов в данных, оно должно быть представлено литералом, без использования переменных. |
-
Для таблиц обогащения типа
file
это условие должно быть объектом VRL, в котором ключи и значения указывают на поле для поиска и значение для поиска в этом поле. Эта функция возвращает строки, соответствующие предоставленным условиям. Все поля должны совпадать, чтобы строки были возвращены; если хотя бы одно поле не совпадает, строки не возвращаются.В настоящее время существуют следующие формы критериев поиска:
-
Поиск точного совпадения. Заданное поле должно точно совпадать со значением. Чувствительность к регистру может быть указана с помощью аргумента
case_sensitive
. Точный поиск может использовать индекс прямо в наборе данных, что делает его менее ресурсозатратным с точки зрения производительности. -
Поиск по диапазону дат. Заданное поле должно попадать в диапазон от даты
from
до датыto
включительно.Поиск по диапазону дат включает последовательное сканирование строк, которые были найдены с помощью любых точных критериев. Такая операция может оказаться ресурсозатратной, если много строк возвращается любыми точными критериями. Рекомендуется использовать диапазоны дат как единственные критерии, когда набор данных обогащения очень мал.
-
-
Для таблиц обогащения
geoip
это условие должно быть объектом VRL с одной парой "ключ — значение", значение которой должно быть действительным IP-адресом. Пример:{"ip": .ip }
. Если ожидается поле с результатом без значения, будет использовано значениеnull
.Поля, возвращаемые из таблицы
-
Базы данных ISP:
-
autonomous_system_number
; -
autonomous_system_organization
; -
isp
; -
organization
.
-
-
Базы данных City:
-
city_name
; -
continent_code
; -
country_code
; -
country_name
; -
region_code
; -
region_name
; -
metro_code
; -
latitude
; -
longitude
; -
postal_code
; -
timezone
.
-
-
Базы данных Connection-Type:
-
connection_type
.
-
-
Спецификация функции
get_enrichment_table_record(table: <строка>, condition: <объект>, [select: <массив>,] [case_sensitive: <логическое значение>]) :: <объект>, <ошибка>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
строка |
Таблица обогащения для поиска. |
да |
|
|
объект |
Условие для поиска. |
да |
|
|
массив |
Подмножество возвращаемых полей из таблицы обогащения. Если не указано, будут возвращены все поля. |
нет |
|
|
логическое значение |
Должны ли текстовые поля соответствовать регистру точно. |
|
нет |
Ошибки
Функция get_enrichment_table_record
возвращает ошибки, для которых требуется обработка:
-
Строка не найдена;
-
Найдено несколько строк, соответствующих условию.
Эта ошибка не возвращается для искусственных таблиц обогащения в поле setup_tests
элементов экспертизы.
Примеры
Точное совпадение
get_enrichment_table_record!("test",
{
"surname": "bob",
"firstname": "John"
},
case_sensitive: false)
{ "id": 1, "firstname": "Bob", "surname": "Smith" }
Поиск по диапазону даты
get_enrichment_table_record!("test",
{
"surname": "Smith",
"date_of_birth": {
"from": t'1985-01-01T00:00:00Z',
"to": t'1985-12-31T00:00:00Z'
}
})
{ "id": 1, "firstname": "Bob", "surname": "Smith" }
Функции активных списков
active_record_excluded
Проверяет, есть ли запись с указанным ключом key
в активном списке active_list
. Значения полей в ключе могут быть указаны с выражением объединения, что приводит к генерации разных вариантов ключа. При проверке функция ищет не только совпадения с переданными значениями полей, но и со значением "*"
.
Функция возвращает true
, если хотя бы один из вариантов ключа совпадает с записью из списка исключений.
Спецификация функции
active_record_excluded(active_list: <строка>, key: <объект>)
:: <логическое значение>, <ошибка>
Аргумент | Тип | Описание | Обязателен |
---|---|---|---|
|
строка |
Название схемы активного списка, в котором выполняется проверка. Название должно быть представлено литералом строки, без использования переменных. |
да |
|
объект |
Ключ записи. |
да |
Ошибки
Функция active_record_excluded
может возвращать ошибки, для которых требуется обработка:
-
Параметр
active_list
не закодирован в UTF-8. -
Параметр
key
не является объектом.
Пример
...
schema:
exclusion_id: string
user: string
host: string
notes: string
...
key:
- rule_id
- user
- host
content:
- exclusion_id: "admin_actions"
user: "admin"
host: "*"
...
{
"user": "admin",
"hostname": "localhost"
}
active_record_excluded!("user_whitelist", { "user": .user ?? "", "host": downcase(.hostname) ?? ""})
true
add_active_record
Добавляет запись в активный список. Если запись с таким ключом уже существует, значение обновляется. В противном случае создается новая запись.
Следует заполнять все поля записи, предусмотренные схемой активного списка, в противном случае запись добавлена не будет. |
Спецификация функции
add_active_record(list: <строка>, value: <объект>)
:: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
строка |
название схемы активного списка, в который добавляется запись |
да |
|
|
объект |
значение записи |
да |
Примеры
Добавление записи в активный список
add_active_record!("suspicious_ips", { "source_ip": .source_ip, "is_suspicious": true })
true
Обновление записи в активном списке
failure_count = get_active_record!("auth_failure_counts", { "user_id": .user_id }).failure_count || 0
add_active_record!("auth_failure_counts", { "user_id": .user_id, {"failure_count": failure_count + 1 })
true
get_active_record
Извлекает значение из активного списка по указанному ключу. Возвращает значение, ассоциированное с ключом, или null
, если запись отсутствует.
Спецификация функции
get_active_record(list: <строка>, key: <объект>)
:: <любое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
строка |
активный список, из которого нужно извлечь запись |
да |
|
|
объект |
уникальный ключ записи |
да |
Пример
Получение записи из активного списка
get_active_record!("allowed_ips", { "ip": .source_ip)
true
remove_active_record
Удаляет запись из активного списка. Если запись с таким ключом отсутствует, ничего не происходит.
Спецификация функции
remove_active_record(list: <строка>, key: <объект>)
:: <логическое значение>
Аргумент | Тип | Описание | По умолчанию | Обязателен |
---|---|---|---|---|
|
строка |
активный список, из которого необходимо удалить запись |
да |
|
|
объект |
уникальный ключ записи, которую необходимо удалить |
да |
Пример
Удаление записи из активного списка
remove_active_record!("auth_failure_counts", { "user_id": .user_id })
true