REST API сервера Wazuh - аутентификация и эндпоинты

REST API Wazuh предоставляет программный интерфейс для управления всеми компонентами платформы. API работает по протоколу HTTPS на порту 55000, использует JWT-аутентификацию и поддерживает ролевую модель доступа. Через API можно управлять агентами, правилами, декодерами, группами, конфигурацией менеджера и кластера.

Обзор API

Базовые характеристики

Параметр	Значение
Протокол	HTTPS (TLS)
Порт по умолчанию	55000
Формат данных	JSON
Аутентификация	JWT (JSON Web Token)
Авторизация	RBAC (Role-Based Access Control)
HTTP-методы	GET, POST, PUT, DELETE
Базовый URL	`https://<WAZUH_SERVER>:55000`

Структура ответа

Все ответы API следуют стандартизированному формату:

{
  "data": {
    "affected_items": [],
    "total_affected_items": 0,
    "failed_items": [],
    "total_failed_items": 0
  },
  "message": "Description of the result",
  "error": 0
}

Коды ошибок в поле error:

0 - операция выполнена успешно
1 - операция завершилась с ошибкой
2 - операция выполнена частично (некоторые элементы обработаны, некоторые нет)

Параметры пагинации

API ограничивает количество возвращаемых записей. По умолчанию - 500 элементов. Для получения большего количества используйте параметры:

limit - максимальное количество записей в ответе
offset - смещение от начала списка
sort - сортировка результатов (например, +name или -id)

Аутентификация

Получение JWT-токена

Для работы с API необходимо получить JWT-токен через эндпоинт аутентификации. Используется базовая HTTP-аутентификация (логин и пароль):

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

Параметр raw=true возвращает токен в текстовом формате без JSON-обертки.

Альтернативный вариант с JSON-ответом:

curl -sk -u wazuh-wui:MyPassword \
  -X POST "https://localhost:55000/security/user/authenticate" | jq -r '.data.token'

Использование токена

Полученный токен передается в заголовке Authorization каждого запроса:

curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/?pretty=true"

Время жизни токена

JWT-токен имеет ограниченное время жизни, которое настраивается в конфигурации API. По истечении срока действия необходимо получить новый токен. Время жизни по умолчанию составляет 900 секунд (15 минут).

Отзыв токена

Для принудительного завершения сессии используйте эндпоинт отзыва:

curl -sk -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://localhost:55000/security/user/authenticate"

Основные группы эндпоинтов

Агенты

Управление агентами - одна из наиболее часто используемых функций API.

# Список всех агентов
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents?pretty=true"

# Список активных агентов с фильтрацией
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents?status=active&limit=10&pretty=true"

# Информация о конкретном агенте
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents?agents_list=001&pretty=true"

# Сводка статусов агентов
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/agents/summary/status?pretty=true"

# Перезапуск агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/001/restart?pretty=true"

# Обновление агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/001/upgrade?pretty=true"

# Удаление агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://localhost:55000/agents?agents_list=001&status=all&older_than=0s&pretty=true"

Правила

# Список всех правил
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/rules?pretty=true&limit=10"

# Получение правила по ID
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/rules?rule_ids=100001&pretty=true"

# Правила по уровню
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/rules?level=12-15&pretty=true"

# Правила по группе
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/rules?group=authentication_failed&pretty=true"

# Список файлов правил
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/rules/files?pretty=true"

Декодеры

# Список всех декодеров
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/decoders?pretty=true&limit=10"

# Поиск декодера по имени
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/decoders?search=sshd&pretty=true"

# Список файлов декодеров
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/decoders/files?pretty=true"

Менеджер

# Информация о менеджере
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/manager/info?pretty=true"

# Статус менеджера
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/manager/status?pretty=true"

# Конфигурация менеджера
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/manager/configuration?pretty=true"

# Логи менеджера
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/manager/logs?pretty=true&limit=20"

# Перезапуск менеджера
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/manager/restart?pretty=true"

Кластер

# Статус кластера
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/cluster/status?pretty=true"

# Список узлов кластера
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/cluster/nodes?pretty=true"

# Информация о конкретном узле
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/cluster/nodes/worker-01?pretty=true"

# Конфигурация кластера
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/cluster/configuration?pretty=true"

Подробнее о настройке кластера см. в разделе серверный кластер Wazuh .

Syscollector (инвентаризация)

# Информация об оборудовании агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/syscollector/001/hardware?pretty=true"

# Установленные пакеты
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/syscollector/001/packages?pretty=true&limit=20"

# Сетевые интерфейсы
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/syscollector/001/netiface?pretty=true"

# Открытые порты
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/syscollector/001/ports?pretty=true"

# Запущенные процессы
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/syscollector/001/processes?pretty=true&limit=20"

# Информация об ОС
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/syscollector/001/os?pretty=true"

Уязвимости

# Обнаруженные уязвимости агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/vulnerability/001?pretty=true"

# Фильтрация по критичности
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/vulnerability/001?severity=Critical&pretty=true"

SCA (оценка конфигурации безопасности)

# Список политик SCA для агента
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/sca/001?pretty=true"

# Результаты проверок конкретной политики
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/sca/001/checks/cis_ubuntu22-04?pretty=true"

Подробнее о модуле SCA см. в разделе оценка конфигурации безопасности .

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

# Список групп
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/groups?pretty=true"

# Создание группы
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X POST "https://localhost:55000/groups?pretty=true" \
  -H "Content-Type: application/json" \
  -d '{"group_id":"web-servers"}'

# Назначение агента в группу
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X PUT "https://localhost:55000/agents/001/group/web-servers?pretty=true"

# Агенты в группе
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/groups/web-servers/agents?pretty=true"

# Удаление группы
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X DELETE "https://localhost:55000/groups?groups_list=web-servers&pretty=true"

Конфигурация API (api.yaml)

Конфигурация API хранится в файле /var/ossec/api/configuration/api.yaml.

Основные параметры

host: 0.0.0.0
port: 55000

https:
  enabled: true
  key: /var/ossec/api/configuration/ssl/server.key
  cert: /var/ossec/api/configuration/ssl/server.crt

logging:
  level: info
  path: /var/ossec/logs/api.log

cors:
  enabled: false
  source_route: "*"
  expose_headers: "*"
  allow_headers: "*"
  allow_credentials: false

access:
  max_login_attempts: 50
  block_time: 300
  max_request_per_minute: 300

behind_proxy_server: false

Описание параметров конфигурации

Параметр	Описание	Значение по умолчанию
`host`	IP-адрес, на котором API принимает соединения	`0.0.0.0`
`port`	TCP-порт API	`55000`
`https.enabled`	Включение HTTPS	`true`
`https.key`	Путь к приватному ключу TLS	`/var/ossec/api/configuration/ssl/server.key`
`https.cert`	Путь к сертификату TLS	`/var/ossec/api/configuration/ssl/server.crt`
`logging.level`	Уровень логирования (debug, info, warning, error)	`info`
`cors.enabled`	Включение CORS-заголовков	`false`
`behind_proxy_server`	Работа за обратным прокси (доверие заголовку X-Forwarded-For)	`false`
`access.max_login_attempts`	Максимальное количество попыток входа	`50`
`access.block_time`	Время блокировки после превышения попыток (секунды)	`300`
`access.max_request_per_minute`	Ограничение запросов в минуту	`300`

После изменения конфигурации перезапустите API:

systemctl restart wazuh-manager

RBAC - ролевая модель доступа

Архитектура RBAC

Wazuh API реализует многоуровневую систему контроля доступа:

Пользователи - учетные записи с JWT-аутентификацией
Роли - наборы политик, назначаемые пользователям
Политики - правила доступа, определяющие разрешенные действия
Правила безопасности - динамическое назначение ролей на основе условий

Режимы работы RBAC

White list (по умолчанию) - запрещено все, кроме явно разрешенного
Black list - разрешено все, кроме явно запрещенного

Управление пользователями

# Создание пользователя
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X POST "https://localhost:55000/security/users" \
  -H "Content-Type: application/json" \
  -d '{"username":"analyst","password":"Analyst_Pass1"}'

# Список пользователей
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/security/users?pretty=true"

# Назначение роли пользователю
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X POST "https://localhost:55000/security/users/analyst/roles?role_ids=2"

Управление ролями

# Список ролей
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/security/roles?pretty=true"

# Создание роли
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X POST "https://localhost:55000/security/roles" \
  -H "Content-Type: application/json" \
  -d '{"name":"readonly_agents"}'

# Назначение политики роли
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X POST "https://localhost:55000/security/roles/100/policies?policy_ids=1"

Управление политиками

# Список политик
curl -sk -H "Authorization: Bearer $TOKEN" \
  "https://localhost:55000/security/policies?pretty=true"

# Создание политики (разрешение чтения агентов)
curl -sk -H "Authorization: Bearer $TOKEN" \
  -X POST "https://localhost:55000/security/policies" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "read_agents",
    "policy": {
      "actions": ["agent:read"],
      "resources": ["agent:id:*"],
      "effect": "allow"
    }
  }'

Ограничение частоты запросов

API ограничивает количество запросов для защиты от злоупотреблений:

Максимум max_request_per_minute запросов в минуту (по умолчанию 300)
Максимум max_login_attempts попыток аутентификации (по умолчанию 50)
Блокировка IP на block_time секунд после превышения лимита попыток

При превышении лимита API возвращает HTTP 429 (Too Many Requests).

Использование API из Dashboard Dev Tools

Wazuh Dashboard предоставляет встроенную консоль Dev Tools для выполнения API-запросов без использования командной строки. Консоль доступна в разделе Server management > Dev Tools.

Формат запросов в Dev Tools:

GET /agents?status=active&limit=5

GET /manager/info

POST /security/user/authenticate

Dev Tools автоматически добавляет аутентификацию и базовый URL.

Примеры на Python

Аутентификация и получение агентов

import requests
import urllib3
from base64 import b64encode

urllib3.disable_warnings(urllib3.exceptions.InsecureRequestWarning)

WAZUH_API = "https://localhost:55000"
USER = "wazuh-wui"
PASSWORD = "MyPassword"


def get_token() -> str:
    """Obtain JWT token from Wazuh API."""
    auth_header = b64encode(f"{USER}:{PASSWORD}".encode()).decode()
    headers = {"Authorization": f"Basic {auth_header}"}
    response = requests.post(
        f"{WAZUH_API}/security/user/authenticate",
        headers=headers,
        verify=False,
    )
    response.raise_for_status()
    return response.json()["data"]["token"]


def get_active_agents(token: str) -> list[dict]:
    """Retrieve list of active agents."""
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(
        f"{WAZUH_API}/agents",
        headers=headers,
        params={"status": "active", "limit": 500},
        verify=False,
    )
    response.raise_for_status()
    return response.json()["data"]["affected_items"]


token = get_token()
agents = get_active_agents(token)
for agent in agents:
    print(f"Agent {agent['id']}: {agent['name']} ({agent['status']})")

Мониторинг уязвимостей

def get_critical_vulnerabilities(token: str, agent_id: str) -> list[dict]:
    """Get critical vulnerabilities for a specific agent."""
    headers = {"Authorization": f"Bearer {token}"}
    response = requests.get(
        f"{WAZUH_API}/vulnerability/{agent_id}",
        headers=headers,
        params={"severity": "Critical", "limit": 100},
        verify=False,
    )
    response.raise_for_status()
    return response.json()["data"]["affected_items"]

Сравнение с API других SIEM-платформ

Характеристика	Wazuh API	Splunk REST API	Elastic Security API	QRadar API
Протокол	HTTPS (порт 55000)	HTTPS (порт 8089)	HTTPS (порт 9200/5601)	HTTPS (порт 443)
Аутентификация	JWT-токен	Session key / Bearer token	API key / Basic auth	SEC token
Авторизация	RBAC	Capabilities	RBAC / Spaces	User roles
Формат ответа	JSON	JSON/XML	JSON	JSON
Документация	OpenAPI / ReDoc	REST API Reference	OpenAPI	Interactive
Стоимость	Бесплатно	Коммерческая	Бесплатно (Basic) / Коммерческая	Коммерческая
SDK	Python (requests)	splunk-sdk	elasticsearch-py	Python SDK
Rate limiting	Настраиваемый	Нет по умолчанию	Нет по умолчанию	Да

Ключевые отличия

Splunk REST API предоставляет доступ к конфигурации через конфигурационные эндпоинты (/servicesNS/) с иерархической структурой пространств имен. Wazuh API использует плоскую структуру эндпоинтов, сгруппированных по функциональности.

Elastic Security API разделяет API на уровне Elasticsearch (индексы, поиск) и Kibana (правила, алерты). Wazuh объединяет все функции управления в едином API.

QRadar API использует статические токены авторизации без истечения срока действия. Wazuh использует JWT с ограниченным временем жизни, что обеспечивает более высокий уровень безопасности.

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

API не отвечает на запросы

Проверки:

Убедитесь, что менеджер запущен:

systemctl status wazuh-manager

Проверьте, что API слушает на нужном порту:

ss -tlnp | grep 55000

Просмотрите лог API:

tail -f /var/ossec/logs/api.log

Ошибка аутентификации (HTTP 401)

Убедитесь, что учетные данные верны
Проверьте, не истек ли JWT-токен (время жизни по умолчанию - 15 минут)
Получите новый токен через эндпоинт аутентификации

Ошибка авторизации (HTTP 403)

Проверьте назначенные пользователю роли и политики
Убедитесь, что политика разрешает запрашиваемое действие и ресурс
Проверьте режим RBAC (white list / black list)

Превышение лимита запросов (HTTP 429)

Уменьшите частоту запросов
Увеличьте параметр max_request_per_minute в api.yaml
Используйте параметры limit и offset для получения данных порциями вместо множественных запросов

Ошибки TLS-сертификата

При использовании самоподписанных сертификатов добавьте флаг -k в curl или verify=False в Python
Для промышленной эксплуатации замените самоподписанные сертификаты на сертификаты от доверенного CA
Проверьте пути к сертификатам в api.yaml

Для общего обзора инфраструктуры см. раздел инфраструктуры Wazuh . Информация о кластерном взаимодействии через API доступна в разделе серверный кластер .

Last updated on 8, апреля 2026

Wazuh Indexer API - запросы и работа с данными