feat(portal): add optional ClickHouse security events summary

2026-06-04 21:51:41 +03:00
parent 90378229ae
commit da17047b38
7 changed files with 1005 additions and 152 deletions
@@ -0,0 +1,102 @@
+# Агрегированные события безопасности через ClickHouse
+
+## Назначение
+
+`detmir-portal` может показывать краткую сводку событий безопасности за последние
+24 часа из ClickHouse. Это дополнительный аналитический слой для управленческого
+вывода, рисков подразделений, карты рисков и связи рисков с активностью.
+
+Важно: этот режим не превращает AWatch-rus в SIEM. Портал не показывает сырые
+журналы, не хранит SIEM-события как первичный источник и не создает инциденты
+автоматически. В интерфейсе отображаются только агрегаты.
+
+## Статус по умолчанию
+
+Режим выключен:
+
+```env
+SECURITY_EVENTS_BACKEND=disabled
+```
+
+В выключенном режиме портал работает как раньше, `/api/reports` возвращает
+валидный JSON, а `detmir-check` не проверяет ClickHouse.
+
+## Переменные окружения
+
+```env
+SECURITY_EVENTS_BACKEND=clickhouse
+CLICKHOUSE_URL=http://127.0.0.1:8123
+CLICKHOUSE_DATABASE=analytics_1c
+CLICKHOUSE_USER=default
+CLICKHOUSE_PASSWORD=
+```
+
+`CLICKHOUSE_PASSWORD` используется только для HTTP Basic Auth и не выводится в
+JSON, markdown-отчеты или health-ответы.
+
+## Ожидаемые агрегаты
+
+Портал формирует блок `security_events_summary`:
+
+- `status`;
+- `backend`;
+- `events_24h`;
+- `failed_logins_24h`;
+- `suspicious_logins_24h`;
+- `rdp_sessions_24h`;
+- `account_changes_24h`;
+- `agent_errors_24h`;
+- `top_departments`;
+- `last_event_utc`;
+- `query_ms`;
+- `fallback_used`.
+
+Текущая реализация использует агрегированные запросы к таблицам
+`entity_timeline` и `host_events` выбранной базы ClickHouse.
+
+## Поведение при отказе
+
+Если `SECURITY_EVENTS_BACKEND=clickhouse`, но ClickHouse недоступен:
+
+- портал не падает;
+- `/api/reports` остается валидным;
+- `security_events_summary.fallback_used=true`;
+- в ролевом представлении “Эксплуатация” показывается причина;
+- `detmir-check` добавляет необязательное предупреждение, но не считает это
+  критическим отказом контура.
+
+## Где видно в портале
+
+- “Сводка руководителя”: короткий счетчик событий за 24 часа.
+- “Главный вывод”: события учитываются как один из подтверждающих слоев риска.
+- “Риски подразделений”: события повышают приоритет подразделения только как
+  агрегированный риск-фактор.
+- “Карта рисков”: события отображаются отдельной колонкой.
+- “Связь рисков и активности”: события участвуют в объяснении корреляции.
+- “ИБ”: блок “События безопасности за 24 часа”.
+- “Эксплуатация”: статус источника и причина fallback.
+
+## Проверка
+
+Выключенный режим:
+
+```bash
+SECURITY_EVENTS_BACKEND=disabled detmir-check --json
+curl -s http://127.0.0.1:8720/portal/api/reports | jq '.security_events_summary'
+```
+
+Включенный режим:
+
+```bash
+SECURITY_EVENTS_BACKEND=clickhouse \
+CLICKHOUSE_URL=http://127.0.0.1:8123 \
+CLICKHOUSE_DATABASE=analytics_1c \
+detmir-check --json
+```
+
+Ожидаемый результат при доступном ClickHouse: `security-events-clickhouse` имеет
+`ok=true`, а `/api/reports.security_events_summary.backend="clickhouse"`.
+
+Ожидаемый результат при недоступном ClickHouse: портал возвращает
+`fallback_used=true`, а `detmir-check` показывает предупреждение
+`security-events-clickhouse` с `required=false`.