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

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

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

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

アーティファクトに関連付けられているワークフローへのリンク。
リポジトリ、組織、環境、コミット 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を参照してください。

バイナリの構築実績の生成

証明するバイナリを構築するワークフローで、次のアクセス許可を追加します。
```
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 CLI で 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@v1
  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@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 コマンドを使用します。

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 コマンドを使用できます。