PapaTramp/security-alert-center
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity
Files
main
security-alert-center/docs/TZ.md
T

16 KiB
Raw Permalink Blame History

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

Security Alert Center (SAC)

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

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

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

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

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

1.2. Цели

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Требования:

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

ssh-monitor:

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

RDP-login-monitor:

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

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

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

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

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

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

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

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

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

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

Детали — architecture.md.

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

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

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

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

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

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

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

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

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

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

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

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

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

Версия Дата Изменения
1.0 2026-05-26 Первоначальная версия ТЗ
Reference in New Issue View Git Blame Copy Permalink