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=<integer>] | FAST | ERGO | DEFAULT | См. Режимы выполнения |
system | system=<boolean> | false | При значении true запрашивается системный лукап, в противном случае пользовательский. |
lookup-field | <string> | Название поля для сравнения. Могут быть указаны несколько полей. Разделитель между полями запятая. | |
event-field | <string> | Имя поля в основном результате для сравнения с lookup-field. Используется в случае если названия lookup-field и event-field не совпадают. | |
lookup-destfield | <string> | Имя результирующего поля с полученными из справочника данными. | |
OUTPUT | OUTPUTNEW | OUTPUT | OUTPUTNEW | OUTPUT | Индикатор OUTPUT указывает, на то что, существующие данные в поле исходного запроса будут перезаписаны данными из lookup. Индикатор OUTPUTNEW указывает на то, что данные в поле исходного запроса будут перезаписаны, если поле не заполнено, но есть данные для этого поля в lookup. |
Режимы выполнения
DEFAULT- режим по умолчанию. Рекомендуется использовать только для небольшого потока входящих событий и маленьких лукапов.FAST- оптимизированная по скорости версия стандартного алгоритма. Рекомендуется использовать в большинстве случаев.ERGO- оптимизированная по использованию оперативной памяти версия стандартного алгоритма. Рекомендуется использовать при сравнении по нескольким полям.SOURCE- выполняет сопоставление средствами хранилища. Дополнительно можно указать значениеpacksize, который определяет размер пачки запросов к хранилищу.
При загрузке в оперативную память лукапов в режимах FAST и ERGO применяется пользовательский лимит Количество запрашиваемых данных. Если размер лукапа превышает этот лимит, его можно повысить или использовать режим 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
source security_incidents-*
| search vulnerabilities="CVE-*"
| lookup type=ERGO vulnerabilities_info cve_id AS vulnerabilities OUTPUT description, severity
Вщ втором примере выполняется сопоставление поля vulnerabilities из события и многозначного поля cve_id в каждой строчке справочника. Команда выполняется в режиме ERGO. Это значит, что сопоставление оптимизировано для экономии оперативной памяти. Опция 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 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 malware AS malware_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 |