아티팩트 증명을 사용하여 빌드의 출처 설정

아티팩트 증명을 사용하면 소프트웨어가 빌드되는 위치와 방법을 설정하여 빌드의 공급망 보안을 강화할 수 있습니다.

누가 이 기능을 사용할 수 있나요?

아티팩트 증명은 모든 현재 GitHub 계획에 대한 공용 리포지토리에서 사용할 수 있습니다. 브론즈, 실버 또는 골드와 같은 레거시 플랜에서는 사용할 수 없습니다. GitHub Free, GitHub Pro 또는 GitHub Team 플랜을 사용 중인 경우 아티팩트 증명은 퍼블릭 리포지토리에서만 사용할 수 있습니다. 개인 또는 내부 리포지토리에서 아티팩트 증명을 사용하려면 GitHub Enterprise Cloud 계획에 있어야 합니다.

이 문서의 내용

필수 조건

아티팩트 증명 생성을 시작하기 전에 아티팩트 증명이 무엇인지, 언제 사용해야 하는지 이해해야 합니다. 아티팩트 증명을(를) 참조하세요.

빌드의 아티팩트 증명 생성

GitHub Actions을(를) 사용하여 이진 파일 및 컨테이너 이미지와 같은 아티팩트에 대한 빌드 출처를 설정하는 아티팩트 증명을 생성할 수 있습니다.

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

워크플로에 적절한 권한이 구성되어 있는지 확인합니다.
attest-build-provenance 작업을 사용하는 단계를 워크플로에 포함합니다.

업데이트된 워크플로를 실행하면 아티팩트가 빌드되고 빌드 출처를 설정하는 아티팩트 증명이 생성됩니다. 리포지토리의 **작업 **탭에서 증명을 볼 수 있습니다. 자세한 내용은 attest-build-provenance 리포지토리를 참조하세요.

이진 파일의 빌드 출처 생성

증명할 이진 파일을 빌드하는 워크플로에서 다음 권한을 추가합니다.
```
permissions:
  id-token: write
  contents: read
  attestations: write
```
이진 파일이 빌드된 단계 뒤에 다음 단계를 추가합니다.
```
- name: Generate artifact attestation
  uses: actions/attest-build-provenance@v2
  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-build-provenance@v2
  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 요약(sha256:HEX_DIGEST 형식)으로 설정해야 합니다. 워크플로에서 docker/build-push-action을 사용하는 경우 해당 단계의 digest 출력을 사용하여 값을 제공할 수 있습니다. 출력 사용에 대한 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

SBOM(소프트웨어 자료 청구서)의 증명 생성

워크플로 아티팩트의 서명된 SBOM 증명을 생성할 수 있습니다.

SBOM의 증명을 생성하려면 다음을 수행해야 합니다.

워크플로에 적절한 권한이 구성되어 있는지 확인합니다.
아티팩트의 SBOM을 만듭니다. 자세한 내용은 GitHub Marketplace에서 anchore-sbom-action을(를) 참조하세요.
attest-sbom 작업을 사용하는 단계를 워크플로에 포함합니다.

업데이트된 워크플로를 실행하면 아티팩트가 빌드되고 SBOM 증명이 생성됩니다. 리포지토리의 작업 탭에서 증명을 볼 수 있습니다. 자세한 내용은 attest-sbom 작업 리포지토리를 참조하세요.

이진 파일의 SBOM 증명 생성

증명할 이진 파일을 빌드하는 워크플로에서 다음 권한을 추가합니다.
```
permissions:
  id-token: write
  contents: read
  attestations: write
```
이진 파일이 빌드된 단계 뒤에 다음 단계를 추가합니다.
```
- name: Generate SBOM attestation
  uses: actions/attest-sbom@v2
  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-sbom@v2
  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 요약(sha256:HEX_DIGEST 형식)으로 설정해야 합니다. 워크플로에서 docker/build-push-action을 사용하는 경우 해당 단계의 digest 출력을 사용하여 값을 제공할 수 있습니다. 출력 사용에 대한 자세한 내용은 GitHub Actions에 대한 워크플로 구문을(를) 참조하세요.

sbom-path 매개 변수의 값은 증명할 JSON 형식의 SBOM 파일 경로로 설정해야 합니다.

GitHub CLI을(를) 사용하여 아티팩트 증명 확인

GitHub CLI를 사용하여 이진 파일과 컨테이너 이미지에 대한 아티팩트 증명의 유효성을 검사하고 SBOM 증명의 유효성을 검사할 수 있습니다. 자세한 내용은 GitHub CLI 매뉴얼의 attestation 섹션을 참조하세요.

참고 항목

이러한 명령은 사용자가 온라인 환경에 있다고 가정합니다. 오프라인 또는 에어 갭 환경에 있는 경우 오프라인에서 증명 확인을(를) 참조하세요.

이진 파일에 대한 아티팩트 증명 확인

이진 파일의 아티팩트 증명을 확인하려면 다음 GitHub CLI 명령을 사용합니다.

Bash

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

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

컨테이너 이미지에 대한 아티팩트 증명 확인

컨테이너 이미지의 아티팩트 증명을 확인하려면 이진 파일의 경로 대신 oci:// 접두사가 있는 이미지의 FQDN을 제공해야 합니다. 다음 GitHub CLI 명령을 사용할 수 있습니다.

Bash

docker login ghcr.io

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

docker login ghcr.io

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

SBOM에 대한 증명 확인

SBOM 증명을 확인하려면 기본이 아닌 조건자를 참조하는 --predicate-type 플래그를 제공해야 합니다. 자세한 내용은 in-toto/attestation 리포지토리의 조건자를 참조하세요.

예를 들어 이 attest-sbom 작업은 현재 SPDX 또는 CycloneDX SBOM 조건자를 지원합니다. SPDX 형식의 SBOM 증명을 확인하려면 다음 GitHub CLI 명령을 사용할 수 있습니다.

Bash

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

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 증명을 검토할 때 특히 유용할 수 있습니다.

Bash

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'

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'

다음 단계

관련성이 있고 관리하기 쉽도록 증명을 유지하려면 더 이상 필요하지 않은 증명은 삭제해야 합니다. 아티팩트 인증서의 수명 주기 관리을(를) 참조하세요.