Сборка Docker images¶
Требования этого документа применяются к сборке images приложений в локальной
среде и GitLab CI/CD. Уровни обязательности определены в корневом README.md.
DEP-IMG-001. Многоэтапный Dockerfile¶
Уровень: SHOULD
Применяется к: image, в котором компилируется приложение, устанавливаются зависимости или преобразуются runtime-файлы
Dockerfile следует использовать multi-stage build как минимум с отдельными именованными стадиями сборки и runtime.
Если компиляция, установка build-зависимостей, генерация кода или подготовка
runtime-файлов выполняется внутри Docker build, её следует выполнять в
build-стадии. В runtime-стадию следует копировать только файлы, допустимые по
DEP-IMG-003. Уже собранный артефакт обязательного pipeline MAY использоваться
по DEP-IMG-002 без повторной компиляции в Dockerfile.
Обоснование¶
Разделение стадий является простым способом не переносить инструменты сборки в поставляемый image. Эквивалентный одноэтапный процесс допустим, если состав, происхождение и runtime-полномочия итогового image проверяются независимо.
Проверка¶
- статическая проверка Dockerfile или эквивалентного описания сборки;
- сравнение build- и runtime-стадий либо анализ слоёв одноэтапной сборки;
- проверка отсутствия build tools, credentials и cache в filesystem и слоях итогового image.
Исключения¶
Одноэтапный Dockerfile для image без сборки, установки зависимостей и
преобразования файлов не относится к этому требованию. Иное отклонение должно
обосновать выполнение DEP-IMG-002, DEP-IMG-003, DEP-IMG-006 и
DEP-IMG-007 и отсутствие build tools, credentials и cache в слоях итогового
image.
DEP-IMG-002. Происхождение runtime-файлов¶
Уровень: MUST
Применяется к: файлам, копируемым в runtime image
Компилируемые, генерируемые и собираемые runtime-файлы должны создаваться либо
в стадии Dockerfile, либо как неизменяемый артефакт обязательного pipeline для
того же commit по DEV-BUILD-003. Произвольные файлы локального host не должны
попадать в release image.
Docker build context должен содержать только необходимые исходные файлы и проверенные входные артефакты. Несекретные параметры и secrets должны передаваться через предназначенные для них механизмы сборки.
Обоснование¶
Проверяемое происхождение устраняет зависимость результата от необъявленного состояния host, не запрещая повторно использовать уже проверенный артефакт.
Проверка¶
- сборка на чистом runner;
- сопоставление commit и digest входного артефакта;
- проверка
.dockerignoreи инструкцийCOPY.
Исключения¶
Метаданные версии и commit SHA MAY вычисляться pipeline и передаваться как несекретные build arguments.
DEP-IMG-003. Минимальное содержимое runtime image¶
Уровень: MUST
Применяется к: финальной стадии Dockerfile
Runtime image должен содержать только приложение, runtime-зависимости и системные файлы, необходимые для его запуска, health checks и корректного завершения.
Исходный код, если он не требуется выбранному runtime, tests, fixtures, compiler, package manager cache, временные файлы, документация сборки и credentials не должны копироваться в финальную стадию.
Обоснование¶
Лишние файлы увеличивают размер image, поверхность атаки и вероятность утечки данных сборки.
Проверка¶
- анализ filesystem итогового image;
- software composition analysis;
- проверка размера и состава слоёв.
Исключения¶
Исходный код интерпретируемого приложения является runtime-файлом, но tests, fixtures и инструменты разработки всё равно должны исключаться.
DEP-IMG-004. Зафиксированные базовые images¶
Уровень: MUST
Применяется к: каждой инструкции FROM
Базовый image должен использовать точную поддерживаемую версию из явно
объявленного registry. В FROM должен быть указан immutable digest либо точный
неплавающий version tag. Выбранные registry и image identifier должны
сохраняться в provenance сборки. Предпочтение утверждённого registry и digest
регулируется DEP-IMG-013.
Build- и runtime-стадии могут использовать разные базовые images, но их runtime, ABI и системные библиотеки должны быть совместимы с собранным артефактом.
Обоснование¶
Mutable tag меняет результат сборки без изменения Git commit и затрудняет аудит уязвимостей.
Проверка¶
- статическая проверка всех
FROMна digest или точный version tag; - проверка источника registry и срока поддержки;
- тест запуска собранного артефакта в runtime-стадии.
Исключения¶
Digest MAY отсутствовать без ADR. Плавающие tags наподобие latest и tags без
точной версии не допускаются.
DEP-IMG-005. Детерминированные системные packages¶
Уровень: SHOULD
Применяется к: установке системных packages в build- и runtime-стадиях
Системные packages следует устанавливать с явно заданными версиями либо из
immutable snapshot repository и без необязательных рекомендаций. Если
репозиторий не обеспечивает такую фиксацию, digest базового image, список
установленных версий и доступный SBOM по DEP-SUP-003 следует использовать для
определения точного состава release. Metadata и временные файлы package manager
следует удалять в той же инструкции слоя, в которой они созданы.
Зависимости приложения регулируются DEV-DEP-001 и не дублируются этим
требованием.
Обоснование¶
Зафиксированные зависимости обеспечивают воспроизводимость и не оставляют служебные данные установки в итоговом слое.
Проверка¶
- review команды установки и источника системных packages;
- повторная сборка одного commit;
- анализ слоёв на cache и metadata package manager.
Исключения¶
Отклонение от фиксации версии допустимо при отсутствии immutable snapshot и не требует ADR, если точный состав release сохраняется в машинно-читаемом перечне packages или SBOM.
DEP-IMG-006. Безопасная передача секретов сборки¶
Уровень: MUST
Применяется к: build credentials и закрытым зависимостям
Если сборке необходим секрет, он должен передаваться через предназначенный для этого ephemeral secret mount механизма сборки и использоваться только в одной инструкции без копирования значения.
Запрещено передавать секреты через ARG, ENV, инструкции COPY, build
context или файлы, сохраняемые в слое. Секрет не должен присутствовать в
Dockerfile, image history, metadata, промежуточном или финальном image.
Обоснование¶
Удаление файла в последующем слое не удаляет его из предыдущего слоя и history.
Проверка¶
- secret scanning Dockerfile, build context и всех стадий image;
- анализ image history;
- контролируемая сборка с тестовым секретом и поиск его значения в layers.
Исключения¶
Не допускаются.
DEP-IMG-007. Безопасная runtime-стадия¶
Уровень: MUST
Применяется к: финальной стадии Dockerfile
Приложение должно запускаться от явно созданного непривилегированного пользователя. Рабочий каталог, entrypoint и необходимые writable paths должны быть заданы явно.
Image не должен полагаться на интерактивный shell, init-систему host или возможность устанавливать packages после запуска. Процесс должен получать сигналы завершения как основной процесс контейнера либо через минимальный init.
Обоснование¶
Явная runtime-модель ограничивает полномочия процесса и обеспечивает предсказуемое завершение контейнера.
Проверка¶
- проверка effective UID/GID;
- тест read-only root filesystem, если приложение его поддерживает;
- тест передачи сигнала и graceful shutdown;
- анализ entrypoint.
Исключения¶
Привилегированный пользователь требует утверждённого ADR с моделью угроз и компенсирующими мерами.
DEP-IMG-011. Метаданные финального image¶
Уровень: MUST
Применяется к: финальной стадии Dockerfile
Image должен содержать OCI labels org.opencontainers.image.title,
org.opencontainers.image.version, org.opencontainers.image.source и
org.opencontainers.image.revision. Последний должен содержать полный Git
commit SHA. Метаданные должны передаваться как несекретные build arguments и
совпадать с проверяемым commit.
Mutable tag не должен использоваться как единственный идентификатор image при развёртывании или передаче между jobs.
Обоснование¶
Метаданные связывают запущенный image с источником, проверками и историей изменений в GitLab.
Проверка¶
- inspection labels финального image;
- сопоставление commit SHA с pipeline;
- проверка deployment manifest на digest или immutable release tag.
Исключения¶
Не допускаются для commit SHA и версии приложения.
DEP-IMG-012. Минимальный базовый runtime image¶
Уровень: SHOULD
Применяется к: финальной стадии Dockerfile
Следует выбирать наименьший утверждённый базовый image, содержащий только необходимые приложению runtime, системные библиотеки, корневые сертификаты и данные часовых поясов.
Для статически скомпонованного приложения следует использовать runtime image без неиспользуемого runtime, shell и package manager. Для интерпретируемого или динамически скомпонованного приложения следует использовать минимальный image, совместимый с требуемыми ABI, расширениями и диагностикой.
Shell и package manager следует включать только при необходимости runtime или утверждённых средств диагностики. Уменьшать размер удалением файлов, необходимых для TLS, локали, часового пояса, health check или graceful shutdown, не следует.
Обоснование¶
Минимальный runtime image сокращает размер загрузки, число уязвимых packages и доступные атакующему инструменты без изменения build-среды.
Проверка¶
- сравнение состава и размера допустимых runtime images;
- software composition analysis финального image;
- тест TLS, времени, health check и graceful shutdown;
- проверка запуска от непривилегированного пользователя.
Исключения¶
Более полный runtime image допускается при документированной несовместимости минимального варианта или необходимости утверждённых средств диагностики.
Связанный ненормативный материал: выбор минимального runtime image.
DEP-IMG-013. Предпочтительные registry и digest¶
Уровень: SHOULD
Применяется к: каждой инструкции FROM
Базовый image следует получать из утверждённого registry и фиксировать по immutable digest. При использовании digest рядом следует указывать читаемый version tag.
Обоснование¶
Проверенный источник уменьшает риск подмены, а digest делает результат сборки устойчивым к изменению tag.
Проверка¶
- проверка registry policy;
- проверка digest и читаемого version tag в
FROM; - сопоставление image identifier с provenance сборки.
Исключения¶
Другой явно объявленный registry и точный неплавающий version tag MAY использоваться без ADR.