Docker Hardened Image 또는 차트 검증하기
Docker Hardened Image 또는 차트 검증하기
Docker Scout, regctl, cosign을 사용해 Docker Hardened Image(DHI)와 차트의 서명된 attestation을 조회·검증하는 방법과, 누락된 투명성 로그 항목을 처리하는 방법을 알아봐요.
출처: 문서
본문
Docker Hardened Images(DHI)와 차트는 빌드 프로세스, 내용, 보안 체계를 검증하는 서명된 attestation을 포함해요.
DHI 이미지와 차트용 Docker 공개 키는 다음에 게시되어 있어요.
- https://registry.scout.docker.com/keyring/dhi/latest.pub
- https://github.com/docker-hardened-images/keyring
Docker는 Docker Scout를 권장하지만, regctl과 cosign을 사용해 attestation을 조회·검증할 수도 있어요. Docker Scout는 몇 가지 핵심 이점을 제공해요: DHI attestation 구조를 이해하고, 플랫폼을 자동으로 해석하며, 사람이 읽을 수 있는 요약을 제공하고, --verify로 한 단계 검증하며, Docker의 attestation 인프라와 긴밀하게 통합돼요.
[!IMPORTANT]
이미지를 풀하려면 Docker Hardened Images 레지스트리(
dhi.io)에 인증해야 해요. 로그인할 때 Docker ID 자격 증명(Docker Hub에 사용하는 동일한 사용자 이름과 비밀번호)을 사용해요. Docker 계정이 없다면 무료로 계정을 만들어요.인증하려면
docker login dhi.io를 실행해요.
이미지 attestation 검증하기
[!NOTE]
docker scout attest명령을 실행하기 전에 로컬에 풀한 이미지가 원격 이미지와 최신 상태인지 확인해요.docker pull을 실행하면 돼요. 하지 않으면No attestation found가 보일 수 있어요.
사용 가능한 attestation 나열
미러링된 DHI 이미지의 attestation을 나열하려면:
Docker Scout
[!NOTE]
이미지가 로컬 디바이스에 존재한다면 이미지 이름 앞에
registry://접두사를 붙여야 해요. 예를 들어dhi.io/python:3.13대신registry://dhi.io/python:3.13을 사용해요.
$ docker scout attest list dhi.io/<image>:<tag>
이 명령은 SBOM, provenance, 취약점 보고서 등을 포함한 모든 사용 가능한 attestation을 보여줘요.
regctl
먼저 두 레지스트리에 모두 인증해요. 이 예시는 조직 액세스 토큰(OAT)을 사용해 Docker 조직으로 인증해요. OAT는 검증하려는 DHI 저장소에 대해 최소한 풀(pull) 접근 권한이 있어야 해요. 토큰 범위 내의 저장소만 접근 가능해요. 또는 개인 액세스 토큰(PAT)으로 Docker Hub 사용자로 인증할 수도 있는데, 이 경우 read only 접근 권한이 필요해요.
[!WARNING]
다음 예시는 데모 목적으로 자격 증명을 명령줄에 직접 내보내요. 이는 셸 히스토리와 프로세스 목록에 민감한 토큰을 노출해요. 프로덕션 환경에서는 제한된 권한의 파일에서 읽기, 런타임에 로드되는 환경 파일, 시크릿 관리 도구 같은 안전한 방법을 사용해요.
$ export DOCKER_ORG="YOUR_DOCKER_ORG"
$ export DOCKER_OAT="YOUR_DOCKER_OAT"
$ echo $DOCKER_OAT | regctl registry login -u "$DOCKER_ORG" --pass-stdin docker.io
$ echo $DOCKER_OAT | regctl registry login -u "$DOCKER_ORG" --pass-stdin registry.scout.docker.com
그런 다음 --external 플래그로 attestation을 나열해요. DHI 저장소는 이미지 레이어를 dhi.io(미러링된 이미지는 docker.io)에, 서명된 attestation은 registry.scout.docker.com에 저장해요.
$ regctl artifact list docker.io/${DOCKER_ORG}/<image>:<tag> \
--external registry.scout.docker.com/${DOCKER_ORG}/<image> \
--platform linux/amd64
예를 들면:
$ regctl artifact list docker.io/${DOCKER_ORG}/dhi-node:22 \
--external registry.scout.docker.com/${DOCKER_ORG}/dhi-node \
--platform linux/amd64
특정 attestation 가져오기
Docker Scout
특정 attestation을 가져오려면 전체 predicate 유형 URI와 함께 --predicate-type 플래그를 사용해요.
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
dhi.io/<image>:<tag>
[!NOTE]
이미지가 로컬 디바이스에 존재한다면 이미지 이름 앞에
registry://접두사를 붙여야 해요. 예를 들어dhi.io/python:3.13대신registry://dhi.io/python:3.13을 사용해요.
예를 들면:
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
dhi.io/python:3.13
predicate 본문만 가져오려면:
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
--predicate \
dhi.io/<image>:<tag>
regctl
attestation을 나열한 후 Name 필드의 digest를 사용해 전체 attestation 아티팩트를 다운로드해요.
$ regctl artifact get <attestation-digest> > attestation.json
예를 들어 SLSA provenance attestation을 저장하려면:
$ regctl artifact get registry.scout.docker.com/${DOCKER_ORG}/dhi-node@sha256:6cbf803796e281e535f2681de7cd33a1012202610322a50ee745d1bb02ac3c18 > slsa_provenance.json
attestation 검증하기
Docker Scout
Docker Scout로 attestation을 검증하려면 --verify 플래그를 사용해요.
$ docker scout attest get dhi.io/<image>:<tag> \
--predicate-type https://scout.docker.com/sbom/v0.1 --verify
[!NOTE]
이미지가 로컬 디바이스에 존재한다면 이미지 이름 앞에
registry://접두사를 붙여야 해요. 예를 들어dhi.io/node:20.19-debian12대신registry://dhi.io/node:20.19-debian12을 사용해요.
예를 들어 dhi.io/node:20.19-debian12 이미지의 SBOM attestation을 검증하려면:
$ docker scout attest get dhi.io/node:20.19-debian12 \
--predicate-type https://scout.docker.com/sbom/v0.1 --verify
cosign
attestation을 나열하고 Name 필드에서 digest를 얻은 후 cosign으로 검증해요.
$ cosign verify \
<attestation-digest-from-name-field> \
--key https://registry.scout.docker.com/keyring/dhi/latest.pub \
--insecure-ignore-tlog=true
예를 들면:
$ cosign verify \
registry.scout.docker.com/${DOCKER_ORG}/dhi-node@sha256:6cbf803796e281e535f2681de7cd33a1012202610322a50ee745d1bb02ac3c18 \
--key https://registry.scout.docker.com/keyring/dhi/latest.pub \
--insecure-ignore-tlog=true
[!NOTE]
DHI attestation이 개인 고객 정보를 보호하기 위해 공개 Rekor 투명성 로그에 기록되지 않을 수 있으므로
--insecure-ignore-tlog=true플래그가 필요해요. attestation 서명은 여전히 Docker 공개 키로 검증돼요.
누락된 투명성 로그 항목 처리
Docker Scout에서 --verify를 사용하거나 cosign verify를 사용할 때 다음과 같은 오류가 가끔 보일 수 있어요.
ERROR no matching signatures: signature not found in transparency log
이 오류는 Docker Hardened Images가 attestation을 항상 공개 Rekor 투명성 로그에 기록하지 않기 때문에 발생해요. attestation이 개인 사용자 정보(예: 이미지 참조의 조직 네임스페이스)를 포함하는 경우 Rekor에 쓰면 해당 정보가 공개적으로 노출돼요.
Rekor 항목이 없더라도 attestation은 여전히 Docker 공개 키로 서명되며, Rekor 투명성 로그 검사를 건너뛰면 오프라인으로 검증할 수 있어요.
투명성 로그 검사를 건너뛰고 Docker 키로 검증하려면 --skip-tlog 플래그를 사용해요.
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
dhi.io/<image>:<tag> \
--verify --skip-tlog
[!NOTE]
--skip-tlog플래그는 Docker Scout CLI 버전 1.18.2 이상에서만 사용할 수 있어요.이미지가 로컬 디바이스에 존재한다면 이미지 이름 앞에
registry://접두사를 붙여야 해요. 예를 들어dhi.io/python:3.13대신registry://dhi.io/python:3.13을 사용해요.
이것은 Docker가 게시한 공개 키에 대해 서명을 검증하지만 투명성 로그 검사는 무시하는 cosign의 --insecure-ignore-tlog=true 플래그를 사용하는 것과 동일해요.
동등한 cosign 명령 표시
--verify 플래그를 사용하면 이미지 서명을 검증하기 위한 해당 cosign 명령도 함께 출력돼요.
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
--verify \
dhi.io/<image>:<tag>
[!NOTE]
이미지가 로컬 디바이스에 존재한다면 이미지 이름 앞에
registry://접두사를 붙여야 해요. 예를 들어dhi.io/python:3.13대신registry://dhi.io/python:3.13을 사용해요.
예를 들면:
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
--verify \
dhi.io/python:3.13
검증이 성공하면 Docker Scout가 전체 cosign verify 명령을 출력해요.
예시 출력:
v SBOM obtained from attestation, 101 packages found
v Provenance obtained from attestation
v cosign verify ...
[!IMPORTANT]
cosign을 사용할 때는 먼저 DHI 레지스트리와 Docker Scout 레지스트리 양쪽에 모두 인증해야 해요.
예를 들면:
$ docker login dhi.io $ docker login registry.scout.docker.com $ cosign verify ...
패키지 attestation 검증하기
이미지 attestation 외에도 개별 강화 패키지에는 자체 attestation이 있어요. 이 패키지 수준 attestation을 통해 이미지 내 특정 패키지의 provenance와 빌드 정보를 검증할 수 있어요.
이미지 attestation에서 패키지 정보를 추출하고 패키지 수준 attestation을 가져오는 방법은 Package attestations를 봐요.
Docker Scout로 Helm 차트 attestation 검증하기
Docker Hardened Image Helm 차트에는 컨테이너 이미지와 동일한 포괄적인 attestation이 포함돼요. 차트 검증 프로세스는 이미지와 동일하며, 같은 Docker Scout CLI 명령을 사용해요.
사용 가능한 차트 attestation 나열
DHI Helm 차트의 attestation을 나열하려면:
$ docker scout attest list dhi.io/<chart>:<version>
예를 들어 external-dns 차트의 attestation을 나열하려면:
$ docker scout attest list dhi.io/external-dns-chart:1.20.0
이 명령은 SBOM, provenance, 취약점 보고서 등을 포함한 모든 사용 가능한 차트 attestation을 보여줘요.
특정 차트 attestation 가져오기
Helm 차트에서 특정 attestation을 가져오려면 전체 predicate 유형 URI와 함께 --predicate-type 플래그를 사용해요.
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
dhi.io/<chart>:<version>
예를 들면:
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
dhi.io/external-dns-chart:1.20.0
predicate 본문만 가져오려면:
$ docker scout attest get \
--predicate-type https://cyclonedx.org/bom/v1.6 \
--predicate \
dhi.io/<chart>:<version>
Docker Scout로 차트 attestation 검증하기
Docker Scout로 차트 attestation을 검증하려면 --verify 플래그를 사용해요.
$ docker scout attest get dhi.io/<chart>:<version> \
--predicate-type https://scout.docker.com/sbom/v0.1 --verify
예를 들어 external-dns 차트의 SBOM attestation을 검증하려면:
$ docker scout attest get dhi.io/external-dns-chart:1.20.0 \
--predicate-type https://scout.docker.com/sbom/v0.1 --verify
누락된 투명성 로그 항목 처리에서 설명한 것과 같은 --skip-tlog 플래그는 필요할 때 차트 attestation에도 사용할 수 있어요.
사용 가능한 DHI attestation
각 DHI 이미지에 사용 가능한 attestation 목록은 available attestations을, 각 DHI 차트에 사용 가능한 attestation 목록은 Helm chart attestations을 참조해요.
Docker Hub에서 attestation 살펴보기
이미지 변형 탐색 시 attestation을 시각적으로 탐색할 수도 있어요. Attestations 섹션은 각 사용 가능한 attestation을 다음과 함께 나열해요.
- 유형(예: SBOM, VEX)
- Predicate 유형 URI
cosign에서 사용할 digest 참조
이 attestation은 Docker Hardened Image 또는 차트 빌드 프로세스의 일부로 자동 생성·서명돼요.