Skip to content

Commit 915ceaf

Browse files
stacknilstacknil
authored
Merge pull request #66 from stacknil/codex/clarify-sbom-reviewer-path
docs(sbom): clarify reviewer path
2 parents 97c4354 + d79fbb9 commit 915ceaf

5 files changed

Lines changed: 204 additions & 26 deletions

File tree

‎README.md‎

Lines changed: 21 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -11,8 +11,10 @@ current flagship tool. It compares SBOMs and dependency manifests, produces
1111
JSON, Markdown, and SARIF review artifacts, supports local policy checks, and
1212
can optionally record PyPI provenance and OpenSSF Scorecard evidence.
1313

14-
For a fast reviewer overview, start with the [`sbom-diff-and-risk` reviewer
15-
brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md).
14+
For the clearest reviewer route, start with the
15+
[`sbom-diff-and-risk` reviewer path](tools/sbom-diff-and-risk/docs/reviewer-path.md);
16+
it separates orientation, artifact inspection, local reproduction, and release
17+
evidence.
1618

1719
## Supporting Spatiotemporal Diagnostics Project
1820

@@ -50,6 +52,7 @@ evidence.
5052
Useful entry points:
5153

5254
- [`sbom-diff-and-risk` README](tools/sbom-diff-and-risk/README.md)
55+
- [Reviewer path](tools/sbom-diff-and-risk/docs/reviewer-path.md)
5356
- [Reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md)
5457
- [Reviewer evidence pack](tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md)
5558
- [v0.9.0 release notes][release-notes-v090]
@@ -104,15 +107,22 @@ publishing is intentionally deferred.
104107
attestations, and PyPI Trusted Publishing provenance as interchangeable
105108
evidence.
106109

107-
## Reviewer Quick Path
108-
109-
1. Read the [`sbom-diff-and-risk` reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md).
110-
2. Skim the [`sbom-diff-and-risk` README](tools/sbom-diff-and-risk/README.md)
111-
for CLI scope and examples.
112-
3. Check the [v0.9.0 release notes][release-notes-v090].
113-
4. Use the [verification guide](tools/sbom-diff-and-risk/docs/verification.md)
114-
to choose the right provenance check.
115-
5. Inspect the [examples](tools/sbom-diff-and-risk/examples/) for sample reports and policy files.
110+
## Reviewer Quick Path
111+
112+
For `sbom-diff-and-risk`, use the
113+
[reviewer path](tools/sbom-diff-and-risk/docs/reviewer-path.md) and first choose
114+
the review question:
115+
116+
1. 30 seconds:
117+
read the [reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md).
118+
2. 5 minutes:
119+
inspect [sample JSON, summary, policy, Markdown, and SARIF artifacts](tools/sbom-diff-and-risk/examples/).
120+
3. 15 minutes:
121+
run the deterministic example check in
122+
[example artifact regeneration](tools/sbom-diff-and-risk/docs/example-artifact-regeneration.md).
123+
4. Release evidence:
124+
use the [verification guide](tools/sbom-diff-and-risk/docs/verification.md)
125+
and [release provenance docs](tools/sbom-diff-and-risk/docs/release-provenance.md).
116126

117127
## Status
118128

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

Lines changed: 8 additions & 3 deletions
Original file line numberDiff line numberDiff line change
@@ -10,11 +10,16 @@ dry-run story, and keeps production PyPI publishing intentionally deferred.
1010

1111
It uses conservative heuristics for change intelligence. By default it does not resolve CVEs, does not act as a reputation oracle, and does not perform hidden network enrichment.
1212

13-
## Start Here
14-
13+
## Start Here
14+
15+
For the clearest reviewer route, start with
16+
[docs/reviewer-path.md](docs/reviewer-path.md). It gives a 30-second,
17+
5-minute, and 15-minute path through the project, plus separate release
18+
evidence and deep-review routes.
19+
1520
This project has two different provenance stories:
1621

17-
For a concise reviewer-facing overview, start with
22+
For a concise reviewer-facing overview after choosing the review route, use
1823
[docs/reviewer-brief.md](docs/reviewer-brief.md). For reproducible review
1924
evidence and verification commands, use
2025
[docs/reviewer-evidence-pack.md](docs/reviewer-evidence-pack.md). For

‎tools/sbom-diff-and-risk/docs/reviewer-brief.md‎

Lines changed: 15 additions & 11 deletions
Original file line numberDiff line numberDiff line change
@@ -1,10 +1,13 @@
11
# Reviewer brief
22

3-
## Summary
4-
3+
## Summary
4+
55
`sbom-diff-and-risk` is a local CLI for comparing two SBOMs or dependency manifests and producing deterministic review artifacts: JSON, Markdown, and SARIF. It is built for conservative supply-chain review, not for vulnerability scanning or package reputation scoring.
66

77
Current released version: `v0.9.0`.
8+
9+
For the shortest ordered review route, use
10+
[reviewer-path.md](reviewer-path.md).
811

912
## Why this project matters
1013

@@ -37,15 +40,16 @@ Dependency review often needs evidence that is stable enough for code review, CI
3740
| Did Trusted Publishing get exercised safely? | `docs/pypi-trusted-publishing-readiness.md` documents the completed TestPyPI dry-run. |
3841
| Is production PyPI enabled? | `docs/pypi-production-publishing-decision.md` documents that production PyPI is intentionally deferred. |
3942

40-
## Quick verification path
41-
42-
1. Read this brief for the 30-second project shape.
43-
2. Read [reviewer-evidence-pack.md](reviewer-evidence-pack.md) for reproducible commands and evidence paths.
44-
3. Read `README.md` for CLI scope, supported inputs, and examples.
45-
4. Read `docs/verification.md` to choose the right verification path.
46-
5. Use `docs/self-provenance.md` when verifying workflow-built wheel or source distribution artifacts.
47-
6. Use `docs/release-provenance.md` when verifying GitHub Release assets.
48-
7. Use `docs/pypi-production-publishing-decision.md` before making any production PyPI publishing decision.
43+
## Quick verification path
44+
45+
1. Use [reviewer-path.md](reviewer-path.md) as the ordered route.
46+
2. Read this brief for the 30-second project shape.
47+
3. Read [reviewer-evidence-pack.md](reviewer-evidence-pack.md) for reproducible commands and evidence paths.
48+
4. Read `README.md` for CLI scope, supported inputs, and examples.
49+
5. Read `docs/verification.md` to choose the right verification path.
50+
6. Use `docs/self-provenance.md` when verifying workflow-built wheel or source distribution artifacts.
51+
7. Use `docs/release-provenance.md` when verifying GitHub Release assets.
52+
8. Use `docs/pypi-production-publishing-decision.md` before making any production PyPI publishing decision.
4953

5054
## What this project intentionally does not claim
5155

‎tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md‎

Lines changed: 4 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -1,6 +1,9 @@
11
# Reviewer evidence pack
22

3-
This page is a reproducible evidence checklist for reviewing `sbom-diff-and-risk`. It focuses on what can be verified from the repository, examples, GitHub release assets, and TestPyPI dry-run documentation. It does not introduce new CLI behavior.
3+
This page is a reproducible evidence checklist for reviewing `sbom-diff-and-risk`. It focuses on what can be verified from the repository, examples, GitHub release assets, and TestPyPI dry-run documentation. It does not introduce new CLI behavior.
4+
5+
For the shortest ordered route through these materials, start with
6+
[reviewer-path.md](reviewer-path.md).
47

58
## Project Identity
69

‎tools/sbom-diff-and-risk/docs/reviewer-path.md‎

Lines changed: 156 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,156 @@
1+
# Reviewer path
2+
3+
Use this page as the ordered review route for `sbom-diff-and-risk`. It is
4+
designed to make one thing clear at every step: what evidence you are checking,
5+
where to find it, and what it does not prove.
6+
7+
## First choose the review question
8+
9+
| Review question | Start here | Good stopping point |
10+
| --- | --- | --- |
11+
| What is this tool? | [30-second orientation](#30-second-orientation) | You can state the tool's scope and non-claims. |
12+
| What artifacts does it produce? | [5-minute artifact review](#5-minute-artifact-review) | You can point to JSON, summary, policy, Markdown, and SARIF examples. |
13+
| Can the examples be reproduced locally? | [15-minute reproduction check](#15-minute-reproduction-check) | `regenerate-example-artifacts.py --check` passes without enrichment. |
14+
| Can the released tool artifacts be verified? | [Release evidence](#release-evidence) | You can choose the correct GitHub release, checksum, or attestation path. |
15+
| Is this enough for a full review? | [Deep review](#deep-review) | You have followed the reproducible checklist in the evidence pack. |
16+
17+
## 30-second orientation
18+
19+
Read:
20+
21+
- [reviewer-brief.md](reviewer-brief.md)
22+
- the first screen of the [tool README](../README.md)
23+
24+
Confirm these claims only:
25+
26+
- local, deterministic SBOM/dependency diff CLI
27+
- supported inputs: CycloneDX JSON, SPDX JSON, `requirements.txt`, and
28+
conservative `pyproject.toml`
29+
- output artifacts: JSON, Markdown, SARIF, `summary.json`, and `policy.json`
30+
- local policy checks with reviewer-facing decision explanation fields
31+
- optional PyPI provenance and OpenSSF Scorecard enrichment only when
32+
explicitly enabled
33+
- production PyPI publishing remains intentionally deferred
34+
35+
Stop here if you only need the project shape for a reviewer, resume, or PR
36+
summary.
37+
38+
Do not infer:
39+
40+
- CVE scanning
41+
- dependency safety verdicts
42+
- package reputation scoring
43+
- hidden network enrichment
44+
- production PyPI availability
45+
46+
## 5-minute artifact review
47+
48+
Inspect the checked-in examples in this order:
49+
50+
| Step | Artifact | What it proves |
51+
| --- | --- | --- |
52+
| 1 | [sample-report.json](../examples/sample-report.json) | Full machine-readable diff, risk, policy, and metadata shape. |
53+
| 2 | [sample-summary.json](../examples/sample-summary.json) | Compact CI-facing `summary` contract. |
54+
| 3 | [sample-policy.json](../examples/sample-policy.json) | Policy-only sidecar for CI consumers. |
55+
| 4 | [sample-report.md](../examples/sample-report.md) | Human-readable reviewer report. |
56+
| 5 | [sample-sarif.sarif](../examples/sample-sarif.sarif) | Conservative code-scanning output for selected high-signal findings. |
57+
| 6 | [github-actions-policy-consumer.yml](../examples/github-actions-policy-consumer.yml) | Copyable consumer path for capturing policy JSON in GitHub Actions. |
58+
59+
Then read:
60+
61+
- [report-schema.md](report-schema.md)
62+
- [policy-decision-explainability.md](policy-decision-explainability.md)
63+
- [github-code-scanning.md](github-code-scanning.md)
64+
65+
Look for these reviewer anchors:
66+
67+
- `summary` is the compact machine-readable entry point
68+
- `summary.policy` appears only when policy evaluation runs
69+
- `summary.enrichment` appears only when enrichment evidence exists
70+
- policy findings explain `decision_reason`, `policy_rule`,
71+
`matched_threshold`, and `observed_value`
72+
- SARIF is intentionally narrow and does not mirror every report finding
73+
74+
Stop here if you need to understand the review outputs without running code.
75+
76+
## 15-minute reproduction check
77+
78+
From `tools/sbom-diff-and-risk`, run the deterministic example checks:
79+
80+
```powershell
81+
python -m pip install -e .[dev]
82+
python scripts/regenerate-example-artifacts.py --check
83+
python scripts/regenerate-example-artifacts.py --check --only requirements
84+
```
85+
86+
Expected result:
87+
88+
- the full checked-in no-network example set is up to date
89+
- the focused requirements example check passes
90+
- JSON, Markdown, summary, policy sidecar, and SARIF examples match the
91+
committed artifacts
92+
- no PyPI, Scorecard, CVE, or advisory network lookup is performed
93+
94+
For the exact regeneration scope, read
95+
[example-artifact-regeneration.md](example-artifact-regeneration.md).
96+
97+
Stop here if you need reproducible local evidence that the examples still match
98+
the code.
99+
100+
## Release evidence
101+
102+
Use this section only when the review question is about the released
103+
`sbom-diff-and-risk` tool artifacts. It is not the path for judging third-party
104+
dependency safety.
105+
106+
| Evidence surface | Use when | Read |
107+
| --- | --- | --- |
108+
| Verification decision guide | You need to choose the right release verification path. | [verification.md](verification.md) |
109+
| GitHub Release assets and checksums | You downloaded wheel or source distribution files from a release. | [release-provenance.md](release-provenance.md) |
110+
| Workflow artifact attestations | You are verifying workflow-built wheel or source distribution artifacts. | [self-provenance.md](self-provenance.md) |
111+
| TestPyPI Trusted Publishing dry-run | You are checking whether the dry-run publisher path worked. | [pypi-trusted-publishing-readiness.md](pypi-trusted-publishing-readiness.md) |
112+
| Production PyPI decision gate | You are deciding whether production PyPI should be enabled later. | [pypi-production-publishing-decision.md](pypi-production-publishing-decision.md) |
113+
114+
Keep the evidence surfaces separate:
115+
116+
- GitHub workflow artifact attestation verifies workflow-built artifacts.
117+
- GitHub Release asset checksums verify downloaded release bytes against the
118+
release checksum manifest.
119+
- GitHub immutable-release verification applies only when the release is
120+
immutable and GitHub has generated release attestations.
121+
- TestPyPI Trusted Publishing proves the dry-run publisher path worked.
122+
- Production PyPI Trusted Publishing is intentionally deferred and does not
123+
exist for this project yet.
124+
125+
Stop here if your review question is release provenance rather than dependency
126+
analysis behavior.
127+
128+
## Deep review
129+
130+
Use [reviewer-evidence-pack.md](reviewer-evidence-pack.md) for the full
131+
reproducible checklist, including:
132+
133+
- local demo commands
134+
- release asset inspection
135+
- checksum verification
136+
- artifact attestation verification
137+
- TestPyPI evidence boundaries
138+
- SARIF/code-scanning boundaries
139+
- non-claims
140+
141+
Use these supporting docs for focused review questions:
142+
143+
- [dependency-risk-heuristics.md](dependency-risk-heuristics.md) for risk bucket
144+
semantics
145+
- [parser-boundaries.md](parser-boundaries.md) for deterministic parser limits
146+
- [policy-schema.md](policy-schema.md) for policy file shape
147+
- [policy-decision-ci-cookbook.md](policy-decision-ci-cookbook.md) for CI policy
148+
consumption
149+
- [summary-json-ci-cookbook.md](summary-json-ci-cookbook.md) for summary-only CI
150+
consumption
151+
152+
## Reviewer bottom line
153+
154+
`sbom-diff-and-risk` is review infrastructure. It makes dependency changes,
155+
policy decisions, and selected supply-chain trust signals easier to inspect.
156+
It does not decide whether a dependency is safe.

0 commit comments

Comments
 (0)