Skip to content

Latest commit

 

History

History
86 lines (58 loc) · 15.4 KB

ARCHITECTURE.md

File metadata and controls

86 lines (58 loc) · 15.4 KB

Архитектура

Обзор для оператора: что ставится на сервер, как компоненты связаны и что от этого ожидать в эксплуатации. Версия продукта (сервер+веб) — в файле VERSION, версия агента — в AGENT_VERSION (версионируются раздельно). Установка — docs/install.md и docs/self-hosted-deploy.md.

1. Компоненты

Сервер — один Go-бинарь (монолит), развёртывание — Docker Compose. Агенты ставятся на устройства парка (Windows — MSI, macOS — .pkg, Linux — systemd-юнит через сгенерированный installer-скрипт) и работают как системная служба.

 Устройства парка                        Ваш сервер (docker compose)
┌──────────────────┐                    ┌─────────────────────────────────────┐
│  Агент Windows   │                    │  nginx (web)                        │
│  Агент macOS     │                    │   80  → редирект на 443             │
│  Агент Linux     │                    │         (кроме /downloads/)         │
└────────┬─────────┘                    │  443  → веб-UI + REST API,          │
         │                             │         enrollment, загрузки        │
         │ gRPC + mTLS ──────────────────► server (Go, монолит)              │
         │ :50051                       │  50051 → gRPC агентов (mTLS)        │
         │                             │  8081  → REST API мимо nginx        │
         │ HTTPS (enrollment,           │     │            │                  │
         │ self-update) ────────────────►    │            │                  │
                                        │     ▼            ▼                  │
 Администратор                          │  PostgreSQL   Redis (asynq —       │
┌──────────────────┐   HTTPS :443       │  (данные)     очередь задач)       │
│  Браузер (React) ├────────────────────►                                    │
└──────────────────┘                    └─────────────────────────────────────┘

Порты:

Порт Наружу Назначение
80 да редирект на 443; исключение — /downloads/ (бинари агентов публичны, установщик сверяет sha256-пин)
443 да веб-интерфейс, REST API, enrollment, /ca.crt, загрузка агентов
50051 да постоянный gRPC-канал агентов (TLS, клиентские сертификаты)
8081 нет — bind 127.0.0.1 REST API напрямую, минуя nginx. /healthz доступен только здесь — nginx его не проксирует
5432 (PostgreSQL) нет — bind 127.0.0.1 данные
Redis нет — только внутри compose-сети очередь доставки задач

Порты и переменные окружения подробно — docs/install.md.

Долговременное состояние живёт в PostgreSQL (named volume postgres_data) и в каталогах хоста certs/, releases/, license/, directory/. Redis — только очередь доставки; источник правды по желаемому состоянию устройств — PostgreSQL.

Две роли в базе, а не одна. Сервер ходит ролью mdm_app (NOSUPERUSER NOBYPASSRLS) — только такая роль подчиняется ROW LEVEL SECURITY, то есть изоляции тенантов; миграции катятся владельцем БД (MIGRATION_DSN), потому что роль без прав не выполнит DDL. Одна роль на оба дела означала бы либо декоративную RLS, либо неработающие миграции. Подробно — docs/self-hosted-deploy.md.

2. Идентичность устройств

Каждый агент имеет клиентский mTLS-сертификат, выданный приватным CA сервера. device_id устройства — это CN сертификата, и только он: сервер не доверяет идентификаторам в теле сообщений. Подменить «своё» устройство на чужое без чужого ключа нельзя.

Регистрация (enrollment): администратор в UI создаёт устройство и получает одноразовый токен (TTL 24 часа, single-use). Агент генерирует ключ локально, отправляет CSR на POST /api/v1/enroll с этим токеном, сервер подписывает сертификат и сам проставляет CN. Приватный ключ устройства сервер не видит. Подробно — docs/enrollment.md.

3. Потоки данных

  • Heartbeat — лёгкий, частый (по умолчанию ~30 с) сигнал «жив» по постоянному gRPC-стриму. По этому же стриму сервер доставляет агенту задачи и команды (запуск скрипта, блокировка и т.д.); доставка идёт через очередь asynq с повторами.
  • Инвентаризация — отдельный, более редкий (по умолчанию раз в 5 минут) и полный отчёт (ОС, железо, серийный номер, установленное ПО, версия агента). Разнесение heartbeat и инвентаризации держит постоянный канал дешёвым при любом размере парка.
  • Результаты скриптов идемпотентны: каждый запуск имеет run_id, повторная отправка того же результата (после обрыва связи) не создаёт дубликатов.
  • Устройство без heartbeat дольше порога AGENT_UNREACHABLE_MINUTES порождает алерт agent_unreachable (с подавлением дребезга от сна/modern standby).
  • Сеанс удалённого стола (Enterprise) идёт по ОТДЕЛЬНОМУ gRPC-соединению, а не по стриму heartbeat: HTTP/2 мультиплексирует стримы одного соединения, и крупные кадры задерживали бы heartbeat. Поток всегда ретранслируется через сервер (агент → сервер → браузер), P2P нет — запись сеанса обязана делать сторона, за которой не наблюдают, а не поднадзорный агент.

Тенант никогда не берётся из тела запроса или из URL: для панели он приходит из claims сессии, для агента выводится из отпечатка его сертификата, для фоновых задач — из строки устройства. Ниже прикладного слоя стоит RLS в Postgres: забытый WHERE даёт ноль строк, а не чужие данные (ADR-6).

4. Автономность агента

Агент не требует постоянной связи с сервером. Скрипт-политики с расписанием исполняются локальным планировщиком (cron-выражения) — по расписанию, даже когда сервер недоступен. В офлайне агент продолжает работать: политики применяются, блокировка экрана держится (офлайн-разблокировка по локально хранимому bcrypt-хешу пароля), результаты и события досылаются при восстановлении связи. При реконнекте агент синхронизирует политики и desired-состояние (например, блокировку) с сервером.

5. Обновления

Каналы обновлений. У группы устройств есть канал (stable по умолчанию, beta), у релиза — тоже. Канареечная выкатка это группа на beta, а не отдельная сущность: обкатали на ней — перевели релиз в stable. Два правила, которые видно только в поведении: beta — надмножество stable (канарейка не может оказаться старее парка), а устройство в нескольких группах разрешает канал по максимуму. Это нужно до роста парка: self-update сам не откатывается, а anti-rollback запрещает движение назад — один плохой билд, уехавший на тысячу машин, чинится только новой версией вперёд.

Агенты обновляются сами: периодически (по умолчанию раз в 6 часов) запрашивают манифест релиза, сверяют sha256 и Ed25519-подпись манифеста публичным ключом релиза (агент получает его при enroll по доверенному каналу; сборки по умолчанию универсальные, без вшитого ключа — без валидной подписи обновление не применяется), атомарно заменяют себя и перезапускаются. Даунгрейд невозможен (anti-rollback floor); битый релиз чинится только версией вперёд. Приватный ключ подписи (release_ed25519.pem) генерируется при установке и уникален для вашей инсталляции. Его потеря не оставляет парк навсегда без обновлений: новый ключ раздаётся через RELEASE_PUBKEY в .env.prod и переэнроллмент — уже развёрнутые устройства подхватят его при переустановке/переэнроллменте, а бинарь остаётся универсальным (подробно — docs/operations.md). Подробно — docs/self-update.md.

Сервер обновляется скриптом update.sh: бэкап БД → git pull → пересборка. Миграции схемы накатывает отдельный fail-closed migrate-сервис до старта сервера: если миграция не прошла, сервер не стартует на несовместимой схеме. Down-миграций нет — откат только из бэкапа, который update.sh делает автоматически перед каждым обновлением.

6. Модель безопасности

Коротко: mTLS на всём канале агентов (сервер требует клиентский сертификат, идентичность = сертификат); веб — HTTPS с httpOnly-cookie-сессиями (JWT, TTL 8 ч, инвалидация при смене пароля) и RBAC на две роли (it_admin — всё, viewer — только чтение, проверка на сервере, не только в UI); все мутации пишутся в журнал аудита с настраиваемым retention. Подробности, границы модели угроз и процесс сообщения об уязвимостях — SECURITY.md.

7. Open-core

Free-сборка (то, что собирает этот репозиторий по умолчанию) — полный операционный MDM: инвентаризация, скрипты (разовые и по расписанию), группы, политики ПО, алерты, блокировка устройств, вывод из эксплуатации, удалённая перезагрузка, владельцы устройств, аудит, RBAC, API-токены, конфигурация-как-код (CLI routineops), каналы обновлений и self-update, интерфейс на русском и английском.

Enterprise-функции собираются отдельным build-tag и в Free-сборку не входят: FileVault-эскроу и блокировка, синхронизация каталога LDAP/AD с авто-привязкой владельца, SSO (OIDC и SAML), MFA/TOTP, SCIM-провизионинг, выгрузка журнала в SIEM, tamper-evident аудит, сканирование ПО на CVE, удалённый рабочий стол, лицензионное ядро.

Изоляция тенантов (tenant_id + RLS) живёт в схеме и в общем коде обеих редакций, а не за build-tag: это механизм безопасности, а «безопасность не продаётся». Инсталляция без Enterprise просто работает в одном тенанте по умолчанию.

🔴 Гейт РЕДАКЦИИ, а не лицензии. У части фич (SCIM, SAML, SIEM, CVE, удалённый стол) в открытой сборке нет самих файлов — не «ручка отвечает отказом», а «ручки нет в сборке». Разница принципиальная: выключенную проверку в открытом коде снимают форком за одну строку, отсутствующий код форком не появляется. Там, где заглушка всё же остаётся (каталог LDAP, SSO по OIDC), она отвечает 501/409, а не притворяется работающей. Free не деградирует без enterprise — это независимо работающий продукт, а не демо.