Архитектура Security Alert Center

Дополнение к TZ.md. Описывает компоненты, границы и модель данных.

1. Диаграмма компонентов

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 — требования
deployment.md — инфраструктура Ubuntu 24.04

4.8 KiB Raw Permalink Blame History