From 4f3adc9429c61c0c649b3ee979becc300cb88321 Mon Sep 17 00:00:00 2001 From: PTah Date: Tue, 26 May 2026 19:54:47 +1000 Subject: [PATCH] =?UTF-8?q?docs:=20=D0=A2=D0=97=20v1.0,=20=D0=BF=D0=BB?= =?UTF-8?q?=D0=B0=D0=BD=D1=8B=20=D0=B8=20=D1=81=D1=85=D0=B5=D0=BC=D0=B0=20?= =?UTF-8?q?SAC=20(=D1=84=D0=B0=D0=B7=D0=B0=200)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Security Alert Center — документация без кода приложения. - TZ, архитектура, интеграция агентов (UseSAC) - JSON Schema событий v1, deployment Ubuntu 24.04 - План работ, roadmap, multi-root workspace --- .gitignore | 36 ++++ README.md | 37 ++++ backend/README.md | 11 ++ deploy/README.md | 10 + docs/INDEX.md | 20 ++ docs/TZ.md | 310 +++++++++++++++++++++++++++++++ docs/agent-integration.md | 183 ++++++++++++++++++ docs/architecture.md | 163 ++++++++++++++++ docs/deployment.md | 195 +++++++++++++++++++ docs/diagrams/data-flow.md | 45 +++++ docs/event-schema-v1.json | 167 +++++++++++++++++ docs/roadmap.md | 96 ++++++++++ docs/work-plan.md | 154 +++++++++++++++ docs/workspace-three-repos.md | 80 ++++++++ frontend/README.md | 9 + schemas/event-schema-v1.json | 167 +++++++++++++++++ security-monitors.code-workspace | 19 ++ 17 files changed, 1702 insertions(+) create mode 100644 .gitignore create mode 100644 README.md create mode 100644 backend/README.md create mode 100644 deploy/README.md create mode 100644 docs/INDEX.md create mode 100644 docs/TZ.md create mode 100644 docs/agent-integration.md create mode 100644 docs/architecture.md create mode 100644 docs/deployment.md create mode 100644 docs/diagrams/data-flow.md create mode 100644 docs/event-schema-v1.json create mode 100644 docs/roadmap.md create mode 100644 docs/work-plan.md create mode 100644 docs/workspace-three-repos.md create mode 100644 frontend/README.md create mode 100644 schemas/event-schema-v1.json create mode 100644 security-monitors.code-workspace diff --git a/.gitignore b/.gitignore new file mode 100644 index 0000000..a59b563 --- /dev/null +++ b/.gitignore @@ -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 diff --git a/README.md b/README.md new file mode 100644 index 0000000..8535f7d --- /dev/null +++ b/README.md @@ -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). diff --git a/backend/README.md b/backend/README.md new file mode 100644 index 0000000..27ca78e --- /dev/null +++ b/backend/README.md @@ -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/` — миграции diff --git a/deploy/README.md b/deploy/README.md new file mode 100644 index 0000000..e04a20f --- /dev/null +++ b/deploy/README.md @@ -0,0 +1,10 @@ +# Deploy + +**Статус:** не реализован. См. [docs/deployment.md](../docs/deployment.md). + +Планируется: + +- `docker-compose.yml` +- `nginx/sacc.conf` +- `.env.example` +- `systemd/` unit-файлы (вариант B) diff --git a/docs/INDEX.md b/docs/INDEX.md new file mode 100644 index 0000000..ef7c19d --- /dev/null +++ b/docs/INDEX.md @@ -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 diff --git a/docs/TZ.md b/docs/TZ.md new file mode 100644 index 0000000..2092384 --- /dev/null +++ b/docs/TZ.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 ` или `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 < 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 < 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](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 | Первоначальная версия ТЗ | diff --git a/docs/agent-integration.md b/docs/agent-integration.md new file mode 100644 index 0000000..2d5b0ab --- /dev/null +++ b/docs/agent-integration.md @@ -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 + +{ ... событие по event-schema-v1.json ... } +``` + +### 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 diff --git a/docs/architecture.md b/docs/architecture.md new file mode 100644 index 0000000..1ccf562 --- /dev/null +++ b/docs/architecture.md @@ -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 diff --git a/docs/deployment.md b/docs/deployment.md new file mode 100644 index 0000000..82dcf58 --- /dev/null +++ b/docs/deployment.md @@ -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 с активного хоста > 90 мин (настраивается) +- Диск > 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) diff --git a/docs/diagrams/data-flow.md b/docs/diagrams/data-flow.md new file mode 100644 index 0000000..dea585d --- /dev/null +++ b/docs/diagrams/data-flow.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. diff --git a/docs/event-schema-v1.json b/docs/event-schema-v1.json new file mode 100644 index 0000000..d5d103c --- /dev/null +++ b/docs/event-schema-v1.json @@ -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" } + } + } + } +} diff --git a/docs/roadmap.md b/docs/roadmap.md new file mode 100644 index 0000000..aabff47 --- /dev/null +++ b/docs/roadmap.md @@ -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 < 30 с (p95) +- 0 потерянных событий при 1 ч недоступности SAC (spool) +- Снижение сообщений в Telegram на 40%+ за счёт dedup (через 1 мес. exclusive) + +--- + +## См. также + +- [work-plan.md](work-plan.md) +- [TZ.md](TZ.md) diff --git a/docs/work-plan.md b/docs/work-plan.md new file mode 100644 index 0000000..e6cb593 --- /dev/null +++ b/docs/work-plan.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) — требования diff --git a/docs/workspace-three-repos.md b/docs/workspace-three-repos.md new file mode 100644 index 0000000..fda4b13 --- /dev/null +++ b/docs/workspace-three-repos.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 diff --git a/frontend/README.md b/frontend/README.md new file mode 100644 index 0000000..420b5d0 --- /dev/null +++ b/frontend/README.md @@ -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 diff --git a/schemas/event-schema-v1.json b/schemas/event-schema-v1.json new file mode 100644 index 0000000..d5d103c --- /dev/null +++ b/schemas/event-schema-v1.json @@ -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" } + } + } + } +} diff --git a/security-monitors.code-workspace b/security-monitors.code-workspace new file mode 100644 index 0000000..293e5e5 --- /dev/null +++ b/security-monitors.code-workspace @@ -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" + } +}