-
Notifications
You must be signed in to change notification settings - Fork 0
[codex] Add reviewer evidence pack #22
New issue
Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.
By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.
Already on GitHub? Sign in to your account
Merged
Merged
Changes from all commits
Commits
File filter
Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
There are no files selected for viewing
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,69 +1,70 @@ | ||
| # scientific-computing-toolkit | ||
|
|
||
| This repository is a portfolio space for scientific-computing infrastructure, systems tooling, and supply-chain-security experiments that favor deterministic behavior, auditable outputs, and clear release evidence. | ||
|
|
||
| ## Current Flagship Project | ||
|
|
||
| [`tools/sbom-diff-and-risk`](tools/sbom-diff-and-risk/README.md) is the current flagship tool. It compares SBOMs and dependency manifests, produces JSON, Markdown, and SARIF review artifacts, supports local policy checks, and can optionally record PyPI provenance and OpenSSF Scorecard evidence. | ||
|
|
||
| For a fast reviewer overview, start with the [`sbom-diff-and-risk` reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md). | ||
|
|
||
| ## Why This Repository Exists | ||
|
|
||
| Scientific and security-oriented engineering often needs small, inspectable tools that make evidence easier to review. This repository collects projects that emphasize: | ||
|
|
||
| - deterministic local analysis | ||
| - machine-readable security and review output | ||
| - conservative policy checks | ||
| - explicit provenance and release verification boundaries | ||
| - documentation that separates tool behavior from distribution evidence | ||
|
|
||
| ## Project Map | ||
|
|
||
| | Project | Status | What to review | | ||
| | --- | --- | --- | | ||
| | [`sbom-diff-and-risk`](tools/sbom-diff-and-risk/README.md) | Released at `v0.5.0` | Deterministic SBOM/dependency diffing, JSON/Markdown/SARIF output, local policy checks, optional provenance and Scorecard evidence. | | ||
|
|
||
| Useful entry points: | ||
|
|
||
| # scientific-computing-toolkit | ||
| This repository is a portfolio space for scientific-computing infrastructure, systems tooling, and supply-chain-security experiments that favor deterministic behavior, auditable outputs, and clear release evidence. | ||
| ## Current Flagship Project | ||
| [`tools/sbom-diff-and-risk`](tools/sbom-diff-and-risk/README.md) is the current flagship tool. It compares SBOMs and dependency manifests, produces JSON, Markdown, and SARIF review artifacts, supports local policy checks, and can optionally record PyPI provenance and OpenSSF Scorecard evidence. | ||
| For a fast reviewer overview, start with the [`sbom-diff-and-risk` reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md). | ||
| ## Why This Repository Exists | ||
| Scientific and security-oriented engineering often needs small, inspectable tools that make evidence easier to review. This repository collects projects that emphasize: | ||
| - deterministic local analysis | ||
| - machine-readable security and review output | ||
| - conservative policy checks | ||
| - explicit provenance and release verification boundaries | ||
| - documentation that separates tool behavior from distribution evidence | ||
| ## Project Map | ||
| | Project | Status | What to review | | ||
| | --- | --- | --- | | ||
| | [`sbom-diff-and-risk`](tools/sbom-diff-and-risk/README.md) | Released at `v0.5.0` | Deterministic SBOM/dependency diffing, JSON/Markdown/SARIF output, local policy checks, optional provenance and Scorecard evidence. | | ||
| Useful entry points: | ||
| - [`sbom-diff-and-risk` README](tools/sbom-diff-and-risk/README.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) | ||
| - [v0.5.0 release notes](tools/sbom-diff-and-risk/RELEASE_NOTES_v0.5.0.md) | ||
| - [Examples](tools/sbom-diff-and-risk/examples/) | ||
|
|
||
| ## Verification And Release Evidence | ||
|
|
||
| `sbom-diff-and-risk` has separate verification surfaces. They are related, but they do not prove the same thing. | ||
|
|
||
| | Evidence | Where to start | | ||
| | --- | --- | | ||
| | Tool verification guide | [`docs/verification.md`](tools/sbom-diff-and-risk/docs/verification.md) | | ||
| | GitHub Release asset verification | [`docs/release-provenance.md`](tools/sbom-diff-and-risk/docs/release-provenance.md) | | ||
| | TestPyPI Trusted Publishing dry-run | [`docs/pypi-trusted-publishing-readiness.md`](tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md) | | ||
| | Production PyPI decision gate | [`docs/pypi-production-publishing-decision.md`](tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md) | | ||
|
|
||
| The TestPyPI Trusted Publishing dry-run has been validated. Production PyPI publishing is intentionally deferred. | ||
|
|
||
| ## What This Repository Intentionally Does Not Claim | ||
|
|
||
| - It does not claim that `sbom-diff-and-risk` is a vulnerability scanner. | ||
| - It does not claim to resolve CVEs, advisories, exploitability, or package safety verdicts. | ||
| - It does not treat optional provenance or Scorecard evidence as proof that a dependency is safe. | ||
| - It does not imply that production PyPI publishing is enabled. | ||
| - It does not treat GitHub release verification, GitHub workflow artifact attestations, and PyPI Trusted Publishing provenance as interchangeable evidence. | ||
|
|
||
| ## Reviewer Quick Path | ||
|
|
||
| 1. Read the [`sbom-diff-and-risk` reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md). | ||
| 2. Skim the [`sbom-diff-and-risk` README](tools/sbom-diff-and-risk/README.md) for CLI scope and examples. | ||
| 3. Check the [v0.5.0 release notes](tools/sbom-diff-and-risk/RELEASE_NOTES_v0.5.0.md). | ||
| 4. Use the [verification guide](tools/sbom-diff-and-risk/docs/verification.md) to choose the right provenance check. | ||
| 5. Inspect the [examples](tools/sbom-diff-and-risk/examples/) for sample reports and policy files. | ||
|
|
||
| ## Status | ||
|
|
||
| - Current flagship release: `sbom-diff-and-risk` `v0.5.0` | ||
| - GitHub Release assets: available for `v0.5.0` | ||
| - TestPyPI Trusted Publishing dry-run: completed | ||
| - Production PyPI publishing: intentionally deferred | ||
|
|
||
| ## Verification And Release Evidence | ||
| `sbom-diff-and-risk` has separate verification surfaces. They are related, but they do not prove the same thing. | ||
| | Evidence | Where to start | | ||
| | --- | --- | | ||
| | Tool verification guide | [`docs/verification.md`](tools/sbom-diff-and-risk/docs/verification.md) | | ||
| | GitHub Release asset verification | [`docs/release-provenance.md`](tools/sbom-diff-and-risk/docs/release-provenance.md) | | ||
| | TestPyPI Trusted Publishing dry-run | [`docs/pypi-trusted-publishing-readiness.md`](tools/sbom-diff-and-risk/docs/pypi-trusted-publishing-readiness.md) | | ||
| | Production PyPI decision gate | [`docs/pypi-production-publishing-decision.md`](tools/sbom-diff-and-risk/docs/pypi-production-publishing-decision.md) | | ||
| The TestPyPI Trusted Publishing dry-run has been validated. Production PyPI publishing is intentionally deferred. | ||
| ## What This Repository Intentionally Does Not Claim | ||
| - It does not claim that `sbom-diff-and-risk` is a vulnerability scanner. | ||
| - It does not claim to resolve CVEs, advisories, exploitability, or package safety verdicts. | ||
| - It does not treat optional provenance or Scorecard evidence as proof that a dependency is safe. | ||
| - It does not imply that production PyPI publishing is enabled. | ||
| - It does not treat GitHub release verification, GitHub workflow artifact attestations, and PyPI Trusted Publishing provenance as interchangeable evidence. | ||
| ## Reviewer Quick Path | ||
| 1. Read the [`sbom-diff-and-risk` reviewer brief](tools/sbom-diff-and-risk/docs/reviewer-brief.md). | ||
| 2. Skim the [`sbom-diff-and-risk` README](tools/sbom-diff-and-risk/README.md) for CLI scope and examples. | ||
| 3. Check the [v0.5.0 release notes](tools/sbom-diff-and-risk/RELEASE_NOTES_v0.5.0.md). | ||
| 4. Use the [verification guide](tools/sbom-diff-and-risk/docs/verification.md) to choose the right provenance check. | ||
| 5. Inspect the [examples](tools/sbom-diff-and-risk/examples/) for sample reports and policy files. | ||
| ## Status | ||
| - Current flagship release: `sbom-diff-and-risk` `v0.5.0` | ||
| - GitHub Release assets: available for `v0.5.0` | ||
| - TestPyPI Trusted Publishing dry-run: completed | ||
| - Production PyPI publishing: intentionally deferred | ||
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
| Original file line number | Diff line number | Diff line change |
|---|---|---|
| @@ -1,56 +1,58 @@ | ||
| # Reviewer brief | ||
|
|
||
| ## Summary | ||
|
|
||
| `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. | ||
|
|
||
| ## Why this project matters | ||
|
|
||
| Dependency review often needs evidence that is stable enough for code review, CI, and audit trails. This project turns dependency changes into repeatable findings, optional policy outcomes, and machine-readable security output while keeping default analysis offline and file-based. | ||
|
|
||
| ## Capability map | ||
|
|
||
| | 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. | | ||
| | 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. | | ||
| | Policy support | Supports local YAML policies for thresholds, source allowlists, provenance requirements, and Scorecard thresholds. | | ||
|
|
||
| # Reviewer brief | ||
| ## Summary | ||
| `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. | ||
| ## Why this project matters | ||
| Dependency review often needs evidence that is stable enough for code review, CI, and audit trails. This project turns dependency changes into repeatable findings, optional policy outcomes, and machine-readable security output while keeping default analysis offline and file-based. | ||
| ## Capability map | ||
| | 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. | | ||
| | 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. | | ||
| | Policy support | Supports local YAML policies for thresholds, source allowlists, provenance requirements, and Scorecard thresholds. | | ||
| ## Evidence map | ||
|
|
||
| | Question | Evidence path | | ||
| | --- | --- | | ||
| | 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. | | ||
| | 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. | | ||
| | Can GitHub release assets be verified? | `docs/release-provenance.md` for release asset verification. | | ||
| | Did Trusted Publishing get exercised safely? | `docs/pypi-trusted-publishing-readiness.md` documents the completed TestPyPI dry-run. | | ||
| | Is production PyPI enabled? | `docs/pypi-production-publishing-decision.md` documents that production PyPI is intentionally deferred. | | ||
|
|
||
| ## Quick verification path | ||
|
|
||
| | Can GitHub release assets be verified? | `docs/release-provenance.md` for release asset verification. | | ||
| | Did Trusted Publishing get exercised safely? | `docs/pypi-trusted-publishing-readiness.md` documents the completed TestPyPI dry-run. | | ||
| | Is production PyPI enabled? | `docs/pypi-production-publishing-decision.md` documents that production PyPI is intentionally deferred. | | ||
| ## Quick verification path | ||
| 1. Read this brief for the 30-second project shape. | ||
| 2. Read `README.md` for CLI scope, supported inputs, and examples. | ||
| 3. Read `docs/verification.md` to choose the right verification path. | ||
| 4. Use `docs/self-provenance.md` when verifying workflow-built wheel or source distribution artifacts. | ||
| 5. Use `docs/release-provenance.md` when verifying GitHub Release assets. | ||
| 6. Use `docs/pypi-production-publishing-decision.md` before making any production PyPI publishing decision. | ||
|
|
||
| ## What this project intentionally does not claim | ||
|
|
||
| - It does not claim to be a vulnerability scanner. | ||
| - It does not resolve CVEs, advisories, or exploitability. | ||
| - It does not score package reputation or declare packages safe. | ||
| - It does not perform hidden network enrichment. | ||
| - It does not treat TestPyPI success as production PyPI readiness. | ||
| - It does not currently publish to production PyPI. | ||
| - It does not treat PyPI Trusted Publishing provenance, GitHub workflow artifact attestations, and GitHub Release asset verification as interchangeable evidence. | ||
|
|
||
| ## Resume / application wording | ||
|
|
||
| Built `sbom-diff-and-risk`, a deterministic SBOM and dependency diff CLI that produces JSON, Markdown, and SARIF review artifacts; supports local policy checks and optional provenance/Scorecard evidence; and documents a release verification story covering GitHub artifact attestations, GitHub Release assets, TestPyPI Trusted Publishing validation, and intentionally deferred production PyPI publishing. | ||
|
|
||
| 2. Read [reviewer-evidence-pack.md](reviewer-evidence-pack.md) for reproducible commands and evidence paths. | ||
| 3. Read `README.md` for CLI scope, supported inputs, and examples. | ||
| 4. Read `docs/verification.md` to choose the right verification path. | ||
| 5. Use `docs/self-provenance.md` when verifying workflow-built wheel or source distribution artifacts. | ||
| 6. Use `docs/release-provenance.md` when verifying GitHub Release assets. | ||
| 7. Use `docs/pypi-production-publishing-decision.md` before making any production PyPI publishing decision. | ||
|
|
||
| ## What this project intentionally does not claim | ||
|
|
||
| - It does not claim to be a vulnerability scanner. | ||
| - It does not resolve CVEs, advisories, or exploitability. | ||
| - It does not score package reputation or declare packages safe. | ||
| - It does not perform hidden network enrichment. | ||
| - It does not treat TestPyPI success as production PyPI readiness. | ||
| - It does not currently publish to production PyPI. | ||
| - It does not treat PyPI Trusted Publishing provenance, GitHub workflow artifact attestations, and GitHub Release asset verification as interchangeable evidence. | ||
|
|
||
| ## Resume / application wording | ||
|
|
||
| Built `sbom-diff-and-risk`, a deterministic SBOM and dependency diff CLI that produces JSON, Markdown, and SARIF review artifacts; supports local policy checks and optional provenance/Scorecard evidence; and documents a release verification story covering GitHub artifact attestations, GitHub Release assets, TestPyPI Trusted Publishing validation, and intentionally deferred production PyPI publishing. | ||
|
|
Oops, something went wrong.
Add this suggestion to a batch that can be applied as a single commit.
This suggestion is invalid because no changes were made to the code.
Suggestions cannot be applied while the pull request is closed.
Suggestions cannot be applied while viewing a subset of changes.
Only one suggestion per line can be applied in a batch.
Add this suggestion to a batch that can be applied as a single commit.
Applying suggestions on deleted lines is not supported.
You must change the existing code in this line in order to create a valid suggestion.
Outdated suggestions cannot be applied.
This suggestion has been applied or marked resolved.
Suggestions cannot be applied from pending reviews.
Suggestions cannot be applied on multi-line comments.
Suggestions cannot be applied while the pull request is queued to merge.
Suggestion cannot be applied right now. Please check back later.
There was a problem hiding this comment.
Choose a reason for hiding this comment
The reason will be displayed to describe this comment to others. Learn more.
This commit rewrites
README.md(and alsotools/sbom-diff-and-risk/docs/reviewer-brief.md) with CRLF line endings, which makesgit diff --checkreport trailing whitespace on nearly every touched line (exit code 2). That introduces avoidable whitespace-check failures and noisy future diffs/merges; these docs should be saved with LF endings to keep the repo’s diff hygiene intact.Useful? React with 👍 / 👎.