PTah
4f3adc9429
Security Alert Center — документация без кода приложения. - TZ, архитектура, интеграция агентов (UseSAC) - JSON Schema событий v1, deployment Ubuntu 24.04 - План работ, roadmap, multi-root workspace
164 lines
4.8 KiB
Markdown
164 lines
4.8 KiB
Markdown
# Архитектура 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
|