Skip to content

release: attest exact sealed SBOM evidence - #797

Draft
seonghobae wants to merge 14 commits into
mainfrom
release/exact-artifact-sbom-attestation
Draft

release: attest exact sealed SBOM evidence#797
seonghobae wants to merge 14 commits into
mainfrom
release/exact-artifact-sbom-attestation

Conversation

@seonghobae

Copy link
Copy Markdown
Contributor

Test-first scope

This draft starts the organization-owned reusable SBOM attestation boundary required by #783 and ContextualWisdomLab/EgressWeave#46.

  • Exact protected-main base: f070c504c1cb06891b800d7ab0cf6ac7d3cf8eae.
  • Initial contract-only commit: 363e4e08ffcf5a27403da007ee2dfdcbda05c534.
  • Exact current RED head: a26f09a9f6c403db1f4db334ec71299a97a4cd7c.

The current head intentionally contains only:

  • a permanent Python contract for the future reusable workflow, trusted verifier, offline bundle, and doctoring; and
  • a dedicated read-only quality workflow pinned to immutable actions, with exact-head checkout, Python 3.10 compilation, and Python 3.14 contract execution.

The RED contract requires the future implementation to:

  • expose only workflow_call, with explicit required repository, exact source SHA, sealed-artifact reference/digest, wheel/sdist/SBOM filenames and digests, source-identity/checksum digests, CycloneDX schema, and predicate type;
  • bind helper checkout to immutable ${{ job.workflow_repository }} and ${{ job.workflow_sha }} rather than caller source or a mutable branch;
  • grant only contents: read, id-token: write, attestations: write, and artifact-metadata: write to the signing boundary;
  • use actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 exactly once for each canonical distribution;
  • treat downloaded artifacts as inert bounded data, never import, build, install, test, execute, or unpack caller-controlled source;
  • independently verify repository/source identity, exact six-file cardinality, digests, strict JSON, CycloneDX 1.7, root artifact binding, and deterministic handoff semantics before signing;
  • cryptographically verify each resulting attestation against the exact predicate and signer identity;
  • export the Sigstore bundles and beginner-readable offline-verification evidence;
  • document the exact-head lifecycle, trust boundary, rollback, incident recovery, nonclaims, and APA 7 primary sources.

No signing workflow or verifier exists on this RED head, so the exact contract must fail for the intended missing implementation rather than pass vacuously. No model, caller, or downloaded file receives OIDC, attestation, artifact-metadata, package, release, ref, pull-request, or repository-write authority.

Do not merge until a later exact GREEN head passes the dedicated quality workflow, complete central tests, 100% production statement/branch coverage and public docstrings for the verifier, Python Security, Security Scan, CodeQL, Semgrep, Secret Scan, OSV, Scorecard, SBOM, completed CodeRabbit/OpenCode/Noema review, qualifying independent non-author approval, zero unresolved valid findings, and every repository protection.

Progresses #783.

Copy link
Copy Markdown
Contributor Author

@opencode-agent Implement the bounded GREEN slice for exact current RED head a26f09a9f6c403db1f4db334ec71299a97a4cd7c on branch release/exact-artifact-sbom-attestation.

The permanent exact-head RED workflow is valid:

  • run 31070177006, job Python 3.10 contract, succeeded;
  • run 31070177006, job Python 3.14 exact contract, failed at the contract with exactly 5 failures because the reusable workflow and doctoring were intentionally absent;
  • the failures are anchored to missing .github/workflows/exact-artifact-sbom-attestation.yml and docs/doctoring/exact-artifact-sbom-attestation.md, not syntax, dependency, checkout, or environment errors;
  • exact-head Security Scan, Secret Scan, OSV-Scanner, Scorecard, and SBOM Generation are successful; remaining security checks must still complete on the GREEN head.

Implement the organization-owned exact-artifact SBOM attestation boundary without changing reviewer identities, model credentials, existing review workflows, protected refs, release jobs, or package publication.

Allowed permanent paths

  • .github/workflows/exact-artifact-sbom-attestation.yml
  • .github/workflows/exact-artifact-sbom-attestation-quality.yml
  • scripts/ci/verify_exact_artifact_sbom_handoff.py
  • tests/test_exact_artifact_sbom_attestation_contract.py
  • new focused tests named tests/test_exact_artifact_sbom_*.py
  • docs/doctoring/exact-artifact-sbom-attestation.md
  • the central reusable-workflow catalogue or README only if needed to register this workflow
  • CHANGELOG.md

Do not add temporary, one-shot, self-modifying, branch-writing, repair, generated-patch, encoded-payload, or model-executing workflows.

Reusable workflow contract

Create .github/workflows/exact-artifact-sbom-attestation.yml with only workflow_call. Require every existing contract input as an explicit required string. Do not infer repository, source, file identity, or digests from mutable branches or filenames discovered at runtime.

Keep the workflow-level token read-only. Scope the credentialed attestation job to the reviewed minimum:

permissions:
  contents: read
  id-token: write
  attestations: write
  artifact-metadata: write

Do not grant package, release, pull-request, issue, ref, workflow, security-event, or repository-content write authority. Do not use secrets: inherit, COPILOT_GITHUB_TOKEN, NVIDIA_NIM_API_KEY, or any model provider.

Checkout the trusted verifier only from the immutable called-workflow identity:

repository: ${{ job.workflow_repository }}
ref: ${{ job.workflow_sha }}
persist-credentials: false

Use a separate trusted-control-plane path. Never checkout the caller repository, caller source SHA, a mutable central branch/tag, or downloaded evidence as executable source.

Download only the explicitly named same-run sealed evidence artifact into a separate untrusted-data path with an immutable official action pin. Verify the caller-supplied artifact digest against trusted GitHub artifact metadata or a cryptographically equivalent fail-closed receipt; GitHub's warning-only digest behavior must not be treated as success. If the platform does not expose a trustworthy exact digest without broadening privileges, fail closed and document the required caller receipt rather than silently weakening the contract.

Trusted verifier

Implement scripts/ci/verify_exact_artifact_sbom_handoff.py as standard-library-only, provider-neutral, data-only verification. It must never import distributions, execute hooks, invoke subprocesses, evaluate code, or extract wheel/sdist archives.

Before any attestation, require:

  • one canonical real evidence root with no symlinked final or ancestor component;
  • exactly six regular direct-child files: one canonical wheel, one canonical sdist, paired .cdx.json files, SOURCE_IDENTITY.json, and SHA256SUMS;
  • finite bounded descriptor reads and descriptor/path identity checks;
  • strict RFC 8259 JSON with duplicate-member and non-finite-number rejection;
  • canonical sorted SHA256SUMS covering exactly the five non-checksum payloads;
  • explicit filename and SHA-256 equality for every caller input;
  • canonical source identity whose repository and 40-character lowercase source SHA equal the explicit inputs;
  • exact CycloneDX 1.7 schema, bomFormat, specVersion, and integer document version;
  • exact root-component artifact SHA-256 and filename-property binding for each distribution;
  • canonical RFC UUIDv5 serial identity where applicable;
  • rehashing of every accepted file and checksum snapshot before emitting a deterministic strict verification manifest;
  • stable non-leaking failures and no runner-local paths or secrets in output.

The verifier must expose a narrow documented CLI and be independently testable without OIDC or GitHub APIs.

Signing and verification

Use immutable actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 exactly twice: once per canonical wheel and sdist. Bind each call to the verified subject name, exact sha256: digest, paired SBOM path, and expected CycloneDX predicate type. Do not rebuild or resolve dependencies.

Capture each action's bundle-path. Before any downstream publication can consume the result, run cryptographic verification against:

  • exact source repository;
  • exact source SHA;
  • signer repository;
  • exact reusable-workflow identity;
  • subject filename and digest;
  • expected CycloneDX predicate type.

Use GitHub CLI attestation verification only as a verifier; it must not publish, create releases, move refs, or mutate repository contents.

Offline evidence

Create a deterministic offline-verification directory containing at least:

  • the strict trusted verification manifest;
  • both Sigstore attestation bundles;
  • trusted-root material required for offline gh attestation verify;
  • a canonical SHA-256 manifest for the offline bundle;
  • beginner-readable offline verification commands and expected identity/predicate checks.

Upload this evidence with an immutable official action pin and finite retention. Keep wheel and sdist as the only package-manager publication inputs; SBOMs and bundles are evidence, not packages.

Quality gates

Extend .github/workflows/exact-artifact-sbom-attestation-quality.yml so the exact GREEN head runs:

  • Python 3.10 compatibility;
  • Python 3.14 focused and complete tests;
  • 100% production statement and branch coverage for the verifier;
  • 100% public docstrings for the verifier;
  • compileall for production and contract tests;
  • workflow source/permissions/action-pin tests;
  • malicious fixtures covering symlinks, nested files, oversized payloads, duplicate JSON keys, NaN/infinity, stale source, digest mismatch, filename mismatch, wrong predicate/schema/version, malformed checksum coverage, artifact cardinality drift, caller-code execution attempts, and output mutation.

Do not weaken existing central full-test coverage or security gates to make this slice pass.

Documentation

Write docs/doctoring/exact-artifact-sbom-attestation.md with:

  • architecture and credential-separation diagram;
  • trust boundary and nonclaims;
  • exact-head lifecycle;
  • caller contract and immutable pinning;
  • incident recovery and rollback;
  • workflow versioning;
  • online and offline verification;
  • SLSA wording restricted to SLSA Build Lx (v1.2) only after every normative requirement is mapped;
  • APA 7 references to CycloneDX 1.7, actions/attest v4.1.0 at the reviewed commit, official GitHub artifact-attestation and offline-verification documentation, in-toto, and SLSA 1.2.

Update CHANGELOG.md and the central workflow catalogue. Keep the PR Draft. Reproduce the complete exact-head central quality and security matrix. Do not ready, approve, auto-merge, merge, tag, release, or publish.

@coderabbitai

coderabbitai Bot commented Aug 6, 2026

Copy link
Copy Markdown

Important

Review skipped

Draft detected.

Please check the settings in the CodeRabbit UI or the .coderabbit.yaml file in this repository. To trigger a single review, invoke the @coderabbitai review command.

⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro Plus

Run ID: 7aba5dec-18a4-4348-aa51-168a78facc5e

You can disable this status message by setting the reviews.review_status to false in the CodeRabbit configuration file.

Use the checkbox below for a quick retry:

  • 🔍 Trigger review

Comment @coderabbitai help to get the list of available commands.

Copy link
Copy Markdown
Contributor Author

@opencode-agent The exact current RED head advanced to 0beb249f1156c9e35c098df990c7f28fb54677f5 through one contract-only refinement; implement against this head, not a26f09a9f6c403db1f4db334ec71299a97a4cd7c.

The refinement closes the artifact-archive identity gap without granting extra authority to the OIDC signer:

  • evidence_artifact_id is now a required explicit input alongside name and digest;
  • a separate verify-evidence-artifact job may hold only actions: read and contents: read;
  • that non-OIDC intake job must query the exact artifact ID in inputs.source_repository and require exact name, SHA-256 digest, non-expired state, and .workflow_run.id == github.run_id before content verification;
  • the credentialed attest-exact-artifacts job must depend on that intake job and retain exactly contents: read, id-token: write, attestations: write, and artifact-metadata: write—no actions: read there;
  • both jobs download the same immutable artifact by exact ID with actions/download-artifact@37930b1c2abaa49bbe596cd826c3c89aef350131 and independently run the trusted content verifier;
  • content-level explicit digests remain the hard integrity gate after download, so the official action's warning-only archive digest behavior cannot silently authorize signing;
  • offline evidence must use actions/upload-artifact@043fb46d1a93c77aae656e7c1c64a875d1fc6a0a and include gh attestation trusted-root material.

No production, workflow, permission, or documentation implementation was added in this commit. Preserve the earlier immutable RED run and reproduce a new exact-current-head RED result before GREEN implementation. All other requirements in comment 5200275244 remain unchanged.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant