Документация
Документация Wazuh 4.14 - руководство по SIEM/XDR
Инфраструктура Wazuh - кластеры, API и управление
Управление агентами Wazuh - регистрация и настройка

Управление агентами Wazuh - регистрация и настройка

Агенты Wazuh устанавливаются на конечных точках и отвечают за сбор логов, мониторинг файловой системы, инвентаризацию системы и выполнение проверок безопасности. Управление агентами включает весь жизненный цикл - от регистрации и назначения групп до централизованной конфигурации, обновления и вывода из эксплуатации. При масштабных развертываниях критически важна автоматизация регистрации и конфигурации через Ansible, GPO или cloud-init. В этом руководстве рассмотрены все аспекты управления агентами Wazuh 4.14.

Жизненный цикл агента

Каждый агент Wazuh проходит через определенные состояния в процессе работы.

Состояния агента

СостояниеОписание
PendingАгент зарегистрирован, но еще не подключался к менеджеру
ActiveАгент подключен и передает данные
DisconnectedАгент потерял связь с менеджером (по умолчанию через 10 минут без heartbeat)
Never connectedАгент зарегистрирован, но ни разу не устанавливал соединение

Диаграмма жизненного цикла 

Установка → Регистрация → Pending → Active ←→ Disconnected
                                                    ↓
                                               Removed

Проверка состояния

Через API:

TOKEN=$(curl -sk -u wazuh-wui:$PASSWORD \
  -X POST "https://localhost:55000/security/user/authenticate?raw=true")

curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents?status=active&limit=10" | jq '.data.affected_items[] | {id,name,status,ip}'

Через CLI на менеджере:

/var/ossec/bin/agent_control -l

# Подробная информация об агенте
/var/ossec/bin/agent_control -i 001

Через файл состояния на агенте:

cat /var/ossec/var/run/wazuh-agentd.state

Настройка времени отключения

По умолчанию агент считается отключенным через 600 секунд (10 минут). Изменение в ossec.conf на менеджере:

<ossec_config>
  <global>
    <agents_disconnection_time>300</agents_disconnection_time>
    <agents_disconnection_alert_time>60</agents_disconnection_alert_time>
  </global>
</ossec_config>

Методы регистрации агентов

Регистрация через конфигурацию агента

Самый распространенный метод. Агент автоматически регистрируется при первом подключении к менеджеру.

На агенте Linux:

<!-- /var/ossec/etc/ossec.conf -->
<ossec_config>
  <client>
    <server>
      <address>192.168.1.5</address>
      <port>1514</port>
      <protocol>tcp</protocol>
    </server>
    <enrollment>
      <enabled>yes</enabled>
      <manager_address>192.168.1.5</manager_address>
      <port>1515</port>
      <agent_name>web-server-01</agent_name>
      <groups>linux,web-servers</groups>
    </enrollment>
  </client>
</ossec_config>

На агенте Windows (при установке):

Invoke-WebRequest -Uri https://packages.wazuh.com/4.x/windows/wazuh-agent-4.14.4-1.msi -OutFile wazuh-agent.msi

msiexec.exe /i wazuh-agent.msi /q `
  WAZUH_MANAGER="192.168.1.5" `
  WAZUH_AGENT_NAME="win-server-01" `
  WAZUH_AGENT_GROUP="windows,servers" `
  WAZUH_REGISTRATION_SERVER="192.168.1.5"

Регистрация с паролем

Для защиты процесса регистрации можно настроить парольную аутентификацию.

На менеджере создайте файл с паролем:

echo "MySecurePassword" > /var/ossec/etc/authd.pass
chmod 640 /var/ossec/etc/authd.pass
chown root:wazuh /var/ossec/etc/authd.pass

Включите парольную аутентификацию в ossec.conf:

<ossec_config>
  <auth>
    <use_password>yes</use_password>
  </auth>
</ossec_config>

На агенте укажите пароль:

<enrollment>
  <enabled>yes</enabled>
  <manager_address>192.168.1.5</manager_address>
  <authorization_pass_path>/var/ossec/etc/authd.pass</authorization_pass_path>
</enrollment>

Регистрация через сертификаты

Сертификатная аутентификация обеспечивает взаимную верификацию агента и менеджера.

На менеджере:

<ossec_config>
  <auth>
    <ssl_agent_ca>/var/ossec/etc/rootCA.pem</ssl_agent_ca>
    <ssl_verify_host>yes</ssl_verify_host>
  </auth>
</ossec_config>

На агенте:

<enrollment>
  <enabled>yes</enabled>
  <manager_address>192.168.1.5</manager_address>
  <agent_certificate_path>/var/ossec/etc/agent.cert</agent_certificate_path>
  <agent_key_path>/var/ossec/etc/agent.key</agent_key_path>
  <server_ca_path>/var/ossec/etc/rootCA.pem</server_ca_path>
</enrollment>

Регистрация через Wazuh API

Двухэтапный процесс: запрос ключа через API и импорт на агенте.

# Шаг 1: Получение ключа через API
TOKEN=$(curl -sk -u wazuh-wui:$PASSWORD \
  -X POST "https://localhost:55000/security/user/authenticate?raw=true")

KEY=$(curl -sk -H "Authorization: Bearer $TOKEN" \
  -X POST "https://localhost:55000/agents" \
  -H "Content-Type: application/json" \
  -d '{"name":"api-agent-01","ip":"any"}' | jq -r '.data.key')

# Шаг 2: Импорт ключа на агенте
/var/ossec/bin/manage_agents -i "$KEY"

# Шаг 3: Запуск агента
systemctl start wazuh-agent

Регистрация через authd

Демон authd автоматически обрабатывает запросы на регистрацию. Он включен по умолчанию и слушает порт 1515/TCP.

# На агенте - запрос регистрации
/var/ossec/bin/agent-auth -m 192.168.1.5

# С указанием имени и группы
/var/ossec/bin/agent-auth -m 192.168.1.5 -A "custom-agent-name" -G "linux,production"

# С паролем
/var/ossec/bin/agent-auth -m 192.168.1.5 -P "MySecurePassword"

Группы агентов

Группы позволяют организовать агентов логически и применять централизованную конфигурацию.

Группа по умолчанию

Все вновь зарегистрированные агенты автоматически попадают в группу default. Конфигурация группы находится в /var/ossec/etc/shared/default/agent.conf.

Создание группы

Через CLI:

/var/ossec/bin/agent_groups -a -g web-servers -q

Через API:

curl -sk -H "Authorization: Bearer $TOKEN" \
  -X POST "https://localhost:55000/groups" \
  -H "Content-Type: application/json" \
  -d '{"group_id": "web-servers"}'

Через Dashboard: Agents management - Groups - Add new group.

Назначение агента в группу 

# Через CLI
/var/ossec/bin/agent_groups -a -i 001 -g web-servers -q

# Через API
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/001/group/web-servers"

Назначение при регистрации 

# При использовании agent-auth
/var/ossec/bin/agent-auth -m 192.168.1.5 -G "web-servers,linux"

# При установке на Windows
msiexec.exe /i wazuh-agent.msi /q WAZUH_AGENT_GROUP="windows,production"

Мультигруппы

Агент может принадлежать нескольким группам одновременно. При конфликте параметров приоритет имеет последняя назначенная группа.

# Назначение в несколько групп
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/001/group/web-servers"

curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/001/group/production"

Порядок приоритета (от низшего к высшему): default - web-servers - production. Конфигурация группы production перезапишет конфликтующие параметры из web-servers и default.

Просмотр групп агента 

# Группы конкретного агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents/001/group" | jq '.data.affected_items'

# Все агенты в группе
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/groups/web-servers/agents" | jq '.data.affected_items[] | {id,name,status}'

Централизованная конфигурация (agent.conf)

Файл agent.conf позволяет централизованно управлять конфигурацией агентов через менеджер. Каждая группа имеет свой agent.conf в /var/ossec/etc/shared/<GROUP_NAME>/agent.conf.

Структура agent.conf 

<!-- /var/ossec/etc/shared/web-servers/agent.conf -->
<agent_config>

  <!-- Сбор логов веб-сервера -->
  <localfile>
    <log_format>apache</log_format>
    <location>/var/log/apache2/access.log</location>
  </localfile>

  <localfile>
    <log_format>apache</log_format>
    <location>/var/log/apache2/error.log</location>
  </localfile>

  <!-- Мониторинг целостности файлов -->
  <syscheck>
    <directories check_all="yes" realtime="yes">/var/www/html</directories>
    <directories check_all="yes">/etc/apache2</directories>
  </syscheck>

  <!-- Active Response -->
  <active-response>
    <disabled>no</disabled>
  </active-response>

</agent_config>

Фильтрация по ОС 

<agent_config os="Linux">
  <localfile>
    <log_format>syslog</log_format>
    <location>/var/log/auth.log</location>
  </localfile>
</agent_config>

<agent_config os="Windows">
  <localfile>
    <log_format>eventchannel</log_format>
    <location>Security</location>
    <query>Event/System[EventID=4625 or EventID=4624]</query>
  </localfile>
</agent_config>

Фильтрация по профилю 

<agent_config profile="database">
  <localfile>
    <log_format>syslog</log_format>
    <location>/var/log/postgresql/postgresql-*.log</location>
  </localfile>
</agent_config>

Общие файлы (shared files)

Помимо agent.conf, директория группы может содержать дополнительные файлы, которые автоматически синхронизируются на агентов:

  • CDB-списки для rootcheck
  • CIS Benchmark файлы
  • Кастомные файлы конфигурации
# Размещение файла для группы
cp custom-rootcheck.txt /var/ossec/etc/shared/web-servers/

# Проверка синхронизации
/var/ossec/bin/agent_groups -S -i 001

Слияние конфигурации (merged.mg)

Менеджер автоматически генерирует файл merged.mg, который объединяет конфигурации всех групп агента. Этот файл отправляется агенту и определяет итоговую конфигурацию.

Обновление агентов

Обновление через WPK

WPK (Wazuh Package) - подписанные пакеты для удаленного обновления агентов.

Через API:

# Обновление одного агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/001/upgrade" | jq '.'

# Обновление всех агентов в группе
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/upgrade" \
  -H "Content-Type: application/json" \
  -d '{"agents_list": ["001", "002", "003"]}'

Проверка статуса обновления 

curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents/upgrade_result" | jq '.data.affected_items'

Обновление через Dashboard

  1. Перейдите в Agents management
  2. Выберите агентов для обновления
  3. Нажмите Upgrade
  4. Подтвердите версию и запустите процесс

Планирование обновлений

Для минимизации воздействия на продуктивные системы обновляйте агентов группами:

# Обновление агентов в группе staging
AGENTS=$(curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/groups/staging/agents?limit=500" | \
  jq -r '.data.affected_items[].id' | tr '\n' ',' | sed 's/,$//')

curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/upgrade" \
  -H "Content-Type: application/json" \
  -d "{\"agents_list\": [\"${AGENTS}\"]}"

Кастомные WPK-пакеты

Для создания собственных WPK:

# Загрузка инструментов сборки
git clone https://github.com/wazuh/wazuh.git
cd wazuh/src/wazuh_modules/agent_upgrade/

# Сборка кастомного WPK (требуется GPG-ключ для подписи)

Метки агентов (labels)

Метки позволяют добавлять кастомные метаданные к агентам. Метки включаются в каждый алерт, что упрощает фильтрацию и маршрутизацию.

Настройка меток

На агенте в ossec.conf:

<ossec_config>
  <labels>
    <label key="environment">production</label>
    <label key="datacenter">us-east-1</label>
    <label key="team">platform</label>
    <label key="cost-center">CC-1234</label>
  </labels>
</ossec_config>

Через централизованную конфигурацию в agent.conf:

<agent_config>
  <labels>
    <label key="compliance">pci-dss</label>
    <label key="tier">tier-1</label>
  </labels>
</agent_config>

Скрытые метки

Метки с префиксом _ не отображаются в алертах, но доступны через API:

<labels>
  <label key="_internal.ticket">JIRA-12345</label>
</labels>

Использование в запросах 

GET wazuh-alerts-*/_search
{
  "query": {
    "term": { "agent.labels.environment": "production" }
  }
}

Управление ключами

Экспорт ключа агента 

/var/ossec/bin/manage_agents -e 001

Импорт ключа на агенте 

/var/ossec/bin/manage_agents -i "<KEY_STRING>"

Список зарегистрированных агентов 

/var/ossec/bin/manage_agents -l

Удаление агента 

# Через CLI
/var/ossec/bin/manage_agents -r 001

# Через API
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://localhost:55000/agents?agents_list=001&status=all&older_than=0s"

Массовое развертывание

Ansible 

# playbook.yml
---
- name: Deploy Wazuh agents
  hosts: all
  become: yes
  vars:
    wazuh_manager: "192.168.1.5"
    wazuh_version: "4.14.4"
    wazuh_group: "{{ group_names | join(',') }}"

  tasks:
    - name: Add Wazuh repository
      apt_repository:
        repo: "deb https://packages.wazuh.com/4.x/apt/ stable main"
        state: present
      when: ansible_os_family == "Debian"

    - name: Install Wazuh agent
      apt:
        name: "wazuh-agent={{ wazuh_version }}-1"
        state: present
      when: ansible_os_family == "Debian"

    - name: Configure agent
      template:
        src: ossec.conf.j2
        dest: /var/ossec/etc/ossec.conf
        owner: root
        group: wazuh
        mode: '0640'

    - name: Start Wazuh agent
      systemd:
        name: wazuh-agent
        state: started
        enabled: yes

GPO с MSI (Windows)

Для массового развертывания на Windows через Group Policy:

  1. Скачайте MSI-пакет: wazuh-agent-4.14.4-1.msi
  2. Разместите в сетевой папке, доступной для компьютеров домена
  3. Создайте GPO для Software Installation:
    • Computer Configuration - Policies - Software Settings - Software Installation
    • Добавьте MSI-пакет
  4. Настройте параметры установки через MST-файл (transform):
WAZUH_MANAGER=192.168.1.5
WAZUH_AGENT_GROUP=windows,production
WAZUH_REGISTRATION_SERVER=192.168.1.5
WAZUH_REGISTRATION_PASSWORD=MySecurePassword

cloud-init 

#cloud-config
package_update: true

runcmd:
  - curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | gpg --dearmor -o /usr/share/keyrings/wazuh.gpg
  - echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main" > /etc/apt/sources.list.d/wazuh.list
  - apt-get update
  - WAZUH_MANAGER="192.168.1.5" WAZUH_AGENT_GROUP="cloud,auto-provisioned" apt-get install -y wazuh-agent
  - systemctl daemon-reload
  - systemctl enable wazuh-agent
  - systemctl start wazuh-agent

Docker 

FROM ubuntu:22.04

ENV WAZUH_MANAGER="192.168.1.5"
ENV WAZUH_AGENT_GROUP="docker,containers"

RUN apt-get update && \
    apt-get install -y curl gnupg && \
    curl -s https://packages.wazuh.com/key/GPG-KEY-WAZUH | \
      gpg --dearmor -o /usr/share/keyrings/wazuh.gpg && \
    echo "deb [signed-by=/usr/share/keyrings/wazuh.gpg] https://packages.wazuh.com/4.x/apt/ stable main" \
      > /etc/apt/sources.list.d/wazuh.list && \
    apt-get update && \
    apt-get install -y wazuh-agent && \
    apt-get clean

ENTRYPOINT ["/var/ossec/bin/wazuh-control", "start"]

Автоматическое удаление отключенных агентов

Для автоматической очистки агентов, которые давно не подключались:

# Удаление агентов, отключенных более 30 дней
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://localhost:55000/agents?status=disconnected&older_than=30d" | jq '.'

Для автоматизации добавьте в cron:

# /etc/cron.daily/wazuh-cleanup-agents
#!/bin/bash
TOKEN=$(curl -sk -u wazuh-wui:$PASSWORD \
  -X POST "https://localhost:55000/security/user/authenticate?raw=true")
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://localhost:55000/agents?status=disconnected&older_than=30d"

Сравнение с другими SIEM-системами

ФункцияWazuh AgentSplunk Universal ForwarderElastic Agent (Fleet)QRadar Log Sources
Модель развертыванияAgent на каждый хостForwarder на каждый хостAgent на каждый хостAgentless + WinCollect
Управление группамиГруппы с agent.confServer classesPoliciesLog Source Groups
Централизованная конфигурацияagent.conf через менеджерDeployment appsFleet policiesНет (per-source)
Удаленное обновлениеWPK через APIDeployment serverFleet upgradeWinCollect update
FIM встроенДаНет (addon)Да (integration)Нет (addon)
Vulnerability scanДаНетДаНет
Массовое развертываниеAnsible, GPO, cloud-initAnsible, GPO, SCCMFleet enrollment tokensWinCollect MSI
ЛицензированиеБесплатноПо объему данныхПо объему данныхPer EPS

Устранение неполадок

Агент не подключается

Симптом: агент остается в статусе never_connected или disconnected.

Диагностика на агенте:

# Проверка конфигурации
cat /var/ossec/etc/ossec.conf | grep -A5 "<server>"

# Проверка логов агента
tail -50 /var/ossec/logs/ossec.log

# Проверка сетевого подключения
nc -zv 192.168.1.5 1514
nc -zv 192.168.1.5 1515

Диагностика на менеджере:

# Проверка логов регистрации
tail -50 /var/ossec/logs/ossec.log | grep -i "agent"

# Проверка, что authd слушает порт
ss -tlnp | grep 1515

# Проверка, что remoted слушает порт
ss -tlnp | grep 1514

Решения:

  • Убедитесь, что порты 1514/TCP и 1515/TCP открыты на файрволе
  • Проверьте правильность адреса менеджера в конфигурации агента
  • При использовании пароля убедитесь, что он совпадает на обеих сторонах
  • Перезапустите wazuh-authd на менеджере

Несовпадение ключей (key mismatch)

Симптом: сообщение Invalid key или Agent key mismatch в логах.

# На менеджере - экспорт ключа для агента
/var/ossec/bin/manage_agents -e 001

# На агенте - удалить старый ключ и импортировать новый
/var/ossec/bin/manage_agents -r
/var/ossec/bin/manage_agents -i "<NEW_KEY>"

# Перезапуск агента
systemctl restart wazuh-agent

Несовместимость версий

Симптом: агент подключается, но функциональность ограничена или появляются ошибки.

Wazuh поддерживает обратную совместимость в пределах мажорной версии. Агент 4.x может подключаться к менеджеру 4.y, где y >= x. Обновите агент до версии менеджера для полной совместимости.

# Проверка версии на агенте
/var/ossec/bin/wazuh-control info | grep VERSION

# Проверка версии на менеджере
/var/ossec/bin/wazuh-control info | grep VERSION

Дублирующиеся агенты

Симптом: один хост зарегистрирован несколько раз с разными ID.

# Поиск дубликатов по IP или имени
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents?name=web-server-01" | jq '.data.affected_items[] | {id,name,ip,status}'

# Удаление дублирующегося агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://localhost:55000/agents?agents_list=002&status=all&older_than=0s"

Предотвращение: используйте force.enabled в конфигурации authd:

<ossec_config>
  <auth>
    <force>
      <enabled>yes</enabled>
      <key_mismatch>yes</key_mismatch>
      <disconnected_time enabled="yes">1h</disconnected_time>
      <after_registration_time>1h</after_registration_time>
    </force>
  </auth>
</ossec_config>

Это позволит агенту с тем же IP или именем заменить существующую регистрацию, если старый агент отключен более 1 часа.

Агент не получает конфигурацию группы

Симптом: изменения в agent.conf не применяются на агенте.

# Проверка синхронизации
/var/ossec/bin/agent_groups -S -i 001

# Проверка файла merged.mg на агенте
cat /var/ossec/etc/shared/merged.mg

# Принудительная синхронизация - перезапуск агента
systemctl restart wazuh-agent

Убедитесь, что agent.conf валиден - некорректный XML блокирует синхронизацию.

Дополнительные материалы

Last updated on
Серверный кластер Wazuh - архитектура и настройка