[GitHub Actions][공급망보안] Docker build-push-action 기본 provenance와 actions/attest 기반 이미지 attestation을 언제 같이 쓰나

IT 리서치 노트

[GitHub Actions][공급망보안] Docker build-push-action 기본 provenance와 actions/attest 기반 이미지 attestation을 언제 같이 쓰나

GitHub Actions로 컨테이너 이미지를 배포할 때 Docker build-push-action의 기본 provenance와 GitHub의 actions/attest 기반 image attestation을 같은 기능으로 취급하면 운영 메모 경계가 자꾸 모호해진다. 2026년 8월 14일 기준 Docker와 GitHub 공식 문서를 다시 보면 기본 provenance는 repo visibility와 output 형식에 따라 자동으로 붙거나 빠질 수 있고, SBOM은 별도 input이 필요하며, actions/attest는 digest와 권한을 갖춘 명시적 step이 필요하다. 이 글은 세 경로를 언제 같이 쓰는 편이 실제 공급망 증거를 더 선명하게 남기는지 정리한다.

목차

1. 개요
2. 어디서 실제로 막히는가
3. 실무에서 적용하는 순서
4. 공식 문서와 예시 화면으로 확인하기
5. 주의사항과 리스크
6. 결론
7. 참고 링크

1. 개요

결론부터 말하면 container image 공급망 증거는 기본 provenance, SBOM, actions/attest 기반 image attestation을 따로 봐야 한다. 기본 provenance는 일부 조건에서 자동으로 붙지만, SBOM은 자동이 아니고, GitHub image attestation은 digest와 권한을 갖춘 별도 step이 필요하다.

즉 첫 질문은 "attestation이 있나"가 아니라 "Docker 기본 provenance가 자동으로 붙는 상황인가, SBOM이 켜졌는가, GitHub attest step으로 별도 signed claim을 남겼는가"다. 세 항목을 따로 적어야 release 증거가 비지 않는다.

2. 어디서 실제로 막히는가

실무에서 자주 섞이는 패턴은 네 가지다. 첫째, public repo라면 기본 provenance가 붙으니 별도 확인을 안 한다. 둘째, sbom input을 안 켠 채 provenance가 있으니 SBOM도 있다고 착각한다. 셋째, load: true나 docker exporter를 쓰면서도 registry provenance가 남을 것이라고 기대한다. 넷째, actions/attest를 붙였는데 permissions나 digest 연결이 빠져 attestation artifact만 실패한다.

Docker Docs는 public repo와 private repo에서 기본 provenance 수준이 다르고, load: true에서는 attestation이 안 붙는다고 설명한다. 같은 문서는 SBOM은 자동이 아니라 sbom input을 켜야 한다고 분명히 적는다. GitHub Docs는 image attestation을 위해 subject-name, subject-digest, push-to-registry와 attestations 권한이 필요하다고 안내한다.

이 셋을 같이 읽으면 build-push-action의 기본 증거와 GitHub artifact attestation이 서로 완전히 같은 것이 아니라는 점이 선명해진다. 하나는 build 결과에 붙는 provenance 증거이고, 다른 하나는 GitHub가 별도로 서명하고 검증할 수 있게 노출하는 attestation 흐름이다.

• 증상: 이미지 빌드는 성공했는데 provenance나 SBOM, attestation 중 일부가 비어 있다.
• 실패: 기본 provenance와 GitHub attestation을 같은 기능으로 적는다.
• 막힘: load: true나 local image store 제약을 빼고 증거 누락을 해석한다.
• 누락: permissions와 digest 연결을 release 메모에 남기지 않는다.

보이는 현상	먼저 볼 값	판단 기준
기본 provenance가 없다	repo visibility, load: true 여부	자동 부착 조건이 깨졌는지 본다
SBOM이 없다	sbom input 또는 별도 SBOM attestation	SBOM 생성 흐름이 명시됐는지 본다
GitHub attestation만 실패한다	permissions, digest, push-to-registry	actions/attest step 입력이 맞는지 본다

3. 실무에서 적용하는 순서

실무 운영 순서는 다섯 단계가 가장 실용적이다. 먼저 repo visibility와 build output 방식을 적는다. 다음으로 build-push-action 기본 provenance가 어떤 수준으로 붙을지 적는다. 세 번째로 sbom input 또는 별도 SBOM attestation 유무를 적는다. 네 번째로 actions/attest step의 permissions, subject-name, digest를 적는다. 마지막으로 registry와 GitHub에서 어떤 경로로 검증할지 남긴다.

1. repo visibility와 build output 방식을 먼저 적는다.
2. 기본 provenance 자동 부착 조건을 확인한다.
3. SBOM 생성 유무를 따로 적는다.
4. actions/attest step의 권한과 digest 연결을 확인한다.
5. registry 검증과 GitHub 검증 경로를 함께 남긴다.

이 순서를 지키면 어떤 증거가 왜 빠졌는지가 빨리 갈린다. 예를 들어 private repo라면 기본 provenance는 mode=min일 수 있고, load: true를 쓰면 registry에 attestation이 안 붙을 수 있다. 반대로 build는 push로 잘 됐는데 GitHub attestation만 비면 permissions나 digest wiring을 먼저 봐야 한다.

또 SBOM은 provenance와 같은 체크가 아니라는 점을 release checklist에 따로 적는 편이 좋다. provenance가 build 출처를 설명한다면 SBOM은 내용물 목록을 설명한다. 소비자 검증 흐름에서는 둘 다 필요할 수 있다.

점검 메모 예시

repo_visibility=public
build_output=push
docker_default_provenance=mode=max
sbom_input=true
actions_attest_permissions=contents,packages,attestations,id-token
subject_digest=${steps.push.outputs.digest}
verify_registry=true
verify_github_attestation=true

이 메모가 있으면 나중에 공급망 검증 요구가 올라왔을 때 어떤 증거는 Docker 쪽, 어떤 증거는 GitHub 쪽에서 찾으면 되는지 곧바로 설명할 수 있다.

4. 공식 문서와 예시 화면으로 확인하기

첫 공식 자료는 Docker build-push-action의 default provenance 설명이다. public repo는 mode=max, private repo는 mode=min, load: true나 docker exporter는 attestation이 안 붙는다는 기본 경계를 먼저 잡아야 한다.

Docker Docs는 build-push-action의 기본 provenance가 repo 공개 여부와 output 형식에 따라 달라진다고 설명한다.

즉 '이미 provenance가 붙겠지'라는 가정은 repo visibility와 output 방식이 달라지는 순간 깨질 수 있다. 기본 provenance가 언제 자동으로 생기고 언제 아예 빠지는지 먼저 고정해야 한다.

두 번째 자료는 SBOM 입력 구간이다. provenance는 일부 경우 자동이지만 SBOM은 자동이 아니라 sbom input을 켜야 한다는 점이 여기서 갈린다.

Docker Docs는 SBOM attestation은 자동이 아니며 build-push-action의 sbom input을 켜야 한다고 설명한다.

이 차이를 놓치면 provenance는 있는데 SBOM은 없는 상태를 release 품질 완료로 오해할 수 있다. provenance와 SBOM은 같은 체크가 아니다.

세 번째 자료는 GitHub의 container image attestation 절차다. 여기서는 actions/attest를 쓰려면 id-token, attestations, packages 권한과 subject-name, subject-digest, push-to-registry가 필요하다고 적고 있다.

GitHub Docs는 container image attestation을 위해 actions/attest step과 전용 권한, digest 입력이 필요하다고 설명한다.

즉 Docker의 기본 provenance와 GitHub의 actions/attest는 서로 완전히 같은 레이어가 아니다. Docker는 build 결과에 붙는 기본 증거를 제공하고, GitHub는 별도 attestation artifact와 linked artifact 흐름을 만든다.

네 번째 자료는 GitHub의 publish-docker-images 예제다. 실제 예제는 build and push 뒤에 actions/attest step을 추가하고, permissions에 attestations: write와 id-token: write를 같이 둔다.

GitHub의 Docker image publishing 예제는 build-push-action 뒤에 actions/attest step을 별도로 붙인다.

이 예제를 보면 기본 provenance만 믿는 흐름과 digest를 받아 별도 attestation을 생성하는 흐름이 어떻게 공존하는지 한 번에 보인다. build step과 attestation step을 같은 것으로 보면 권한 설계 경계가 모호해진다.

다섯 번째 자료는 artifact attestations 개념 문서다. GitHub가 attestation을 provenance와 integrity 보장의 별도 개념으로 설명한다는 점이 중요하다.

GitHub Docs는 artifact attestations를 provenance와 integrity 보장을 제공하는 별도 보안 수단으로 설명한다.

이 설명 덕분에 release runbook을 더 명확히 쓸 수 있다. Docker provenance는 build metadata의 기본 증거이고, GitHub attestation은 소비자가 검증할 수 있는 별도 signed claim으로 다루는 편이 맞다.

실무에서는 세 가지를 한 표에 놓는 편이 가장 이해가 빠르다. 기본 provenance, SBOM, actions/attest 기반 attestation은 생성 조건과 확인 위치가 다르다.

기본 provenance, SBOM, actions/attest 기반 image attestation을 구분한 비교표다.

이미 npm trusted publishing 글과 public 전환과 provenance 조건 글을 읽었다면, 이번 표는 container image 쪽 공급망 증거를 따로 정리하는 허브판이다.

마지막 자료는 release 메모 예시다. repo visibility, build output 방식, sbom 설정, actions/attest 유무, digest 확인 위치를 한 줄로 남기면 나중에 왜 증거가 빠졌는지 재현이 빨라진다.

Docker provenance와 GitHub attestation을 같이 운영할 때 남기면 좋은 릴리스 메모 예시다.

이 메모가 있으면 public repo였는지, load:true를 썼는지, attestation 권한이 빠졌는지 같은 원인을 한 번에 좁힐 수 있다. 공급망 증거도 로그 구조가 있어야 운영이 된다.

5. 주의사항과 리스크

첫 번째 리스크는 기본 provenance가 붙는다고 해서 SBOM과 GitHub attestation까지 자동이라고 생각하는 것이다. 두 번째 리스크는 load: true 같은 output 제약을 빼고 증거 누락을 해석하는 것이다. 세 번째 리스크는 attestation step을 넣고도 권한과 digest 연결을 남기지 않는 것이다.

또 public repo 기본 provenance는 build arg 값을 포함할 수 있다는 Docker 경고도 놓치면 안 된다. build arg로 비밀을 넘겼다면 provenance가 붙는 순간 노출 문제가 더 커질 수 있으므로, secret mount로 바꾸고 rotate 계획을 같이 세워야 한다.

• 기본 provenance, SBOM, GitHub attestation은 같은 체크가 아니다.
• output 방식과 repo visibility가 자동 증거 생성 조건을 바꾼다.
• build arg 비밀은 provenance에 드러날 수 있으므로 별도 조치가 필요하다.

6. 결론

GitHub Actions로 컨테이너 이미지를 배포할 때는 Docker 기본 provenance, SBOM, GitHub actions/attest 기반 image attestation을 따로 적어야 공급망 증거가 선명해진다. 세 경로를 구분해 두면 자동으로 붙는 것과 직접 만들어야 하는 것, registry에서 확인할 것과 GitHub에서 검증할 것을 한 번에 정리할 수 있다.

그리고 단일 registry에서 attestation verify 흐름까지 정리한 뒤 multi-registry publish를 시작했다면, 후속편인 multi-registry digest drift와 attestation verify 분기 글로 이어서 보는 편이 좋다. 345번 글이 provenance·SBOM·image attestation 층을 나누는 앞단이라면, 356번 글은 그다음에 registry별 ref와 registry별 digest와 verify 대상 FQDN을 분리하는 단계다.

• 기본 provenance 자동 조건을 먼저 확인한다.
• SBOM은 별도 입력 또는 별도 attestation으로 본다.
• GitHub image attestation은 digest와 permissions까지 같이 남긴다.

7. 참고 링크

1. https://docs.docker.com/build/ci/github-actions/attestations/
2. https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations
3. https://docs.github.com/en/actions/tutorials/publish-packages/publish-docker-images
4. https://docs.github.com/en/actions/concepts/security/artifact-attestations