Skip to content

Commit bbf7abb

Browse files
ViacheslavKudinovViacheslav Kudinovstevehipwell
authored
chore(actions): Add doc how to verify GitHub Attestations with GitHub cli and verify release artifacts with Cosign (#2846)
* Add GH attestation on release Signed-off-by: Viacheslav Kudinov <viacheslav@kudinov.tech> * Add information that attestations are available sine v6.9.0 Signed-off-by: Viacheslav Kudinov <viacheslav@kudinov.tech> * Add Cosign verification * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Use ${version} in all the commands Signed-off-by: Viacheslav Kudinov <viacheslav@kudinov.tech> * Add Cosign attestation verification * Use artifact variable Signed-off-by: Viacheslav Kudinov <viacheslav@kudinov.tech> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update headings and blockquote * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> * Update VERIFY_ATTESTATIONS.md Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com> --------- Signed-off-by: Viacheslav Kudinov <viacheslav@kudinov.tech> Co-authored-by: Viacheslav Kudinov <viacheslavkudinov@VK-MacBook-Air-M4-13.local> Co-authored-by: Steve Hipwell <steve.hipwell@gmail.com>
1 parent 19e9e83 commit bbf7abb

1 file changed

Lines changed: 211 additions & 0 deletions

File tree

‎VERIFY_ATTESTATIONS.md‎

Lines changed: 211 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,211 @@
1+
# Using Artifact Attestations to Achieve SLSA v1 Build Level 3
2+
3+
This project started to use GitHub Action to create attestations for the release artifacts. Building software with artifact attestation streamlines supply chain security and helps us achieve [SLSA](https://slsa.dev/) v1.0 Build Level 3 for this project.
4+
5+
> [!NOTE]
6+
> Not all artifacts may have attestations generated for them. Please check the [repository attestations](https://github.com/integrations/terraform-provider-github/attestations) to see which artifacts have attestations available.
7+
>
8+
> Attestations are only available for releases from `v6.9.0`.
9+
10+
## Verifying with GitHub CLI
11+
12+
### Prerequisites
13+
14+
First, install GitHub CLI if you haven't already. See the [installation instructions](https://github.com/cli/cli#installation) for your platform.
15+
16+
### Verifying Attestations
17+
18+
To verify artifact attestations generated during the build process, use the `gh attestation verify` command from the GitHub CLI.
19+
20+
The `gh attestation verify` command requires either `--owner` or `--repo` flags to be used with it.
21+
22+
> [!NOTE]
23+
> Make sure to replace x.y.z with the actual release tag you want to verify.
24+
> Replace artifact name with the actual artifact you want to verify.
25+
26+
Download the release artifacts first:
27+
28+
```bash
29+
version="x.y.z"
30+
artifact="terraform-provider-github_${version}_darwin_amd64.zip"
31+
32+
gh release download "v${version}" --repo integrations/terraform-provider-github -p "*.zip" --clobber
33+
```
34+
35+
To verify the artifact attestations for this project, you can run the following command:
36+
37+
```bash
38+
gh attestation verify --repo integrations/terraform-provider-github --source-ref "refs/tags/v${version}"\
39+
--signer-workflow integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version} \
40+
"$artifact"
41+
```
42+
43+
### Verifying All Artifacts
44+
45+
Alternatively, you can verify all downloaded artifacts with a loop that provides individual status reporting:
46+
47+
```bash
48+
for artifact in terraform-provider-github_${version}_*.zip; do
49+
echo "Verifying: $artifact"
50+
gh attestation verify --repo integrations/terraform-provider-github --source-ref "refs/tags/v${version}" \
51+
--signer-workflow integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version} \
52+
"$artifact" && echo "✓ Verified" || echo "✗ Failed"
53+
done
54+
```
55+
56+
### Using Optional Flags
57+
58+
The `gh attestation verify` command supports additional flags for more specific verification:
59+
60+
Use the `--signer-repo` flag to specify the repository:
61+
62+
```bash
63+
gh attestation verify --owner integrations --signer-repo \
64+
integrations/terraform-provider-github \
65+
"$artifact"
66+
```
67+
68+
If you would like to require an artifact attestation to be signed with a specific workflow, use the `--signer-workflow` flag to indicate the workflow file that should be used.
69+
70+
```bash
71+
gh attestation verify --owner integrations --signer-workflow \
72+
integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version} \
73+
"$artifact"
74+
```
75+
76+
## Verifying with Cosign
77+
78+
> [!NOTE]
79+
> Not all artifacts may have attestations generated for them. Please check the [repository attestations](https://github.com/integrations/terraform-provider-github/attestations) to see which artifacts have attestations available.
80+
>
81+
> Attestations are only available for releases from `v6.9.0`.
82+
83+
In addition to artifact attestations, you can verify release artifacts using [Cosign](https://docs.sigstore.dev/cosign/overview/). Cosign is a tool for signing and verifying software artifacts and container images.
84+
85+
### Prerequisites
86+
87+
First, install Cosign if you haven't already. See the [installation instructions](https://docs.sigstore.dev/cosign/system_config/installation/) for your platform.
88+
89+
### Verify Checksums File
90+
91+
Download the checksums file and its signature bundle:
92+
93+
```bash
94+
gh release download v${version} --repo integrations/terraform-provider-github \
95+
-p "terraform-provider-github_${version}_SHA256SUMS" \
96+
-p "terraform-provider-github_${version}_SHA256SUMS.sbom.json.bundle" --clobber
97+
```
98+
99+
Verify the checksums file signature:
100+
101+
```bash
102+
cosign verify-blob \
103+
--bundle "terraform-provider-github_${version}_SHA256SUMS.sbom.json.bundle" \
104+
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
105+
--certificate-identity "https://github.com/integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version}" \
106+
"terraform-provider-github_${version}_SHA256SUMS"
107+
```
108+
109+
### Verify Artifact Checksums
110+
111+
After verifying the checksums file, verify your downloaded artifacts match the checksums:
112+
113+
Download the artifact you want to verify:
114+
115+
```bash
116+
artifact="terraform-provider-github_${version}_darwin_amd64.zip"
117+
gh release download v${version} --repo integrations/terraform-provider-github \
118+
-p "$artifact" --clobber
119+
```
120+
121+
Verify the checksum:
122+
123+
```bash
124+
shasum -a 256 -c terraform-provider-github_${version}_SHA256SUMS --ignore-missing
125+
```
126+
127+
This will verify that your downloaded artifact matches the signed checksum, confirming its integrity and authenticity.
128+
129+
## Verifying SLSA Provenance Attestations with Cosign
130+
131+
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.
132+
133+
### Prerequisites
134+
135+
1. Install `cosign` for verifying attestations. See the [installation instructions](https://docs.sigstore.dev/cosign/system_config/installation/).
136+
2. Install `gh` (GitHub CLI) if you haven't already. See the [installation instructions](https://github.com/cli/cli#installation).
137+
138+
### Download and Verify Attestation
139+
140+
> [!NOTE]
141+
> Make sure to replace x.y.z with the actual release tag you want to verify.
142+
> Replace artifact name with the actual artifact you want to verify.
143+
144+
> [!NOTE]
145+
> Not all artifacts may have attestations generated for them. Please check the [repository attestations](https://github.com/integrations/terraform-provider-github/attestations) to see which artifacts have attestations available.
146+
>
147+
> Attestations are only available for releases from `v6.9.0`.
148+
149+
First, download the artifact you want to verify:
150+
151+
```bash
152+
version="x.y.z"
153+
artifact="terraform-provider-github_${version}_darwin_amd64.zip"
154+
155+
gh release download "v${version}" --repo integrations/terraform-provider-github \
156+
-p "$artifact" --clobber
157+
```
158+
159+
Then, download the attestation associated with the artifact:
160+
161+
```bash
162+
gh attestation download "$artifact" \
163+
--repo integrations/terraform-provider-github
164+
```
165+
166+
This will create a file named `sha256:[digest].jsonl` in the current directory.
167+
168+
Verify the attestation using Cosign:
169+
170+
```bash
171+
# Calculate the digest and verify using the specific bundle file
172+
digest=$(shasum -a 256 "$artifact" | awk '{ print $1 }')
173+
cosign verify-blob-attestation \
174+
--bundle "sha256:${digest}.jsonl" \
175+
--new-bundle-format \
176+
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
177+
--certificate-identity "https://github.com/integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version}" \
178+
"$artifact"
179+
```
180+
181+
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.
182+
183+
### Verifying All Release Artifacts
184+
185+
To verify all release artifacts for a specific version:
186+
187+
```bash
188+
version="x.y.z"
189+
190+
# Download all release artifacts
191+
gh release download "v${version}" --repo integrations/terraform-provider-github -p "*.zip" --clobber
192+
193+
# Download attestations for all artifacts
194+
for artifact in terraform-provider-github_${version}_*.zip; do
195+
gh attestation download "$artifact" --repo integrations/terraform-provider-github
196+
done
197+
198+
# Verify all artifacts using specific digest-based bundle files
199+
for artifact in terraform-provider-github_${version}_*.zip; do
200+
echo "Verifying: $artifact"
201+
digest=$(shasum -a 256 "$artifact" | awk '{ print $1 }')
202+
cosign verify-blob-attestation \
203+
--bundle "sha256:${digest}.jsonl" \
204+
--new-bundle-format \
205+
--certificate-oidc-issuer https://token.actions.githubusercontent.com \
206+
--certificate-identity "https://github.com/integrations/terraform-provider-github/.github/workflows/release.yaml@refs/tags/v${version}" \
207+
"$artifact" > /dev/null && echo "✓ Verified" || echo "✗ Failed"
208+
done
209+
```
210+
211+
This approach calculates the digest for each artifact and uses the corresponding specific bundle file, ensuring each artifact is verified against its own attestation.

0 commit comments

Comments
 (0)