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

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

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

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

이 문서의 내용

필수 조건

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

빌드의 아티팩트 증명 생성

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

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

  • 워크플로에 적절한 권한이 구성되어 있는지 확인합니다.
  •         [
        `attest-build-provenance` 작업](https://github.com/actions/attest-build-provenance)을 사용하는 단계를 워크플로에 포함합니다.

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

이진 파일의 빌드 출처 생성

  1. 증명할 이진 파일을 빌드하는 워크플로에서 다음 권한을 추가합니다.

    permissions:
  id-token: write
  contents: read
  attestations: write

  2. 이진 파일이 빌드된 단계 뒤에 다음 단계를 추가합니다.

    - name: Generate artifact attestation
  uses: actions/attest-build-provenance@v3
  with:
    subject-path: 'PATH/TO/ARTIFACT'

           `subject-path` 매개 변수의 값은 증명할 이진 파일 경로로 설정해야 합니다.

컨테이너 이미지의 빌드 출처 생성

  1. 증명할 컨테이너 이미지를 빌드하는 워크플로에서 다음 권한을 추가합니다.

    permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write

  2. 이미지가 빌드된 단계 뒤에 다음 단계를 추가합니다.

    - name: Generate artifact attestation
  uses: actions/attest-build-provenance@v3
  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`](https://github.com/docker/build-push-action?tab=readme-ov-file#outputs) 출력을 사용하여 값을 제공할 수 있습니다. 출력 사용에 대한 자세한 내용은 [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs)을(를) 참조하세요.

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

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

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

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

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

이진 파일의 SBOM 증명 생성

  1. 증명할 이진 파일을 빌드하는 워크플로에서 다음 권한을 추가합니다.

    permissions:
  id-token: write
  contents: read
  attestations: write

  2. 이진 파일이 빌드된 단계 뒤에 다음 단계를 추가합니다.

    - 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 증명 생성

  1. 증명할 컨테이너 이미지를 빌드하는 워크플로에서 다음 권한을 추가합니다.

    permissions:
  id-token: write
  contents: read
  attestations: write
  packages: write

  2. 이미지가 빌드된 단계 뒤에 다음 단계를 추가합니다.

    - 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`](https://github.com/docker/build-push-action?tab=readme-ov-file#outputs) 출력을 사용하여 값을 제공할 수 있습니다. 출력 사용에 대한 자세한 내용은 [AUTOTITLE](/actions/using-workflows/workflow-syntax-for-github-actions#jobsjob_idoutputs)을(를) 참조하세요.


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

linked artifacts page에 아티팩트를 업로드

증명된 자산을 조직의 linked artifacts page에 업로드할 것을 추천합니다. 이 페이지에는 아티팩트의 빌드 기록, 배포 레코드 및 스토리지 세부 정보가 표시됩니다. 이 데이터를 사용하여 보안 경고의 우선 순위를 지정하거나 취약한 아티팩트들을 자신의 소유 팀, 소스 코드 및 빌드 실행에 신속하게 연결할 수 있습니다. 자세한 내용은 연동된 아티팩트 개요을(를) 참조하세요.

증명 및 증명-빌드-출처 작업은 둘 다 해당하는 경우 linked artifacts page에 스토리지 레코드를 자동으로 만듭니다.

  • 옵션 push-to-registry이(가) true로 설정됩니다.
  • 작업을 포함하는 워크플로우에 artifact-metadata: write 사용 권한이 있습니다.

예제 워크플로는 스토리지 및 배포 데이터를 linked artifacts page에 업로드합니다.을(를) 참조하세요.

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

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

          **컨테이너 이미지**의 아티팩트 증명을 확인하려면 이진 파일의 경로 대신 `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

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

증명에 대한 자세한 내용을 보려면 --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'

다음 단계

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

또한, 소비자가 릴리스의 무결성 및 출처를 확인하는 데 도움이 되는 릴리스 증명을 생성할 수도 있습니다. 자세한 내용은 변경이 불가능한 릴리스을(를) 참조하세요.