security-alert-center/docs/TZ.md

Техническое задание

Security Alert Center (SAC)

Поле	Значение
Версия документа	1.0
Дата	2026-05-26
Статус	Черновик на согласование
Целевая ОС сервера	Ubuntu 24.04 LTS

---

1. Назначение и цели

1.1. Назначение

Security Alert Center (SAC) — центральное веб-приложение, которое:

1. Принимает структурированные события безопасности от агентов ssh-monitor (Linux) и RDP-login-monitor (Windows).
2. Хранит их в базе данных для поиска, аудита и аналитики.
3. Отображает ленту событий, инциденты (Problems) и дашборды в стиле Zabbix (Monitoring → Problems, графики, хосты).
4. По правилам доставляет оповещения операторам (Telegram, email, webhook) — когда на агентах включён режим UseSAC.

1.2. Цели

• Единая точка наблюдения за входами, неудачными попытками, sudo, банами IP, RD Gateway и т.д.
• Снижение «шума» в мессенджерах за счёт дедупликации, группировки и правил в SAC.
• Сохранение привычного поведения агентов при UseSAC=off (уведомления напрямую в Telegram/email, как сейчас).
• Эксплуатация на одном сервере Ubuntu 24.04 без обязательного Kubernetes.

1.3. Не входит в scope MVP (см. roadmap.md)

• Кластеризация SAC (active-active).
• Полноценный SIEM / ML-аномалии.
• Замена существующих агентов — они остаются, меняется только канал доставки при UseSAC.

---

2. Контекст: три репозитория

№	Репозиторий	Роль
1	ssh-monitor	Агент на Linux-серверах
2	RDP-login-monitor	Агент на Windows Server
3	security-alert-center	Центральный сервер (этот проект)

Совместная разработка в multi-root workspace — см. workspace-three-repos.md.

---

3. Как это работает (архитектура потоков)

Ниже — целевая схема взаимодействия компонентов (рис. 1).

flowchart LR
  subgraph agents [Агенты на хостах]
    SSH[ssh-monitor Linux]
    RDP[RDP-login-monitor Windows]
  end

  subgraph sac [Security Alert Center Ubuntu 24.04]
    API[Ingest API HTTPS]
    Q[Очередь / воркер]
    DB[(PostgreSQL)]
    RT[Realtime SSE/WebSocket]
    UI[Web UI]
    NOTIFY[Правила оповещений]
  end

  subgraph channels [Каналы наружу]
    TG[Telegram]
    MAIL[Email]
    WEBHOOK[Webhook / Slack]
  end

  SSH -->|JSON события + API key| API
  RDP -->|JSON события + API key| API
  API --> Q --> DB
  DB --> UI
  DB --> RT --> UI
  DB --> NOTIFY --> TG
  NOTIFY --> MAIL
  NOTIFY --> WEBHOOK

Рис. 1. Поток данных: агенты → SAC → БД/UI; оповещения пользователю при UseSAC=exclusive идут только из SAC.

3.1. Жизненный цикл события

1. На хосте возникает событие (успешный SSH, неудачный RDP, sudo, бан IP и т.д.).
2. Агент формирует каноническое JSON-событие (схема v1 — event-schema-v1.json).
3. POST /api/v1/events по HTTPS с API-ключом; при сбое — запись в локальный spool и повтор.
4. SAC: валидация → дедупликация → запись в PostgreSQL → оценка правил → при необходимости создание Problem.
5. Оператор просматривает UI; при UseSAC=exclusive Telegram/email отправляет SAC, не агент.

3.2. Режим UseSAC на агентах

Режим	Значение	Поведение агента	Кто шлёт в Telegram/email
off	0	Как сейчас	Агент
exclusive	1	Только SAC (расширенный JSON)	Только SAC
dual	2	SAC + локальные каналы	Оба (миграция/отладка)
fallback	3	SAC; при N сбоях подряд — снова локально	SAC, при аварии SAC — агент

Требования:

• При UseSAC=exclusive функции notify_send / Send-TelegramMessage для оповещений о событиях не вызываются.
• Локальные лог-файлы на агенте (LOG_FILE, login_monitor.log и т.д.) сохраняются всегда.
• При UseSAC=exclusive обязательны SAC_URL, SAC_API_KEY; при старте — проверка доступности SAC (--check-sac / аналог).
• Подробности — agent-integration.md.

---

4. Функциональные требования

4.1. Приём событий (Ingest API)

ID	Требование
F-ING-01	POST /api/v1/events принимает одно событие JSON, соответствующее event-schema-v1.json.
F-ING-02	Аутентификация: заголовок Authorization: Bearer <api_key> или X-SAC-API-Key.
F-ING-03	Ответ 202 Accepted с event_id, sac_event_url; при создании Problem — problem_id (опционально).
F-ING-04	Идемпотентность: повтор с тем же event_id не создаёт дубликат.
F-ING-05	POST /api/v1/events/batch — до 100 событий (фаза 1.5).
F-ING-06	Rate limiting: настраиваемый лимит на ключ/хост.
F-ING-07	GET /health — проверка БД и версии (для агентов и мониторинга).

4.2. Учёт хостов (Hosts)

ID	Требование
F-HST-01	Первый валидный ingest с API key регистрирует/обновляет карточку хоста.
F-HST-02	Поля: hostname, display_name, os_family, os_version, ipv4/ipv6, версия агента, use_sac_mode, last_seen, tags.
F-HST-03	Статус «жив/мёртв» по последнему agent.heartbeat (порог N минут — настраивается).
F-HST-04	UI: список хостов, фильтр, переход к событиям хоста.

4.3. Хранение событий (Events)

ID	Требование
F-EVT-01	Хранение всех полей события + received_at, host_id.
F-EVT-02	Поиск/фильтр: период, хост, type, severity, IP, user, текст в summary.
F-EVT-03	Просмотр карточки события с details, raw (с лимитом отображения).
F-EVT-04	Экспорт CSV за выбранный фильтр (фаза 1.5).
F-EVT-05	Retention: настраиваемое хранение сырых событий (по умолчанию 90 дней).

4.4. Инциденты (Problems)

ID	Требование
F-PRB-01	Правила создают Problem из одного или нескольких событий (пример: ≥30 ssh.login.failed за 15 мин с одного IP).
F-PRB-02	Статусы: open, acknowledged, resolved.
F-PRB-03	UI: список Problems с severity, хостом, временем, действиями ack/resolve.
F-PRB-04	Связь Problem ↔ Events (просмотр связанных событий).

4.5. Веб-интерфейс

ID	Требование
F-UI-01	Страница Problems — активные инциденты, счётчики по severity.
F-UI-02	Страница Events — лента с пагинацией и фильтрами.
F-UI-03	Страница Hosts — инвентарь агентов.
F-UI-04	Страница Dashboards — графики: успешные/неудачные входы по времени, топ IP, sudo, баны (MVP: базовый набор виджетов).
F-UI-05	Live-лента последних событий (SSE или WebSocket).
F-UI-06	Аутентификация в UI: логин/пароль (MVP); LDAP — фаза 3.
F-UI-07	Роли MVP: admin, operator, viewer.

4.6. Оповещения из SAC

ID	Требование
F-NOT-01	Каналы: Telegram, SMTP email, generic webhook (JSON).
F-NOT-02	Правила: условие (тип, severity, хост, тег) → каналы + шаблон.
F-NOT-03	Дедупликация и cooldown на уровне SAC (аналог BRUTE_NOTIFY_COOLDOWN_SEC, SSH_ACCEPT_NOTIFY_DEDUP_SEC).
F-NOT-04	Расписание тишины (maintenance window) — фаза 2.
F-NOT-05	Суточные отчёты (report.daily.*) формируются и отправляются из SAC, не с агента при UseSAC=exclusive.

4.7. Типы событий (минимальный перечень MVP)

ssh-monitor:

• ssh.login.success, ssh.login.failed, ssh.session.disconnected
• privilege.sudo.command
• ssh.ip.banned, ssh.ip.bruteforce.threshold, ssh.bruteforce.mass
• session.logind.new, session.logind.removed, session.logind.failed
• report.daily.ssh, agent.heartbeat, agent.recovered, agent.test

RDP-login-monitor:

• rdp.login.success, rdp.login.failed, auth.explicit.credentials (4648)
• rdg.connection.success, rdg.connection.failed
• report.daily.rdp, agent.heartbeat, agent.lifecycle, agent.test

Полный контракт — event-schema-v1.json и agent-integration.md.

4.8. Расширенные поля событий (при UseSAC=exclusive)

Агент передаёт структуру сверх текущего текста Telegram:

• Идентификаторы: event_id, correlation_id, dedup_key, fingerprint
• Контекст хоста: FQDN, timezone, версия продукта, agent.instance_id
• Пороги: enrichment.attempt_number, enrichment.threshold
• SSH/RDP-специфика: port, logon_type, gateway target, sudo command, ban_until
• raw: обрезанный фрагмент journal / Event XML
• filtered_out + filter_reason (опционально, отдельный тип)

Обогащение в SAC (не обязательно в MVP): GeoIP, «новый IP для user», корреляция SSH+RDP с одного IP.

---

5. Нефункциональные требования

ID	Требование
NF-01	Сервер приложения: Ubuntu 24.04 LTS (единственная поддерживаемая платформа для SAC).
NF-02	БД: PostgreSQL 16+ (production); SQLite допустим только для dev.
NF-03	Ingest: p95 < 2 с при нормальной нагрузке (до 50 событий/с мин суммарно).
NF-04	Доступность UI по HTTPS (TLS).
NF-05	API keys хранятся в БД как hash; секреты конфигурации — в /etc/security-alert-center/ или env, не в git.
NF-06	Резервное копирование БД: документированная процедура pg_dump (см. deployment.md).
NF-07	Логи приложения: structured JSON, ротация logrotate.
NF-08	Язык UI: русский (основной); i18n — фаза 3.
NF-09	Время в БД: UTC; отображение — timezone пользователя или Europe/Moscow по умолчанию.

---

6. Технологический стек (целевой)

Слой	Технология
Backend	Python 3.12, FastAPI, SQLAlchemy 2, Alembic
БД	PostgreSQL 16
Очередь (фаза 1.5+)	Redis 7, воркер (ARQ или Celery)
Frontend	Vue 3 + Vite, UI-kit (Naive UI / PrimeVue), ECharts
Realtime	Server-Sent Events (приоритет MVP)
Reverse proxy	nginx
Развёртывание	Native: PostgreSQL + systemd + nginx (production). Docker Compose — альтернатива для стенда

Детали — architecture.md.

---

7. Безопасность

• Только HTTPS для ingest и UI.
• Отдельные API keys на хост (ротация из UI).
• RBAC в UI (MVP: 3 роли).
• Аудит действий: ack/resolve, смена правил.
• PII в raw — ограничение размера; опция маскирования в логах SAC.
• Разделение сетей: агенты → исходящий 443 на SAC; SAC не требует входящих на агенты.

---

8. Интеграция с существующими агентами

Изменения в репозиториях ssh-monitor и RDP-login-monitor — отдельные задачи, не в этом репозитории.

Обязательно:

1. Параметры UseSAC, SAC_URL, SAC_API_KEY, SAC_MODE (off|exclusive|dual|fallback).
2. Функция отправки структурированного события + локальный spool.
3. Команда проверки --test-sac / Test-SacConnection.
4. Сохранение локальных логов при любом режиме.

Спецификация — agent-integration.md.

---

9. Критерии приёмки MVP

1. Развёрнут SAC на Ubuntu 24.04, доступны UI и POST /api/v1/events.
2. Тестовый агент (curl / agent.test) создаёт событие, видимое в UI < 10 с.
3. Реализованы режимы ingest для типов из п. 4.7 (тестовыми payload).
4. Страницы Problems (базовые правила), Events, Hosts, Dashboard (минимум 3 виджета).
5. Настроен канал Telegram из SAC; при UseSAC=exclusive на тестовом ssh-monitor Telegram с агента не приходит, с SAC — приходит.
6. Heartbeat: Problem «хост недоступен» при отсутствии heartbeat > N мин.
7. Документация развёртывания воспроизводима с нуля по deployment.md.
8. Spool: при остановке SAC события буферизуются на агенте и доставляются после восстановления.

---

10. Риски и митигация

Риск	Митигация
SAC недоступен, алерты потеряны	spool на агенте, режим fallback
Дубли SSH + logind	dedup_key на агенте и в SAC
Перегруз БД	партиции по месяцу, retention, агрегаты (фаза 2)
Двойные Telegram при миграции	явный dual, затем exclusive

---

11. Связанные документы

• architecture.md
• event-schema-v1.json
• agent-integration.md
• work-plan.md
• roadmap.md
• deployment.md
• workspace-three-repos.md

---

12. История изменений

Версия	Дата	Изменения
1.0	2026-05-26	Первоначальная версия ТЗ