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

> Руководство по REST API Wazuh 4.14 - JWT-аутентификация, управление агентами и правилами, RBAC, конфигурация api.yaml и примеры запросов curl и Python

Source: https://opennix.org/docs/wazuh/infrastructure/wazuh-server-api/


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 следуют стандартизированному формату:

```json
{
  "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-аутентификация (логин и пароль):

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

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

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

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

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

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

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

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

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

### Отзыв токена

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

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

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

### Агенты

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

```bash
# Список всех агентов
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"
```

### Правила

```bash
# Список всех правил
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"
```

### Декодеры

```bash
# Список всех декодеров
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"
```

### Менеджер

```bash
# Информация о менеджере
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"
```

### Кластер

```bash
# Статус кластера
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](/docs/wazuh/infrastructure/wazuh-server-cluster/).

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

```bash
# Информация об оборудовании агента
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"
```

### Уязвимости

```bash
# Обнаруженные уязвимости агента
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 (оценка конфигурации безопасности)

```bash
# Список политик 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 см. в разделе [оценка конфигурации безопасности](/docs/wazuh/capabilities/wazuh-sca/).

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

```bash
# Список групп
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`.

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

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

```bash
systemctl restart wazuh-manager
```

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

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

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

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

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

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

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

```bash
# Создание пользователя
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"
```

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

```bash
# Список ролей
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"
```

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

```bash
# Список политик
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

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

```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']})")
```

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

```python
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 не отвечает на запросы

**Проверки:**

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

```bash
systemctl status wazuh-manager
```

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

```bash
ss -tlnp | grep 55000
```

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

```bash
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](/docs/wazuh/infrastructure/). Информация о кластерном взаимодействии через API доступна в разделе [серверный кластер](/docs/wazuh/infrastructure/wazuh-server-cluster/).