아티팩트 증명으로 빌드 출처 확립하기

아티팩트 증명을 사용하면 소프트웨어가 어디서 어떻게 빌드되었는지 확립해 빌드의 공급망 보안을 높일 수 있어요.

출처: 문서

본문

아티팩트 증명을 사용하면 소프트웨어가 어디서 어떻게 빌드되었는지 확립해 빌드의 공급망 보안을 높일 수 있어요.

사전 요구 사항

아티팩트 증명 생성을 시작하기 전에 그것이 무엇이고 언제 사용해야 하는지 이해해야 합니다. Artifact attestations 참고.

빌드에 대한 아티팩트 증명 생성하기

GitHub Actions를 사용해 바이너리나 컨테이너 이미지 같은 아티팩트에 대한 빌드 출처를 확립하는 아티팩트 증명을 생성할 수 있어요.

아티팩트 증명을 생성하려면 다음을 수행해야 합니다:

워크플로우에 적절한 권한이 구성되어 있는지 확인하세요.
워크플로우에 attest 액션을 사용하는 단계를 포함하세요.

업데이트된 워크플로우를 실행하면 아티팩트를 빌드하고 빌드 출처를 확립하는 아티팩트 증명을 생성합니다. 저장소의 Actions 탭에서 증명을 볼 수 있어요. 자세한 내용은 attest 저장소를 참고하세요.

바이너리에 대한 빌드 출처 생성하기

증명하려는 바이너리를 빌드하는 워크플로우에서 다음 권한을 추가하세요.
```
permissions:
  id-token: write
  contents: read
  attestations: write
```
바이너리가 빌드된 단계 뒤에 다음 단계를 추가하세요.
```
- name: Generate artifact attestation
  uses: actions/attest@v4
  with:
    subject-path: 'PATH/TO/ARTIFACT'
```
subject-path 매개변수의 값은 증명하려는 바이너리의 경로로 설정해야 해요.

컨테이너 이미지에 대한 빌드 출처 생성하기

증명하려는 컨테이너 이미지를 빌드하는 워크플로우에서 다음 권한을 추가하세요.
```
permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write
```
이미지가 빌드된 단계 뒤에 다음 단계를 추가하세요.
```
- name: Generate artifact attestation
  uses: actions/attest@v4
  with:
    subject-name: ${{ env.REGISTRY }}/${{ env.IMAGE_NAME }}
    subject-digest: 'sha256:fedcba0...'
    push-to-registry: true
```
subject-name 매개변수의 값은 정규화된 이미지 이름을 지정해야 해요. 예: ghcr.io/user/app 또는 acme.azurecr.io/user/app. 이미지 이름에 태그를 포함하지 마세요.

subject-digest 매개변수의 값은 sha256:HEX_DIGEST 형식으로 증명의 subject에 대한 SHA256 다이제스트로 설정해야 해요. 워크플로우가 docker/build-push-action을 사용한다면 해당 단계의 digest 출력을 사용해 값을 제공할 수 있어요. 출력 사용에 대한 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

SBOM(소프트웨어 자재 명세서)에 대한 증명 생성하기

워크플로우 아티팩트에 대한 서명된 SBOM 증명을 생성할 수 있어요.

SBOM에 대한 증명을 생성하려면 다음을 수행해야 합니다:

워크플로우에 적절한 권한이 구성되어 있는지 확인하세요.
아티팩트에 대한 SBOM을 만드세요. 자세한 내용은 GitHub Marketplace의 anchore-sbom-action을 참고하세요.
워크플로우에 sbom-path 입력으로 attest 액션을 사용하는 단계를 포함하세요.

업데이트된 워크플로우를 실행하면 아티팩트를 빌드하고 SBOM 증명을 생성합니다. 저장소의 Actions 탭에서 증명을 볼 수 있어요. 자세한 내용은 attest 저장소를 참고하세요.

바이너리에 대한 SBOM 증명 생성하기

증명하려는 바이너리를 빌드하는 워크플로우에서 다음 권한을 추가하세요.
```
permissions:
  id-token: write
  contents: read
  attestations: write
```
바이너리가 빌드된 단계 뒤에 다음 단계를 추가하세요.
```
- name: Generate SBOM attestation
  uses: actions/attest@v4
  with:
    subject-path: 'PATH/TO/ARTIFACT'
    sbom-path: 'PATH/TO/SBOM'
```
subject-path 매개변수의 값은 SBOM이 설명하는 바이너리의 경로로 설정해야 해요. sbom-path 매개변수의 값은 생성한 SBOM 파일의 경로로 설정해야 합니다.

컨테이너 이미지에 대한 SBOM 증명 생성하기

증명하려는 컨테이너 이미지를 빌드하는 워크플로우에서 다음 권한을 추가하세요.
```
permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write
```
이미지가 빌드된 단계 뒤에 다음 단계를 추가하세요.
```
- name: Generate SBOM attestation
  uses: actions/attest@v4
  with:
    subject-name: ${{ env.REGISTRY }}/PATH/TO/IMAGE
    subject-digest: 'sha256:fedcba0...'
    sbom-path: 'sbom.json'
    push-to-registry: true
```
subject-name 매개변수의 값은 정규화된 이미지 이름을 지정해야 해요. 예: ghcr.io/user/app 또는 acme.azurecr.io/user/app. 이미지 이름에 태그를 포함하지 마세요.

subject-digest 매개변수의 값은 sha256:HEX_DIGEST 형식으로 증명의 subject에 대한 SHA256 다이제스트로 설정해야 해요. 워크플로우가 docker/build-push-action을 사용한다면 해당 단계의 digest 출력을 사용해 값을 제공할 수 있어요. 출력 사용에 대한 자세한 내용은 Workflow syntax for GitHub Actions를 참고하세요.

sbom-path 매개변수의 값은 증명하려는 JSON 형식 SBOM 파일의 경로로 설정해야 해요.

아티팩트를 연결된 아티팩트 페이지에 업로드하기

증명된 자산을 조직의 연결된 아티팩트(linked artifacts) 페이지에 업로드하는 것을 권장합니다. 이 페이지는 아티팩트의 빌드 기록, 배포 기록, 저장 세부 정보를 표시해요. 이 데이터를 사용해 보안 경고의 우선순위를 정하거나 취약한 아티팩트를 담당 팀, 소스 코드, 빌드 실행에 빠르게 연결할 수 있습니다. 자세한 내용은 About linked artifacts를 참고하세요.

다음 두 조건이 모두 충족되면 attest 액션이 연결된 아티팩트 페이지에 저장 기록을 자동으로 생성해요:

push-to-registry 옵션이 true로 설정됨
액션이 포함된 워크플로우에 artifact-metadata: write 권한이 있음

예시 워크플로우는 Uploading storage and deployment data to the linked artifacts page를 참고하세요.

GitHub CLI로 아티팩트 증명 검증하기

GitHub CLI를 사용해 바이너리와 컨테이너 이미지에 대한 아티팩트 증명을 검증하고 SBOM 증명을 검증할 수 있어요. 자세한 내용은 GitHub CLI 매뉴얼의 attestation 섹션을 참고하세요.

[!NOTE] 이 명령들은 온라인 환경에 있다고 가정합니다. 오프라인 또는 에어갭(air-gapped) 환경이라면 Verifying attestations offline을 참고하세요.

바이너리에 대한 아티팩트 증명 검증하기

바이너리에 대한 아티팩트 증명을 검증하려면 다음 GitHub CLI 명령을 사용하세요.

gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY -R ORGANIZATION_NAME/REPOSITORY_NAME

컨테이너 이미지에 대한 아티팩트 증명 검증하기

컨테이너 이미지에 대한 아티팩트 증명을 검증하려면 바이너리 경로 대신 oci://가 접두사로 붙은 이미지의 FQDN을 제공해야 합니다. 다음 GitHub CLI 명령을 사용할 수 있어요.

docker login ghcr.io

gh attestation verify oci://ghcr.io/ORGANIZATION_NAME/IMAGE_NAME:test -R ORGANIZATION_NAME/REPOSITORY_NAME

SBOM에 대한 증명 검증하기

SBOM 증명을 검증하려면 기본이 아닌 predicate를 참조하도록 --predicate-type 플래그를 제공해야 합니다. 자세한 내용은 in-toto/attestation 저장소의 Vetted predicates를 참고하세요.

예를 들어 attest 액션은 현재 SPDX 또는 CycloneDX SBOM predicate를 지원해요. SPDX 형식의 SBOM 증명을 검증하려면 다음 GitHub CLI 명령을 사용할 수 있습니다.

gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3

증명에 대한 더 많은 정보를 보려면 --format json 플래그를 참조하세요. 특히 SBOM 증명을 검토할 때 유용해요.

gh attestation verify PATH/TO/YOUR/BUILD/ARTIFACT-BINARY \
  -R ORGANIZATION_NAME/REPOSITORY_NAME \
  --predicate-type https://spdx.dev/Document/v2.3 \
  --format json \
  --jq '.[].verificationResult.statement.predicate'

다음 단계

증명을 관련성 있고 관리 가능하게 유지하려면 더 이상 필요하지 않은 증명을 삭제해야 합니다. Managing the lifecycle of artifact attestations 참고.

또한 소비자가 릴리스의 무결성과 출처를 검증하는 데 도움이 되도록 릴리스 증명을 생성할 수 있어요. 자세한 내용은 Immutable releases를 참고하세요.

아티팩트 증명으로 빌드 출처 확립하기