Андрей Ефремов

Wazuh хорошо собирает события безопасности, но чтобы найти в них ответ, нужно знать язык запросов и сотни полей индекса. Опытный инженер SOC напишет запрос за минуту, но вот коллегам, которые не работали в Wazuh или с SIEM-системами, это сделать не так просто. Дашборд Wazuh построен на OpenSearch Dashboards, а у OpenSearch есть готовый ассистент — OpenSearch Assistant. В поставку Wazuh он не входит, но ставится штатными плагинами той же версии, без переделки самого Wazuh. В статье мы установим его, подключим собственную модель и добавим в интерфейс кнопку, которая объясняет любой документ. После настройки в дашборде появятся три инструмента. Окно чата. Аналитик задает вопрос своими словами и получает в ответ от LLM. Query Assist в Discover. «Словесный» вопрос превращается в запрос PPL (Piped Processing Language, язык запросов OpenSearch), а результат открывается обычной таблицей. Кнопка Explain Document в панели просмотра документа. Модель разбирает алерт или запись об уязвимости: что произошло, насколько это серьезно и что проверить. Как это работает Вопрос аналитика проходит следующий путь: Плагины дашборда рисуют окно чата, строку Query Assist и кнопку. Сами они ничего не вычисляют, а передают вопрос в индексатор. Плагин ml-commons в индексаторе хранит подключение к модели и агентов. Агент — это сценарий работы: какой промпт отправить модели и какие инструменты ей дать. Главный инструмент здесь — PPLTool. Он просит модель составить запрос PPL и сам его выполняет. Модель работает отдельно. Индексатор обращается к ней по HTTPS через коннектор — объект с адресом, форматом запроса и правилом разбора ответа. Настраивать будем в том же порядке: плагины, модель, агенты, а на конец оставим кнопку в интерфейсе. Требования Инструкция проверена на следующей конфигурации: Wazuh 4.14.7 в Docker (репозиторий wazuh-docker, вариант single-node). Внутри Wazuh 4.14.7 работает OpenSearch 2.19.5; модель qwen3-next-80b за OpenWebUI. Подойдет любая модель с OpenAI-совместимым API, которая уверенно следует инструкциям. Подготовьте заранее: адрес API модели, имя модели и токен; root-доступ к серверу, где работают индексатор и дашборд Wazuh; для кнопки Explain Document — машину с Linux и Docker, 8 ГБ оперативной памяти и доступом к GitHub и npm. Большая часть команд выполняется в меню консоли дашборда: Indexer management → Dev Tools. Консоль сама подставляет адрес индексатора и авторизацию. Не перепутайте ее с пунктом Server management → Dev Tools: там консоль API менеджера Wazuh, запросы из статьи в ней не сработают. Там, где нужен терминал сервера, это указано над блоком кода. При этом в командах встречаются значения, которые нужно заменить на свои: ЗначениеНа что заменить Адрес API модели — например, https://llm.example.com. Путь к методу чата: /v1/chat/completions. У OpenWebUI — это /api/chat/completions. Имя модели так, как его понимает API. Токен доступа к модели. , Идентификаторы, которые вернут команды шага 3. , , Идентификаторы агентов из шагов 4–6. , Имена контейнеров индексатора и дашборда. Посмотреть их можно командой docker ps. Шаг 1. Установка плагинов Ассистенту нужны два плагина индексатора (opensearch-skills и opensearch-flow-framework) и три плагина дашборда (assistantDashboards, mlCommonsDashboards, observabilityDashboards). Отдельных архивов у них нет, поэтому возьмем их из официальной сборки OpenSearch той же версии. Архивы весят около 1,3 ГБ. Выполните на сервере Wazuh следующие шаги. 1. Скачайте сборки OpenSearch и OpenSearch Dashboards и распакуйте из них только нужные плагины: 2. Подключите плагины. Если Wazuh работает в Docker, назначьте владельцем файлов пользователя, имеющего UID 1000 — под ним работают процессы в контейнерах: Затем добавьте тома в docker-compose.yml: первые две строки в раздел volumes сервиса wazuh.indexer, остальные три — в раздел volumes сервиса wazuh.dashboard. Если Wazuh установлен из пакетов, скопируйте плагины в каталоги сервисов и перезапустите их: 3. Проверьте, что индексатор загрузил плагины. В ответе должны быть строки opensearch-skills 2.19.5.0 и opensearch-flow-framework 2.19.5.0: Шаг 2. Включение ассистента 1. Включите агентов в ml-commons и разрешите подключение к вашей модели. В последнем параметре замените адрес llm.example.com на хост своей модели: Рассмотрим подробнее, что делают эти настройки. agent_framework_enabled и memory_feature_enabled включают агентов и память диалога. Без памяти не будут работать уточняющие вопросы вроде «а сколько событий из них критичны?». only_run_on_ml_node: false разрешает работу моделей на обычных узлах. По умолчанию ml-commons ждет отдельных ML-узлов, которых в Wazuh нет. connector.private_ip_enabled нужен, если модель находится во внутренней сети. trusted_connector_endpoints_regex — список разрешенных адресов моделей. По умолчанию там только облачные сервисы вроде OpenAI и Bedrock. Это регулярное выражение: каждая точка в имени хоста записывается как \\., иначе она совпадет с любым символом. В ответе должно прийти "acknowledged": true. Перезапуск индексатора не нужен. 2. Включите интерфейс ассистента. Добавьте в конец opensearch_dashboards.yml пять строк. В Docker этот файл лежит на сервере в config/wazuh_dashboard/opensearch_dashboards.yml рядом с docker-compose.yml, в пакетной установке — в /etc/wazuh-dashboard/opensearch_dashboards.yml: 3. Перезапустите дашборд: После перезапуска в шапке дашборда появится строка Ask a question, а по нажатию на нее откроется окно OpenSearch Assistant. Отвечать оно пока не сможет, так как модель еще не подключена. Окно ассистента после шага 2. Шаг 3. Подключение модели Индексатор не запускает модель у себя, а обращается к ней по API. Для этого нужны коннектор и зарегистрированная поверх него модель. 1. Создайте коннектор. Замените значения в угловых скобках на свои и выполните запрос целиком: Тройные кавычки """ — это возможность консоли Dev Tools: текст между ними можно писать как есть, а консоль сама превратит его в JSON-строку. В двух местах коннектор отличается от стандартного шаблона OpenAI, и оба отличия обязательны: request_body подставляет в запрос параметр ${parameters.prompt}. Именно его передают агенты ассистента. Стандартный шаблон с ${parameters.messages} для агентов не подходит: модель получает сломанный запрос, а ml-commons отвечает Invalid payload. post_process_function достает текст из ответа модели и возвращает его в виде {"response": "..."}, как этого ждут инструменты. Заодно функция убирает блок рассуждений и обертку Markdown, которые добавляют некоторые модели. В ответе придет connector_id. Запишите его, это . 2. Зарегистрируйте и запустите модель: В ответе придет model_id — это . Модель работает на стороне API OpenWebUI, поэтому запускается за несколько секунд. Проверить состояние можно запросом GET _plugins/_ml/models/ : поле model_state должно быть DEPLOYED. 3. Проверьте, что модель отвечает: В ответе должно быть поле dataAsMap.response с коротким ответом модели. Если пришла ошибка, проверьте адрес, путь, токен и регулярное выражение из шага 2. Шаг 4. Агент чата В окне чата общение происходит не с моделью, а с агентом. Агент принимает вопрос, при необходимости вызывает PPLTool, получает результат запроса и формулирует ответ. Поведение агента задают три текста, ознакомиться с ними можно под спойлерами ниже. Приложение А — системный промпт: отвечать по-русски, не писать запросы самому, показывать выполненный запрос. Вставляется в параметр prompt.prefix в шаге 4. Приложение Б — шаблон, по которому PPLTool просит модель составить запрос. В нем правила языка PPL для индексов Wazuh и примеры. Вставляется в параметр prompt инструмента PPLTool в шагах 4 и 5. Перед вставкой замените на список групп вашего кластера. Строки ${indexInfo.indexName}, ${indexInfo.mappingInfo} и ${indexInfo.question} не меняйте: вместо них PPLTool подставит имя индекса, список его полей и вопрос. Приложение В — инструкция формата ответа. Она заменяет стандартную инструкцию ml-commons, которая просит модель ответить одним предложением. Без замены блок с запросом пропадает из ответов на простые вопросы. Вставляется в параметр prompt.format_instruction в шаге 4. Это стандартная инструкция ml-commons 2.19.5, в которой изменено только описание поля final_answer. Остальной текст должен совпадать дословно: агент разбирает ответы модели по этой схеме. Приложение Г — создается в шаге 6.2 по пути plugins/main/public/components/common/wazuh-discover/components/incontext-insight.tsx. 1. Соберите список групп правил вашего кластера. Модель должна искать события по группам (rule.groups), которые реально есть в ваших данных, а не угадывать номера правил: номера у каждого кластера свои. Из ответа выпишите значения key через запятую. Группы стандартов соответствия (pci_dss_*, gdpr_*, hipaa_*, nist_800_53_*, tsc_*, gpg13_*) пропустите: они есть почти в каждом событии и только мешают. Получившейся строкой замените в тексте приложения Б. 2. Зарегистрируйте агента. Вместо строк вставьте тексты приложений целиком, тройные кавычки оставьте на месте: Значения параметров подобраны на стенде, менять их без причины не стоит: ПараметрЗачем такое значениеmodel_type: "FINETUNE"Со значением OPENAI инструмент удаляет из запроса обратные кавычки. Без них имена полей с точками (rule.id, wazuh-alerts-*) ломают разбор запроса.head: 5Ограничивает число строк в результате. Каждый алерт — это документ на сотни полей, и большая выдача переполняет контекст модели.message_history_limit: "3"Сколько прошлых реплик диалога передавать модели. При значении по умолчанию контекст переполняется уже на третьем вопросе, и ответ приходит пустым.max_iteration: 10Сколько шагов может сделать агент. Составному вопросу нужно два вызова инструмента и еще шаг на ответ. В ответе придет agent_id — это . 3. Привяжите агента к окну чата. Окно ищет агента в системном индексе .plugins-ml-config по ключу os_chat. В системные индексы OpenSearch пускает только с административным сертификатом, поэтому этот запрос выполняется не в Dev Tools, а в терминале сервера. Wazuh в Docker: Пакетная установка: та же команда без docker exec , сертификаты лежат в /etc/wazuh-indexer/certs/admin.pem и /etc/wazuh-indexer/certs/admin-key.pem. В ответе должно быть "result": "created". Если ключ уже был привязан к другому агенту, придет "result": "updated". 4. Откройте окно ассистента и задайте несколько вопросов. Вот что мы спрашивали на стенде ( все числа в ответах совпали с проверочными запросами): «Сколько алертов за сегодня?», а следом «А сколько из них уровня 10 и выше?» — второй вопрос должен учитывать период из первого; «С каких адресов больше всего неудачных входов за неделю и сколько их всего?» — агент должен выполнить два запроса и объединить результаты; «Объясни правило 5712» — агент найдет правило по номеру и расскажет, что оно означает. Каждый ответ состоит из блока Ответ с числами и блока Запрос с выполненным PPL. Запрос можно скопировать в Discover и перепроверить число. Шаг 5. Query Assist в Discover Query Assist — строка в Discover, в которой вопрос словами превращается в запрос PPL. Для нее нужен отдельный агент: у него нет памяти диалога, только PPLTool. 1. Зарегистрируйте агента. Вместо вставьте тот же текст, что и в шаге 4, со списком групп: В ответе придет agent_id — это . 2. Привяжите его под ключом os_query_assist_ppl. Команда такая же, как в шаге 4, отличаются ключ в адресе и идентификатор агента: 3. Откройте Discover, выберите шаблон индекса wazuh-alerts-* и переключите язык запросов на PPL. Введите вопрос, например «покажи неудачные входы по SSH за 3 дня». Над таблицей появится сгенерированный запрос, который можно поправить вручную. Query Assist: вопрос словами и сгенерированный запрос PPL. Шаг 6. Кнопка Explain Document С этой функции удобнее всего начинать внедрение. В чате модель сама составляет запрос и иногда ошибается. Здесь она получает готовый документ в формате JSON и только объясняет его, поэтому результат стабильный. Включить кнопку одной настройкой не получится. Плагин ассистента дает механизм для таких кнопок, но сами кнопки регистрируют плагины страниц. В OpenSearch это делает плагин Alerting, но плагин Wazuh на это не способен, так что добавим кнопку в код плагина Wazuh и пересоберем его. Правка общая для всех модулей: панель просмотра документа у Wazuh одна, и кнопка появится и в Threat Hunting, и в Vulnerability Detection, и во всех остальных разделах. 6.1. Агент объяснения 1. Зарегистрируйте агента: Плагин ассистента передает агенту два параметра: ${parameters.context} — сам документ и ${parameters.question} — вопрос. В ответе придет agent_id — это . 2. Привяжите агента под ключом os_summary: 6.2. Правка кода Все действия этого и следующего раздела выполняются на машине сборки. Плагин Wazuh собирается только внутри исходников платформы, поэтому понадобятся два репозитория одной версии. 1. Скачайте исходники и положите плагины Wazuh внутрь платформы: 2. Создайте файл кнопки incontext-insight.tsx. Полный текст — в приложении Г. 3. Подключите кнопку в двух компонентах просмотра документа. Они лежат в том же каталоге. В каждом файле нужно добавить импорт и обернуть возвращаемую разметку: вместо return ( написать const content (, а в конце функции вернуть результат withIncontextInsight. Строки со знаком «+» добавляются, а со знаком «-» — удаляются. 4. Выровняйте версию библиотеки node-cron. В плагине main указана версия ^1.1.2, а в wazuh-core и wazuh-check-updates — ^3.0.2. 6.3. Сборка Собирать удобнее в контейнере с Node.js 18: не нужно ничего ставить на машину. Сборка идет от обычного пользователя node, потому что OpenSearch Dashboards отказывается работать от root. Первая сборка занимает 30–60 минут, почти все это время уходит на загрузку зависимостей. 1. Запустите контейнер сборки: 2. Внутри контейнера загрузите зависимости и соберите плагин: Версию платформы передавайте только переменной OPENSEARCH_DASHBOARDS_VERSION. Скрипт сборки сам добавляет флаг --opensearch-dashboards-version, и если указать его еще раз вручную, сборка остановится с ошибкой expected a single --opensearch-dashboards-version flag. Успешная сборка заканчивается строкой bundles compiled successfully. Готовые файлы лежат в каталоге plugins/main/build/opensearch-dashboards/wazuh/target/public. 6.4. Установка Замените собранными файлами каталог target/public плагина Wazuh и перезапустите дашборд. Команды ниже написаны для случая, когда сборка шла на том же сервере. Если собирали на другой машине, скопируйте каталог public на сервер и укажите в команде путь к нему. Обновите страницу дашборда с очисткой кэша (Ctrl+Shift+R): имена файлов после сборки не меняются, и браузер может показать старую версию. Откройте любой документ, например алерт в Threat Hunting. Над вкладками Table и JSON появится кнопка Explain Document. Первый ответ приходит за 10–20 секунд. Разбор алерта о подборе пароля по SSH. Если что-то не работает Здесь собраны ошибки, с которыми мы столкнулись при настройке. Большинство из них не объясняет причину, поэтому таблица начинается с текста ошибки. Что видноПричинаЧто сделатьСоздание коннектора: Connector URL is not matching the trusted connector endpoint regexАдрес модели не подходит под регулярное выражение из шага 2Проверьте хост в выражении. Точки в нем записываются как \\., нестандартный порт разрешается группой (:+)? сразу после хостаРегистрация модели: No eligible node found to execute this requestНе выключен параметр only_run_on_ml_node: ml-commons ищет отдельные ML-узлыПовторите запрос настроек из шага 2Invalid payload в чатеВ коннекторе используется ${parameters.messages} из стандартного шаблонаПересоздайте коннектор с request_body из шага 3Remote endpoint fails to inferenceУ коннектора нет post_process_function, и PPLTool не находит поле responseПересоздайте коннектор с функцией из шага 3NullPointerException при вызове агентаУ коннектора или агента задан response_filterУберите response_filter: разбор ответа уже делает post_process_functionsecurity_exception при записи в .plugins-ml-configЗапись в системный индекс по паролю запрещенаВыполните привязку командой с административным сертификатомОтвет пустой, чаще на третьем вопросе диалогаПереполнен контекст моделиПроверьте message_history_limit: "3" и head: 5В ответе нет блока с запросомУ агента нет prompt.format_instructionЗарегистрируйте агента заново с текстом приложения ВЗапрос PPL падает на имени поля с точкойУ PPLTool указан model_type: "OPENAI"Зарегистрируйте агента заново с model_type: "FINETUNE"Query Assist пишет или падает на символе <Модель перепутала тег вокруг запросаФункция разбора из шага 3 исправляет тег. Проверьте, что коннектор создан именно с нейКнопка отвечает Invalid payloadДокумент передан модели чистым JSON. ml-commons не экранирует параметры, которые уже являются корректным JSON, и кавычки ломают запрос к моделиПередавайте документ строкой с текстовым префиксом, как в приложении ГКнопка не появилась после установкиБраузер показывает старые файлы из кэшаОбновите страницу через Ctrl+Shift+RСборка: should not be run as rootСборка запущена от rootЗапускайте контейнер с -u nodeИзменили промпт, а агент отвечает по-старомуЗарегистрированного агента нельзя изменитьЗарегистрируйте нового агента и привяжите его под тем же ключом Ограничения Чат ошибается чаще, чем кнопка. Составляя запрос, модель может выбрать не то поле или добавить лишний фильтр. Чат ошибается чаще, чем кнопка. Составляя запрос, модель может выбрать не то поле или добавить лишний фильтр. Поэтому в каждом ответе есть выполненный запрос. Для отчетов проверяйте цифры обычным поиском. Модель получает данные. В промпт уходят вопрос, результат запроса или документ целиком: адреса, имена пользователей, команды. Если модель работает во внешнем сервисе, согласуйте это со службой безопасности. Проверено под пользователем admin. Для других пользователей понадобятся права на ml-commons, отдельно мы их не настраивали. Список групп нужно обновлять. Появились новые источники событий — соберите список заново, обновите приложение Б и перерегистрируйте агентов. Заключение Два часа настройки — и Wazuh начинает отвечать на вопросы обычными словами. Для этого хватает штатных плагинов OpenSearch, своей модели и трех агентов, а код приходится трогать только ради кнопки Explain Document. Если внедрять по шагам, начните с кнопки: она объясняет готовый документ и почти не ошибается в фактах. Чат оставьте для быстрых вопросов к данным и не забывайте смотреть на запрос под ответом.

Андрей Ефремов

Материалы автора

Как встроить ИИ-ассистент в Wazuh

Wazuh: расширяем функциональность с помощью индексов

Мониторинг модулей ядра и защита от Dirty-уязвимостей с помощью Wazuh

Справочник по Wazuh: функционал SIEM, возможности и настройка