diff --git a/tools/sbom-diff-and-risk/docs/reviewer-brief.md b/tools/sbom-diff-and-risk/docs/reviewer-brief.md index 30d6ee6..268894c 100644 --- a/tools/sbom-diff-and-risk/docs/reviewer-brief.md +++ b/tools/sbom-diff-and-risk/docs/reviewer-brief.md @@ -15,7 +15,7 @@ Dependency review often needs evidence that is stable enough for code review, CI | Area | What exists | | --- | --- | | Deterministic local analysis | Compares CycloneDX, SPDX, `requirements.txt`, and conservative `pyproject.toml` inputs without hidden network access by default. | -| Reviewer output | Produces JSON and Markdown reports for dependency diffs, heuristic risk buckets, and policy outcomes. | +| Reviewer output | Produces JSON and Markdown reports for dependency diffs, heuristic risk buckets, and policy outcomes. It can also write compact `summary.json` and policy-only `policy.json` sidecars for CI consumers. | | Security tooling output | Emits a conservative SARIF subset for selected high-signal findings and explicit policy violations. | | Provenance-aware reporting | Optionally records PyPI provenance and integrity evidence when `--enrich-pypi` is enabled. | | Scorecard signals | Optionally records OpenSSF Scorecard evidence when `--enrich-scorecard` is enabled and a repository mapping is explicit enough. | @@ -29,6 +29,7 @@ Dependency review often needs evidence that is stable enough for code review, CI | 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. | | How are policy findings explained? | [policy-decision-explainability.md](policy-decision-explainability.md) documents the policy decision metadata in JSON reports. | +| Can CI consume compact policy decisions? | [policy-decision-ci-cookbook.md](policy-decision-ci-cookbook.md), [examples/sample-policy.json](../examples/sample-policy.json), and [examples/github-actions-policy-consumer.yml](../examples/github-actions-policy-consumer.yml) show the policy sidecar path. | | 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 1d6db35..82745f0 100644 --- a/tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md +++ b/tools/sbom-diff-and-risk/docs/reviewer-evidence-pack.md @@ -37,8 +37,8 @@ sbom-diff-risk compare ` --out-md outputs/report.md ``` -Expected output files: - +Expected output files: + - `outputs/report.json` - `outputs/summary.json` - `outputs/report.md` @@ -55,8 +55,33 @@ No differences means the sample path reproduced the committed example output. `examples/sample-summary.json` is the summary-only artifact for the same run and is expected to match `examples/sample-report.json`'s `summary` object. - -Generate the strict-policy SARIF sample: + +Generate the strict-policy JSON sidecar: + +```powershell +sbom-diff-risk compare ` + --before examples/cdx_before.json ` + --after examples/cdx_after.json ` + --policy examples/policy-strict.yml ` + --out-json outputs/policy-report.json ` + --policy-json outputs/policy.json +``` + +The strict policy example returns exit code `1` because it intentionally +produces blocking local policy findings. The JSON artifacts are still written. + +Compare the sidecar output against the checked-in sample: + +```powershell +Compare-Object (Get-Content examples/sample-policy.json) (Get-Content outputs/policy.json) +``` + +`examples/sample-policy.json` is expected to match the policy-related sections +from `outputs/policy-report.json`, including `summary.policy`, policy finding +lists, and `rule_catalog`. It intentionally omits full report `components` and +`risks`. + +Generate the strict-policy SARIF sample: ```powershell sbom-diff-risk compare ` @@ -86,6 +111,9 @@ and suppressions. For CI job-summary examples that consume policy decision metadata, see [policy-decision-ci-cookbook.md](policy-decision-ci-cookbook.md). +For a copyable GitHub Actions example that captures `outputs/policy.json`, see +[../examples/github-actions-policy-consumer.yml](../examples/github-actions-policy-consumer.yml). + For CI dashboard, job-summary, and local-threshold examples that consume `outputs/summary.json`, see [summary-json-ci-cookbook.md](summary-json-ci-cookbook.md).