chore(home): mirror from kalinamall (9883e6a) with papatramp URLs

2026-07-14 20:43:52 +10:00
commit ed4e78f6c3
312 changed files with 42790 additions and 0 deletions
@@ -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