アーティファクトの構成証明を使用して構築の実績を確立する

アーティファクト構成証明を使用すると、ソフトウェアが構築された場所と方法を確立し、構築のサプライ チェーンのセキュリティを強化できます。

この機能を使用できるユーザーについて

アーティファクト構成証明は、現在のすべての GitHub プランのパブリック リポジトリで使用できます。 ブロンズ、シルバー、ゴールドなどの従来のプランでは使用できません。 GitHub Free、GitHub Pro、または GitHub Team プランを利用している場合、成果物の構成証明はパブリック リポジトリでのみ使用できます。 プライベートまたは内部リポジトリでアーティファクト構成証明を使用するには、GitHub Enterprise Cloud プランを利用している必要があります。

この記事の内容

アーティファクト構成証明について

構成証明を使用することで、ビルドするソフトウェアに対して検証不可能な証明と整合性の保証を作成できます。 さらに、ソフトウェアを使用するユーザーは、ソフトウェアがビルドされた場所と方法の確認ができます。

ソフトウェアで成果物の構成証明を生成する場合は、ビルドの実績を確立し、次の情報など暗号署名付き要求を作成します。

  • アーティファクトに関連付けられているワークフローへのリンク。
  • リポジトリ、組織、環境、コミット SHA、およびアーティファクトのトリガー イベント。
  • 証明の確立に使用する OIDC トークンからのその他の情報。 詳しくは、「OpenID Connect を使ったセキュリティ強化について」をご覧ください。

関連するソフトウェア部品表 (SBOM) を含む構成証明を生成することもできます。 ビルドを、その中で使用されるオープンソースの依存関係の一覧に関連付けることで、透明性は提供され、コンシューマーがデータ保護標準に準拠できるようになります。

アーティファクト構成証明の SLSA レベルについて

SLSA フレームワークは、サプライ チェーンのセキュリティを評価に使用される業界標準です。 これは、レベルに編成されています。 各レベルは、ソフトウェア サプライ チェーンのセキュリティと信頼性の程度を表します。 アーティファクト構成証明自体が、SLSA v1.0 構築レベル 2 を提供します。

これにより、アーティファクトとその構築命令間のリンクが提供されますが、既知の検査済みの構築命令を使用して構築を要求することで、この手順をさらに進めることができます。 これを実現するのに良い方法は、組織全体の多くのリポジトリが共有する再利用可能なワークフローで構築を実行することです。 再利用可能なワークフローは、SLSA v1.0 構築レベル 3 を満たすために、構築プロセスと呼び出し元のワークフローの間で分離を提供できます。 詳しくは、「成果物の構成証明と再利用可能なワークフローを使用して SLSA v1 ビルド レベル 3 を実現する」をご覧ください。

SLSA レベルの詳細については、「SLSA セキュリティ レベル」を参照してください。

アーティファクト構成証明に Sigstore を使用する方法について

アーティファクト構成証明を生成するために、GitHub は Sigstore を使用します。これは、構成証明を介してソフトウェアのアーティファクトに署名して検証するための包括的なソリューションを提供するオープンソース プロジェクトです。

アーティファクト構成証明を生成するパブリック リポジトリ では、Sigstore Public Good Instance が使用されます。 生成された Sigstore バンドルのコピーについては GitHub と共に格納され、インターネット上でパブリックに読み取り可能な不変の透過性ログにも書き込まれます。

アーティファクト構成証明を生成するプライベート リポジトリ では、GitHub の Sigstore インスタンスを使用します。 GitHub の Sigstore インスタンスは Sigstore Public Good Instance と同じコードベースを使用していますが、透過性ログはなく、GitHub Actions とのみフェデレーションします。

証明する内容

構成証明を生成するだけではセキュリティ上の利点はありません。利点を実現するには、構成証明を検証する必要があります。 署名の対象と頻度について検討する方法に関するガイドラインを次に示します。

以下に署名する必要があります。

  • ユーザーが gh attestation verify ... を実行することを期待しているリリース対象のソフトウェア。
  • ユーザーが実行するバイナリ、ユーザーがダウンロードするパッケージ、または詳細な内容のハッシュを含むマニフェスト。

以下には署名しないでください。

  • 自動テスト用の頻繁な構築。
  • ソース コード、ドキュメント ファイル、埋め込みイメージなどの個々のファイル。

アーティファクト構成証明の検証について

アーティファクト構成証明を発行するソフトウェアを使用する場合は、GitHub CLI を使用してそれらの構成証明を確認できます。 構成証明ではソフトウェアの構築場所と方法に関する情報が提供されるため、その情報を使用して、サプライ チェーンのセキュリティを昇格させるセキュリティ ポリシーを作成して適用できます。 詳細については、「GitHub CLI を使用したアーティファクト構成証明の確認」を参照してください。

Warning

アーティファクト構成証明 は、アーティファクトがセキュリティで保護されている保証_ではない_ことに注意することが重要です。 代わりに、アーティファクト構成証明によって、ソース コードとそれらを生成した構築命令にリンクされます。 ポリシーの条件を定義し、コンテンツを評価してそのポリシーを評価して、ソフトウェアを使用する際に情報に基づいたリスクを判断するのは、ユーザーの責任です。

構築のアーティファクト構成証明の生成

GitHub 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@v2
  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@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 CLI で anchore-sbom-action をご覧ください。
  • attest-sbomアクションを使用するステップをワークフローに含めます。

更新されたワークフローを実行すると、アーティファクトが構築され、SBOM 構成証明が生成されます。 構成証明は、リポジトリの [アクション] タブで表示できます。詳細については、attest-sbomアクション リポジトリを参照してください。

バイナリの SBOM 構成証明の生成

  1. 証明するバイナリを構築するワークフローで、次のアクセス許可を追加します。

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

  2. バイナリが構築された手順の後に、次の手順を追加します。

    - name: Generate SBOM attestation
  uses: actions/attest-sbom@v1
  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@v1
  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 セクションをご覧ください。

Note

これらのコマンドは、オンライン環境であることを前提としています。 オフライン環境またはエアギャップ環境の場合は、「オフラインでの構成証明の確認」を参照してください。

バイナリの成果物構成証明を検証する

バイナリのアーティファクト構成証明を確認するには、次の 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'