Skip to content

Commit 78df03e

Browse files
stacknilstacknil
authored
Polish sbom-diff-and-risk self-provenance docs (#8)
* Add policy schema and stable enforcement exit codes * Add policy-aware reports and SARIF export * Add GitHub code scanning workflow example * Tighten parser boundaries for deterministic inputs * Polish sbom-diff-and-risk self provenance docs * Normalize policy report paths across platforms
1 parent 0020896 commit 78df03e

8 files changed

Lines changed: 1308 additions & 1147 deletions

File tree

‎.github/workflows/sbom-diff-and-risk-ci.yml‎

Lines changed: 50 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -11,9 +11,14 @@ on:
1111
- ".github/workflows/sbom-diff-and-risk-ci.yml"
1212
- "tools/sbom-diff-and-risk/**"
1313

14+
env:
15+
SBOM_DIFF_RISK_DIST_ARTIFACT_NAME: sbom-diff-and-risk-dist
16+
1417
jobs:
1518
test:
1619
runs-on: ubuntu-latest
20+
permissions:
21+
contents: read
1722
defaults:
1823
run:
1924
working-directory: tools/sbom-diff-and-risk
@@ -49,3 +54,48 @@ jobs:
4954
test -f "$tmpdir/report.md"
5055
diff -u examples/sample-report.json "$tmpdir/report.json"
5156
diff -u examples/sample-report.md "$tmpdir/report.md"
57+
58+
build-and-attest:
59+
# Keep provenance publication on trusted non-PR runs so consumers verify
60+
# workflow-produced wheel and sdist artifacts from this repository workflow.
61+
if: github.event_name != 'pull_request'
62+
needs: test
63+
runs-on: ubuntu-latest
64+
permissions:
65+
contents: read
66+
id-token: write
67+
attestations: write
68+
defaults:
69+
run:
70+
working-directory: tools/sbom-diff-and-risk
71+
steps:
72+
- name: Check out repository
73+
uses: actions/checkout@v4
74+
75+
- name: Set up Python
76+
uses: actions/setup-python@v5
77+
with:
78+
python-version: "3.11"
79+
80+
- name: Upgrade pip
81+
run: python -m pip install --upgrade pip
82+
83+
- name: Install build tooling
84+
run: python -m pip install build
85+
86+
- name: Build distributable artifacts
87+
run: python -m build
88+
89+
- name: Upload wheel and source distribution artifact
90+
uses: actions/upload-artifact@v4
91+
with:
92+
name: ${{ env.SBOM_DIFF_RISK_DIST_ARTIFACT_NAME }}
93+
path: |
94+
tools/sbom-diff-and-risk/dist/*.whl
95+
tools/sbom-diff-and-risk/dist/*.tar.gz
96+
if-no-files-found: error
97+
98+
- name: Generate artifact attestation for built distributions
99+
uses: actions/attest@v4
100+
with:
101+
subject-path: ${{ github.workspace }}/tools/sbom-diff-and-risk/dist/*

‎tools/sbom-diff-and-risk/README.md‎

Lines changed: 11 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -228,6 +228,17 @@ sbom-diff-risk compare \
228228

229229
For GitHub code scanning integration guidance and a minimal upload workflow, see [docs/github-code-scanning.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/github-code-scanning.md).
230230

231+
## Self-provenance
232+
233+
This repository also records provenance for `sbom-diff-and-risk` itself by generating GitHub artifact attestations for the wheel and source distribution produced by the `sbom-diff-and-risk-ci` workflow.
234+
235+
- the attested files are the wheel and source distribution built by `python -m build` from `tools/sbom-diff-and-risk`
236+
- the build files are uploaded together as the `sbom-diff-and-risk-dist` workflow artifact
237+
- only trusted non-PR runs publish the attestation
238+
- consumers can verify provenance with GitHub's attestation tooling after downloading one of those artifacts
239+
- this complements the tool's analysis of third-party supply-chain inputs, but it does not replace that analysis
240+
241+
See [docs/self-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/self-provenance.md) for the exact attested filenames, where the evidence appears in GitHub, and a run-by-run verification flow for consumers.
231242
## Parser Boundaries
232243

233244
Deterministic local mode intentionally supports a conservative subset of packaging syntax. The detailed matrix lives in [docs/parser-boundaries.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/parser-boundaries.md).

‎tools/sbom-diff-and-risk/docs/self-provenance.md‎

Lines changed: 100 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,100 @@
1+
# Self-provenance and artifact attestations
2+
3+
`sbom-diff-and-risk` analyzes third-party dependency changes, but consumers should also be able to verify where the tool itself came from. This repository generates GitHub artifact attestations for the packaged build outputs produced by the `sbom-diff-and-risk-ci` workflow.
4+
5+
## What is attested in this repository
6+
7+
The attested subjects are the exact Python distributables built from `tools/sbom-diff-and-risk` via `python -m build`:
8+
9+
- the wheel: `dist/sbom_diff_and_risk-<version>-py3-none-any.whl`
10+
- the source distribution: `dist/sbom_diff_and_risk-<version>.tar.gz`
11+
12+
Those two files are uploaded together as the workflow artifact named `sbom-diff-and-risk-dist`. The attestation applies to the built files themselves, not just to the artifact bundle name shown in the Actions UI.
13+
14+
Current attestations cover workflow-built wheel and sdist artifacts, not GitHub Release assets or PyPI-published distributions.
15+
16+
## Workflow and permissions
17+
18+
The attestation is generated in `.github/workflows/sbom-diff-and-risk-ci.yml` by the `build-and-attest` job in the `sbom-diff-and-risk-ci` workflow.
19+
20+
That job runs only for trusted non-PR events in this repository:
21+
22+
- `push`
23+
- `workflow_dispatch`
24+
25+
Pull request runs still execute the `test` job, but they do not publish artifact attestations.
26+
27+
The `build-and-attest` job uses the minimum explicit permissions required for GitHub-hosted build provenance:
28+
29+
- `contents: read` for repository checkout
30+
- `id-token: write` for GitHub's signing identity
31+
- `attestations: write` to publish the attestation
32+
33+
## Where provenance evidence appears in GitHub
34+
35+
After a successful non-PR run of `sbom-diff-and-risk-ci`, consumers can find the evidence in two useful places:
36+
37+
1. On the workflow run page:
38+
- the uploaded artifact appears as `sbom-diff-and-risk-dist`
39+
- this is the run consumers should use to confirm the workflow name, job name, and downloaded artifact bundle before verification
40+
2. In the repository-wide attestations view:
41+
- open **Actions**
42+
- in the left sidebar, under **Management**, open **Attestations**
43+
- search for `sbom_diff_and_risk-` or filter by recent creation date
44+
45+
On the **Attestations** page, the relevant subjects are the wheel and sdist filenames, not the workflow artifact bundle name. On the workflow run page, the main visible bundle name is still `sbom-diff-and-risk-dist`.
46+
47+
## Manual verification for one workflow run
48+
49+
Use this path after a merge to the default branch or an intentional `workflow_dispatch` run.
50+
51+
1. Open the repository's **Actions** tab.
52+
2. Open a successful `sbom-diff-and-risk-ci` run triggered by `push` or `workflow_dispatch`.
53+
3. Confirm that the `build-and-attest` job ran successfully.
54+
4. Download the `sbom-diff-and-risk-dist` artifact from that run.
55+
5. Confirm the downloaded archive contains exactly the expected build outputs for that version:
56+
- `sbom_diff_and_risk-<version>-py3-none-any.whl`
57+
- `sbom_diff_and_risk-<version>.tar.gz`
58+
6. Verify one of the files with the GitHub CLI:
59+
60+
```bash
61+
gh attestation verify path/to/sbom_diff_and_risk-<version>-py3-none-any.whl \
62+
--repo OWNER/scientific-computing-toolkit \
63+
--signer-workflow OWNER/scientific-computing-toolkit/.github/workflows/sbom-diff-and-risk-ci.yml
64+
```
65+
66+
You can verify the source distribution the same way:
67+
68+
```bash
69+
gh attestation verify path/to/sbom_diff_and_risk-<version>.tar.gz \
70+
--repo OWNER/scientific-computing-toolkit \
71+
--signer-workflow OWNER/scientific-computing-toolkit/.github/workflows/sbom-diff-and-risk-ci.yml
72+
```
73+
74+
If you want more inspection detail during review, ask the CLI for structured output:
75+
76+
```bash
77+
gh attestation verify path/to/sbom_diff_and_risk-<version>-py3-none-any.whl \
78+
--repo OWNER/scientific-computing-toolkit \
79+
--signer-workflow OWNER/scientific-computing-toolkit/.github/workflows/sbom-diff-and-risk-ci.yml \
80+
--format json
81+
```
82+
83+
A successful verification confirms that:
84+
85+
- the downloaded file matches an attested subject
86+
- the attestation was linked to `OWNER/scientific-computing-toolkit`
87+
- the attestation was signed by `.github/workflows/sbom-diff-and-risk-ci.yml`
88+
89+
## Release-consumer note
90+
91+
If these same wheel or source distribution bytes are later attached to a GitHub release, consumers should verify the downloaded release asset file itself with the same `gh attestation verify` flow. In the current setup, the provenance source of truth is still the workflow-produced build artifact and its attestation, not a separate release-attestation workflow.
92+
93+
## How this complements the tool's own analysis
94+
95+
Self-provenance and dependency analysis solve different problems:
96+
97+
- artifact attestations help consumers verify where `sbom-diff-and-risk` itself was built
98+
- `sbom-diff-and-risk` helps users review and gate third-party dependency changes in their own projects
99+
100+
These attestations strengthen trust in the tool's own distributable artifacts, but they do not replace the tool's analysis of external SBOM inputs, policy decisions, or trust-signal reporting for third-party packages.

0 commit comments

Comments
 (0)