128 lines
5.6 KiB
Markdown
128 lines
5.6 KiB
Markdown
# Агрегированные события безопасности через 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`.
|
||
|
||
## Пилотная проверка UI
|
||
|
||
Для демонстрационного стенда проверяются три режима:
|
||
|
||
1. `SECURITY_EVENTS_BACKEND=disabled` - штатный режим без ClickHouse.
|
||
2. `SECURITY_EVENTS_BACKEND=clickhouse` и доступный ClickHouse - сводка
|
||
показывает “События безопасности доступны”.
|
||
3. `SECURITY_EVENTS_BACKEND=clickhouse` и недоступный ClickHouse - портал
|
||
показывает “События безопасности временно недоступны”, но `/api/reports`
|
||
остается валидным.
|
||
|
||
Smoke-тест поддерживает явное ожидание режима:
|
||
|
||
```bash
|
||
DETMIR_PORTAL_SMOKE_SECURITY_EVENTS_EXPECT=disabled \
|
||
node scripts/detmir-portal-tabs-smoke.mjs
|
||
|
||
DETMIR_PORTAL_SMOKE_SECURITY_EVENTS_EXPECT=fallback \
|
||
node scripts/detmir-portal-tabs-smoke.mjs
|
||
```
|
||
|
||
В представлении руководителя не выводятся технические параметры
|
||
`SECURITY_EVENTS_BACKEND` и `CLICKHOUSE_*`. Подробная причина отказа видна в
|
||
представлении эксплуатации.
|