lookup

Описание

Позволяет получить данные из предопределенного справочника (lookup). Команда выполняет сравнение заданных полей в событии и справочнике. При полном соответствии событие будет обогащено указанными полями из справочника.

Синтаксис

lookup [dedup=<boolean>] [<execution-type>] [system=<boolean>] <lookup-name>  ( <lookup-field> [AS <event-field>] )... [ OUTPUT | OUTPUTNEW (<lookup-destfield> [AS <event-destfield>] )... ]

---

Обязательные аргументы

Параметр	Синтаксис	Описание
lookup-name	<lookup-name>	Имя предопределенного lookup.

---

Опциональные аргументы

Параметр	Синтаксис	По умолчанию	Описание
dedup	dedup=<boolean>	false	Указывает, нужно ли убирать дубликаты из данных, которые сравниваются с лукапом.
<execution-type>	type=SOURCE [packsize=<int>] | FAST | ERGO	DEFAULT	См. Режимы выполнения
system	system=<boolean>	false	При значении true запрашивается системный лукап, в противном случае пользовательский.
lookup-field	<field>		Название поля для сравнения. Могут быть указаны несколько полей. Разделитель между полями запятая.
event-field	<field>		Имя поля в основном результате для сравнения с lookup-field. Используется в случае если названия lookup-field и event-field не совпадают.
lookup-destfield	<field>		Имя результирующего поля с полученными из справочника данными.
OUTPUT | OUTPUTNEW	OUTPUT | OUTPUTNEW	OUTPUT	Индикатор OUTPUT указывает, на то что, существующие данные в поле исходного запроса будут перезаписаны данными из lookup. Индикатор OUTPUTNEW указывает на то, что данные в поле исходного запроса будут перезаписаны, если поле не заполнено, но есть данные для этого поля в lookup.

Режимы выполнения

• DEFAULT - режим по умолчанию. Рекомендуется использовать только для небольшого потока входящих событий и маленьких лукапов
• FAST - оптимизированная по скорости версия стандартного алгоритма. Рекомендуется использовать в большинстве случаев
• ERGO - оптимизированная по использованию оперативной памяти версия стандартного алгоритма. Рекомендуется использовать при сравнении по нескольким полям
• SOURCE - выполняет сопоставление средствами хранилища. Дополнительно можно указать значение packsize, который определяет размер пачки запросов к хранилищу

Лимиты при загрузке лукапов

При загрузке в оперативную память лукапов в режимах FAST и ERGO применяется пользовательский лимит Количество запрашиваемых данных. Если размер лукапа превышает этот лимит, его можно повысить или использовать режим SOURCE.

Ограничения режимов FAST и ERGO

В режимах FAST и ERGO сопоставление выполняется по точному совпадению значений с учетом регистра.

Настройки полей Чувствительность к регистру, Wildcard и Cidrmatch, заданные в конфигурации lookup, в этих режимах не учитываются.

Для применения указанных правил сопоставления используйте режим DEFAULT или SOURCE.

Рекомендации по настройке режима SOURCE

Для типа выполнения SOURCE рекомендуется не ставить большой max_initial_query_len. Параметр packsize указывает на то, по сколько событий будет за один запрос обрабатываться движком в каждой итерации. То есть если max_initial_query_len = 10.000, а packsize = 5.000, то за одну итерацию в 10 тысяч событий будет отправлено два запроса (max_initial_query_len/packsize). Если max_initial_query_len больше 20 тысяч, то рекомендуется выполнять команду с параметром packsize в два или три раза меньше max_initial_query_len.

---

Работа с multivalue

к сведению

Multivalue - это возможность для атрибута иметь несколько значений, вместо одного. Multivalue можно представить в виде списка значений. Примерами multivalue может выступать список ролей пользователя.

При работе команды lookup тип значения multivalue могут принимать как поля из результатов поиска (multivalue слева), так и поля из справочников (multivalue справа). Таким образом, существует три случая, когда команда lookup содержит в себе multivalue:

• multivalue слева
• multivalue справа
• multivalue и слева, и справа

Multivalue-значение слева

Значение из справочника сопоставляется с результатом поиска в случае, если значение из справочника содержится в multivalue-значении результата поиска.

Значение слева	Значение справа	Пересечение значений	Сопоставление
[1, 2, 3, 4, 5]	3	3	Да
[1, 2, 3, 4, 5]	6	-	Нет

Multivalue-значение справа

Значение из справочника сопоставляется с результатом поиска в случае, если результат поиска содержится в multivalue-значении из справочника.

Значение слева	Значение справа	Пересечение значений	Сопоставление
3	[1, 2, 3, 4, 5]	3	Да
6	[1, 2, 3, 4, 5]	-	Нет

Multivalue-значение и слева, и справа

Значение из справочника с результатом поиска в случае, если пересечение multivalue-значений слева и справа не является пустым

Значение слева	Значение справа	Пересечение значений	Сопоставление
[1, 2, 3, 4, 5]	[3]	[3]	Да
[1, 2, 3, 4, 5]	[1, 2, 5]	[1, 2, 5]	Да
[1, 2, 3, 4, 5]	[1, 2, 6]	[1, 2]	Да
[1, 2, 3]	[4, 5, 6]	-	Нет
[1, 2, 3]	[4]	-	Нет

---

Примеры запросов

Пример 1

В первом примере для каждого входящего события выполняется сопоставление поля database из события и поля name в каждой строчке справочника. Если эти значения совпали, в событие будет добавлено поле engine, значение которого будет взято из соответствующей строчки справочника. Если в событие уже было поле engine, оно будет перезаписано новым значением.

Пример входных данных tables-*:

_time	database	table_name	engine
2025-06-05 14:30:00	hr	employees
2025-06-05 14:31:00	hr	departments	MyISAM
2025-06-05 14:32:00	sales	orders	InnoDB

Справочник my_click_db:

name	table_name	engine	description	version	rows	size.mb
hr	employees	InnoDB	Employee data	8.0.30	100	1.2
hr	departments	InnoDB	Department data	8.0.30	10	0.5
sales	orders	MyISAM	Orders data	5.7.42	250000	45.7
finance	transactions	InnoDB	Financial transactions	8.0.30	50000	8.1

Использование опции OUTPUT

Опция OUTPUT перезаписывает поле engine в событиях значениями из справочника, даже если engine уже заполнено.

source tables
| search database = "hr"
| lookup my_click_db name as database OUTPUT engine

Результатом запроса может быть следующая таблица:

_time	database	table_name	engine	description	version	rows	size.mb
2025-06-05 14:30:00	hr	employees	InnoDB	Employee data	8.0.30	100	1.2
2025-06-05 14:31:00	hr	departments	InnoDB	Department data	8.0.30	10	0.5

Использование опции OUTPUTNEW и режима выполнения SOURCE

В данном примере выполняется аналогичное сопоставление в режиме SOURCE. Это значит, что сопоставление будет выполнено средствами хранилища. Параметр packsize=5000 указывает, что запросы к хранилищу будут отправляться пачками по 5000. Опция OUTPUTNEW указывает, что поле engine не будет перезаписано, если оно уже есть в событии.

source tables
| search database = "hr"
| lookup type=SOURCE packsize=5000 my_click_db name as database OUTPUTNEW engine

Результатом запроса может быть следующая таблица:

_time	database	table_name	engine	description	version	rows	size.mb
2025-06-05 14:30:00	hr	employees	InnoDB	Employee data	8.0.30	100	1.2
2025-06-05 14:31:00	hr	departments	MyISAM	Department data	8.0.30	10	0.5

---

Пример 2

В данном примере выполняется сопоставление поля vulnerabilities из события и многозначного поля cve_id в каждой строчке справочника. Команда выполняется в режиме ERGO. Это значит, что сопоставление оптимизировано для экономии оперативной памяти. Опция OUTPUT указывает, что поля description и severity из справочника перезаписывают или добавляются в события, обогащая их информацией об уязвимостях.

source security_incidents-*
| search vulnerabilities="CVE-*"
| lookup type=ERGO vulnerabilities_info cve_id AS vulnerabilities OUTPUT description, severity

Пример входных данных security_incidents-*:

_time	host	vulnerabilities	affected_system
2025-06-05 14:30:00	VLG-01	CVE-2023-1234 CVE-2023-5678	WebServer
2025-06-05 14:32:00	VLG-02	CVE-2023-5678 CVE-2024-9012	Database

Справочник vulnerabilities_info:

cve_id	description	severity
CVE-2023-1234	SQL Injection Vulnerability	High
CVE-2023-5678	Cross-Site Scripting (XSS)	Medium
CVE-2024-9012	Remote Code Execution	Critical

Результатом запроса может быть следующая таблица:

host	affected_system	description	severity
VLG-01	WebServer	SQL Injection Vulnerability	High
VLG-01	WebServer	Cross-Site Scripting (XSS)	Medium
VLG-02	Database	Cross-Site Scripting (XSS)	Medium
VLG-02	Database	Remote Code Execution	Critical

Использование аргумента dedup

Команда lookup обогащает события информацией об уязвимостях description и severity, исключая дубликаты в поле vulnerabilities перед сопоставлением благодаря опции dedup=true.

source security_incidents-*
| search vulnerabilities="CVE-*"
| lookup dedup=true type=ERGO vulnerabilities_info cve_id AS vulnerabilities OUTPUT description, severity

Пример входных данных security_incidents-* с повторяющимися значениями CVE-2023-5678 в первой записи, где affected_system="WebServer", и во второй записи, где affected_system="Database":

_time	host	vulnerabilities	affected_system
2025-06-05 14:30:00	VLG-01	CVE-2023-1234 CVE-2023-5678 CVE-2023-5678	WebServer
2025-06-05 14:32:00	VLG-02	CVE-2023-5678 CVE-2024-9012 CVE-2023-5678	Database

В данном случае в результате запроса будут исключены дубликаты CVE, как в начале примера 2:

host	affected_system	description	severity
VLG-01	WebServer	SQL Injection Vulnerability	High
VLG-01	WebServer	Cross-Site Scripting (XSS)	Medium
VLG-02	Database	Cross-Site Scripting (XSS)	Medium
VLG-02	Database	Remote Code Execution	Critical

---

Пример 3

В третьем примере выполняется сопоставление многозначного поля malware_description из события и многозначного поля description в каждой строке справочника. Команда lookup обогащает события информацией о типе вредоносного ПО malware_type на основе частичного или полного пересечения списков сигнатур.

Пример входных данных security_alerts-*:

_time	host	malware_description	file	malware_type
2025-06-05 14:30:00	VLG-01	W32.File.Mal W32.2C2D W32.Auto.A	mssecsvc.exe
2025-06-05 14:30:00	VLG-02	W32.ED01 W32.Overdrive	OLD.exe	Virus
2025-06-05 14:30:00	VLG-03	W32.ED01 W32.Generic	Fax.exe	Worm

Справочник malware_info:

description	type
W32.File.Mal W32.2C2D W32.Auto.A	Ransomware
W32.ED01 W32.44D7	Worm

Использование опции OUTPUT

Опция OUTPUT перезаписывает поле malware_type в событиях значениями из справочника для всех событий, где есть непустое пересечение между malware_description события и description справочника, независимо от того, было ли поле malware_type заполнено изначально.

source security_alerts-*
| search malware_info="W32*"
| lookup malware_info description AS malware_description OUTPUT type as malware_type

Результатом запроса может быть следующая таблица:

_time	host	malware_description	file	malware_type
2025-06-05 14:30:00	VLG-01	W32.File.Mal W32.2C2D W32.Auto.A	mssecsvc.exe	Ransomware
2025-06-05 14:30:00	VLG-02	W32.ED01 W32.Overdrive	OLD.exe	Worm
2025-06-05 14:30:00	VLG-03	W32.ED01 W32.Generic	Fax.exe	Worm

Использование опции OUTPUTNEW

OUTPUTNEW добавляет значения type из справочника только для событий, где поле malware_type отсутствует или пустое. Если malware_type уже заполнено, оно сохраняется.

source security_alerts-*
| search malware_info="W32*"
| lookup malware_info description AS malware_description OUTPUTNEW type AS malware_type

Результатом запроса может быть следующая таблица:

_time	host	malware_description	file	malware_type
2025-06-05 14:30:00	VLG-01	W32.File.Mal W32.2C2D W32.Auto.A	mssecsvc.exe	Ransomware
2025-06-05 14:30:00	VLG-02	W32.ED01 W32.Overdrive	OLD.exe	Virus
2025-06-05 14:30:00	VLG-03	W32.ED01 W32.Generic	Fax.exe	Worm