docs: ТЗ v1.0, планы и схема SAC (фаза 0)

Security Alert Center — документация без кода приложения. - TZ, архитектура, интеграция агентов (UseSAC) - JSON Schema событий v1, deployment Ubuntu 24.04 - План работ, roadmap, multi-root workspace
2026-05-26 19:54:47 +10:00
commit 4f3adc9429
17 changed files with 1702 additions and 0 deletions
@@ -0,0 +1,36 @@
+# Python
+__pycache__/
+*.py[cod]
+.venv/
+venv/
+.env
+.env.*
+!.env.example
+
+# Node / frontend (будущее)
+node_modules/
+dist/
+.nuxt/
+.output/
+
+# IDE
+.idea/
+.vscode/*
+!.vscode/extensions.json
+
+# OS
+.DS_Store
+Thumbs.db
+
+# Runtime / deploy secrets
+/config/local.yaml
+/deploy/*.local.*
+*.pem
+*.key
+
+# Data
+*.db
+pgdata/
+
+# Logs
+*.log
@@ -0,0 +1,37 @@
+# Security Alert Center (SAC)
+
+Центральная платформа сбора, хранения и отображения событий безопасности с Linux- и Windows-хостов.
+
+**Агенты (отдельные репозитории):**
+
+| Репозиторий | Назначение |
+|-------------|------------|
+| [ssh-monitor](https://git.kalinamall.ru/PapaTramp/ssh-monitor) | Linux: SSH, sudo, logind, брутфорс, баны |
+| [RDP-login-monitor](https://git.kalinamall.ru/PapaTramp/RDP-login-monitor) | Windows: RDP/RDS, RD Gateway |
+| **security-alert-center** (этот репозиторий) | Ubuntu 24.04: API, БД, UI, оповещения |
+
+## Статус проекта
+
+**Фаза документации.** Реализация кода начнётся после утверждения ТЗ и планов.
+
+## Документация
+
+| Документ | Описание |
+|----------|----------|
+| [docs/TZ.md](docs/TZ.md) | Техническое задание (основной документ) |
+| [docs/architecture.md](docs/architecture.md) | Архитектура и компоненты |
+| [docs/event-schema-v1.json](docs/event-schema-v1.json) | JSON Schema событий v1 |
+| [docs/agent-integration.md](docs/agent-integration.md) | Интеграция агентов, режим `UseSAC` |
+| [docs/work-plan.md](docs/work-plan.md) | План работ (этапы разработки) |
+| [docs/roadmap.md](docs/roadmap.md) | Дорожная карта продуктовых фаз |
+| [docs/deployment.md](docs/deployment.md) | Развёртывание на Ubuntu 24.04 |
+| [docs/workspace-three-repos.md](docs/workspace-three-repos.md) | Multi-root workspace для трёх репо |
+
+## Целевая платформа
+
+- **Сервер SAC:** Ubuntu 24.04 LTS
+- **Агенты:** существующие скрипты на Linux и Windows (изменения — отдельными задачами в их репозиториях)
+
+## Лицензия
+
+Уточняется (TBD).
@@ -0,0 +1,11 @@
+# Backend (FastAPI)
+
+**Статус:** не реализован. См. [docs/work-plan.md](../docs/work-plan.md) фаза 1.
+
+Планируется:
+
+- `app/main.py` — точка входа
+- `app/api/v1/events.py` — ingest
+- `app/models/` — SQLAlchemy
+- `app/services/` — правила, уведомления
+- `alembic/` — миграции
@@ -0,0 +1,10 @@
+# Deploy
+
+**Статус:** не реализован. См. [docs/deployment.md](../docs/deployment.md).
+
+Планируется:
+
+- `docker-compose.yml`
+- `nginx/sacc.conf`
+- `.env.example`
+- `systemd/` unit-файлы (вариант B)
@@ -0,0 +1,20 @@
+# Индекс документации SAC
+
+| Документ | Назначение |
+|----------|------------|
+| [TZ.md](TZ.md) | **Техническое задание** (главный документ) |
+| [diagrams/data-flow.md](diagrams/data-flow.md) | Диаграмма «Как это работает» (Mermaid) |
+| [architecture.md](architecture.md) | Компоненты, API, модель данных |
+| [agent-integration.md](agent-integration.md) | UseSAC, протокол ingest, маппинг типов |
+| [event-schema-v1.json](event-schema-v1.json) | JSON Schema событий |
+| [work-plan.md](work-plan.md) | План работ по фазам |
+| [roadmap.md](roadmap.md) | Дорожная карта версий |
+| [deployment.md](deployment.md) | Ubuntu 24.04, backup, TLS |
+| [workspace-three-repos.md](workspace-three-repos.md) | Cursor multi-root |
+
+## Порядок чтения
+
+1. TZ.md  
+2. diagrams/data-flow.md  
+3. agent-integration.md + event-schema-v1.json  
+4. work-plan.md  
@@ -0,0 +1,310 @@
+# Техническое задание  
+# 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` | Центральный сервер (этот проект) |
+
+Совместная разработка в Cursor: 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 |
+| Развёртывание | Docker Compose **или** native systemd (на выбор при реализации) |
+
+Детали — [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 | Первоначальная версия ТЗ |
@@ -0,0 +1,183 @@
+# Интеграция агентов с SAC
+
+Контракт между **ssh-monitor**, **RDP-login-monitor** и **Security Alert Center**.  
+Изменения вносятся в репозитории агентов отдельными задачами.
+
+---
+
+## 1. Режим `UseSAC`
+
+### 1.1. Параметры конфигурации
+
+**ssh-monitor** (`/etc/ssh-monitor.conf`):
+
+```ini
+# off | exclusive | dual | fallback
+UseSAC="exclusive"
+SAC_URL="https://sac.example.com/api/v1/events"
+SAC_API_KEY="sac_xxxxxxxx"
+SAC_SPOOL_DIR="/var/lib/ssh-monitor/sac-spool"
+SAC_SEND_HEARTBEAT="1"
+SAC_FALLBACK_FAILURES="5"
+SAC_TIMEOUT_SEC="12"
+```
+
+**RDP-login-monitor** (`Login_Monitor.ps1` или отдельный `.conf`):
+
+```powershell
+$UseSAC = "exclusive"   # off | exclusive | dual | fallback
+$SacUrl = "https://sac.example.com/api/v1/events"
+$SacApiKey = "sac_xxxxxxxx"
+$SacSpoolDir = "D:\Soft\Logs\sac-spool"
+```
+
+### 1.2. Матрица поведения
+
+| Событие | `off` | `exclusive` | `dual` | `fallback` |
+|---------|-------|-------------|--------|------------|
+| Auth / sudo / ban / RDP login | Telegram/email с агента | Только SAC JSON | SAC + Telegram | SAC; при сбоях → Telegram |
+| Daily report | С агента | SAC формирует и шлёт | Оба | SAC, fallback как выше |
+| Heartbeat | С агента (если включён) | Только SAC (`agent.heartbeat`) | Оба | SAC |
+| Локальный LOG_FILE | Да | Да | Да | Да |
+
+### 1.3. Проверка при старте
+
+- `UseSAC=off` — без изменений: хотя бы один канал `NOTIFY_CHAIN` (как сейчас).
+- `UseSAC≠off` — обязательны `SAC_URL`, `SAC_API_KEY`; HTTP `GET {base}/health` OK.
+- `--check-sac` / `Test-SacConnection` — отправка `agent.test`, ожидание `202`.
+
+---
+
+## 2. Протокол ingest
+
+### 2.1. Запрос
+
+```http
+POST /api/v1/events HTTP/1.1
+Host: sac.example.com
+Content-Type: application/json
+Authorization: Bearer sac_xxxxxxxx
+Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000
+
+```
+
+### 2.2. Ответ
+
+```json
+{
+  "status": "accepted",
+  "event_id": "550e8400-e29b-41d4-a716-446655440000",
+  "sac_event_url": "/events/12345",
+  "problem_id": null
+}
+```
+
+### 2.3. Spool при ошибке
+
+1. Записать JSON в `SAC_SPOOL_DIR/{event_id}.json`.
+2. Периодически (каждая итерация цикла / отдельный timer) повторять POST.
+3. После успеха — удалить файл.
+4. Лимит размера spool (например 500 MB) — логировать WARN, не удалять без алерта.
+
+---
+
+## 3. Маппинг уведомлений → типы событий
+
+### 3.1. ssh-monitor
+
+| Текущий текст (сокращённо) | `type` | `severity` |
+|----------------------------|--------|------------|
+| Успешное SSH | `ssh.login.success` | info |
+| Неудачная SSH | `ssh.login.failed` | warning |
+| IP заблокирован | `ssh.ip.banned` | high |
+| Лимит без бана | `ssh.ip.bruteforce.threshold` | warning |
+| Массовый брутфорс | `ssh.bruteforce.mass` | high |
+| Sudo | `privilege.sudo.command` | warning–critical* |
+| logind new/removed/failed | `session.logind.*` | info–warning |
+| Ежедневный отчёт | `report.daily.ssh` | info |
+| Heartbeat | `agent.heartbeat` | info |
+
+\* critical — по эвристике команды (`useradd`, `passwd`, `rm -rf`, …) в `details.risk_level`.
+
+**Дополнительные поля в `details` (exclusive):**
+
+- `user`, `source_ip`, `port`, `attempt_number`, `max_attempts`
+- `sudo`: `run_as`, `command`, `pwd`, `risk_level`
+- `ban`: `ban_until`, `enable_ip_ban`
+- `brute`: `window_sec`, `fails_in_window`
+- `whitelist_matched`: boolean
+
+### 3.2. RDP-login-monitor
+
+| Событие | `type` | `severity` |
+|---------|--------|------------|
+| 4624 успех | `rdp.login.success` | info |
+| 4625 неудача | `rdp.login.failed` | warning |
+| 4648 | `auth.explicit.credentials` | warning |
+| RD Gateway 302 | `rdg.connection.success` | info |
+| RD Gateway 303 | `rdg.connection.failed` | warning |
+| Старт/стоп | `agent.lifecycle` | info |
+| Отчёт | `report.daily.rdp` | info |
+
+**Дополнительные поля:**
+
+- `event_id_windows`, `logon_type`, `ip_address`, `workstation_name`
+- `gateway_target`, `gateway_error_code`
+- `filtered_out`, `filter_reason`
+
+---
+
+## 4. Поля `dedup_key` (рекомендации)
+
+| Тип | Формат dedup_key |
+|-----|------------------|
+| ssh.login.success | `{product}\|{host}\|ssh.login.success\|{user}\|{ip}` |
+| ssh.login.failed | `{product}\|{host}\|ssh.login.failed\|{ip}` (окно в SAC) |
+| privilege.sudo | `{product}\|{host}\|sudo\|{user}\|{hash(command)}` |
+| rdp.login.failed | `{product}\|{host}\|rdp.failed\|{ip}\|{user}` |
+
+SAC применяет cooldown по `dedup_key` + правилам.
+
+---
+
+## 5. Точки встраивания в код агентов
+
+### ssh-monitor
+
+- Новая функция `send_sac_event()` вызывается из мест, где сейчас `notify_send "$message"`.
+- Обёртка `notify_or_sac()`:
+  - `UseSAC=off` → `notify_send`
+  - `exclusive` → только `send_sac_event` (в `summary` — тот же текст)
+  - `dual` → оба
+  - `fallback` → `send_sac_event`; при fail increment counter → при пороге `notify_send`
+
+### RDP-login-monitor
+
+- `Send-SacEvent` + замена вызовов `Send-TelegramMessage` для событий мониторинга.
+- Heartbeat и daily report — отдельные типы в SAC.
+
+---
+
+## 6. Обратная совместимость
+
+- По умолчанию `UseSAC=off` — поведение 100% как сейчас.
+- `BACKUP_WEBHOOK_URL` в ssh-monitor при `exclusive` не используется для обычных алертов (только emergency в `fallback` — опционально).
+
+---
+
+## 7. Чеклист готовности агента
+
+- [ ] Параметры конфига задокументированы в README агента
+- [ ] `--check-sac` / `Test-SacConnection`
+- [ ] Spool и повторная отправка
+- [ ] Все типы из п. 3 покрыты
+- [ ] `event_id` UUID на каждое событие
+- [ ] Секреты не в git
+
+---
+
+## 8. См. также
+
+- [event-schema-v1.json](event-schema-v1.json)
+- [TZ.md](TZ.md) §3.2, §4.8
+- [TZ.md](TZ.md) §3.2, §4.8
@@ -0,0 +1,163 @@
+# Архитектура Security Alert Center
+
+Дополнение к [TZ.md](TZ.md). Описывает компоненты, границы и модель данных.
+
+---
+
+## 1. Диаграмма компонентов
+
+```mermaid
+flowchart TB
+  subgraph external [Внешние системы]
+    AG_SSH[ssh-monitor]
+    AG_RDP[RDP-login-monitor]
+    TG[Telegram API]
+    SMTP[SMTP]
+  end
+
+  subgraph sac_host [Ubuntu 24.04 — хост SAC]
+    NGX[nginx TLS]
+    API[FastAPI — api]
+    WRK[Worker]
+    FE[Static SPA]
+    PG[(PostgreSQL)]
+    RD[(Redis — фаза 1.5+)]
+  end
+
+  AG_SSH -->|HTTPS ingest| NGX
+  AG_RDP -->|HTTPS ingest| NGX
+  NGX --> API
+  NGX --> FE
+  API --> PG
+  API --> RD
+  WRK --> PG
+  WRK --> RD
+  WRK --> TG
+  WRK --> SMTP
+  FE -->|REST + SSE| NGX
+```
+
+---
+
+## 2. Компоненты
+
+| Компонент | Ответственность |
+|-----------|-----------------|
+| **nginx** | TLS, rate limit, раздача static UI, прокси `/api` → FastAPI |
+| **api** | Ingest, REST для UI, auth JWT, health |
+| **worker** | Правила Problems, отправка уведомлений, суточные отчёты, retention |
+| **frontend** | SPA: Problems, Events, Hosts, Dashboards, Settings |
+| **PostgreSQL** | События, хосты, problems, пользователи, правила, audit |
+| **Redis** | Очередь задач, pub/sub для SSE (опционально) |
+
+---
+
+## 3. Границы контекстов
+
+### 3.1. Агент (вне SAC)
+
+- Чтение локальных журналов (journalctl, Security.evtx).
+- Формирование JSON-события.
+- Режим `UseSAC`: маршрутизация «локальные каналы» vs «только SAC».
+- Локальный spool при недоступности SAC.
+
+### 3.2. SAC
+
+- Единственный источник доставки оповещений при `UseSAC=exclusive`.
+- Дедупликация, корреляция, Problems.
+- Долговременное хранение и UI.
+
+---
+
+## 4. Логическая модель данных
+
+### 4.1. Сущности
+
+```
+tenants (опционально, фаза 3)
+  └── hosts
+        └── events (партиции по occurred_at)
+  └── problems
+        └── problem_events (M:N)
+  └── notification_rules
+  └── notification_log
+  └── users
+  └── audit_log
+  └── api_keys (hash)
+```
+
+### 4.2. Ключевые поля
+
+**hosts**
+
+- `id`, `agent_instance_id` (unique), `hostname`, `display_name`
+- `os_family`, `os_version`, `product` (`ssh-monitor` | `rdp-login-monitor`)
+- `use_sac_mode`, `last_seen_at`, `tags[]`
+
+**events**
+
+- `id`, `event_id` (UUID от агента, unique), `host_id`
+- `occurred_at`, `received_at`
+- `category`, `type`, `severity`
+- `title`, `summary`, `details` (JSONB), `raw` (JSONB/text)
+- `dedup_key`, `correlation_id`
+
+**problems**
+
+- `id`, `title`, `severity`, `status`
+- `opened_at`, `acknowledged_at`, `resolved_at`
+- `rule_id`, `dedup_key`
+
+---
+
+## 5. API (черновой перечень)
+
+| Метод | Путь | Назначение |
+|-------|------|------------|
+| POST | `/api/v1/events` | Ingest одного события |
+| POST | `/api/v1/events/batch` | Batch (фаза 1.5) |
+| GET | `/health` | Healthcheck |
+| GET | `/api/v1/events` | Список (UI, auth) |
+| GET | `/api/v1/events/{id}` | Карточка |
+| GET | `/api/v1/problems` | Список Problems |
+| PATCH | `/api/v1/problems/{id}` | ack / resolve |
+| GET | `/api/v1/hosts` | Хосты |
+| GET | `/api/v1/dashboards/summary` | Агрегаты для виджетов |
+| GET | `/api/v1/stream/events` | SSE live |
+| POST | `/api/v1/auth/login` | JWT |
+| CRUD | `/api/v1/notification-rules` | Правила (admin) |
+
+OpenAPI — генерируется FastAPI при реализации.
+
+---
+
+## 6. Каталоги репозитория (целевая структура)
+
+```
+security-alert-center/
+  backend/           # FastAPI, models, services
+  frontend/          # Vue SPA
+  deploy/
+    docker-compose.yml
+    nginx/
+    systemd/
+  docs/              # ТЗ, планы (текущая фаза)
+  schemas/           # Копия/ссылка JSON Schema
+```
+
+На фазе документации каталоги `backend/` и `frontend/` — заглушки (см. README внутри).
+
+---
+
+## 7. Наблюдаемость SAC
+
+- `GET /health` — для агентов и внешнего мониторинга.
+- Метрики (фаза 2): Prometheus endpoint или textfile.
+- Логирование: каждый ingest (без полного `raw` в info-логах).
+
+---
+
+## 8. См. также
+
+- [TZ.md](TZ.md) — требования
+- [deployment.md](deployment.md) — инфраструктура Ubuntu 24.04
@@ -0,0 +1,195 @@
+# Развёртывание на Ubuntu 24.04
+
+Руководство для эксплуатации SAC. Реализация `deploy/` — в фазе 1; здесь — целевая архитектура развёртывания.
+
+---
+
+## 1. Требования к серверу
+
+| Параметр | Минимум | Рекомендуется |
+|----------|---------|---------------|
+| ОС | Ubuntu 24.04 LTS | Ubuntu 24.04 LTS |
+| CPU | 2 vCPU | 4 vCPU |
+| RAM | 4 GB | 8 GB |
+| Диск | 50 GB SSD | 100+ GB SSD (отдельный том для PostgreSQL) |
+| Сеть | Статический IP или DNS | TLS-сертификат (Let's Encrypt / внутренний CA) |
+
+**Порты:**
+
+| Порт | Назначение |
+|------|------------|
+| 443 | HTTPS (UI + API ingest) |
+| 80 | Редирект на 443 (опционально) |
+
+PostgreSQL **не** публикуется наружу.
+
+---
+
+## 2. Сетевые правила
+
+**Исходящие с агентов:**
+
+- Linux (ssh-monitor) → `https://sac.example.com:443`
+- Windows (RDP-monitor) → тот же URL
+
+**Исходящие с SAC:**
+
+- `api.telegram.org` (если Telegram)
+- SMTP-сервер организации
+
+**Входящие на SAC:**
+
+- 443 от сетей, где расположены агенты и админы UI
+
+---
+
+## 3. Вариант A: Docker Compose (рекомендуется)
+
+Целевая структура (фаза 1):
+
+```
+deploy/
+  docker-compose.yml
+  .env.example
+  nginx/
+    sac.conf
+```
+
+Сервисы:
+
+- `postgres:16`
+- `api` (FastAPI)
+- `worker` (тот же образ, другая command)
+- `nginx` (static + proxy)
+
+### 3.1. Установка Docker
+
+```bash
+sudo apt update
+sudo apt install -y ca-certificates curl
+# Официальная инструкция Docker CE для Ubuntu 24.04
+```
+
+### 3.2. Конфигурация
+
+```bash
+sudo mkdir -p /etc/security-alert-center
+sudo cp deploy/.env.example /etc/security-alert-center/.env
+sudo chmod 600 /etc/security-alert-center/.env
+# Заполнить: POSTGRES_PASSWORD, JWT_SECRET, TELEGRAM_*, SAC_PUBLIC_URL
+```
+
+### 3.3. Запуск
+
+```bash
+cd /opt/security-alert-center/deploy
+sudo docker compose up -d
+sudo docker compose exec api alembic upgrade head
+```
+
+### 3.4. Обновление
+
+```bash
+git pull
+sudo docker compose build
+sudo docker compose up -d
+sudo docker compose exec api alembic upgrade head
+```
+
+---
+
+## 4. Вариант B: Native systemd
+
+Пакеты:
+
+```bash
+sudo apt install -y postgresql nginx python3.12 python3.12-venv
+```
+
+- PostgreSQL: БД `sac`, пользователь `sac`
+- venv в `/opt/security-alert-center/.venv`
+- Units: `sac-api.service`, `sac-worker.service`
+- Static UI в `/var/www/sac/`
+- nginx site `/etc/nginx/sites-available/sac`
+
+Детальные unit-файлы — при реализации фазы 1.
+
+---
+
+## 5. TLS
+
+- Публичный: **certbot** + nginx
+- Внутренний: корпоративный CA, полный chain в nginx
+
+Агенты должны доверять CA (или `SAC_TLS_SKIP_VERIFY=1` только для dev — **запрещено в prod**).
+
+---
+
+## 6. Резервное копирование
+
+### 6.1. Ежедневный pg_dump
+
+```bash
+# /etc/cron.d/sac-backup (пример)
+0 3 * * * postgres pg_dump -Fc sac > /var/backups/sac/sac_$(date +\%Y\%m\%d).dump
+```
+
+Ротация: 14 daily + 4 weekly.
+
+### 6.2. Восстановление (тест раз в месяц)
+
+```bash
+pg_restore -d sac_restored /var/backups/sac/sac_YYYYMMDD.dump
+```
+
+---
+
+## 7. Обслуживание
+
+| Задача | Периодичность |
+|--------|---------------|
+| `unattended-upgrades` security | автоматически |
+| Проверка диска PostgreSQL | еженедельно |
+| Ротация логов nginx/app | logrotate |
+| Проверка `/health` | каждые 5 мин (Uptime Kuma / cron) |
+| Review Problems «хост мёртв» | ежедневно |
+| Тест restore БД | ежемесячно |
+
+---
+
+## 8. Мониторинг самого SAC
+
+- `GET https://sac.example.com/health` → `200`, `"database": "ok"`
+- Алерт если нет ingest с активного хоста &gt; 90 мин (настраивается)
+- Диск &gt; 85% — алерт ОС
+
+---
+
+## 9. Создание API key для хоста
+
+(После реализации UI)
+
+1. Войти как admin → Hosts → Add / Generate API key.
+2. Скопировать ключ в `/etc/ssh-monitor.conf` или RDP-конфиг.
+3. `UseSAC=exclusive`, перезапуск агента.
+4. `--check-sac` на хосте.
+
+---
+
+## 10. Чеклист первого prod-развёртывания
+
+- [ ] Ubuntu 24.04, hostname, DNS A-record
+- [ ] TLS работает
+- [ ] PostgreSQL backup настроен
+- [ ] `.env` не в git, chmod 600
+- [ ] Создан admin-пользователь
+- [ ] Telegram test notification
+- [ ] Тестовый ingest с одного Linux и одного Windows
+- [ ] Firewall: только нужные порты
+
+---
+
+## См. также
+
+- [TZ.md](TZ.md) §5, §9
+- [agent-integration.md](agent-integration.md)
@@ -0,0 +1,45 @@
+# Диаграмма потоков данных (рис. 1 к ТЗ)
+
+Используется в [TZ.md](../TZ.md), раздел 3.  
+В GitLab/GitHub и в VS Code/Cursor с поддержкой Mermaid диаграмма рендерится автоматически.
+
+## Экспорт в PNG/SVG
+
+1. Открыть этот файл в Cursor preview или на https://mermaid.live
+2. Экспортировать как изображение для презентаций
+
+```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
+```
+
+## Режим UseSAC=exclusive
+
+При включённом `UseSAC` стрелки от агентов к Telegram/email **отсутствуют**; доставка пользователю только через блок `NOTIFY` в SAC.
@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://git.kalinamall.ru/PapaTramp/security-alert-center/schemas/event-v1.json",
+  "title": "Security Alert Center Event v1",
+  "description": "Каноническое событие от ssh-monitor или RDP-login-monitor",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "event_id",
+    "occurred_at",
+    "source",
+    "host",
+    "category",
+    "type",
+    "severity",
+    "title",
+    "summary"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "event_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "UUID v4, уникален глобально, для идемпотентности"
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 с offset, время события на хосте"
+    },
+    "source": {
+      "type": "object",
+      "required": ["product", "product_version"],
+      "additionalProperties": false,
+      "properties": {
+        "product": {
+          "type": "string",
+          "enum": ["ssh-monitor", "rdp-login-monitor"]
+        },
+        "product_version": {
+          "type": "string"
+        },
+        "agent_instance_id": {
+          "type": "string",
+          "description": "Стабильный ID установки агента"
+        }
+      }
+    },
+    "host": {
+      "type": "object",
+      "required": ["hostname", "os_family"],
+      "additionalProperties": false,
+      "properties": {
+        "hostname": { "type": "string" },
+        "display_name": { "type": "string" },
+        "fqdn": { "type": "string" },
+        "os_family": {
+          "type": "string",
+          "enum": ["linux", "windows"]
+        },
+        "os_version": { "type": "string" },
+        "ipv4": { "type": "string" },
+        "ipv6": { "type": "string" },
+        "timezone": {
+          "type": "string",
+          "description": "IANA, например Europe/Moscow"
+        }
+      }
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "auth",
+        "privilege",
+        "network",
+        "session",
+        "report",
+        "agent"
+      ]
+    },
+    "type": {
+      "type": "string",
+      "description": "Машиночитаемый тип, см. docs/agent-integration.md",
+      "examples": [
+        "ssh.login.success",
+        "ssh.login.failed",
+        "privilege.sudo.command",
+        "ssh.ip.banned",
+        "ssh.bruteforce.mass",
+        "session.logind.new",
+        "rdp.login.success",
+        "rdp.login.failed",
+        "rdg.connection.success",
+        "report.daily.ssh",
+        "agent.heartbeat",
+        "agent.test"
+      ]
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "warning", "high", "critical"]
+    },
+    "title": {
+      "type": "string",
+      "maxLength": 256
+    },
+    "summary": {
+      "type": "string",
+      "description": "Человекочитаемый текст (как в Telegram сейчас)",
+      "maxLength": 8192
+    },
+    "details": {
+      "type": "object",
+      "description": "Структурированные поля по типу события",
+      "additionalProperties": true
+    },
+    "raw": {
+      "type": "object",
+      "properties": {
+        "format": {
+          "type": "string",
+          "enum": ["journal", "windows_event_xml", "text"]
+        },
+        "payload": {
+          "type": "string",
+          "maxLength": 16384
+        }
+      },
+      "additionalProperties": false
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "maxLength": 64 },
+      "maxItems": 32
+    },
+    "dedup_key": {
+      "type": "string",
+      "maxLength": 512
+    },
+    "correlation_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "fingerprint": {
+      "type": "string",
+      "maxLength": 128
+    },
+    "enrichment": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "attempt_number": { "type": "integer", "minimum": 0 },
+        "threshold": { "type": "integer", "minimum": 0 },
+        "risk_level": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"]
+        },
+        "filtered_out": { "type": "boolean" },
+        "filter_reason": { "type": "string" }
+      }
+    }
+  }
+}
@@ -0,0 +1,96 @@
+# Дорожная карта Security Alert Center
+
+Продуктовые фазы после MVP. Сроки ориентировочные, уточняются после фазы 1.
+
+---
+
+## v0.1 — MVP (ядро SAC)
+
+**Цель:** центр без изменений прод-агентов (тест через curl/mock).
+
+- Ingest API + PostgreSQL
+- Events, Hosts, базовый UI
+- Problems (2 правила)
+- Telegram из SAC
+- 3 виджета dashboard
+- Ubuntu 24.04 deploy
+
+---
+
+## v0.2 — Агенты + UseSAC
+
+**Цель:** production-пилот с `UseSAC=exclusive` на части хостов.
+
+- ssh-monitor: UseSAC, spool, все типы событий
+- RDP-login-monitor: аналог
+- Режимы `dual`, `fallback`
+- Daily reports из SAC
+- Документация миграции с Telegram-only
+
+---
+
+## v0.3 — Операционная зрелость
+
+- `POST /events/batch`
+- Email SMTP из SAC
+- UI: редактор правил уведомлений
+- Maintenance windows (тишина)
+- Retention job + агрегаты по часам
+- Экспорт CSV
+- Redis + выделенный worker
+
+---
+
+## v0.4 — Аналитика и корреляция
+
+- GeoIP / ASN по source IP
+- «Новый IP для пользователя»
+- Корреляция: один IP → SSH + RDP на разных хостах → один Problem
+- Расширенные дашборды (RD Gateway vs RDP, sudo heatmap)
+- Тёмная тема UI
+
+---
+
+## v0.5 — Enterprise
+
+- LDAP / OIDC
+- Multi-tenant (несколько организаций)
+- RBAC расширенный, audit export
+- Prometheus metrics endpoint
+- Webhook CEF/JSON для SIEM
+- HA: документированный cold standby (второй сервер, restore БД)
+
+---
+
+## Не планируется (пока)
+
+- Замена Zabbix для инфраструктурного мониторинга
+- Агент для macOS
+- Мобильное приложение
+
+---
+
+## Зависимости от внешних репо
+
+| Версия SAC | Минимальная версия ssh-monitor | Минимальная версия RDP-monitor |
+|------------|-------------------------------|--------------------------------|
+| v0.1 | — (не требуется) | — |
+| v0.2 | TBD (тег с UseSAC) | TBD |
+| v0.3+ | совместимость schema 1.0 | совместимость schema 1.0 |
+
+При breaking change схемы — `schema_version: 1.1` с поддержкой 1.0 на ingest.
+
+---
+
+## Метрики успеха (KPI)
+
+- Среднее время от события до Telegram &lt; 30 с (p95)
+- 0 потерянных событий при 1 ч недоступности SAC (spool)
+- Снижение сообщений в Telegram на 40%+ за счёт dedup (через 1 мес. exclusive)
+
+---
+
+## См. также
+
+- [work-plan.md](work-plan.md)
+- [TZ.md](TZ.md)
@@ -0,0 +1,154 @@
+# План работ — Security Alert Center
+
+План разработки **после утверждения ТЗ**. Код не пишется до завершения фазы 0.
+
+---
+
+## Фаза 0. Документация и согласование (текущая)
+
+| # | Задача | Статус |
+|---|--------|--------|
+| 0.1 | ТЗ [TZ.md](TZ.md) | ✅ |
+| 0.2 | Архитектура, схема событий, интеграция агентов | ✅ |
+| 0.3 | План работ, roadmap, deployment | ✅ |
+| 0.4 | Согласование ТЗ с заказчиком | ⏳ |
+| 0.5 | Репозиторий на git.kalinamall.ru (создать remote, push) | ⏳ |
+| 0.6 | Multi-root workspace для трёх репо | ⏳ |
+
+**Выход:** утверждённое ТЗ v1.0, тег `docs-v1.0` в git.
+
+---
+
+## Фаза 1. MVP — ядро SAC (оценка: 3–4 недели)
+
+### 1.1. Инфраструктура проекта
+
+| # | Задача | Зависимости |
+|---|--------|-------------|
+| 1.1.1 | Scaffold `backend/` FastAPI, структура пакетов | 0.4 |
+| 1.1.2 | Scaffold `frontend/` Vue 3 + Vite | 0.4 |
+| 1.1.3 | `deploy/docker-compose.yml` (api, postgres, nginx) | 1.1.1 |
+| 1.1.4 | Alembic, первая миграция (hosts, events, users) | 1.1.1 |
+| 1.1.5 | `.env.example`, документация локального dev | 1.1.3 |
+
+### 1.2. Ingest API
+
+| # | Задача |
+|---|--------|
+| 1.2.1 | Модель Event + валидация по JSON Schema |
+| 1.2.2 | `POST /api/v1/events`, auth API key |
+| 1.2.3 | Идемпотентность по `event_id` |
+| 1.2.4 | Авторегистрация host при ingest |
+| 1.2.5 | `GET /health` |
+| 1.2.6 | Unit-тесты ingest |
+
+### 1.3. UI — базовый
+
+| # | Задача |
+|---|--------|
+| 1.3.1 | Auth: login, JWT |
+| 1.3.2 | Страница Events (таблица, фильтры, пагинация) |
+| 1.3.3 | Страница Hosts |
+| 1.3.4 | Карточка события |
+| 1.3.5 | SSE live-лента (последние N) |
+
+### 1.4. Problems (минимум)
+
+| # | Задача |
+|---|--------|
+| 1.4.1 | Модель Problem + 2 встроенных правила (brute SSH, missing heartbeat) |
+| 1.4.2 | UI Problems: список, ack, resolve |
+
+### 1.5. Уведомления из SAC
+
+| # | Задача |
+|---|--------|
+| 1.5.1 | Канал Telegram (настройки в env/БД) |
+| 1.5.2 | Worker: отправка по правилу severity ≥ warning |
+| 1.5.3 | Шаблон сообщения (summary + ссылка на UI) |
+
+### 1.6. Dashboard MVP
+
+| # | Задача |
+|---|--------|
+| 1.6.1 | API агрегатов: events/hour, failed by type |
+| 1.6.2 | UI: 3 виджета (график входов, failed, топ IP) |
+
+### 1.7. Приёмка MVP
+
+| # | Задача |
+|---|--------|
+| 1.7.1 | Чеклист [TZ.md](TZ.md) §9 |
+| 1.7.2 | Развёртывание на тестовом Ubuntu 24.04 |
+| 1.7.3 | Демо с curl / mock-agent |
+
+**Выход фазы 1:** тег `v0.1.0-mvp`, работающий SAC без изменений в прод-агентах.
+
+---
+
+## Фаза 2. Интеграция агентов (оценка: 2–3 недели)
+
+| # | Задача | Репозиторий |
+|---|--------|-------------|
+| 2.1 | `UseSAC`, `send_sac_event`, spool | ssh-monitor |
+| 2.2 | `UseSAC`, `Send-SacEvent`, spool | RDP-login-monitor |
+| 2.3 | `--check-sac`, README | оба |
+| 2.4 | E2E: exclusive на 1 Linux + 1 Windows | все три |
+| 2.5 | Daily report через SAC | SAC + агенты |
+| 2.6 | Режим `fallback` | агенты |
+
+**Выход:** теги `ssh-monitor-x.y`, `rdp-monitor-x.y`, `sac-v0.2.0`.
+
+---
+
+## Фаза 3. Улучшения эксплуатации (оценка: 2–4 недели)
+
+См. [roadmap.md](roadmap.md): batch ingest, email, правила UI, retention job, экспорт CSV, GeoIP, LDAP.
+
+---
+
+## Параллельные потоки
+
+```mermaid
+gantt
+  title План SAC (упрощённо)
+  dateFormat YYYY-MM-DD
+  section Документы
+  Фаза 0 ТЗ           :done, f0, 2026-05-26, 3d
+  section SAC
+  MVP backend+UI      :f1, after f0, 21d
+  section Агенты
+  ssh-monitor SAC     :f2, after f1, 10d
+  RDP-monitor SAC     :f2b, after f1, 10d
+  section Prod
+  Пилот exclusive     :f3, after f2, 7d
+```
+
+---
+
+## Роли (рекомендация)
+
+| Роль | Фокус |
+|------|--------|
+| Backend | API, БД, worker, правила |
+| Frontend | UI, графики, SSE |
+| DevOps | Ubuntu 24.04, nginx, backup |
+| Агенты | ssh-monitor + RDP изменения |
+
+На малой команде — одна person full-stack + выделенное время на агенты.
+
+---
+
+## Definition of Done (общий)
+
+- Код в `main`, проходит lint/test в CI (когда появится).
+- Документация обновлена.
+- Нет секретов в git.
+- Критерии приёмки фазы выполнены.
+
+---
+
+## См. также
+
+- [roadmap.md](roadmap.md) — продуктовые фазы
+- [TZ.md](TZ.md) — требования
@@ -0,0 +1,80 @@
+# Multi-root workspace: три репозитория
+
+Как работать в Cursor над **ssh-monitor**, **RDP-login-monitor** и **security-alert-center** одновременно.
+
+---
+
+## 1. Расположение репозиториев (пример)
+
+| Имя в workspace | Путь (пример Windows) | Remote |
+|-----------------|----------------------|--------|
+| `ssh-monitor` | `D:\Soft\Git\ssh-monitor` | git.kalinamall.ru |
+| `rdp-monitor` | `C:\Users\...\RDP-login-monitor` | git.kalinamall.ru |
+| `security-alert-center` | `C:\Users\papatramp\Projects\security-alert-center` | TBD |
+
+Пути подставьте свои.
+
+---
+
+## 2. Файл workspace
+
+Создайте `security-monitors.code-workspace`:
+
+```json
+{
+  "folders": [
+    {
+      "path": "D:/Soft/Git/ssh-monitor",
+      "name": "ssh-monitor"
+    },
+    {
+      "path": "C:/Users/papatramp/RDP-login-monitor",
+      "name": "rdp-monitor"
+    },
+    {
+      "path": "C:/Users/papatramp/Projects/security-alert-center",
+      "name": "security-alert-center"
+    }
+  ],
+  "settings": {
+    "files.eol": "\n"
+  }
+}
+```
+
+Открыть: **File → Open Workspace from File**.
+
+---
+
+## 3. Порядок работ по фазам
+
+| Фаза | Где править |
+|------|-------------|
+| 0 — ТЗ | `security-alert-center/docs/` |
+| 1 — MVP SAC | `security-alert-center/backend`, `frontend` |
+| 2 — UseSAC | `ssh-monitor`, `RDP-login-monitor` + мелкие правки SAC при необходимости |
+
+---
+
+## 4. Соглашения
+
+- Контракт событий: `security-alert-center/docs/event-schema-v1.json` — **единственный источник истины**.
+- Изменение схемы → обновить ТЗ + версию `schema_version` + оба агента.
+- Коммиты в три репо **раздельные**; связь через теги/версии в README (см. [roadmap.md](roadmap.md)).
+
+---
+
+## 5. Remote для SAC
+
+После создания репозитория на git.kalinamall.ru:
+
+```bash
+git remote add origin https://git.kalinamall.ru/PapaTramp/security-alert-center.git
+git push -u origin main
+```
+
+---
+
+## См. также
+
+- [work-plan.md](work-plan.md) фаза 0.6
@@ -0,0 +1,9 @@
+# Frontend (Vue 3 + Vite)
+
+**Статус:** не реализован. См. [docs/work-plan.md](../docs/work-plan.md) фаза 1.
+
+Планируется:
+
+- Problems, Events, Hosts, Dashboards
+- SSE live-лента
+- Auth JWT
@@ -0,0 +1,167 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "$id": "https://git.kalinamall.ru/PapaTramp/security-alert-center/schemas/event-v1.json",
+  "title": "Security Alert Center Event v1",
+  "description": "Каноническое событие от ssh-monitor или RDP-login-monitor",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "event_id",
+    "occurred_at",
+    "source",
+    "host",
+    "category",
+    "type",
+    "severity",
+    "title",
+    "summary"
+  ],
+  "additionalProperties": false,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "const": "1.0"
+    },
+    "event_id": {
+      "type": "string",
+      "format": "uuid",
+      "description": "UUID v4, уникален глобально, для идемпотентности"
+    },
+    "occurred_at": {
+      "type": "string",
+      "format": "date-time",
+      "description": "ISO 8601 с offset, время события на хосте"
+    },
+    "source": {
+      "type": "object",
+      "required": ["product", "product_version"],
+      "additionalProperties": false,
+      "properties": {
+        "product": {
+          "type": "string",
+          "enum": ["ssh-monitor", "rdp-login-monitor"]
+        },
+        "product_version": {
+          "type": "string"
+        },
+        "agent_instance_id": {
+          "type": "string",
+          "description": "Стабильный ID установки агента"
+        }
+      }
+    },
+    "host": {
+      "type": "object",
+      "required": ["hostname", "os_family"],
+      "additionalProperties": false,
+      "properties": {
+        "hostname": { "type": "string" },
+        "display_name": { "type": "string" },
+        "fqdn": { "type": "string" },
+        "os_family": {
+          "type": "string",
+          "enum": ["linux", "windows"]
+        },
+        "os_version": { "type": "string" },
+        "ipv4": { "type": "string" },
+        "ipv6": { "type": "string" },
+        "timezone": {
+          "type": "string",
+          "description": "IANA, например Europe/Moscow"
+        }
+      }
+    },
+    "category": {
+      "type": "string",
+      "enum": [
+        "auth",
+        "privilege",
+        "network",
+        "session",
+        "report",
+        "agent"
+      ]
+    },
+    "type": {
+      "type": "string",
+      "description": "Машиночитаемый тип, см. docs/agent-integration.md",
+      "examples": [
+        "ssh.login.success",
+        "ssh.login.failed",
+        "privilege.sudo.command",
+        "ssh.ip.banned",
+        "ssh.bruteforce.mass",
+        "session.logind.new",
+        "rdp.login.success",
+        "rdp.login.failed",
+        "rdg.connection.success",
+        "report.daily.ssh",
+        "agent.heartbeat",
+        "agent.test"
+      ]
+    },
+    "severity": {
+      "type": "string",
+      "enum": ["info", "warning", "high", "critical"]
+    },
+    "title": {
+      "type": "string",
+      "maxLength": 256
+    },
+    "summary": {
+      "type": "string",
+      "description": "Человекочитаемый текст (как в Telegram сейчас)",
+      "maxLength": 8192
+    },
+    "details": {
+      "type": "object",
+      "description": "Структурированные поля по типу события",
+      "additionalProperties": true
+    },
+    "raw": {
+      "type": "object",
+      "properties": {
+        "format": {
+          "type": "string",
+          "enum": ["journal", "windows_event_xml", "text"]
+        },
+        "payload": {
+          "type": "string",
+          "maxLength": 16384
+        }
+      },
+      "additionalProperties": false
+    },
+    "tags": {
+      "type": "array",
+      "items": { "type": "string", "maxLength": 64 },
+      "maxItems": 32
+    },
+    "dedup_key": {
+      "type": "string",
+      "maxLength": 512
+    },
+    "correlation_id": {
+      "type": "string",
+      "format": "uuid"
+    },
+    "fingerprint": {
+      "type": "string",
+      "maxLength": 128
+    },
+    "enrichment": {
+      "type": "object",
+      "additionalProperties": true,
+      "properties": {
+        "attempt_number": { "type": "integer", "minimum": 0 },
+        "threshold": { "type": "integer", "minimum": 0 },
+        "risk_level": {
+          "type": "string",
+          "enum": ["low", "medium", "high", "critical"]
+        },
+        "filtered_out": { "type": "boolean" },
+        "filter_reason": { "type": "string" }
+      }
+    }
+  }
+}
@@ -0,0 +1,19 @@
+{
+  "folders": [
+    {
+      "path": "../ssh-monitor",
+      "name": "ssh-monitor"
+    },
+    {
+      "path": "../../RDP-login-monitor",
+      "name": "rdp-monitor"
+    },
+    {
+      "path": ".",
+      "name": "security-alert-center"
+    }
+  ],
+  "settings": {
+    "files.eol": "\n"
+  }
+}