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](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](workspace-three-repos.md).

---

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

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

```mermaid
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](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](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](event-schema-v1.json) и [agent-integration.md](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 &lt; 2 с при нормальной нагрузке (до 50 событий/с мин суммарно). |
| NF-04 | Доступность UI по HTTPS (TLS). |
| NF-05 | API keys хранятся в БД как hash; секреты конфигурации — в `/etc/security-alert-center/` или env, не в git. |
| NF-06 | Резервное копирование БД: документированная процедура `pg_dump` (см. [deployment.md](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](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](agent-integration.md).

---

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

1. Развёрнут SAC на Ubuntu 24.04, доступны UI и `POST /api/v1/events`.
2. Тестовый агент (curl / `agent.test`) создаёт событие, видимое в UI &lt; 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 &gt; N мин.
7. Документация развёртывания воспроизводима с нуля по [deployment.md](deployment.md).
8. Spool: при остановке SAC события буферизуются на агенте и доставляются после восстановления.

---

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

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

---

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

- [architecture.md](architecture.md)
- [event-schema-v1.json](event-schema-v1.json)
- [agent-integration.md](agent-integration.md)
- [work-plan.md](work-plan.md)
- [roadmap.md](roadmap.md)
- [deployment.md](deployment.md)
- [workspace-three-repos.md](workspace-three-repos.md)

---

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

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