release: provide organization-owned exact-artifact SBOM attestation workflow #783

Buyer-visible and cross-repository gap

ContextualWisdomLab/EgressWeave now generates deterministic CycloneDX 1.7 SBOMs for each exact wheel and source distribution, but its repository-local release workflow contains publication identities and is therefore the wrong trust boundary for a pull-request branch to add or modify SBOM attestation behavior. The organization needs an immutable, credential-separated reusable workflow that can be consumed by EgressWeave, naruon, and other CWL services without granting model- or branch-controlled source a publication path.

This issue is the organization-level implementation dependency for ContextualWisdomLab/EgressWeave#46.

Trust-boundary requirements

• The reusable workflow source must be organization-owned, independently reviewed, and invoked by immutable commit SHA rather than a mutable branch or tag.
• The caller and reusable workflow must bind every operation to the caller's exact protected-main commit and independently verified artifact digests.
• No job holding id-token: write, attestations: write, artifact-metadata: write, package publication, release, tag, or repository write authority may execute caller-controlled or model-modified source.
• The attestation job must consume a sealed artifact set produced and verified by a credential-free build/verifier job; it must not rebuild or resolve mutable dependencies.
• Required permissions must be job-scoped and least privilege. The reviewed actions/attest v4.1.0 contract requires contents: read, id-token: write, attestations: write, and artifact-metadata: write; the last permission creates the GitHub artifact storage record and is not package, release, tag, or repository-content publication authority. All publication identities remain separate.
• A pull-request branch must not be able to modify the effective reusable workflow source, retarget its immutable pin, publish, move refs, push branches, or self-modify workflows before independent review and exact-tree verification.
• Stale-head, wrong-repository, wrong-workflow, wrong-predicate, wrong-digest, incomplete-artifact, mutable-action, excessive-permission, and caller-code-under-credential states must fail closed.

Acceptance criteria

• Add a reusable workflow that accepts only explicit artifact names/digests, repository identity, exact source commit, expected predicate type/schema, and a sealed evidence artifact reference.
• Verify the caller is an approved CWL repository and the source equals the exact protected default-branch head before accepting evidence.
• Download only the sealed, exact-SHA evidence set; verify SHA256SUMS, canonical artifact cardinality, artifact digests, CycloneDX 1.7 schema identity, strict JSON representability, and SBOM root-component digest binding before attestation.
• Generate one signed SBOM attestation per canonical distribution with immutable actions/attest@59d89421af93a897026c735860bf21b6eb4f7b26 (v4.1.0) or a later independently reviewed commit pin; record the reviewed action commit and upstream release in documentation.
• Grant only contents: read, id-token: write, attestations: write, and artifact-metadata: write to the attestation job, unless a later pinned action contract demonstrably removes a permission; deny contents, packages, pull-request, release, and ref write authority.
• Verify each attestation cryptographically against the exact repository, workflow identity, source commit, subject digest, and expected SBOM predicate before any downstream release/publication job can proceed.
• Export an offline-verification bundle and beginner-readable commands for acquired or air-gapped environments.
• Keep PyPI/package-manager publication inputs limited to canonical distributions; SBOMs, checksums, and attestation bundles remain release evidence rather than extra packages.
• Add contract tests that reject mutable action refs, missing/excess permissions, branch refs, unpinned caller use, stale source heads, incomplete pagination, artifact cardinality drift, digest mismatch, predicate/schema mismatch, non-strict JSON, verification after publication, and execution of caller code under credentialed jobs.
• Add threat model, incident recovery, keyless-signing assumptions, exact-head lifecycle, reusable-workflow versioning, and rollback guidance under docs/.
• Update CHANGELOG.md and the organization workflow catalogue.
• State any achieved SLSA level only as SLSA Build Lx (v1.2) after mapping every normative requirement to independently verified evidence; do not infer a level from attestations alone.

Integration sequence

1. Implement and independently review the organization-owned reusable workflow.
2. Merge and pin its exact commit.
3. In EgressWeave, add only a narrowly scoped caller that passes already verified exact artifacts and cannot alter the reusable workflow implementation.
4. Re-run EgressWeave release-contract tests, security gates, package acceptance, provenance verification, and independent review at the exact integrated head.

Primary references (APA 7th)

Ecma International, & OWASP Foundation. (2025). CycloneDX specification 1.7 (ECMA-424). https://cyclonedx.org/specification/overview/

GitHub. (2026). Generate signed attestations for workflow artifacts [Computer software documentation]. actions/attest (Version 4.1.0, commit 59d89421af93a897026c735860bf21b6eb4f7b26). https://github.com/actions/attest/blob/59d89421af93a897026c735860bf21b6eb4f7b26/README.md

GitHub. (n.d.). Using artifact attestations and reusable workflows to achieve SLSA v1 Build Level 3. GitHub Docs. Retrieved August 5, 2026, from https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/increase-security-rating

GitHub. (n.d.). Using artifact attestations to establish provenance for builds. GitHub Docs. Retrieved August 5, 2026, from https://docs.github.com/en/actions/how-tos/secure-your-work/use-artifact-attestations/use-artifact-attestations

Supply-chain Levels for Software Artifacts Community. (2025). SLSA specification version 1.2. https://slsa.dev/spec/v1.2/

Non-goals

• No branch-local publication or tag creation.
• No model execution under a write, OIDC, attestation, or artifact-metadata credential.
• No weakening of caller repository review, branch protection, exact-head, package acceptance, or release-environment gates.
• No claim that an SBOM or attestation proves absence of vulnerabilities, malicious dependencies, or license obligations.