Docker Content Trust: подпись и проверка Docker-образов

Быстрые ссылки

• Генерация ключей

• Добавление публичного ключа в реестр

• Подпись образов

• Проверка доверенных образов

• Резюме

Короткое определение

Content Trust — механизм Docker для цифровой подписи образов и проверки авторства. Он использует наборы ключей и сервис Notary для хранения и проверки метаданных подписи.

Важно: цифровая подпись подтверждает целостность и происхождение, но не гарантирует безопасность уязвимостей в самом образе.

Генерация ключей

Вам потребуется пара ключей (приватный + публичный) перед началом работы. Ключ можно сгенерировать с помощью Docker CLI или получить от центра сертификации.

Выполните:

docker trust key generate your-name

Вас попросят ввести фразу-пароль (passphrase). Её нужно будет вводить при каждой операции подписи или использования приватного ключа. Для продолжения нажимайте Enter на соответствующих подсказках.

После завершения в каталоге

~/.docker/trust

появятся два файла: приватный ключ и соответствующий публичный ключ. Приватный ключ храните в безопасном месте и ни в коем случае не передавайте третьим лицам. Если вам нужно переместить ключ между машинами, импортируйте приватный ключ в другую установку Docker:

docker trust key load my-key.pem

Важно: сделайте резервную копию приватного ключа и фразы-пароля (в безопасном хранилище), иначе потеря ключа приведёт к невозможности подписывать образы под этой подписью.

Добавление публичного ключа в ваш реестр

Docker Hub по умолчанию поддерживает функциональность docker trust. Для частного реестра потребуется отдельный Notary-сервер, который обрабатывает верификацию подписей при push/pull операций.

Notary состоит из трёх компонентов: сервера, сервиса подписи и базы данных (MySQL). Рекомендуется разворачивать Notary на том же URL, что и ваш реестр, чтобы клиенты автоматически обращались к нему.

Простейший способ запустить Notary для разработки:

git clone https://github.com/theupdateframework/notary.git  
docker-compose up -d

Этот пример использует самоподписанный TLS-сертификат и предназначен только для разработки. Для тестовых клиентов нужно добавить корневой CA-файл fixtures/root-ca.crt в хранилище доверия ОС:

sudo mkdir -p /usr/share/ca-certificates/extra  
sudo cp fixtures/root-ca.crt /usr/share/ca-certificates/extra/notary.crt  
sudo update-ca-certificates

Эти команды скопируют сертификат в системное хранилище и обновят список доверенных центров сертификации.

Для продакшна обязательно включите аутентификацию, чтобы только авторизованные пользователи могли добавлять ключи. При запуске Notary через docker-compose задавайте переменную окружения NOTARY_AUTH, содержащую Base64-encodированные логин и пароль в формате username:password. Пример:

export NOTARY_AUTH=$(echo "username" | base64):$(echo "password" | base64)  
docker-compose up -d

После запуска Notary добавьте публичный ключ для конкретного репозитория. Подписи хранятся на уровне репозитория, что даёт возможность изолировать права для разных образов и делегировать подписания третьим лицам:

docker trust signer add your-key-name registry.example.com/my-image

Вас попросят ввести passphrase ключа. После этого ключ будет зарегистрирован на сервере Notary и станет доступен для проверок.

Важно: права подписанта и делегирование можно настраивать детально — планируйте роль доступа заранее.

Подпись образов

Когда публичный ключ зарегистрирован на реестре, можно подписывать образы. Используется команда:

docker trust sign registry.example.com/my-image:latest

Команда подпишет образ и сразу отправит данные подписи в реестр — дополнительный docker push не требуется. При первом использовании потребуется создать и защитить репозиторный ключ и задать passphrase; следуйте подсказкам.

Если в ваших рабочих процессах уже используется docker push, можно вместо явной docker trust sign включить Content Trust глобально через переменную окружения, чтобы Docker автоматически создавал подписи при пуше:

export DOCKER_CONTENT_TRUST=1  
docker push registry.example.com/my-image:latest

Вы увидите вывод, аналогичный docker trust sign.

Совет по безопасности: используйте отдельные ключи для автоматизированных CI-процессов и для людей. Храните CI-ключи в защищённых секретных хранилищах и регулярно обновляйте их.

Проверка доверенных образов

Переменная окружения DOCKER_CONTENT_TRUST становится критичной при pull: по умолчанию Docker не проверяет подписи. Чтобы принудительно включить проверку:

export DOCKER_CONTENT_TRUST=1  
docker pull registry.example.com/my-image:latest

При включённой проверке Docker обращается к Notary-серверу реестра и сверяет подписи. Если Notary не может предоставить данные доверия, образ считается неподписанным и загрузка будет прервана. Это предотвращает использование образов, которые могли быть опубликованы злоумышленниками под чужим именем.

Docker Enterprise позволяет дополнительно настроить демон, чтобы он не работал с недоверенными образами, уже существующими на хосте. Это важно, если образы попали на систему из tar-архивов или других ненадёжных источников.

Добавьте в /etc/docker/daemon.json:

{
    "content-trust": {
        "mode": "enforced"
    }
}

Затем перезагрузите конфигурацию демона:

systemctl reload docker

Чтобы увидеть текущие подписи для образа, используйте:

docker trust inspect registry.example.com/my-image:latest

Если вы хотите отменить подпись образа и удалить данные доверия, используйте:

docker trust revoke registry.example.com/my-image:latest

Это удалит доверительные метаданные и приведёт к тому, что последующие проверки будут считать образ неподписанным.

Когда система подписи может не помочь

• Подпись подтверждает происхождение, но не гарантирует отсутствие уязвимостей в составе образа. Проверяйте уязвимости отдельно.
• Если злоумышленник получил приватный ключ, он сможет подписывать вредоносные образы от вашего имени — храните ключи в HSM/секретных хранилищах.
• Самоподписанные Notary-серверы уязвимы к ошибкам конфигурации; используйте доверенные CA в продакшне.
• Notary в момент написания может не иметь официального стабильного релиза — учитывайте это в оценке риска.

Альтернативные подходы

• Использовать систему подписей на уровне CI/CD (например, подпись артефактов в GitHub Actions) с хранением публичных ключей в реестре.
• Применять сканирование уязвимостей (SCA) вместе с подписью для более полной цепочки доверия.
• Использовать форматы подписей OCI (например, cosign/notation) как альтернативу Notary — они предлагают иной рабочий процесс и интеграции.

Руководство на практике (мини-методология)

1. Сгенерируйте ключ для каждого человека/CI, кто будет подписывать.
2. Зарегистрируйте публичные ключи на Notary (или эквивалент) для каждого репозитория.
3. Настройте CI так, чтобы при успешном тестировании выполнялся docker trust sign или docker push с DOCKER_CONTENT_TRUST=1.
4. Для pull-операций включите DOCKER_CONTENT_TRUST=1 во всех средах исполнения и добавьте проверку на CI/CD.
5. Периодически ревокируйте ключи при подозрении на компрометацию и обновляйте ключи в реестре.

Чек‑лист ролей

• Администратор реестра:

  • Развернуть Notary (если приватный реестр).
  • Настроить TLS с доверенным CA.
  • Включить аутентификацию и политики доступа.

• Разработчик/Публишер:

  • Сгенерировать приватный ключ и сделать бэкап.
  • Добавить публичный ключ в Notary для нужного репозитория.
  • Подписывать релизы или обеспечить подпись через CI.

• Оператор/DevOps:

  • Включить DOCKER_CONTENT_TRUST в production средах.
  • Контролировать и ревокировать устаревшие ключи.
  • Настроить мониторинг и логирование активности Notary.

Критерии приёмки

• Образ загружается с включенной переменной DOCKER_CONTENT_TRUST и проходит проверку Notary.
• docker trust inspect показывает действительные подписи и корректных подписантов.
• Для каждого публичного релиза ключи зарегистрированы на реестре и доступны только авторизованным подписантам.
• При попытке pull неподписанного образа операция прерывается (при включённой валидации).

Инцидентный сценарий и откат подписи

Сценарий: приватный ключ подписанта скомпрометирован.

Шаги отката:

1. Немедленно откликните (revoke) подписанта на всех соответствующих репозиториях: docker trust revoke : или используйте административные инструменты Notary для удаления ключа.
2. Удалите скомпрометированный публичный ключ из Notary.
3. Сгенерируйте новые ключи для владельца и зарегистрируйте их.
4. Подпишите заново доверенные образы новыми ключами.
5. Проинформируйте команды и инициируйте аудит логов доступа.

Матрица совместимости и советы по миграции

• Docker Hub: поддерживает docker trust «из коробки».
• Частный Registry: требуется Notary (или альтернатива). Планируйте дополнительную операционную нагрузку и CA-инфраструктуру.
• CI/CD: интегрируйте подпись в пайплайны, храните приватные ключи в безопасных хранилищах (Vault, Secrets Manager).

Примечания по безопасности и приватности

• Храните приватные ключи в аппаратных HSM или защищённых секретных хранилищах. Не храните приватные ключи в репозиториях исходного кода.
• Контролируйте доступ к Notary и ведите аудит запросов к сервису.
• Подумайте о политике ротации ключей и об обязательных проверках подписей в production.

Короткое резюме

Docker Content Trust предоставляет механизм подписи Docker-образов и их проверки с помощью ключей и сервиса Notary. Для Docker Hub всё проще — готовая поддержка. Для приватных реестров потребуется настройка Notary и TLS/аутентификации. Обязательно защищайте приватные ключи, интегрируйте подписи в CI и включайте проверку при pull в production средах.

Важно: подпись подтверждает авторство и целостность, но не заменяет сканирование на уязвимости и другие процедуры безопасности.

Ключевые команды (шпаргалка):

• Генерация ключа: docker trust key generate your-name
• Загрузка ключа: docker trust key load my-key.pem
• Добавление подписанта в репозиторий: docker trust signer add your-key-name registry.example.com/my-image
• Подпись образа: docker trust sign registry.example.com/my-image:latest
• Принудительный push с подписью: export DOCKER_CONTENT_TRUST=1 && docker push registry.example.com/my-image:latest
• Pull с проверкой: export DOCKER_CONTENT_TRUST=1 && docker pull registry.example.com/my-image:latest
• Инспекция подписей: docker trust inspect registry.example.com/my-image:latest
• Отзыв подписи: docker trust revoke registry.example.com/my-image:latest

Дополнительно: рассмотрите альтернативы (cosign, notation) если Notary не соответствует требованиям вашей организации по поддержке, функционалу или операционной модели.