Add Cosign attestation verification

Author: ViacheslavKudinov

VERIFY_ATTESTATIONS.md

@@ -27,17 +27,30 @@ Download the release artifacts first:
 
 ```bash
 version="x.y.z"
-gh release download "v${version}" --repo integrations/terraform-provider-github -p "*.zip"
+gh release download "v${version}" --repo integrations/terraform-provider-github -p "*.zip" --clobber
 ```
 
 To verify the artifact attestations for this project, you can run the following command:
 
 ```bash
-gh attestation verify --repo integrations/terraform-provider-github --source-ref "v${version}"\
-  --signer-workflow integrations/terraform-provider-github/.github/workflows/release.yaml \
+gh attestation verify --repo integrations/terraform-provider-github --source-ref "refs/tags/v${version}"\
+  --signer-workflow integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version} \
   "terraform-provider-github_${version}_darwin_amd64.zip"
 ```
 
+### Verifying all artifacts at once
+
+Alternatively, you can verify all downloaded artifacts with a loop that provides individual status reporting:
+
+```bash
+for artifact in terraform-provider-github_${version}_*.zip; do
+  echo "Verifying: $artifact"
+  gh attestation verify --repo integrations/terraform-provider-github --source-ref "refs/tags/v${version}" \
+    --signer-workflow integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version} \
+    "$artifact" && echo "✓ Verified" || echo "✗ Failed"
+done
+```
+
 ### Using optional flags
 
 The `gh attestation verify` command supports additional flags for more specific verification:
@@ -54,11 +67,11 @@ If you would like to require an artifact attestation to be signed with a specifi
 
 ```bash
 gh attestation verify --owner integrations --signer-workflow \
-  integrations/terraform-provider-github/.github/workflows/release.yaml \
+  integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version} \
   terraform-provider-github_${version}_darwin_amd64.zip
 ```
 
-## Verifying release artifacts with Cosign
+## Verifying checksums file signature with Cosign and checking artifact integrity
 
 > [!WARNING]
 > Not all the releases may have Cosign signature for the checksum files.
@@ -74,15 +87,12 @@ First, install Cosign if you haven't already. See the [installation instructions
 
 ### Verify checksums file
 
-> [!NOTE]
-> Make sure to replace X.Y.Z with the actual release tag you want to verify.
-
 Download the checksums file and its signature bundle:
 
 ```bash
 gh release download v${version} --repo integrations/terraform-provider-github \
   -p "terraform-provider-github_${version}_SHA256SUMS" \
-  -p "terraform-provider-github_${version}_SHA256SUMS.sbom.json.bundle"
+  -p "terraform-provider-github_${version}_SHA256SUMS.sbom.json.bundle" --clobber
 ```
 
 Verify the checksums file signature:
@@ -103,7 +113,7 @@ Download the artifact you want to verify:
 
 ```bash
 gh release download v${version} --repo integrations/terraform-provider-github \
-  -p "terraform-provider-github_${version}_darwin_amd64.zip"
+  -p "terraform-provider-github_${version}_darwin_amd64.zip" --clobber
 ```
 
 Verify the checksum:
@@ -113,3 +123,82 @@ shasum -a 256 -c terraform-provider-github_${version}_SHA256SUMS --ignore-missin
 ```
 
 This will verify that your downloaded artifact matches the signed checksum, confirming its integrity and authenticity.
+
+## Verifying SLSA Provenance Attestations with Cosign
+
+In addition to using the GitHub CLI, you can verify SLSA provenance attestations using Cosign by downloading the attestation and verifying it against your local artifact.
+
+### Prerequisites
+
+1. Install `cosign` for verifying attestations. See the [installation instructions](https://docs.sigstore.dev/cosign/system_config/installation/).
+2. Install `gh` (GitHub CLI) if you haven't already. See the [installation instructions](https://github.com/cli/cli#installation).
+
+### Download and verify attestation
+
+> [!NOTE]
+> Make sure to replace x.y.z with the actual release tag you want to verify.
+
+> [!CAUTION]
+> The attestations are available only for the releases created since the version `v6.9.0` of this project.
+
+First, download the artifact you want to verify:
+
+```bash
+version="x.y.z"
+gh release download "v${version}" --repo integrations/terraform-provider-github \
+  -p "terraform-provider-github_${version}_darwin_amd64.zip" --clobber
+```
+
+Then, download the attestation associated with the artifact:
+
+```bash
+gh attestation download "terraform-provider-github_${version}_darwin_amd64.zip" \
+  --repo integrations/terraform-provider-github
+```
+
+This will create a file named `sha256:[digest].jsonl` in the current directory.
+
+Verify the attestation using Cosign:
+
+```bash
+# Calculate the digest and verify using the specific bundle file
+digest=$(shasum -a 256 "terraform-provider-github_${version}_darwin_amd64.zip" | awk '{ print $1 }')
+cosign verify-blob-attestation \
+  --bundle "sha256:${digest}.jsonl" \
+  --new-bundle-format \
+  --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+  --certificate-identity "https://github.com/integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version}" \
+  "terraform-provider-github_${version}_darwin_amd64.zip"
+```
+
+A successful verification will output `Verified OK`, confirming that the artifact was built by the trusted GitHub Actions workflow and its provenance is securely recorded.
+
+### Verifying all release artifacts
+
+To verify all release artifacts for a specific version:
+
+```bash
+version="x.y.z"
+
+# Download all release artifacts
+gh release download "v${version}" --repo integrations/terraform-provider-github -p "*.zip" --clobber
+
+# Download attestations for all artifacts
+for artifact in terraform-provider-github_${version}_*.zip; do
+  gh attestation download "$artifact" --repo integrations/terraform-provider-github
+done
+
+# Verify all artifacts using specific digest-based bundle files
+for artifact in terraform-provider-github_${version}_*.zip; do
+  echo "Verifying: $artifact"
+  digest=$(shasum -a 256 "$artifact" | awk '{ print $1 }')
+  cosign verify-blob-attestation \
+    --bundle "sha256:${digest}.jsonl" \
+    --new-bundle-format \
+    --certificate-oidc-issuer https://token.actions.githubusercontent.com \
+    --certificate-identity "https://github.com/integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version}" \
+    "$artifact" > /dev/null && echo "✓ Verified" || echo "✗ Failed"
+done
+```
+
+This approach calculates the digest for each artifact and uses the corresponding specific bundle file, ensuring each artifact is verified against its own attestation.