Аналитика событий фаервола

qf-analytics строит отчёты по событиям фаервола и экспортирует агрегированные данные. Сервис разворачивается отдельно от Control Plane и только читает данные из PostgreSQL или OpenSearch.

Инструкция по развёртыванию — в разделе установки, переменные окружения — в справочнике конфигурации.

Источник данных

Источник выбирается по объёму данных. Сервис выполняет только SQL-запросы SELECT или запросы OpenSearch _search.

Масштаб	ANALYTICS_SOURCE	Источник
Малый	postgres	CP-primary, RO-роль
Средний	postgres	RO-реплика (тот же адаптер, другой DSN)
Крупный	opensearch	Копия событий в SIEM

От источника зависят скорость широких временных окон и способ поиска аномалий. Фильтры по имени правила и политики для OpenSearch требуют ANALYTICS_ENRICH_DSN; без него отчёт показывает идентификаторы правил и не строит срез по политикам.

Доступ и SSO

Сервис использует роли Control Plane. Операторский access-токен RS256 проверяется по JWKS. Каждый защищённый запрос дополнительно проверяет текущие права через GET /auth/validate Control Plane; готовый отчёт и экспорт проверяются ещё раз перед выдачей. При недоступности CP выдача запрещается, даже если публичный ключ есть в кэше. ANALYTICS_ROLES задаёт список ролей с доступом; по умолчанию разрешены admin, editor, auditor. Остальным сервис отвечает 403.

При публикации под тем же родительским доменом, что и Control Plane, cookie qf_token передаётся сервису и повторный вход не нужен.

Запросы и экспорт ограничены tenant из проверенного access-токена. Пустой или невалидный tenant даёт 403; заголовок и query-параметр не меняют scope. Фильтры по именам действуют внутри tenant. Resolver хранит отдельные снимки имён на пять минут для каждого tenant. OpenSearch исключает документы без tenant_id.

Выбранный в консоли tenant действует и в аналитике. При переключении страница сбрасывает предыдущий отчёт. Несовпадение X-Expected-Tenant-ID со scope cookie возвращает 409.

Эта изоляция относится к запросам через qf-analytics. Доступ пользователей напрямую к OpenSearch, его ролям, индексам и tenants Dashboards настраивается отдельно администратором SIEM; qf не управляет этими разрешениями.

Эндпоинты

Путь	Доступ	Назначение
GET /healthz	открыт	Liveness/readiness.
GET /version	открыт	Версия.
GET /app/	открыт	Интерфейс отчётов; сами данные защищены API-аутентификацией.
GET /api/session	роль из allowlist и valid tenant	Текущий tenant проверенного JWT.
GET /api/report	роль из allowlist	JSON-отчёт.
GET /api/report/export	роль из allowlist	Скачивание отчёта файлом.

Параметры /api/report и /api/report/export:

Параметр	Значения	Назначение
since	duration (24h, 48h, 336h, 720h, …)	Окно отчёта от «сейчас» назад.
from / to	RFC3339	Явное окно (альтернатива since).
host / rule / policy	имя	Фильтр по имени; применяется ко всем агрегациям окна. Для OpenSearch фильтры rule и policy требуют ANALYTICS_ENRICH_DSN.
redact	mask (по умолчанию) | hash | none	Режим обезличивания IP-осей.
format (только export)	json | md | csv	Формат файла-артефакта.

Состав отчёта и фильтры

Отчёт содержит общий итог за период, первые N значений по каждому измерению и найденные аномалии.

Измерения отчёта: хост, действие, направление, протокол, состояние conntrack, исходный и конечный IP-адреса и порты, правило, политика и время. Срез по правилам охватывает только события, совпавшие с правилом. Политика определяется по правилу. Протокол показывается именем (tcp, udp и другие), пустое значение — как (none).

В UI:

• Панели сворачиваются и по умолчанию закрыты.
• Готовые периоды: сутки, двое суток, две недели и месяц. API также принимает произвольные from и to.
• Фильтры по хосту, правилу и политике применяются по Enter или кнопке Generate report. Новый запрос отменяет предыдущий.

Для фильтров по хосту и правилу в PostgreSQL есть индексы на партициях log_events. Отчёт без фильтра группирует все события периода и на большом объёме может выполняться долго.

Обезличивание IP-адресов

Параметр redact задаёт обработку исходных и конечных IP-адресов:

• mask (по умолчанию) — IPv4 сворачивается до /24, IPv6 до /64.
• hash — адрес заменяется стабильным сокращённым SHA-256.
• none — сырой адрес (для доверенного контура).

Хосты, порты и остальные измерения не меняются. Обезличивание выполняется при построении отчёта, поэтому необработанный IP-адрес не попадает ни в API-ответ, ни в экспорт при режимах mask и hash.

Экспорт

Экспорт содержит агрегированный отчёт, а не исходные события. Доступны JSON, Markdown и CSV. Сервис не отправляет файл во внешние системы: он возвращает его оператору. Пустые срезы в JSON сериализуются как [], а не null. CSV защищает текстовые значения от интерпретации как формул электронных таблиц; JSON и Markdown сохраняют исходный текст.

Детекция аномалий

Способ поиска аномалий зависит от источника:

• postgres — встроенная эвристика ищет всплески deny относительно медианы и рост conntrack=invalid. Пороги задают переменные ANALYTICS_ANOMALY_*.
• opensearch — серверные агрегации OpenSearch вычисляют отклонение доли deny и количество invalid по временным интервалам. ML-плагин не требуется.

Эта проверка выполняется при построении отчёта и не заменяет постоянный мониторинг. Для непрерывных уведомлений используется мониторинг на стороне SIEM; пример — в разделе установки.

Производительность и выбор источника

Отчёт без фильтра группирует все события периода. На большой таблице log_events это может привести к полному чтению партиций и тайм-ауту.

• Для частых запросов используются фильтры host и rule.
• ANALYTICS_PG_MAX_WINDOW_HOURS ограничивает период для PostgreSQL. Превышение возвращает 422.
• Для больших объёмов и широких периодов используется OpenSearch.

Границы отчёта

• Видны только логируемые события: правила silent/log=false в отчёт не попадают.
• Оси rule/policy покрывают только rule-matched трафик; default-action (без правила) не атрибутируется.

При смене tenant в консоли вкладка аналитики сбрасывает отчёт и фильтры. Вкладка на другом origin тоже проверяет текущий scope по таймеру и при возврате фокуса. Запросы отчёта и выгрузки передают ожидаемый tenant; при несовпадении сервер отвечает 409, а страница закрывает прежние данные и предлагает повторную проверку. API возвращает фактический scope в X-Tenant-ID ответа.

Открытая вкладка после отзыва доступа

Консоль проверяет сессию каждые две секунды и при возвращении во вкладку. Отзыв доступа или смена сессии очищает отчёт и фильтры, отменяет незавершённые запросы отчёта и экспорта. Поздний ответ не запускает скачивание. При сетевом сбое данные также очищаются, но сообщение указывает на невозможность проверить доступ. После нового входа нажмите Проверить доступ снова, затем постройте новый отчёт. Автоматического переноса отчёта в другой tenant нет. Новые сообщения доступны на русском и английском; язык берётся из настройки консоли CP или браузера.