Проверка целостности
1. Назначение
Документ описывает механизмы контроля целостности программных компонентов и конфигурационных файлов платформы Rapeed BI на всех этапах: сборка, доставка, развёртывание, эксплуатация.
Основным инструментом автоматизированной проверки целостности Docker-образов является скрипт verify_digests.py, входящий в состав дистрибутива. Скрипт запрашивает SHA-256 digest каждого образа напрямую у реестра через Docker Registry API v2 и сравнивает с эталонными значениями из файла checksums.lock.
2. Объекты контроля целостности
| Объект | Механизм контроля | Алгоритм |
|---|---|---|
| Docker-образы компонентов | verify_digests.py + checksums.lock | SHA-256 (Docker-Content-Digest) |
| Конфигурационные файлы | Шифрование SOPS/AGE | X25519 + ChaCha20-Poly1305 |
| Дистрибутив (архивы образов) | Image digest при загрузке | SHA-256 |
3. Контроль целостности Docker-образов
Каждый Docker-образ в реестре имеет неизменяемый идентификатор (digest). Digest вычисляется реестром как SHA-256 от манифеста образа. Любое изменение содержимого образа приводит к изменению digest.
3.1. Алгоритм получения digest
Скрипт verify_digests.py получает digest напрямую из реестра через Docker Registry API v2, не требуя скачивания образа:
Docker-Content-Digest, возвращаемый реестром — это авторитетное значение, совпадающее с digest, по которому Docker выполняет docker pull image@sha256:.... Digest не вычисляется локально, а запрашивается у источника.3.2. Реестр образов
| Параметр | Значение |
|---|---|
| Адрес реестра | <адрес-реестра> |
| Протокол | HTTPS |
| Аутентификация | Basic Auth (переменные REGISTRY_USER / REGISTRY_PASS или ~/.docker/config.json) |
| API | Docker Registry HTTP API v2 |
| Неизменяемость digest | Гарантируется Docker Content Trust |
3.3. Перечень контролируемых образов
| Образ | Назначение |
|---|---|
| registry.rapeed.ai/rapeed-frontend | Веб-интерфейс |
| registry.rapeed.ai/rapeed-services-widgets | REST API |
| registry.rapeed.ai/rapeed-services-ids | Аналитическое ядро |
| registry.rapeed.ai/rapeed-services-import-cpp | Импорт данных |
| registry.rapeed.ai/rapeed-microservices-pivot-ms | Сводные таблицы |
| registry.rapeed.ai/rapeed-microservices-ui-settings-ms | Настройки интерфейса |
| registry.rapeed.ai/rapeed-upload | Загрузка файлов |
| registry.rapeed.ai/auth-proxy | WebSocket-аутентификация |
| registry.rapeed.ai/rapeed-keycloak | Управление идентификацией |
| registry.rapeed.ai/rapeed-grafana | Мониторинг |
| registry.rapeed.ai/rapeed-composevector | Сбор логов контейнеров |
Помимо образов из приватного реестра, контролируются также сторонние образы, объявленные в docker-compose.yml: nginx, postgres, grafana/tempo, victoriametrics/*, ghcr.io/google/cadvisor, cr.yandex/mirror/rabbitmq.
3.4. Эталонный файл checksums.lock
Файл checksums.lock содержит зафиксированные digest всех образов, объявленных в docker-compose.yml. Генерируется при подготовке релиза и поставляется вместе с дистрибутивом.
latest и development помечаются предупреждением (WARN): digest записывается в lock-файл для информации, но при проверке (--check) не сравнивается, так как тег не является детерминированным.4. Защита конфигурации
Конфигурационные файлы, содержащие секреты, защищены шифрованием:
| Параметр | Значение |
|---|---|
| Инструмент | Mozilla SOPS |
| Бэкенд шифрования | AGE |
| Алгоритм обмена ключами | X25519 |
| Алгоритм шифрования данных | ChaCha20-Poly1305 |
| Зашифрованный файл | .env.enc |
| Ключ расшифровки | SOPS_AGE_KEY |
4.1. Принцип работы
- В дистрибутиве поставляется только зашифрованный файл
.env.enc - Ключ расшифровки
SOPS_AGE_KEYпередаётся отдельно от дистрибутива - При запуске скрипт установки расшифровывает конфигурацию в память
- Любое изменение зашифрованного файла без ключа приводит к ошибке расшифровки, подмена обнаруживается автоматически
4.2. Верификация
5. Контроль целостности при доставке
Дистрибутив содержит Docker-образы в виде архивов .tgz. Целостность контролируется на каждом этапе:
| Этап | Механизм | Описание |
|---|---|---|
| Сборка (CI/CD) | Docker digest | Образ получает неизменяемый SHA-256 digest при публикации в реестр |
| Фиксация эталона | verify_digests.py --update | Digest всех образов из docker-compose.yml запрашивается у реестра и записывается в checksums.lock |
| Упаковка | crane pull + save | Образ выгружается из реестра с проверкой digest |
| Доставка | Зашифрованный архив | Дистрибутив передаётся как единый пакет, включая checksums.lock |
| Установка | docker load | При загрузке образа Docker проверяет целостность слоёв |
| Верификация у заказчика | verify_digests.py --local | Digest локально загруженных образов сравниваются с checksums.lock через docker inspect; доступ к реестру не требуется |
6. Процедура верификации
6.1. Проверка digest образов у заказчика (основная процедура)
Скрипт verify_digests.py и файл checksums.lock входят в состав дистрибутива. Требования: Python 3.8+, библиотека pyyaml, Docker CLI. Доступ к реестру не требуется.
Шаг 1. Загрузите образы из архивов дистрибутива:
Шаг 2. Запустите проверку целостности:
Скрипт сравнивает digest каждого загруженного образа (через docker inspect) с эталонными значениями из checksums.lock. Сетевые подключения не выполняются.
Ожидаемый результат при успешной проверке:
При обнаружении расхождения:
checksums.lock. Необходимо повторно получить дистрибутив у поставщика и убедиться в его целостности.docker load для всех архивов дистрибутива.6.2. Обновление эталонного файла (выполняется вендором)
Процедура выполняется поставщиком при подготовке нового релиза — после публикации образов в реестр. Заказчику не требуется.
checksums.lock включается в дистрибутив вместе с docker-compose.yml и архивами образов.6.3. Проверка целостности конфигурации
6.4. Справочник кодов статуса verify_digests.py
| Статус | Описание | Действие |
|---|---|---|
| PASS | Digest совпадает с эталоном | — |
| FAIL | Digest изменился — образ подменён или обновлён | Выяснить причину, обновить lock или остановить деплой |
| WARN | Тег недетерминирован (latest, development) | Рекомендуется перейти на версионные теги |
| MISSING | Образ есть в compose, но отсутствует в checksums.lock | Обратиться к поставщику — возможно, устаревший lock-файл |
| ERROR | Образ не найден локально или ошибка docker inspect | Убедиться, что docker load выполнен для всех архивов |
6.5. Коды завершения и автоматизация
Скрипт возвращает код выхода 0 при успехе и 1 при наличии статусов FAIL или ERROR.