Note
構成証明はパブリック ベータ版であり、変更される可能性があります。
アーティファクト構成証明について
構成証明を使用することで、ビルドするソフトウェアに対して検証不可能な証明と整合性の保証を作成できます。 さらに、ソフトウェアを使用するユーザーは、ソフトウェアがビルドされた場所と方法の確認ができます。
ソフトウェアで成果物の構成証明を生成する場合は、ビルドの実績を確立し、次の情報など暗号署名付き要求を作成します。
- アーティファクトに関連付けられているワークフローへのリンク。
- リポジトリ、組織、環境、コミット SHA、およびアーティファクトのトリガー イベント。
- 証明の確立に使用する OIDC トークンからのその他の情報。 詳しくは、「OpenID Connect を使ったセキュリティ強化について」を参照してください。
関連するソフトウェア部品表 (SBOM) を含む構成証明を生成することもできます。 ビルドを、その中で使用されるオープンソースの依存関係の一覧に関連付けることで、透明性は提供され、コンシューマーがデータ保護標準に準拠できるようになります。
アーティファクト構成証明の SLSA レベルについて
SLSA フレームワークは、サプライ チェーンのセキュリティを評価に使用される業界標準です。 これは、レベルに編成されています。 各レベルは、ソフトウェア サプライ チェーンのセキュリティと信頼性の程度を表します。 アーティファクト構成証明は、SLSA v1.0 ビルド レベル 2 を提供します。
アーティファクト構成証明を使用して、SLSA v1.0 ビルド レベル 3 を実現できます。ただし、まず、組織全体でビルド レベル 2 の広範な導入に焦点を当てることを強くお勧めします。 レベル 3 に達するビルドのごく一部を用意することに比べて、ビルド全体で一貫してレベル 2 を満たす方がはるかに優れています。 ビルド レベル 3 を実現するには、再利用可能なワークフローでビルド プロセスを標準化し、再利用可能なワークフローを監査してレベル 3 の要件を満たしていることを確認してから、監査済みの再利用可能なワークフローを要求するように検証ポリシーの更新をお勧めします。
詳細については、SLSA ドキュメントの Provenance セクションを参照してください。
アーティファクト構成証明に Sigstore を使用する方法について
アーティファクト構成証明を生成するために、GitHub は Sigstore を使用します。これは、構成証明を介してソフトウェア成果物に署名して検証するための包括的なソリューションを提供するオープンソース プロジェクトです。
アーティファクト構成証明を生成するパブリック リポジトリ では、Sigstore Public Good Instance が使用されます。 生成された Sigstore バンドルのコピーについては GitHub と共に格納され、インターネット上でパブリックに読み取り可能な不変の透過性ログにも書き込まれます。
アーティファクト構成証明を生成するプライベート リポジトリ では、GitHub の Sigstore インスタンスを使用します。 GitHub の Sigstore インスタンスは Sigstore Public Good Instance と同じコードベースを使用していますが、透過性ログはなく、GitHub Actions とのみフェデレーションします。
アーティファクト構成証明の検証について
アーティファクト構成証明を発行するソフトウェアを使用する場合は、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@v1 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@v1 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
出力を 使用して値を指定できます。 出力の使用について詳しくは、「ギットハブ アクション のワークフロー構文」を参照してください。
ソフトウェア部品表 (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
出力を 使用して値を指定できます。 出力の使用について詳しくは、「ギットハブ アクション のワークフロー構文」を参照してください。パラメーターの
sbom-path
値は、構成証明する JSON 形式の SBOM ファイルへのパスに設定する必要があります。
GitHub CLI を使用したアーティファクト構成証明の検証
バイナリのアーティファクト構成証明を確認するには、次の GitHub CLI コマンドを使用します。
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 コマンドを使用できます。
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
詳しくは、GitHub CLI のマニュアルで attestation
セクションをご覧ください。