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

> Управление агентами Wazuh 4.14 - регистрация, группы, централизованная конфигурация, обновление, массовое развертывание и устранение неполадок

Source: https://opennix.org/docs/wazuh/infrastructure/wazuh-agent-management/


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

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

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

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

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

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

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

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

Через API:

```bash
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 на менеджере:

```bash
/var/ossec/bin/agent_control -l

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

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

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

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

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

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

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

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

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

На агенте Linux:

```xml
<!-- /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 (при установке):

```powershell
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"
```

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

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

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

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

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

```xml
<ossec_config>
  <auth>
    <use_password>yes</use_password>
  </auth>
</ossec_config>
```

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

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

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

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

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

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

На агенте:

```xml
<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 и импорт на агенте.

```bash
# Шаг 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.

```bash
# На агенте - запрос регистрации
/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:

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

Через API:

```bash
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.

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

```bash
# Через 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"
```

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

```bash
# При использовании 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"
```

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

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

```bash
# Назначение в несколько групп
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`.

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

```bash
# Группы конкретного агента
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

```xml
<!-- /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>
```

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

```xml
<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>
```

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

```xml
<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 файлы
- Кастомные файлы конфигурации

```bash
# Размещение файла для группы
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:

```bash
# Обновление одного агента
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"]}'
```

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

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

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

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

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

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

```bash
# Обновление агентов в группе 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:

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

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

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

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

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

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

```xml
<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`:

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

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

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

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

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

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

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

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

```bash
/var/ossec/bin/manage_agents -e 001
```

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

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

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

```bash
/var/ossec/bin/manage_agents -l
```

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

```bash
# Через 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

```yaml
# 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

```yaml
#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

```dockerfile
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"]
```

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

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

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

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

```bash
# /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 Agent | Splunk Universal Forwarder | Elastic Agent (Fleet) | QRadar Log Sources |
|---|---|---|---|---|
| Модель развертывания | Agent на каждый хост | Forwarder на каждый хост | Agent на каждый хост | Agentless + WinCollect |
| Управление группами | Группы с agent.conf | Server classes | Policies | Log Source Groups |
| Централизованная конфигурация | agent.conf через менеджер | Deployment apps | Fleet policies | Нет (per-source) |
| Удаленное обновление | WPK через API | Deployment server | Fleet upgrade | WinCollect update |
| FIM встроен | Да | Нет (addon) | Да (integration) | Нет (addon) |
| Vulnerability scan | Да | Нет | Да | Нет |
| Массовое развертывание | Ansible, GPO, cloud-init | Ansible, GPO, SCCM | Fleet enrollment tokens | WinCollect MSI |
| Лицензирование | Бесплатно | По объему данных | По объему данных | Per EPS |

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

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

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

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

```bash
# Проверка конфигурации
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
```

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

```bash
# Проверка логов регистрации
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` в логах.

```bash
# На менеджере - экспорт ключа для агента
/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. Обновите агент до версии менеджера для полной совместимости.

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

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

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

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

```bash
# Поиск дубликатов по 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:

```xml
<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` не применяются на агенте.

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

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

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

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

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

- [Установка Wazuh Agent](/docs/wazuh/installation/wazuh-agent-installation/) - установка агентов на различные ОС
- [Настройка Wazuh Dashboard](/docs/wazuh/infrastructure/wazuh-dashboard-configuration/) - мониторинг агентов через веб-интерфейс
- [Wazuh Indexer API](/docs/wazuh/infrastructure/wazuh-indexer-api/) - запросы к данным агентов
- [Сбор логов](/docs/wazuh/capabilities/wazuh-log-data-collection/) - настройка источников данных на агентах