Функции событий и активных списков
|
В данном разделе при описании функций приняты следующие обозначения:
|
Функции секретов
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
Была ли полезна эта страница?