Функции событий и активных списков

В данном разделе при описании функций приняты следующие обозначения:

  • Типы значений, которые принимает аргумент, указаны в угловых скобках.

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

  • После :: в угловых скобках указаны типы значений, которые возвращает функция.

Функции секретов

get_secret

Возвращает значение заданного секрета из события.

Спецификация функции

get_secret(key: <строка>)
:: <строка>
Аргумент Тип Описание По умолчанию Обязателен

key

строка

Имя секрета.

да

Пример

Получение ключа API Datadog из метаданных события

Пример 1. Исходный код
get_secret("datadog_api_key")
Пример 2. Результат
"secret value"

remove_secret

Удаляет секрет из события.

Спецификация функции

remove_secret(key: <строка>)
:: <пустое значение>
Аргумент Тип Описание По умолчанию Обязателен

key

строка

Имя секрета для удаления.

да

Пример

Удаление ключа API Datadog из события

Пример 3. Исходный код
remove_secret("datadog_api_key")
Пример 4. Результат
null

set_secret

Устанавливает указанный секрет в событие.

Спецификация функции

set_secret(key: <строка>, secret: <строка>)
:: <пустое значение>
Аргумент Тип Описание По умолчанию Обязателен

key

строка

Имя секрета

да

secret

строка

Значение секрета

да

Пример

Установка значения ключа API Datadog

Пример 5. Исходный код
set_secret("datadog_api_key", "abc122")
Пример 6. Результат
null

set_semantic_meaning

Устанавливает семантический смысл для события.

Эта функция устанавливает значение при запуске и не выполняется поведения во время работы программы. Рекомендуется размещать все вызовы этой функции в начале программы VRL.

Функцию нельзя вызывать внутри условия. Например, нельзя предотвратить присваивание значения с использованием оператора if.

Спецификация функции

set_semantic_meaning(target: <путь>, meaning: <строка>)
:: <пустое значение>
Аргумент Тип Описание По умолчанию Обязателен

target

путь

Путь к значению, которому будет назначено семантическое значение.

да

meaning

строка

Имя назначаемого значения.

да

Пример

Присваивание полю пользовательского семантического смысла

Пример 7. Исходный код
set_semantic_meaning(.foo, "bar")
Пример 8. Результат
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: <логическое значение>])
:: <массив>
Аргумент Тип Описание По умолчанию Обязателен

table

строка

Таблица обогащения для поиска.

да

condition

объект

Условие для поиска.

да

select

массив

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

нет

case_sensitive

логическое значение

Определяет, нужно ли точное совпадение текстовых полей.

true

нет

Примеры

Точное совпадение

Пример 9. Исходный код
find_enrichment_table_records!("test",
{"surname": "smith",},
case_sensitive: false)
Пример 10. Результат
[
  {
    "id": 1,
    "firstname": "Bob",
    "surname": "Smith"
  },
  {
    "id": 2,
    "firstname": "Fred",
    "surname": "Smith"
  }
]

Поиск по диапазону дат

Пример 11. Исходный код
find_enrichment_table_records!("test",
{
  "surname": "Smith",
  "date_of_birth": {
  "from": t'1985-01-01T00:00:00Z',
  "to": t'1985-12-31T00:00:00Z'
  }
})
Пример 12. Результат
[
  {
    "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: <логическое значение>])
:: <объект>, <ошибка>
Аргумент Тип Описание По умолчанию Обязателен

table

строка

Таблица обогащения для поиска.

да

condition

объект

Условие для поиска.

да

select

массив

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

нет

case_sensitive

логическое значение

Должны ли текстовые поля соответствовать регистру точно.

true

нет

Ошибки

Функция get_enrichment_table_record возвращает ошибки, для которых требуется обработка:

  • Строка не найдена;

  • Найдено несколько строк, соответствующих условию.

    Эта ошибка не возвращается для искусственных таблиц обогащения в поле setup_tests элементов экспертизы.

Примеры

Точное совпадение

Пример 13. Исходный код
get_enrichment_table_record!("test",
{
  "surname": "bob",
  "firstname": "John"
},
case_sensitive: false)
Пример 14. Результат
{
  "id": 1,
  "firstname": "Bob",
  "surname": "Smith"
}

Поиск по диапазону даты

Пример 15. Исходный код
get_enrichment_table_record!("test",
{
  "surname": "Smith",
  "date_of_birth": {
    "from": t'1985-01-01T00:00:00Z',
    "to": t'1985-12-31T00:00:00Z'
  }
})
Пример 16. Результат
{
  "id": 1,
  "firstname": "Bob",
  "surname": "Smith"
}

Функции активных списков

active_record_excluded

Проверяет, есть ли запись с указанным ключом key в активном списке active_list. Значения полей в ключе могут быть указаны с выражением объединения, что приводит к генерации разных вариантов ключа. При проверке функция ищет не только совпадения с переданными значениями полей, но и со значением "*".

Функция возвращает true, если хотя бы один из вариантов ключа совпадает с записью из списка исключений.

Спецификация функции

active_record_excluded(active_list: <строка>, key: <объект>)
:: <логическое значение>, <ошибка>
Аргумент Тип Описание Обязателен

active_list

строка

Название схемы активного списка, в котором выполняется проверка.

Название должно быть представлено литералом строки, без использования переменных.

да

key

объект

Ключ записи.

да

Ошибки

Функция active_record_excluded может возвращать ошибки, для которых требуется обработка:

  • Параметр active_list не закодирован в UTF-8.

  • Параметр key не является объектом.

Пример

Пример 17. Фрагмент схемы активного списка
...
schema:
  exclusion_id: string
  user: string
  host: string
  notes: string
  ...
key:
  - rule_id
  - user
  - host
content:
  - exclusion_id: "admin_actions"
    user: "admin"
    host: "*"
    ...
Пример 18. Фрагмент события
{
  "user": "admin",
  "hostname": "localhost"
}
Пример 19. Исходный код
active_record_excluded!("user_whitelist", { "user": .user ?? "", "host": downcase(.hostname) ?? ""})
Пример 20. Результат
true

add_active_record

Добавляет запись в активный список. Если запись с таким ключом уже существует, значение обновляется. В противном случае создается новая запись.

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

Спецификация функции

add_active_record(list: <строка>, value: <объект>)
:: <логическое значение>
Аргумент Тип Описание По умолчанию Обязателен

list

строка

название схемы активного списка, в который добавляется запись

да

value

объект

значение записи

да

Примеры

Добавление записи в активный список

Пример 21. Исходный код
add_active_record!("suspicious_ips", { "source_ip": .source_ip, "is_suspicious": true })
Пример 22. Результат
true

Обновление записи в активном списке

Пример 23. Исходный код
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 })
Пример 24. Результат
true

get_active_record

Извлекает значение из активного списка по указанному ключу. Возвращает значение, ассоциированное с ключом, или null, если запись отсутствует.

Спецификация функции

get_active_record(list: <строка>, key: <объект>)
:: <любое значение>
Аргумент Тип Описание По умолчанию Обязателен

list

строка

активный список, из которого нужно извлечь запись

да

key

объект

уникальный ключ записи

да

Пример

Получение записи из активного списка

Пример 25. Исходный код
get_active_record!("allowed_ips", { "ip": .source_ip)
Пример 26. Результат
true

remove_active_record

Удаляет запись из активного списка. Если запись с таким ключом отсутствует, ничего не происходит.

Спецификация функции

remove_active_record(list: <строка>, key: <объект>)
:: <логическое значение>
Аргумент Тип Описание По умолчанию Обязателен

list

строка

активный список, из которого необходимо удалить запись

да

key

объект

уникальный ключ записи, которую необходимо удалить

да

Пример

Удаление записи из активного списка

Пример 27. Исходный код
remove_active_record!("auth_failure_counts", { "user_id": .user_id })
Пример 28. Результат
true