Using artifact attestations to establish provenance for builds

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

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

이 문서의 내용

아티팩트 증명을 사용하면 빌드한 소프트웨어에 대해 수정할 수 없는 출처 및 무결성 보장을 생성할 수 있습니다. 따라서 소프트웨어를 사용하는 사용자는 소프트웨어가 빌드된 위치와 방법을 확인할 수 있습니다.

소프트웨어를 사용하여 아티팩트 증명을 생성하는 경우 빌드의 출처를 설정하고 다음 정보가 포함된 암호화 서명된 클레임을 만듭니다.

  • 아티팩트와 연결된 워크플로의 링크입니다.
  • 아티팩트의 리포지토리, 조직, 환경, 커밋 SHA 및 트리거 이벤트입니다.
  • 출처를 설정하는 데 사용되는 OIDC 토큰의 기타 정보입니다. 자세한 내용은 OpenID Connect를 사용한 보안 강화 정보을(를) 참조하세요.

관련 SBOM(소프트웨어 자료 청구서)을 포함하는 아티팩트 증명을 생성할 수도 있습니다. 빌드에 사용되는 오픈 소스 종속성 목록과 빌드를 연결하면 투명성을 보장하고 소비자가 데이터 보호 표준을 준수하도록 할 수 있습니다.

The SLSA framework is an industry standard used to evaluate supply chain security. It is organized into levels. Each level represents an increasing degree of security and trustworthiness for a software supply chain. Artifact attestations by itself provides SLSA v1.0 Build Level 2.

This provides a link between your artifact and its build instructions, but you can take this a step further by requiring builds make use of known, vetted build instructions. A great way to do this is to have your build take place in a reusable workflow that many repositories across your organization share. Reusable workflows can provide isolation between the build process and the calling workflow, to meet SLSA v1.0 Build Level 3. For more information, see Using artifact attestations and reusable workflows to achieve SLSA v1 Build Level 3.

For more information on SLSA levels, see SLSA Security Levels.

To generate artifact attestations, uses Sigstore, which is an open source project that offers a comprehensive solution for signing and verifying software artifacts via attestations.

Public repositories that generate artifact attestations use the Sigstore Public Good Instance. A copy of the generated Sigstore bundle is stored with and is also written to an immutable transparency log that is publicly readable on the internet.

Private repositories that generate artifact attestations use 's Sigstore instance. 's Sigstore instance uses the same codebase as the Sigstore Public Good Instance, but it does not have a transparency log and only federates with Actions.

Generating attestations alone doesn't provide any security benefit, the attestations must be verified for the benefit to be realized. Here are some guidelines for how to think about what to sign and how often:

You should sign:

  • Software you are releasing that you expect people to run gh attestation verify ... on.
  • Binaries people will run, packages people will download, or manifests that include hashes of detailed contents.

You should not sign:

  • Frequent builds that are just for automated testing.
  • Individual files like source code, documentation files, or embedded images.

If you consume software that publishes artifact attestations, you can use the CLI to verify those attestations. Because the attestations give you information about where and how software was built, you can use that information to create and enforce security policies that elevate your supply chain security. For more information, see Verifying artifact attestations with the CLI.

경고

It is important to remember that artifact attestations are not a guarantee that an artifact is secure. Instead, artifact attestations link you to the source code and the build instructions that produced them. It is up to you to define your policy criteria, evaluate that policy by evaluating the content, and make an informed risk decision when you are consuming software.

You can use Actions to generate artifact attestations that establish build provenance for artifacts such as binaries and container images.

To generate an artifact attestation, you must:

When you run your updated workflows, they will build your artifacts and generate an artifact attestation that establishes build provenance. You can view attestations in your repository's Actions tab. For more information, see the attest-build-provenance repository.

  1. In the workflow that builds the binary you would like to attest, add the following permissions.

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

  2. After the step where the binary has been built, add the following step.

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

    The value of the subject-path parameter should be set to the path to the binary you want to attest.

  1. In the workflow that builds the container image you would like to attest, add the following permissions.

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

  2. After the step where the image has been built, add the following step.

    - 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

    The value of the subject-name parameter should specify the fully-qualified image name. For example, ghcr.io/user/app or acme.azurecr.io/user/app. Do not include a tag as part of the image name.

    The value of the subject-digest parameter should be set to the SHA256 digest of the subject for the attestation, in the form sha256:HEX_DIGEST. If your workflow uses docker/build-push-action, you can use the digest output from that step to supply the value. For more information on using outputs, see Actions에 대한 워크플로 구문.

You can generate signed SBOM attestations for workflow artifacts.

To generate an attestation for an SBOM, you must:

  • Ensure you have the appropriate permissions configured in your workflow.
  • Create an SBOM for your artifact. For more information, see anchore-sbom-action in the Marketplace.
  • Include a step in your workflow that uses the attest-sbom action.

When you run your updated workflows, they will build your artifacts and generate an SBOM attestation. You can view attestations in your repository's Actions tab. For more information, see the attest-sbom action repository.

  1. In the workflow that builds the binary you would like to attest, add the following permissions.

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

  2. After the step where the binary has been built, add the following step.

    - name: Generate SBOM attestation
  uses: actions/attest-sbom@v2
  with:
    subject-path: 'PATH/TO/ARTIFACT'
    sbom-path: 'PATH/TO/SBOM'

    The value of the subject-path parameter should be set to the path of the binary the SBOM describes. The value of the sbom-path parameter should be set to the path of the SBOM file you generated.

  1. In the workflow that builds the container image you would like to attest, add the following permissions.

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

  2. After the step where the image has been built, add the following step.

    - 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

    The value of the subject-name parameter should specify the fully-qualified image name. For example, ghcr.io/user/app or acme.azurecr.io/user/app. Do not include a tag as part of the image name.

    The value of the subject-digest parameter should be set to the SHA256 digest of the subject for the attestation, in the form sha256:HEX_DIGEST. If your workflow uses docker/build-push-action, you can use the digest output from that step to supply the value. For more information on using outputs, see Actions에 대한 워크플로 구문.

    The value of the sbom-path parameter should be set to the path to the JSON-formatted SBOM file you want to attest.

You can validate artifact attestations for binaries and container images and validate SBOM attestations using the CLI. For more information, see the attestation section of the CLI manual.

참고 항목

These commands assume you are in an online environment. If you are in an offline or air-gapped environment, see Verifying attestations offline.

To verify artifact attestations for binaries, use the following CLI command.

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

To verify artifact attestations for container images, you must provide the image's FQDN prefixed with oci:// instead of the path to a binary. You can use the following CLI command.

Bash
docker login ghcr.io

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

To verify SBOM attestations, you have to provide the --predicate-type flag to reference a non-default predicate. For more information, see Vetted predicates in the in-toto/attestation repository.

For example, the attest-sbom action currently supports either SPDX or CycloneDX SBOM predicates. To verify an SBOM attestation in the SPDX format, you can use the following CLI command.

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

To view more information on the attestation, reference the --format json flag. This can be especially helpful when reviewing SBOM attestations.

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'