From 65f72a08b26ab09d991c12f3b34575b54876a293 Mon Sep 17 00:00:00 2001 From: stacknil Date: Thu, 30 Apr 2026 15:56:52 +0800 Subject: [PATCH] document json report schema and clean public links --- tools/sbom-diff-and-risk/README.md | 60 ++++++------- .../docs/pypi-trusted-publishing-readiness.md | 6 +- .../docs/release-provenance.md | 8 +- .../sbom-diff-and-risk/docs/report-schema.md | 85 +++++++++++++++++++ .../sbom-diff-and-risk/docs/reviewer-brief.md | 1 + .../docs/reviewer-evidence-pack.md | 12 +-- tools/sbom-diff-and-risk/docs/sbom-basics.md | 2 +- .../docs/self-provenance.md | 8 +- tools/sbom-diff-and-risk/docs/verification.md | 14 +-- 9 files changed, 142 insertions(+), 54 deletions(-) create mode 100644 tools/sbom-diff-and-risk/docs/report-schema.md diff --git a/tools/sbom-diff-and-risk/README.md b/tools/sbom-diff-and-risk/README.md index c1a6440..2ab3f5f 100644 --- a/tools/sbom-diff-and-risk/README.md +++ b/tools/sbom-diff-and-risk/README.md @@ -10,9 +10,9 @@ It uses conservative heuristics for change intelligence. By default it does not This project has two different provenance stories: -For a concise reviewer-facing overview, start with [docs/reviewer-brief.md](docs/reviewer-brief.md). For reproducible review evidence and verification commands, use [docs/reviewer-evidence-pack.md](docs/reviewer-evidence-pack.md). +For a concise reviewer-facing overview, start with [docs/reviewer-brief.md](docs/reviewer-brief.md). For reproducible review evidence and verification commands, use [docs/reviewer-evidence-pack.md](docs/reviewer-evidence-pack.md). For machine-readable JSON output shape, see [docs/report-schema.md](docs/report-schema.md). -1. If you want to verify `sbom-diff-and-risk` itself, start with [docs/verification.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/verification.md). +1. If you want to verify `sbom-diff-and-risk` itself, start with [docs/verification.md](docs/verification.md). 2. If you want to use `sbom-diff-and-risk` to analyze third-party dependency provenance, start with [Dependency provenance analysis](#dependency-provenance-analysis-opt-in) and [Dependency provenance reporting](#dependency-provenance-reporting). ## Scope @@ -228,13 +228,13 @@ sbom-diff-risk compare \ --out-json outputs/report-scorecard.json ``` -If you want policy gating, make it explicit with a v3 policy such as [policy-scorecard-minimal.yml](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/policy-scorecard-minimal.yml), which sets `minimum_scorecard_score` and opts into the `scorecard_below_threshold` rule. +If you want policy gating, make it explicit with a v3 policy such as [policy-scorecard-minimal.yml](examples/policy-scorecard-minimal.yml), which sets `minimum_scorecard_score` and opts into the `scorecard_below_threshold` rule. Setting `minimum_scorecard_score` alone is advisory metadata for review. It only affects policy outcomes when `scorecard_below_threshold` is configured explicitly in `block_on`, `warn_on`, or `ignore_rules`. ## Tool Provenance And Verification -This section is about verifying `sbom-diff-and-risk` itself. If you want the shortest path to the right verification instructions, start with [docs/verification.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/verification.md). +This section is about verifying `sbom-diff-and-risk` itself. If you want the shortest path to the right verification instructions, start with [docs/verification.md](docs/verification.md). 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. @@ -249,29 +249,29 @@ This repository also records provenance for `sbom-diff-and-risk` itself by gener Verification docs: -- [docs/verification.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/verification.md) for the quick decision guide -- [docs/self-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/self-provenance.md) for workflow-artifact attestation -- [docs/release-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/release-provenance.md) for release-asset verification and immutable release guidance -- [docs/pypi-trusted-publishing-readiness.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md) for TestPyPI Trusted Publishing readiness and dry-run notes -- [docs/pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md) for the production PyPI decision gate, publisher identity, future workflow shape, and production prerequisites +- [docs/verification.md](docs/verification.md) for the quick decision guide +- [docs/self-provenance.md](docs/self-provenance.md) for workflow-artifact attestation +- [docs/release-provenance.md](docs/release-provenance.md) for release-asset verification and immutable release guidance +- [docs/pypi-trusted-publishing-readiness.md](docs/pypi-trusted-publishing-readiness.md) for TestPyPI Trusted Publishing readiness and dry-run notes +- [docs/pypi-production-publishing-decision.md](docs/pypi-production-publishing-decision.md) for the production PyPI decision gate, publisher identity, future workflow shape, and production prerequisites ## Examples -The [examples/](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples) directory includes: +The [examples/](examples/) directory includes: - before/after inputs for CycloneDX JSON, SPDX JSON, `requirements.txt`, and `pyproject.toml` - dependency-group examples at `examples/pyproject_groups_before.toml` and `examples/pyproject_groups_after.toml` - example policies at `examples/policy-minimal.yml` and `examples/policy-strict.yml` - provenance-aware policy examples at `examples/policy-provenance-minimal.yml` and `examples/policy-provenance-strict.yml` - a Scorecard-aware policy example at `examples/policy-scorecard-minimal.yml` -- a sample pass JSON report at [sample-report.json](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-report.json) -- a sample pass Markdown report at [sample-report.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-report.md) -- sample policy-warn reports at [sample-policy-warn-report.json](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-policy-warn-report.json) and [sample-policy-warn-report.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-policy-warn-report.md) -- sample policy-fail reports at [sample-policy-fail-report.json](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-policy-fail-report.json) and [sample-policy-fail-report.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-policy-fail-report.md) -- a sample SARIF export at [sample-sarif.sarif](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-sarif.sarif) -- provenance-aware sample reports at [sample-provenance-report.json](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-provenance-report.json), [sample-provenance-report.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-provenance-report.md), and [sample-provenance-report.sarif](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-provenance-report.sarif) -- Scorecard-aware sample reports at [sample-scorecard-report.json](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-scorecard-report.json), [sample-scorecard-report.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-scorecard-report.md), and [sample-scorecard-report.sarif](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-scorecard-report.sarif) -- requirements-based sample reports at [sample-requirements-report.json](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-requirements-report.json) and [sample-requirements-report.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/examples/sample-requirements-report.md) +- a sample pass JSON report at [sample-report.json](examples/sample-report.json) +- a sample pass Markdown report at [sample-report.md](examples/sample-report.md) +- sample policy-warn reports at [sample-policy-warn-report.json](examples/sample-policy-warn-report.json) and [sample-policy-warn-report.md](examples/sample-policy-warn-report.md) +- sample policy-fail reports at [sample-policy-fail-report.json](examples/sample-policy-fail-report.json) and [sample-policy-fail-report.md](examples/sample-policy-fail-report.md) +- a sample SARIF export at [sample-sarif.sarif](examples/sample-sarif.sarif) +- provenance-aware sample reports at [sample-provenance-report.json](examples/sample-provenance-report.json), [sample-provenance-report.md](examples/sample-provenance-report.md), and [sample-provenance-report.sarif](examples/sample-provenance-report.sarif) +- Scorecard-aware sample reports at [sample-scorecard-report.json](examples/sample-scorecard-report.json), [sample-scorecard-report.md](examples/sample-scorecard-report.md), and [sample-scorecard-report.sarif](examples/sample-scorecard-report.sarif) +- requirements-based sample reports at [sample-requirements-report.json](examples/sample-requirements-report.json) and [sample-requirements-report.md](examples/sample-requirements-report.md) ## Enforcement Mode @@ -326,21 +326,21 @@ sbom-diff-risk compare \ --out-sarif outputs/report.sarif ``` -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). - -For the shortest path to the tool-verification docs, start with [docs/verification.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/verification.md). - -For details on how this repository attests the tool's own wheel and source distribution artifacts, see [docs/self-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/self-provenance.md). - -For details on how version-tag releases publish those same build outputs as release assets, and how consumers can verify immutable releases with GitHub CLI, see [docs/release-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/release-provenance.md). - -For TestPyPI Trusted Publishing readiness and the completed dry-run path, see [docs/pypi-trusted-publishing-readiness.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md). - -For the production PyPI decision gate, including the intended package name, first-version rule, publisher identity, future workflow shape, and provenance boundaries, see [docs/pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md). +For GitHub code scanning integration guidance and a minimal upload workflow, see [docs/github-code-scanning.md](docs/github-code-scanning.md). + +For the shortest path to the tool-verification docs, start with [docs/verification.md](docs/verification.md). + +For details on how this repository attests the tool's own wheel and source distribution artifacts, see [docs/self-provenance.md](docs/self-provenance.md). + +For details on how version-tag releases publish those same build outputs as release assets, and how consumers can verify immutable releases with GitHub CLI, see [docs/release-provenance.md](docs/release-provenance.md). + +For TestPyPI Trusted Publishing readiness and the completed dry-run path, see [docs/pypi-trusted-publishing-readiness.md](docs/pypi-trusted-publishing-readiness.md). + +For the production PyPI decision gate, including the intended package name, first-version rule, publisher identity, future workflow shape, and provenance boundaries, see [docs/pypi-production-publishing-decision.md](docs/pypi-production-publishing-decision.md). ## Parser Boundaries -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). +Deterministic local mode intentionally supports a conservative subset of packaging syntax. The detailed matrix lives in [docs/parser-boundaries.md](docs/parser-boundaries.md). ### requirements.txt subset diff --git a/tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md b/tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md index feb1d2e..1f4c195 100644 --- a/tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md +++ b/tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md @@ -2,7 +2,7 @@ This page documents the PR 4 TestPyPI / Trusted Publishing dry-run path for `sbom-diff-and-risk`. -The PR 5 production PyPI decision gate is documented separately in [pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md). +The PR 5 production PyPI decision gate is documented separately in [pypi-production-publishing-decision.md](pypi-production-publishing-decision.md). The repository now has a safe GitHub Actions path that always builds and checks the Python distributions, and can publish those already-checked distributions to TestPyPI only when a maintainer explicitly enables the manual upload input. It does not publish to production PyPI. @@ -23,7 +23,7 @@ Current outcome for this PR: - **Trusted Publishing readiness and TestPyPI dry-run completed** after the external TestPyPI publisher was configured and a maintainer manually enabled upload - **No production PyPI publishing** -- **Production PyPI deferred** to the decision gate in [pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md) +- **Production PyPI deferred** to the decision gate in [pypi-production-publishing-decision.md](pypi-production-publishing-decision.md) The workflow file is `.github/workflows/sbom-diff-and-risk-testpypi.yml`. @@ -146,7 +146,7 @@ PR 5 decides: - the GitHub environment name for production, if any - how PyPI distribution provenance should be documented alongside GitHub artifact and release verification -See [pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md) for the current production gate. +See [pypi-production-publishing-decision.md](pypi-production-publishing-decision.md) for the current production gate. ## Current decision diff --git a/tools/sbom-diff-and-risk/docs/release-provenance.md b/tools/sbom-diff-and-risk/docs/release-provenance.md index b541744..2824d8d 100644 --- a/tools/sbom-diff-and-risk/docs/release-provenance.md +++ b/tools/sbom-diff-and-risk/docs/release-provenance.md @@ -7,7 +7,7 @@ This document is about the second surface: verifying a GitHub Release and a downloaded release asset. -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](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/verification.md). +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). 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. @@ -36,7 +36,7 @@ GitHub Release verification is distinct from workflow artifact attestation: Release verification only works for immutable releases. Per GitHub's release integrity and immutable release documentation, immutable releases automatically generate a release attestation and protect release assets from modification after publication. -If immutable releases are not enabled for the repository, the release may still contain assets, but `gh release verify` and `gh release verify-asset` are not the source of truth. In that case, use the workflow-artifact attestation flow from [self-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/self-provenance.md). +If immutable releases are not enabled for the repository, the release may still contain assets, but `gh release verify` and `gh release verify-asset` are not the source of truth. In that case, use the workflow-artifact attestation flow from [self-provenance.md](self-provenance.md). ## Manual verification for a release @@ -69,7 +69,7 @@ gh release verify-asset path/to/sbom_diff_and_risk--py3-none-any. --repo stacknil/scientific-computing-toolkit ``` -If `isImmutable` is `false`, the release asset can still be downloaded, but the supported provenance path for this repository remains the workflow-artifact attestation flow from [self-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/self-provenance.md). +If `isImmutable` is `false`, the release asset can still be downloaded, but the supported provenance path for this repository remains the workflow-artifact attestation flow from [self-provenance.md](self-provenance.md). You can inspect structured output as JSON: @@ -127,4 +127,4 @@ A passing checksum check means the local downloaded wheel and source distributio - `sbom-diff-and-risk-SHA256SUMS.txt` checks local file integrity against the release manifest. It does not replace provenance verification. - GitHub's generated source-code ZIP and tarball downloads are not covered by `gh release verify-asset`. - A successful release verification does not replace the workflow-artifact attestation story; it complements it. -- This repository now has a separate TestPyPI Trusted Publishing readiness workflow, but production PyPI publishing remains deferred. For the production decision gate, publisher identity, future workflow shape, and provenance boundary, see [pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md). +- This repository now has a separate TestPyPI Trusted Publishing readiness workflow, but production PyPI publishing remains deferred. For the production decision gate, publisher identity, future workflow shape, and provenance boundary, see [pypi-production-publishing-decision.md](pypi-production-publishing-decision.md). diff --git a/tools/sbom-diff-and-risk/docs/report-schema.md b/tools/sbom-diff-and-risk/docs/report-schema.md new file mode 100644 index 0000000..ed34c3e --- /dev/null +++ b/tools/sbom-diff-and-risk/docs/report-schema.md @@ -0,0 +1,85 @@ +# JSON report schema + +This document describes the stable, reviewer-facing shape of `sbom-diff-and-risk` JSON reports. The JSON format is intended for machine consumption in CI, review tooling, and audit trails. Human-readable review notes remain in the Markdown report. + +The schema is conservative and additive where possible. Golden sample reports in `examples/` lock important output shape for the default, policy, provenance, and Scorecard paths. + +## Top-level structure + +JSON reports currently use this top-level structure: + +| Field | Description | +| --- | --- | +| `summary` | Compact count-only run summary for deterministic machine consumption. | +| `components` | Added, removed, and changed component records. | +| `risks` | Heuristic risk findings generated from the diff. | +| `policy_evaluation` | Policy evaluation details when policy state is represented in the report. | +| `blocking_findings` | Policy findings that make the run fail. | +| `warning_findings` | Policy findings that are warnings only. | +| `suppressed_findings` | Policy findings suppressed by policy configuration. | +| `rule_catalog` | Policy rule metadata used to interpret policy findings. | +| `provenance_summary` | PyPI provenance evidence summary when available from report presentation. | +| `attestation_summary` | PyPI file attestation summary when available from report presentation. | +| `scorecard_summary` | OpenSSF Scorecard evidence summary when available from report presentation. | +| `enrichment_metadata` | Top-level enrichment metadata used by trust-signal report sections. | +| `trust_signal_notes` | Review notes for provenance and Scorecard trust signals. | +| `metadata` | Run metadata such as input formats, generation time, strict mode, policy state, and enrichment state. | +| `notes` | Additional report notes. | + +When provenance policy fields are relevant, reports may also include `provenance_policy` and `provenance_policy_impact`. Consumers should treat unrecognized top-level fields as additive report data. + +## Summary contract + +`summary` is the stable, compact entry point for automation that needs counts without walking the full report. + +Base `summary` fields: + +| Field | Meaning | +| --- | --- | +| `added` | Number of components present only in the after input. | +| `removed` | Number of components present only in the before input. | +| `changed` | Number of components present in both inputs with a detected change. | +| `risk_counts` | Map of risk bucket name to count. | + +There is intentionally no `unchanged` field. The current diff model does not track unchanged components, so reporting an unchanged count would imply a model guarantee that does not exist. + +`summary.policy` appears only when a policy is applied. Absence of `summary.policy` means policy was not used, not that policy evaluation failed. + +| Field | Meaning | +| --- | --- | +| `summary.policy.status` | `pass`, `warn`, or `fail`. | +| `summary.policy.blocking` | Count of blocking policy violations. | +| `summary.policy.warning` | Count of warning policy violations. | +| `summary.policy.suppressed` | Count of suppressed policy violations. | + +`summary.enrichment` appears only when PyPI or Scorecard enrichment is used. Absence of `summary.enrichment` means enrichment was not used, not that enrichment failed. + +| Field | Meaning | +| --- | --- | +| `summary.enrichment.status` | Currently `used` when enrichment ran. | +| `summary.enrichment.mode` | Enrichment mode recorded for the run. | +| `summary.enrichment.pypi.candidate_components` | Count of components considered for PyPI enrichment. | +| `summary.enrichment.pypi.supported_components` | Count of components supported by PyPI enrichment. | +| `summary.enrichment.pypi.status_counts` | Sorted map of PyPI enrichment status names to counts. | +| `summary.enrichment.scorecard.candidate_components` | Count of components considered for Scorecard enrichment. | +| `summary.enrichment.scorecard.supported_components` | Count of components supported by Scorecard enrichment. | +| `summary.enrichment.scorecard.status_counts` | Sorted map of Scorecard enrichment status names to counts. | + +Provider-specific `pypi` and `scorecard` objects appear only for the providers used in that run. Their `status_counts` maps are sorted by key to keep output stable for tests and downstream consumers. + +## Stability notes + +- JSON reports are intended for machine consumption. +- Golden samples lock important output shape for stable reviewer and CI expectations. +- The schema is conservative and additive where possible. +- Missing `summary.policy` means policy was not applied. +- Missing `summary.enrichment` means PyPI and Scorecard enrichment were not used. +- Runtime details remain in the fuller report fields; `summary` stays count-only. + +## Non-claims + +- The report does not resolve CVEs. +- The report does not produce package safety verdicts. +- Default runs do not perform hidden network access. +- PyPI and Scorecard enrichment are opt-in. +- Missing provenance, attestation, or Scorecard evidence is an evidence gap, not proof of compromise. diff --git a/tools/sbom-diff-and-risk/docs/reviewer-brief.md b/tools/sbom-diff-and-risk/docs/reviewer-brief.md index 67fa952..a0de9dd 100644 --- a/tools/sbom-diff-and-risk/docs/reviewer-brief.md +++ b/tools/sbom-diff-and-risk/docs/reviewer-brief.md @@ -25,6 +25,7 @@ Dependency review often needs evidence that is stable enough for code review, CI | --- | --- | | What does the tool do? | `README.md`, examples, tests, and generated sample reports. | | How can a reviewer reproduce the core evidence? | [reviewer-evidence-pack.md](reviewer-evidence-pack.md) for demo, release, TestPyPI, and SARIF verification paths. | +| What is the stable JSON shape? | [report-schema.md](report-schema.md) documents the machine-readable report structure and `summary` contract. | | Are default runs offline? | CLI docs, tests for no-enrichment behavior, and explicit enrichment flags. | | Can code scanning consume the output? | `docs/github-code-scanning.md` and `examples/sample-sarif.sarif`. | | Can the tool's own artifacts be verified? | `docs/self-provenance.md` for workflow artifact attestations. | diff --git a/tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md b/tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md index f6b49ee..a240ecd 100644 --- a/tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md +++ b/tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md @@ -64,9 +64,11 @@ Compare the SARIF output against the sample: Compare-Object (Get-Content examples/sample-sarif.sarif) (Get-Content outputs/report.sarif) ``` -The SARIF sample is intentionally conservative. It covers selected high-signal findings and explicit policy violations, not every enrichment fact. - -## Release Verification Path +The SARIF sample is intentionally conservative. It covers selected high-signal findings and explicit policy violations, not every enrichment fact. + +For consumers of the JSON output, see [report-schema.md](report-schema.md). It documents the stable `summary` contract, including conditional `summary.policy` and `summary.enrichment` fields. + +## Release Verification Path Start with the GitHub Release for the version under review. For `v0.5.0`, inspect the release and assets: @@ -184,8 +186,8 @@ Avoid overclaiming: ## 30-Second Reviewer Checklist - Can I identify what the tool does? Read `README.md` and `reviewer-brief.md`. -- Can I reproduce a deterministic demo? Run the CycloneDX example and compare `outputs/report.*` to `examples/sample-report.*`. -- Can I see machine-readable security output? Inspect or regenerate `examples/sample-sarif.sarif`. +- Can I reproduce a deterministic demo? Run the CycloneDX example and compare `outputs/report.*` to `examples/sample-report.*`. +- Can I see machine-readable security output? Inspect or regenerate `examples/sample-sarif.sarif`, and read `report-schema.md` for JSON report shape. - Can I verify release/distribution evidence? Read `verification.md`, `self-provenance.md`, and `release-provenance.md`. - Can I distinguish TestPyPI from production PyPI? Read `pypi-trusted-publishing-readiness.md` and `pypi-production-publishing-decision.md`. - Can I state the non-claims? No CVE scanner, no reputation oracle, no dependency safety verdicts, no production PyPI package yet. diff --git a/tools/sbom-diff-and-risk/docs/sbom-basics.md b/tools/sbom-diff-and-risk/docs/sbom-basics.md index 04f64d9..bf1709b 100644 --- a/tools/sbom-diff-and-risk/docs/sbom-basics.md +++ b/tools/sbom-diff-and-risk/docs/sbom-basics.md @@ -29,7 +29,7 @@ For v0.2, the tool is intentionally limited to local-file parsing, normalization These boundaries are deliberate so the tool can stay deterministic and explicit about what it does and does not parse. -For the detailed supported/unsupported matrix, see [parser-boundaries.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/parser-boundaries.md). +For the detailed supported/unsupported matrix, see [parser-boundaries.md](parser-boundaries.md). ## Normalization goals diff --git a/tools/sbom-diff-and-risk/docs/self-provenance.md b/tools/sbom-diff-and-risk/docs/self-provenance.md index 94c3604..ee8223b 100644 --- a/tools/sbom-diff-and-risk/docs/self-provenance.md +++ b/tools/sbom-diff-and-risk/docs/self-provenance.md @@ -2,7 +2,7 @@ `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. -This page is only about verifying the `sbom-diff-and-risk` tool's own build artifacts. If you want the top-level decision guide, start with [verification.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/verification.md). If you want to analyze third-party dependency provenance with the CLI, go back to the README's dependency provenance sections instead of this page. +This page is only about verifying the `sbom-diff-and-risk` tool's own build artifacts. If you want the top-level decision guide, start with [verification.md](verification.md). If you want to analyze third-party dependency provenance with the CLI, go back to the README's dependency provenance sections instead of this page. ## What is attested in this repository @@ -15,7 +15,7 @@ Those two files are uploaded together as the workflow artifact named `sbom-diff- On version tags matching `v*`, the same workflow also publishes those exact wheel and sdist files as GitHub Release assets for the matching tag. The workflow-artifact attestation story remains the build-provenance source of truth for the files themselves; release verification is an additional GitHub-hosted surface layered on top of those same bytes. -This repository does not currently publish production PyPI Trusted Publishing provenance. The separate TestPyPI readiness workflow is a pre-production validation path and is documented in [pypi-trusted-publishing-readiness.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md). The production PyPI decision gate is documented in [pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md). Release verification is separate from workflow-artifact attestations and depends on GitHub immutable releases being enabled for the repository. When immutable releases are enabled, GitHub automatically generates a release attestation covering the published release record and its attached assets. +This repository does not currently publish production PyPI Trusted Publishing provenance. The separate TestPyPI readiness workflow is a pre-production validation path and is documented in [pypi-trusted-publishing-readiness.md](pypi-trusted-publishing-readiness.md). The production PyPI decision gate is documented in [pypi-production-publishing-decision.md](pypi-production-publishing-decision.md). Release verification is separate from workflow-artifact attestations and depends on GitHub immutable releases being enabled for the repository. When immutable releases are enabled, GitHub automatically generates a release attestation covering the published release record and its attached assets. ## Workflow and permissions @@ -103,9 +103,9 @@ If these same wheel or source distribution bytes are attached to a GitHub releas - use `gh attestation verify` when you want to verify the workflow-built file against the workflow artifact attestation - use `gh release verify` and `gh release verify-asset` when you want to verify the GitHub Release record and a downloaded release asset from an immutable release -These flows complement each other. The workflow-artifact attestation answers "were these bytes built by this workflow?", while immutable release verification answers "does this published release and local release asset exactly match GitHub's release attestation?" See [release-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/release-provenance.md) for the release-specific consumer flow. +These flows complement each other. The workflow-artifact attestation answers "were these bytes built by this workflow?", while immutable release verification answers "does this published release and local release asset exactly match GitHub's release attestation?" See [release-provenance.md](release-provenance.md) for the release-specific consumer flow. -Future production PyPI Trusted Publishing provenance will be a third, separate surface. It will answer whether a PyPI distribution was uploaded through the configured GitHub publisher identity, not whether the file is byte-identical to a GitHub workflow artifact or release asset. See [pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md) for that boundary. +Future production PyPI Trusted Publishing provenance will be a third, separate surface. It will answer whether a PyPI distribution was uploaded through the configured GitHub publisher identity, not whether the file is byte-identical to a GitHub workflow artifact or release asset. See [pypi-production-publishing-decision.md](pypi-production-publishing-decision.md) for that boundary. ## How this complements the tool's own analysis diff --git a/tools/sbom-diff-and-risk/docs/verification.md b/tools/sbom-diff-and-risk/docs/verification.md index cc10945..a903597 100644 --- a/tools/sbom-diff-and-risk/docs/verification.md +++ b/tools/sbom-diff-and-risk/docs/verification.md @@ -8,9 +8,9 @@ Use this page when you are trying to figure out which provenance or verification Use the tool provenance docs: -- [self-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/self-provenance.md) if you want to verify the workflow-built wheel or source distribution with `gh attestation verify` -- [release-provenance.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/release-provenance.md) if you want to verify a GitHub Release or a downloaded release asset with `gh release verify` or `gh release verify-asset` -- [pypi-trusted-publishing-readiness.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md) if you want to know whether this package is ready for PyPI Trusted Publishing +- [self-provenance.md](self-provenance.md) if you want to verify the workflow-built wheel or source distribution with `gh attestation verify` +- [release-provenance.md](release-provenance.md) if you want to verify a GitHub Release or a downloaded release asset with `gh release verify` or `gh release verify-asset` +- [pypi-trusted-publishing-readiness.md](pypi-trusted-publishing-readiness.md) if you want to know whether this package is ready for PyPI Trusted Publishing Current boundaries: @@ -21,15 +21,15 @@ Current boundaries: - release verification depends on immutable releases being enabled for the repository - the TestPyPI readiness workflow is `sbom-diff-and-risk-testpypi` - the TestPyPI Trusted Publishing dry-run has completed for version `0.4.1` -- production PyPI publishing remains deferred behind the gate in [pypi-production-publishing-decision.md](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md) +- production PyPI publishing remains deferred behind the gate in [pypi-production-publishing-decision.md](pypi-production-publishing-decision.md) ### 2. "How do I use `sbom-diff-and-risk` to analyze third-party dependency provenance?" Use the dependency-analysis docs in the README: -- [Dependency provenance analysis](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/README.md#dependency-provenance-analysis-opt-in) -- [Dependency provenance reporting](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/README.md#dependency-provenance-reporting) -- [Enforcement mode](D:/OneDrive/Code/scientific-computing-toolkit/tools/sbom-diff-and-risk/README.md#enforcement-mode) +- [Dependency provenance analysis](../README.md#dependency-provenance-analysis-opt-in) +- [Dependency provenance reporting](../README.md#dependency-provenance-reporting) +- [Enforcement mode](../README.md#enforcement-mode) Current boundaries: