feat: backend ingest API, Docker Compose, Ubuntu install guide

- FastAPI: POST /api/v1/events, GET /health, JSON Schema validation - PostgreSQL models, Alembic migration, bootstrap API key - deploy/docker-compose.yml, .env.example - docs/install-ubuntu-24.04.md, updated work-plan (agents first)
2026-05-26 20:21:31 +10:00
parent bf1c1c9fe9
commit 69a232d08a
34 changed files with 1139 additions and 134 deletions
@@ -9,6 +9,7 @@
 | [event-schema-v1.json](event-schema-v1.json) | JSON Schema событий |
 | [work-plan.md](work-plan.md) | План работ по фазам |
 | [roadmap.md](roadmap.md) | Дорожная карта версий |
+| [install-ubuntu-24.04.md](install-ubuntu-24.04.md) | **Подготовка сервера:** Docker, git, firewall, первый запуск |
 | [deployment.md](deployment.md) | Ubuntu 24.04, backup, TLS |
 | [workspace-three-repos.md](workspace-three-repos.md) | Cursor multi-root |

@@ -1,6 +1,9 @@
 # Развёртывание на Ubuntu 24.04

-Руководство для эксплуатации SAC. Реализация `deploy/` — в фазе 1; здесь — целевая архитектура развёртывания.
+Руководство для эксплуатации SAC.
+
+> **Подготовка чистого сервера (установка Docker, git, firewall, первый запуск):**  
+> **[install-ubuntu-24.04.md](install-ubuntu-24.04.md)** — пошаговые команды для администратора.

 ---

@@ -0,0 +1,277 @@
+# Подготовка сервера Ubuntu 24.04 для Security Alert Center
+
+Пошаговое руководство: установка софта на **чистый** или обновлённый хост перед развёртыванием SAC.  
+Целевой способ запуска — **Docker Compose** (рекомендуется). В конце — проверка и ссылка на [deployment.md](deployment.md).
+
+---
+
+## 0. Исходные данные
+
+Запишите до начала:
+
+| Параметр | Пример |
+|----------|--------|
+| FQDN | `sac.kalinin.example` |
+| IP | `10.0.0.50` |
+| Пользователь sudo | `deploy` |
+| Каталог установки | `/opt/security-alert-center` |
+
+---
+
+## 1. Базовая настройка ОС
+
+```bash
+sudo apt update
+sudo apt upgrade -y
+sudo timedatectl set-timezone Europe/Moscow   # или ваша IANA-зона
+timedatectl status
+```
+
+Опционально — hostname:
+
+```bash
+sudo hostnamectl set-hostname sac-01
+```
+
+### 1.1. Firewall (ufw)
+
+```bash
+sudo apt install -y ufw
+sudo ufw default deny incoming
+sudo ufw default allow outgoing
+sudo ufw allow OpenSSH
+sudo ufw allow 80/tcp
+sudo ufw allow 443/tcp
+sudo ufw enable
+sudo ufw status verbose
+```
+
+SSH оставьте только с доверенных подсетей, если политика безопасности требует:
+
+```bash
+# пример: только внутренняя сеть
+# sudo ufw allow from 10.0.0.0/8 to any port 22
+```
+
+---
+
+## 2. Установка Git
+
+```bash
+sudo apt install -y git
+git --version
+```
+
+Клонирование (после доступа к репозиторию):
+
+```bash
+sudo mkdir -p /opt
+sudo git clone https://git.kalinamall.ru/PapaTramp/security-alert-center.git /opt/security-alert-center
+sudo chown -R "$USER:$USER" /opt/security-alert-center
+```
+
+---
+
+## 3. Установка Docker Engine + Compose plugin
+
+Официальный репозиторий Docker для Ubuntu 24.04 (noble):
+
+```bash
+sudo apt install -y ca-certificates curl gnupg
+sudo install -m 0755 -d /etc/apt/keyrings
+curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo gpg --dearmor -o /etc/apt/keyrings/docker.gpg
+sudo chmod a+r /etc/apt/keyrings/docker.gpg
+
+echo "deb [arch=$(dpkg --print-architecture) signed-by=/etc/apt/keyrings/docker.gpg] https://download.docker.com/linux/ubuntu noble stable" | \
+  sudo tee /etc/apt/sources.list.d/docker.list > /dev/null
+
+sudo apt update
+sudo apt install -y docker-ce docker-ce-cli containerd.io docker-buildx-plugin docker-compose-plugin
+```
+
+Добавить пользователя в группу `docker` (перелогиниться после):
+
+```bash
+sudo usermod -aG docker "$USER"
+```
+
+Проверка:
+
+```bash
+docker --version
+docker compose version
+sudo docker run --rm hello-world
+```
+
+---
+
+## 4. Каталоги данных и конфигурации
+
+```bash
+sudo mkdir -p /etc/security-alert-center
+sudo mkdir -p /var/lib/sac/postgres
+sudo mkdir -p /var/backups/sac
+sudo chown -R "$USER:docker" /var/lib/sac
+```
+
+Права на секреты:
+
+```bash
+sudo chmod 750 /etc/security-alert-center
+```
+
+---
+
+## 5. Конфигурация SAC (.env)
+
+```bash
+cd /opt/security-alert-center/deploy
+cp .env.example /etc/security-alert-center/.env
+chmod 600 /etc/security-alert-center/.env
+nano /etc/security-alert-center/.env
+```
+
+Обязательно задать (см. комментарии в `.env.example`):
+
+- `POSTGRES_PASSWORD` — длинный случайный пароль
+- `JWT_SECRET` — `openssl rand -hex 32`
+- `SAC_PUBLIC_URL` — публичный URL, например `https://sac.kalinin.example`
+- `SAC_ADMIN_PASSWORD` — пароль первого admin (только первый запуск)
+
+Симлинк для compose (удобно):
+
+```bash
+ln -sf /etc/security-alert-center/.env /opt/security-alert-center/deploy/.env
+```
+
+---
+
+## 6. Первый запуск SAC
+
+```bash
+cd /opt/security-alert-center/deploy
+docker compose build
+docker compose up -d --build
+docker compose run --rm migrate
+docker compose ps
+```
+
+Проверка health (пока без TLS — с хоста):
+
+```bash
+curl -sS http://127.0.0.1:8000/health | jq .
+```
+
+Ожидается JSON с `"status": "ok"` и `"database": "ok"`.
+
+Тест ingest (подставьте ключ из `.env` — `SAC_BOOTSTRAP_API_KEY` или созданный в UI):
+
+```bash
+curl -sS -X POST http://127.0.0.1:8000/api/v1/events \
+  -H "Authorization: Bearer ВАШ_API_KEY" \
+  -H "Content-Type: application/json" \
+  -d '{
+    "schema_version": "1.0",
+    "event_id": "00000000-0000-4000-8000-000000000001",
+    "occurred_at": "2026-05-26T12:00:00+03:00",
+    "source": {"product": "ssh-monitor", "product_version": "test"},
+    "host": {"hostname": "test-host", "os_family": "linux"},
+    "category": "agent",
+    "type": "agent.test",
+    "severity": "info",
+    "title": "Test",
+    "summary": "Install check"
+  }'
+```
+
+---
+
+## 7. Nginx и TLS (production)
+
+Установка nginx на хосте **или** использование контейнера из `docker compose` (см. `deploy/docker-compose.yml`).
+
+### 7.1. Certbot (Let's Encrypt), если есть публичный DNS
+
+```bash
+sudo apt install -y nginx certbot python3-certbot-nginx
+# после настройки server_name в nginx:
+sudo certbot --nginx -d sac.kalinin.example
+```
+
+### 7.2. Внутренний CA
+
+Используйте корпоративный сертификат в `deploy/nginx/certs/` и смонтируйте в compose.  
+Агентам (ssh-monitor / Windows) нужно доверять этому CA.
+
+---
+
+## 8. Автозапуск после перезагрузки
+
+Docker Compose с `restart: unless-stopped` в `docker-compose.yml` — сервисы поднимутся сами.
+
+Проверка:
+
+```bash
+sudo reboot
+# после входа:
+docker compose -f /opt/security-alert-center/deploy/docker-compose.yml ps
+```
+
+---
+
+## 9. Резервное копирование PostgreSQL
+
+```bash
+sudo tee /etc/cron.d/sac-backup <<'EOF'
+0 3 * * * root docker compose -f /opt/security-alert-center/deploy/docker-compose.yml exec -T postgres pg_dump -U sac -Fc sac > /var/backups/sac/sac_$(date +\%Y\%m\%d).dump
+EOF
+```
+
+Ротация старых дампов — `logrotate` или скрипт по политике (14 daily).
+
+---
+
+## 10. Обновление SAC
+
+```bash
+cd /opt/security-alert-center
+git pull
+cd deploy
+docker compose build
+docker compose up -d
+docker compose exec api alembic upgrade head
+```
+
+---
+
+## 11. Чеклист готовности сервера
+
+- [ ] Ubuntu 24.04, время и timezone верные
+- [ ] ufw: 22 (по политике), 80, 443
+- [ ] Docker и compose работают
+- [ ] Репозиторий в `/opt/security-alert-center`
+- [ ] `/etc/security-alert-center/.env` заполнен, chmod 600
+- [ ] `docker compose up` — все контейнеры healthy
+- [ ] `GET /health` — ok
+- [ ] Тестовый `POST /api/v1/events` — 202
+- [ ] TLS настроен (prod)
+- [ ] cron backup
+
+---
+
+## 12. Устранение неполадок
+
+| Симптом | Действие |
+|---------|----------|
+| `database: error` в /health | `docker compose logs postgres api`, проверить `DATABASE_URL` |
+| 401 на ingest | неверный API key; см. `SAC_BOOTSTRAP_API_KEY` в .env |
+| Нет места на диске | `df -h`, очистка journal/docker: `docker system prune` |
+| Порт 8000 занят | изменить mapping в compose или остановить конфликтующий сервис |
+
+---
+
+## См. также
+
+- [deployment.md](deployment.md) — архитектура, порты, эксплуатация
+- [agent-integration.md](agent-integration.md) — настройка агентов после поднятия SAC
+- [TZ.md](TZ.md) — требования
@@ -6,9 +6,9 @@

 ## v0.1 — MVP (ядро SAC)

-**Цель:** центр без изменений прод-агентов (тест через curl/mock).
+**Цель:** ingest на сервере; агенты в `dual` по мере готовности фазы 1A.

- Ingest API + PostgreSQL
+- Ingest API + PostgreSQL (**в работе — фаза 1B**)
 - Events, Hosts, базовый UI
 - Problems (2 правила)
 - Telegram из SAC
@@ -1,154 +1,103 @@
 # План работ — Security Alert Center

-План разработки **после утверждения ТЗ**. Код не пишется до завершения фазы 0.
+**Актуальный порядок:** сначала подготовка агентов (параллельно с минимальным SAC ingest), затем полный SAC MVP, затем prod rollout `UseSAC=exclusive`.

 ---

-## Фаза 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.
+| 0.1–0.3 | ТЗ, архитектура, схема, deployment | ✅ |
+| 0.5 | Репозиторий git.kalinamall.ru | ✅ |
+| 0.6 | Multi-root workspace | ✅ |

 ---

-## Фаза 1. MVP — ядро SAC (оценка: 3–4 недели)
+## Фаза 1A. Агенты — контракт SAC (параллельно с 1B)

-### 1.1. Инфраструктура проекта
+**Репозитории:** `ssh-monitor`, `RDP-login-monitor`  
+**Прод:** везде `UseSAC=off` по умолчанию.

-| # | Задача | Зависимости |
-|---|--------|-------------|
-| 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 |
+| # | Задача | Статус |
+|---|--------|--------|
+| 1A.1 | Параметры `UseSAC`, `SAC_URL`, `SAC_API_KEY`, spool | ⏳ |
+| 1A.2 | `build_sac_event()` + `send_sac_event()` по schema v1 | ⏳ |
+| 1A.3 | `notify_or_sac()`: off / dual / exclusive / fallback | ⏳ |
+| 1A.4 | `--check-sac` / `Test-SacConnection` | ⏳ |
+| 1A.5 | README агентов | ⏳ |

-### 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 без изменений в прод-агентах.
+**Выход:** на тестовом хосте `dual` шлёт JSON в SAC + Telegram.

 ---

-## Фаза 2. Интеграция агентов (оценка: 2–3 недели)
+## Фаза 1B. SAC — минимальный ingest (текущая разработка)

-| # | Задача | Репозиторий |
-|---|--------|-------------|
-| 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` | агенты |
+| # | Задача | Статус |
+|---|--------|--------|
+| 1B.1 | Scaffold backend FastAPI | 🔄 |
+| 1B.2 | PostgreSQL + Alembic (hosts, events, api_keys) | 🔄 |
+| 1B.3 | `POST /api/v1/events`, `GET /health` | 🔄 |
+| 1B.4 | docker-compose + [install-ubuntu-24.04.md](install-ubuntu-24.04.md) | 🔄 |
+| 1B.5 | Валидация JSON Schema v1 | ⏳ |

-**Выход:** теги `ssh-monitor-x.y`, `rdp-monitor-x.y`, `sac-v0.2.0`.
+**Выход:** сервер Ubuntu принимает события от curl и от агентов в `dual`.

 ---

-## Фаза 3. Улучшения эксплуатации (оценка: 2–4 недели)
+## Фаза 1C. SAC — MVP UI и оповещения

-См. [roadmap.md](roadmap.md): batch ingest, email, правила UI, retention job, экспорт CSV, GeoIP, LDAP.
+| # | Задача |
+|---|--------|
+| 1C.1 | Frontend Vue: Events, Hosts |
+| 1C.2 | Auth JWT, admin bootstrap |
+| 1C.3 | Problems (базовые правила) |
+| 1C.4 | Telegram из SAC |
+| 1C.5 | Dashboard (3 виджета), SSE |
+
+**Выход:** тег `v0.1.0-mvp`.

 ---

-## Параллельные потоки
+## Фаза 2. Пилот и exclusive
+
+| # | Задача |
+|---|--------|
+| 2.1 | E2E: 1 Linux + 1 Windows, `UseSAC=exclusive` |
+| 2.2 | Daily report / heartbeat через SAC |
+| 2.3 | fallback на агентах |
+
+**Выход:** `v0.2.0`.
+
+---
+
+## Фаза 3. Эксплуатация
+
+См. [roadmap.md](roadmap.md).
+
+---
+
+## Gantt (упрощённо)

 ```mermaid
 gantt
-  title План SAC (упрощённо)
+  title SAC — актуальный план
  dateFormat YYYY-MM-DD
  section Документы
-  Фаза 0 ТЗ           :done, f0, 2026-05-26, 3d
+  Фаза 0            :done, 2026-05-26, 1d
  section SAC
-  MVP backend+UI      :f1, after f0, 21d
+  1B ingest+deploy  :active, 2026-05-26, 7d
+  1C UI+notify      :2026-06-02, 14d
  section Агенты
-  ssh-monitor SAC     :f2, after f1, 10d
-  RDP-monitor SAC     :f2b, after f1, 10d
+  1A UseSAC dual     :2026-05-26, 10d
  section Prod
-  Пилот exclusive     :f3, after f2, 7d
+  Пилот exclusive   :2026-06-16, 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) — требования
+- [install-ubuntu-24.04.md](install-ubuntu-24.04.md) — подготовка сервера
+- [roadmap.md](roadmap.md)
+- [TZ.md](TZ.md)