Skip to content
Merged
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension


Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
12 changes: 7 additions & 5 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -84,7 +84,7 @@ Project:
[`sbom-diff-and-risk`](tools/sbom-diff-and-risk/README.md)

Status:
Stable GitHub release: `v1.0.0`. Production PyPI publishing remains deferred.
Stable GitHub release: `v1.1.0`. Production PyPI publishing remains deferred.

What to review:
Deterministic SBOM/dependency diffing, JSON/Markdown/SARIF output, local policy
Expand All @@ -98,6 +98,7 @@ Useful entry points:
- [Reviewer path](tools/sbom-diff-and-risk/docs/reviewer-path.md)
- [Reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md)
- [Reviewer evidence pack](tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md)
- [v1.1.0 release notes][release-notes-v110]
- [v1.0.0 release notes][release-notes-v100]
- [v1.0-rc.1 release notes][release-notes-v10rc1]
- [Examples](tools/sbom-diff-and-risk/examples/)
Expand Down Expand Up @@ -225,12 +226,13 @@ the review question:

## Status

- Current stable flagship release: `sbom-diff-and-risk` `v1.0.0`
- GitHub Release assets: available for `v1.0.0`
- GitHub Latest: `v1.0.0`
- Package metadata: `1.0.0`
- Current stable flagship release: `sbom-diff-and-risk` `v1.1.0`
- GitHub Release assets: available for `v1.1.0`
- GitHub Latest: `v1.1.0`
- Package metadata: `1.1.0`
- TestPyPI Trusted Publishing dry-run: completed
- Production PyPI publishing: intentionally deferred

[release-notes-v110]: tools/sbom-diff-and-risk/RELEASE_NOTES_v1.1.0.md
[release-notes-v100]: tools/sbom-diff-and-risk/RELEASE_NOTES_v1.0.0.md
[release-notes-v10rc1]: tools/sbom-diff-and-risk/RELEASE_NOTES_v1.0-rc.1.md
10 changes: 5 additions & 5 deletions scripts/validate-reviewer-routes.py
Original file line number Diff line number Diff line change
Expand Up @@ -176,8 +176,8 @@
"not a package safety verdict engine",
"not part of the `sbom-diff-and-risk` release surface",
"why the scientific-computing background helps",
"Current stable flagship release: `sbom-diff-and-risk` `v1.0.0`",
"GitHub Latest: `v1.0.0`",
"Current stable flagship release: `sbom-diff-and-risk` `v1.1.0`",
"GitHub Latest: `v1.1.0`",
"Production PyPI publishing: intentionally deferred",
),
Path("docs/reviewer-brief.md"): (
Expand Down Expand Up @@ -267,9 +267,9 @@
"any malware verdict",
),
Path("tools/sbom-diff-and-risk/docs/release-provenance.md"): (
"`v1.0.0` is the stable GitHub Release contract and is marked GitHub Latest",
"`v1.1.0` is the stable GitHub Release contract and is marked GitHub Latest",
"Production PyPI publishing remains deferred as a separate contract",
"marks final tags such as `v1.0.0` as GitHub Latest",
"marks final tags such as `v1.1.0` as GitHub Latest",
"workflow artifact attestation",
),
Path("tools/sbom-diff-and-risk/docs/reviewer-path.md"): (
Expand All @@ -288,7 +288,7 @@
"runs the tool, uploads `policy.json`, and fails or passes from the policy exit code",
"not current PyPI package truth",
"not current repository reputation",
"`v1.0.0` is the stable GitHub release and GitHub Latest",
"`v1.1.0` is the stable GitHub release and GitHub Latest",
"`v1.0-rc.1` remains historical prerelease evidence",
"It does not decide whether a dependency is safe.",
),
Expand Down
2 changes: 1 addition & 1 deletion tools/sbom-diff-and-risk/README.md
Original file line number Diff line number Diff line change
@@ -1,6 +1,6 @@
# sbom-diff-and-risk

`v1.0.0` is the stable Policy Evidence GitHub release. GitHub Release assets
`v1.1.0` is the stable Policy Evidence GitHub release. GitHub Release assets
are the supported distribution surface for this version, while production
PyPI publishing remains intentionally deferred.

Expand Down
71 changes: 71 additions & 0 deletions tools/sbom-diff-and-risk/RELEASE_NOTES_v1.1.0.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,71 @@
# sbom-diff-and-risk v1.1.0

`v1.1.0` is the stable v1.1 GitHub Release for `sbom-diff-and-risk`.

The Python package metadata version for this tag is `1.1.0`. The package
authors metadata is intentionally omitted; the public package identity remains
the repository and project name.

## Highlights

- Adds input and policy contract versioning while preserving readable v1.0
policy and report fields.
- Adds policy decision explainability with stable rule, evidence, reason,
and confidence fields.
- Adds typed canonical component identity with fail-closed duplicate and
conflicting-metadata diagnostics.
- Adds an explicit ecosystem canonicalization matrix for PyPI, npm, Maven,
NuGet, generic, and unknown ecosystems.
- Treats a no-purl `bom_ref` as an opaque local identifier: surrounding
whitespace is trimmed, case is preserved, and local identifiers are not
inferred to be aliases.
- Keeps the local CI consumer path, JSON/Markdown/SARIF report surfaces, and
release artifact verification path available for reviewers.

## Compatibility

- CLI commands and flags remain unchanged.
- Existing v1.0 report fields remain readable for the lifetime of report
schema v1.
- Legacy policy files remain readable while versioned policy schema identifiers
are emitted and validated.
- Purl identity remains authoritative over `bom_ref`; a version change remains
a change rather than an add/remove pair.
- Case-differing opaque bom-refs no longer collide. Exact duplicate identities
and same-identity conflicting metadata still fail closed.

## Release policy

- `v1.1.0` is the stable GitHub Release contract and GitHub Latest.
- GitHub Release assets are the supported distribution surface for this
version.
- Production PyPI publishing remains intentionally deferred.
- TestPyPI Trusted Publishing evidence remains evidence of the test publishing
path only.

## Boundaries

- Default analysis remains local-file based and deterministic.
- Optional PyPI and OpenSSF Scorecard enrichment remains explicit opt-in
network access.
- No CVE lookup, advisory resolution, malware scanning, or package safety
verdict was added.
- Policy warnings and failures remain bounded local policy decisions, not
third-party safety verdicts.

## Release evidence

The tag-gated GitHub Actions workflow builds the wheel and source distribution,
normalizes build timestamps from the tagged commit time, generates a SHA256
checksum manifest, records workflow artifact attestations, and publishes the
same built files as GitHub Release assets. Final tags are explicitly marked as
GitHub Latest; rc tags remain prereleases.

Expected assets:

- `sbom_diff_and_risk-1.1.0-py3-none-any.whl`
- `sbom_diff_and_risk-1.1.0.tar.gz`
- `sbom-diff-and-risk-SHA256SUMS.txt`

Use `docs/verification.md`, `docs/release-provenance.md`, and
`docs/self-provenance.md` for the correct verification path.
Original file line number Diff line number Diff line change
Expand Up @@ -12,7 +12,7 @@ Production PyPI publishing is intentionally deferred, so consumers should not
install `sbom-diff-and-risk` from production PyPI. Use a GitHub Release asset or
a local checkout instead.

The checked-in workflow pins the stable GitHub Release contract, `v1.0.0`.
The checked-in workflow pins the stable GitHub Release contract, `v1.1.0`.

## Minimal policy workflow

Expand Down Expand Up @@ -49,15 +49,15 @@ jobs:
GH_TOKEN: ${{ github.token }}
run: |
mkdir -p .tooling/sbom-diff-risk
gh release download v1.0.0 \
gh release download v1.1.0 \
--repo stacknil/scientific-computing-toolkit \
--pattern "sbom_diff_and_risk-1.0.0-py3-none-any.whl" \
--pattern "sbom_diff_and_risk-1.1.0-py3-none-any.whl" \
--dir .tooling/sbom-diff-risk

- name: Install sbom-diff-risk
run: |
python -m pip install \
.tooling/sbom-diff-risk/sbom_diff_and_risk-1.0.0-py3-none-any.whl
.tooling/sbom-diff-risk/sbom_diff_and_risk-1.1.0-py3-none-any.whl

- name: Run dependency policy
id: compare
Expand Down
8 changes: 4 additions & 4 deletions tools/sbom-diff-and-risk/docs/release-provenance.md
Original file line number Diff line number Diff line change
Expand Up @@ -9,17 +9,17 @@ This document is about the second surface: verifying a GitHub Release and a down

This page is only about the `sbom-diff-and-risk` tool's own GitHub Releases. If you want the quick "which verification page do I need?" guide, start with [verification.md](verification.md).

## v1.0 release policy
## v1.1 release policy

`v1.0.0` is the stable GitHub Release contract and is marked GitHub Latest.
`v1.1.0` is the stable GitHub Release contract and is marked GitHub Latest.
Production PyPI publishing remains deferred as a separate contract.

For `v1.0.0`, stability applies to the CLI, report schemas, policy decision
For `v1.1.0`, stability applies to the CLI, report schemas, policy decision
examples, evidence-confidence labels, reviewer case, and GitHub Release asset
verification path. It does not claim production PyPI availability.

The tag workflow marks rc tags as prereleases and not Latest. It explicitly
marks final tags such as `v1.0.0` as GitHub Latest.
marks final tags such as `v1.1.0` as GitHub Latest.

Release assets produced by the updated workflow also include a deterministic SHA256 checksum manifest named `sbom-diff-and-risk-SHA256SUMS.txt`. The manifest is written with filenames sorted in a stable order. It is not a separate provenance system; it is a local byte-integrity check that helps reviewers confirm downloaded wheel and source distribution files match the hashes published with the same GitHub Release.

Expand Down
2 changes: 1 addition & 1 deletion tools/sbom-diff-and-risk/docs/reviewer-brief.md
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@

`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.

Current stable GitHub release: `v1.0.0`. Production PyPI remains deferred.
Current stable GitHub release: `v1.1.0`. Production PyPI remains deferred.

For the shortest ordered review route, use
[reviewer-path.md](reviewer-path.md).
Expand Down
20 changes: 10 additions & 10 deletions tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md
Original file line number Diff line number Diff line change
Expand Up @@ -14,7 +14,7 @@ workflow templates.

`sbom-diff-and-risk` is a local-first deterministic CLI for comparing SBOMs and dependency manifests. It is designed to produce stable review evidence for dependency changes.

Current stable GitHub release: `v1.0.0`.
Current stable GitHub release: `v1.1.0`.

Core identity:

Expand Down Expand Up @@ -149,19 +149,19 @@ For CI dashboard, job-summary, and local-threshold examples that consume

## Release Verification Path

Start with the GitHub Release for the version under review. For `v1.0.0`,
Start with the GitHub Release for the version under review. For `v1.1.0`,
inspect the release and assets:

```powershell
gh release view v1.0.0 `
gh release view v1.1.0 `
--repo stacknil/scientific-computing-toolkit `
--json tagName,name,isDraft,isPrerelease,assets,url
```

Expected release assets:

- `sbom_diff_and_risk-1.0.0-py3-none-any.whl`
- `sbom_diff_and_risk-1.0.0.tar.gz`
- `sbom_diff_and_risk-1.1.0-py3-none-any.whl`
- `sbom_diff_and_risk-1.1.0.tar.gz`
- `sbom-diff-and-risk-SHA256SUMS.txt`

For this stable release, `isPrerelease` should be `false`.
Expand Down Expand Up @@ -194,13 +194,13 @@ For workflow-built artifacts downloaded from a trusted workflow run, verify
artifact attestations with the signer workflow:

```powershell
gh attestation verify path/to/sbom_diff_and_risk-1.0.0-py3-none-any.whl `
gh attestation verify path/to/sbom_diff_and_risk-1.1.0-py3-none-any.whl `
--repo stacknil/scientific-computing-toolkit `
--signer-workflow stacknil/scientific-computing-toolkit/.github/workflows/sbom-diff-and-risk-ci.yml
```

```powershell
gh attestation verify path/to/sbom_diff_and_risk-1.0.0.tar.gz `
gh attestation verify path/to/sbom_diff_and_risk-1.1.0.tar.gz `
--repo stacknil/scientific-computing-toolkit `
--signer-workflow stacknil/scientific-computing-toolkit/.github/workflows/sbom-diff-and-risk-ci.yml
```
Expand All @@ -210,15 +210,15 @@ releases. Use them only when the repository release is immutable and GitHub has
generated release attestations:

```powershell
gh release view v1.0.0 --repo stacknil/scientific-computing-toolkit --json isImmutable,assets,url
gh release view v1.1.0 --repo stacknil/scientific-computing-toolkit --json isImmutable,assets,url
```

If `isImmutable` is true, release verification can check the release record and
downloaded release assets:

```powershell
gh release verify v1.0.0 --repo stacknil/scientific-computing-toolkit
gh release verify-asset v1.0.0 path/to/sbom_diff_and_risk-1.0.0-py3-none-any.whl --repo stacknil/scientific-computing-toolkit
gh release verify v1.1.0 --repo stacknil/scientific-computing-toolkit
gh release verify-asset v1.1.0 path/to/sbom_diff_and_risk-1.1.0-py3-none-any.whl --repo stacknil/scientific-computing-toolkit
```

If `isImmutable` is false, use the workflow artifact attestation path as the primary artifact verification story.
Expand Down
2 changes: 1 addition & 1 deletion tools/sbom-diff-and-risk/docs/reviewer-path.md
Original file line number Diff line number Diff line change
Expand Up @@ -199,7 +199,7 @@ Use this section only when the review question is about the released
`sbom-diff-and-risk` tool artifacts. It is not the path for judging third-party
dependency safety.

Release status: `v1.0.0` is the stable GitHub release and GitHub Latest.
Release status: `v1.1.0` is the stable GitHub release and GitHub Latest.
`v1.0-rc.1` remains historical prerelease evidence. Production PyPI publishing
is still deferred as a separate contract.

Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -29,15 +29,15 @@ jobs:
GH_TOKEN: ${{ github.token }}
run: |
mkdir -p .tooling/sbom-diff-risk
gh release download v1.0.0 \
gh release download v1.1.0 \
--repo stacknil/scientific-computing-toolkit \
--pattern "sbom_diff_and_risk-1.0.0-py3-none-any.whl" \
--pattern "sbom_diff_and_risk-1.1.0-py3-none-any.whl" \
--dir .tooling/sbom-diff-risk

- name: Install sbom-diff-risk
run: |
python -m pip install \
.tooling/sbom-diff-risk/sbom_diff_and_risk-1.0.0-py3-none-any.whl
.tooling/sbom-diff-risk/sbom_diff_and_risk-1.1.0-py3-none-any.whl

- name: Run dependency policy
id: compare
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
"driver": {
"name": "sbom-diff-risk",
"fullName": "sbom-diff-risk",
"version": "1.1.0.dev0",
"semanticVersion": "1.1.0.dev0",
"version": "1.1.0",
"semanticVersion": "1.1.0",
"rules": [
{
"id": "sdr.new_package",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
"driver": {
"name": "sbom-diff-risk",
"fullName": "sbom-diff-risk",
"version": "1.1.0.dev0",
"semanticVersion": "1.1.0.dev0",
"version": "1.1.0",
"semanticVersion": "1.1.0",
"rules": [
{
"id": "sdr.policy_violation.provenance_required",
Expand Down
4 changes: 2 additions & 2 deletions tools/sbom-diff-and-risk/examples/sample-sarif.sarif
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
"driver": {
"name": "sbom-diff-risk",
"fullName": "sbom-diff-risk",
"version": "1.1.0.dev0",
"semanticVersion": "1.1.0.dev0",
"version": "1.1.0",
"semanticVersion": "1.1.0",
"rules": [
{
"id": "sdr.major_upgrade",
Expand Down
Original file line number Diff line number Diff line change
Expand Up @@ -7,8 +7,8 @@
"driver": {
"name": "sbom-diff-risk",
"fullName": "sbom-diff-risk",
"version": "1.1.0.dev0",
"semanticVersion": "1.1.0.dev0",
"version": "1.1.0",
"semanticVersion": "1.1.0",
"rules": [
{
"id": "sdr.policy_violation.scorecard_below_threshold",
Expand Down
2 changes: 1 addition & 1 deletion tools/sbom-diff-and-risk/pyproject.toml
Original file line number Diff line number Diff line change
Expand Up @@ -4,7 +4,7 @@ build-backend = "setuptools.build_meta"

[project]
name = "sbom-diff-and-risk"
version = "1.1.0.dev0"
version = "1.1.0"
description = "Deterministic SBOM diff CLI with heuristic risk reporting."
readme = { file = "PYPI_DESCRIPTION.md", content-type = "text/markdown" }
requires-python = ">=3.11"
Expand Down
2 changes: 1 addition & 1 deletion tools/sbom-diff-and-risk/src/sbom_diff_risk/__init__.py
Original file line number Diff line number Diff line change
Expand Up @@ -2,4 +2,4 @@

__all__ = ["__version__"]

__version__ = "1.1.0.dev0"
__version__ = "1.1.0"
4 changes: 2 additions & 2 deletions tools/sbom-diff-and-risk/tests/test_ci_consumer_demo.py
Original file line number Diff line number Diff line change
Expand Up @@ -40,8 +40,8 @@ def test_policy_consumer_uploads_policy_json_before_enforcing_exit_code() -> Non
assert "--out-md" not in text
assert "--out-sarif" not in text
assert "tee " not in text
assert "gh release download v1.0.0" in text
assert "sbom_diff_and_risk-1.0.0-py3-none-any.whl" in text
assert "gh release download v1.1.0" in text
assert "sbom_diff_and_risk-1.1.0-py3-none-any.whl" in text

run_index = step_names.index("Run dependency policy")
upload_index = step_names.index("Upload policy JSON")
Expand Down
Loading