Goal

Adopt SBOM (Software Bill of Materials) generation and sigstore signing for proxybroker2 releases so downstream users can:

1. Audit dependencies before installing (catch supply-chain compromises).
2. Verify build integrity of PyPI wheels and Docker images (was this really built by the maintainer's release pipeline, or replaced in transit?).

Why this matters for proxybroker2

• proxybroker2 has 1k+ stars and is installed via pip and Docker — both paths are vulnerable to supply-chain attacks (typosquatting, package takeover, registry tampering).
• Modern projects (cpython, kubernetes, sigstore itself, all major cloud SDKs) ship SBOMs + signatures as standard. proxybroker2 is increasingly behind by not doing so.
• Recent supply-chain incidents (PyPI typosquats, npm event-stream, xz backdoor) show this is a real, not theoretical, threat. A 1k-star tool is exactly the size attackers target — large enough to be worth compromising, small enough to lack hardened CI.

Scope

A. SBOM generation

• Generate CycloneDX SBOM for every release (Python ecosystem standard via cyclonedx-bom or cyclonedx-python).
• Attach SBOM to GitHub release as proxybroker2-{version}-sbom.json.
• Include SBOM in Docker image as OCI annotation org.opencontainers.image.bom (new label) or as a separate manifest entry via docker buildx imagetools.
• For PyPI: pyproject.toml build hook generates SBOM into the wheel META-INF/.

B. Sigstore signing

• Sign GitHub releases with sigstore-python using GitHub OIDC (no manual key management).
• Sign PyPI uploads — PyPI now supports sigstore attestations natively (since 2024).
• Sign Docker images with cosign using GitHub OIDC + Fulcio (no key files to leak).
• Verify signatures in CI before publishing (defense in depth).

C. Workflow integration

• New job in .github/workflows/python-publish.yml: generate SBOM + sigstore attestation, upload to release.
• New job in .github/workflows/docker-publish.yml: cosign sign the published image with OIDC.
• Document verification in README ("how to verify your install").

Acceptance criteria

1. Every GitHub release has a *-sbom.json asset (CycloneDX format).
2. Every PyPI publish includes sigstore attestation visible at pypi.org/project/proxybroker2/{version}/#sigstore.
3. Every Docker image push has a cosign signature verifiable via:

   cosign verify --certificate-identity-regexp "https://github.com/bluet/proxybroker2/.*" \
                 --certificate-oidc-issuer "https://token.actions.githubusercontent.com" \
                 bluet/proxybroker2:VERSION
   

4. README has a "Verifying your install" section with copy-paste verification commands.
5. CI fails if signing/SBOM steps fail (no silent skips).

References

• SLSA framework levels — proxybroker2 is at L0 currently; this PR targets L2-L3.
• sigstore-python docs
• cosign with GitHub OIDC
• PyPI attestations announcement
• CycloneDX Python SBOM tooling

Out of scope

• Reproducible builds (separate, harder problem; bit-for-bit determinism requires fixing build env).
• Hash-pinning all transitive deps in poetry.lock (Poetry already does this; not strictly SBOM/sigstore).
• VEX (Vulnerability Exploitability eXchange) statements (related but separate; tracks whether SBOM-listed vulns actually apply).

Estimated effort

• SBOM: ~3 hours (mostly workflow YAML + cyclonedx CLI invocations).
• Sigstore PyPI: ~2 hours (sigstore-python is well-documented).
• Cosign Docker: ~3 hours (need to handle multi-arch manifest signing).
• Verification docs + CI verification: ~2 hours.

Total ~10 hours. Recommend single PR since the three pieces are tightly coupled (all use GitHub OIDC, all run in publish workflows).