Skip to content

Commit a14a208

Browse files
spoorccspoorcc
committed
Move integrity into separate howto
1 parent f685598 commit a14a208

3 files changed

Lines changed: 226 additions & 189 deletions

File tree

‎doc/howto/verify-integrity.rst‎

Lines changed: 222 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,222 @@
1+
Verify release integrity
2+
========================
3+
4+
Every dfetch release, and every commit merged to ``main``, has cryptographic
5+
attestations signed by GitHub Actions and anchored in
6+
`Sigstore <https://www.sigstore.dev/>`_, all published in the
7+
`attestation registry <https://github.com/dfetch-org/dfetch/attestations>`_.
8+
There are four complementary kinds:
9+
10+
- **SLSA build provenance** — answers *"where did this come from?"*: proves the
11+
artifact was produced from the official source commit by the official CI
12+
workflow, and records the exact inputs used at build time.
13+
- **SBOM attestation** (CycloneDX) — answers *"what is inside it?"*: lists every
14+
dependency bundled in the package so you can audit its composition.
15+
- **Verification Summary Attestation (VSA)** — answers *"was the source
16+
independently verified?"*: records that the source archive for this commit was
17+
attested and verified before the binary was produced, linking source-level
18+
trust to the binary package.
19+
- **Test result attestation** (in-toto) — answers *"did the source pass its tests?"*:
20+
records that the full CI test suite ran against this exact source archive and every
21+
check passed, before any binary was produced.
22+
23+
Binary installers have **build provenance, SBOM, and VSA** attestations when source
24+
provenance verification passes (signed by ``build.yml``).
25+
Python packages installed from PyPI have an **SBOM attestation only** (signed by
26+
``python-publish.yml``).
27+
The source archive has a **SLSA build provenance** attestation (signed by
28+
``source-provenance.yml``) and a **test result attestation** (signed by ``test.yml``).
29+
30+
To verify, use the `GitHub CLI <https://cli.github.com/>`_. Pass
31+
``--predicate-type`` to target one kind specifically; omit it to accept any.
32+
33+
In the commands below, replace ``@refs/tags/v<version>`` with
34+
``@refs/heads/main`` when verifying a development build installed directly
35+
from the ``main`` branch.
36+
37+
.. tabs::
38+
39+
.. tab:: Linux
40+
41+
**Binary installer — verify build provenance:**
42+
43+
.. code-block:: bash
44+
45+
$ gh attestation verify dfetch-<version>-nix.deb \
46+
--repo dfetch-org/dfetch \
47+
--predicate-type https://slsa.dev/provenance/v1 \
48+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
49+
--cert-oidc-issuer https://token.actions.githubusercontent.com
50+
51+
**Binary installer — verify SBOM attestation:**
52+
53+
.. code-block:: bash
54+
55+
$ gh attestation verify dfetch-<version>-nix.deb \
56+
--repo dfetch-org/dfetch \
57+
--predicate-type https://cyclonedx.org/bom \
58+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
59+
--cert-oidc-issuer https://token.actions.githubusercontent.com
60+
61+
**Binary installer — verify source provenance summary (VSA):**
62+
63+
.. code-block:: bash
64+
65+
$ gh attestation verify dfetch-<version>-nix.deb \
66+
--repo dfetch-org/dfetch \
67+
--predicate-type https://slsa.dev/verification_summary/v1 \
68+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
69+
--cert-oidc-issuer https://token.actions.githubusercontent.com
70+
71+
**pip / PyPI wheel — verify SBOM attestation:**
72+
73+
Download the wheel before installing so you have the original file to verify:
74+
75+
.. code-block:: bash
76+
77+
$ pip download dfetch==<version> --no-deps -d .
78+
$ gh attestation verify dfetch-<version>-py3-none-any.whl \
79+
--repo dfetch-org/dfetch \
80+
--predicate-type https://cyclonedx.org/bom \
81+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/python-publish.yml@refs/tags/v<version> \
82+
--cert-oidc-issuer https://token.actions.githubusercontent.com
83+
84+
.. tab:: macOS
85+
86+
**Binary installer — verify build provenance:**
87+
88+
.. code-block:: bash
89+
90+
$ gh attestation verify dfetch-<version>-osx.pkg \
91+
--repo dfetch-org/dfetch \
92+
--predicate-type https://slsa.dev/provenance/v1 \
93+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
94+
--cert-oidc-issuer https://token.actions.githubusercontent.com
95+
96+
**Binary installer — verify SBOM attestation:**
97+
98+
.. code-block:: bash
99+
100+
$ gh attestation verify dfetch-<version>-osx.pkg \
101+
--repo dfetch-org/dfetch \
102+
--predicate-type https://cyclonedx.org/bom \
103+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
104+
--cert-oidc-issuer https://token.actions.githubusercontent.com
105+
106+
**Binary installer — verify source provenance summary (VSA):**
107+
108+
.. code-block:: bash
109+
110+
$ gh attestation verify dfetch-<version>-osx.pkg \
111+
--repo dfetch-org/dfetch \
112+
--predicate-type https://slsa.dev/verification_summary/v1 \
113+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> \
114+
--cert-oidc-issuer https://token.actions.githubusercontent.com
115+
116+
**pip / PyPI wheel — verify SBOM attestation:**
117+
118+
Download the wheel before installing so you have the original file to verify:
119+
120+
.. code-block:: bash
121+
122+
$ pip download dfetch==<version> --no-deps -d .
123+
$ gh attestation verify dfetch-<version>-py3-none-any.whl \
124+
--repo dfetch-org/dfetch \
125+
--predicate-type https://cyclonedx.org/bom \
126+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/python-publish.yml@refs/tags/v<version> \
127+
--cert-oidc-issuer https://token.actions.githubusercontent.com
128+
129+
.. tab:: Windows
130+
131+
**Binary installer — verify build provenance:**
132+
133+
.. code-block:: powershell
134+
135+
> gh attestation verify dfetch-<version>-win.msi `
136+
--repo dfetch-org/dfetch `
137+
--predicate-type https://slsa.dev/provenance/v1 `
138+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> `
139+
--cert-oidc-issuer https://token.actions.githubusercontent.com
140+
141+
**Binary installer — verify SBOM attestation:**
142+
143+
.. code-block:: powershell
144+
145+
> gh attestation verify dfetch-<version>-win.msi `
146+
--repo dfetch-org/dfetch `
147+
--predicate-type https://cyclonedx.org/bom `
148+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> `
149+
--cert-oidc-issuer https://token.actions.githubusercontent.com
150+
151+
**Binary installer — verify source provenance summary (VSA):**
152+
153+
.. code-block:: powershell
154+
155+
> gh attestation verify dfetch-<version>-win.msi `
156+
--repo dfetch-org/dfetch `
157+
--predicate-type https://slsa.dev/verification_summary/v1 `
158+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/build.yml@refs/tags/v<version> `
159+
--cert-oidc-issuer https://token.actions.githubusercontent.com
160+
161+
**pip / PyPI wheel — verify SBOM attestation:**
162+
163+
Download the wheel before installing so you have the original file to verify:
164+
165+
.. code-block:: powershell
166+
167+
> pip download dfetch==<version> --no-deps -d .
168+
> gh attestation verify dfetch-<version>-py3-none-any.whl `
169+
--repo dfetch-org/dfetch `
170+
--predicate-type https://cyclonedx.org/bom `
171+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/python-publish.yml@refs/tags/v<version> `
172+
--cert-oidc-issuer https://token.actions.githubusercontent.com
173+
174+
**Source archive — verify build provenance and test results:**
175+
176+
The source archive has two attestations and is produced for every release and
177+
every ``main``-branch commit. Download ``source.tar.gz`` from the *Artifacts*
178+
section of the relevant CI run, then verify each in turn. Use
179+
``@refs/tags/v<version>`` for a release or ``@refs/heads/main`` for a
180+
development build.
181+
182+
Verify SLSA build provenance (proves the archive was produced by the official
183+
workflow from the tagged commit):
184+
185+
.. code-block:: bash
186+
187+
$ gh attestation verify source.tar.gz \
188+
--repo dfetch-org/dfetch \
189+
--predicate-type https://slsa.dev/provenance/v1 \
190+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/source-provenance.yml@refs/tags/v<version> \
191+
--cert-oidc-issuer https://token.actions.githubusercontent.com
192+
193+
Verify test results (proves the full CI suite passed on that exact source before
194+
any binary was produced):
195+
196+
.. code-block:: bash
197+
198+
$ gh attestation verify source.tar.gz \
199+
--repo dfetch-org/dfetch \
200+
--predicate-type https://in-toto.io/attestation/test-result/v0.1 \
201+
--cert-identity https://github.com/dfetch-org/dfetch/.github/workflows/test.yml@refs/tags/v<version> \
202+
--cert-oidc-issuer https://token.actions.githubusercontent.com
203+
204+
See `GitHub artifact attestations`_ for details.
205+
206+
.. note::
207+
208+
The VSA is present on releases built from a commit whose source provenance
209+
was verified. If the ``verification_summary`` attestation is absent for a
210+
release, fall back to checking build provenance and SBOM independently.
211+
212+
.. note::
213+
214+
``--cert-oidc-issuer https://token.actions.githubusercontent.com`` pins
215+
verification to GitHub Actions as the identity provider. Without it, an
216+
attacker could generate a valid attestation using a different OIDC issuer
217+
(for example a self-hosted Sigstore instance) that also produces a
218+
certificate matching the ``--cert-identity`` workflow path. Supplying
219+
both flags together ensures the certificate was issued specifically by
220+
GitHub Actions for the declared workflow.
221+
222+
.. _`GitHub artifact attestations`: https://docs.github.com/en/actions/security-for-github-actions/using-artifact-attestations

‎doc/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -67,6 +67,7 @@ upstream. See :ref:`vendoring` for background on the problem this solves.
6767
howto/patching
6868
howto/check-ci
6969
howto/sbom
70+
howto/verify-integrity
7071
howto/troubleshooting
7172
howto/contributing
7273

0 commit comments

Comments
 (0)