ci(sbom): verify bomsh provenance end-to-end; pyspdxtools-validate enriched SPDX

CI previously asserted only that a gitoid externalRef exists.  Add
`scripts/bomsh_verify.py` (with 8 synthetic-fixture unit tests) verifying
every gitoid resolves, blobs round-trip their sha1, and the wolfSSL
gitoid matches the built `libwolfssl.*`; pyspdxtools schema-validates the
enriched SPDX and `make bomsh` records the traced artefact in `_bomsh.artefact`.

Author: sameehj

.github/workflows/sbom.yml

@@ -981,6 +981,57 @@ jobs:
           print(f'bomsh enrichment ok: {len(gitoid_refs)} gitoid refs')
           PY
 
+      - name: Bomsh-enriched SPDX validates per pyspdxtools
+        # Schema gate.  `make sbom` already runs pyspdxtools on the
+        # un-enriched SPDX; the enriched document was previously
+        # ungated.  A bomsh_sbom.py change that emits a malformed
+        # SPDX 2.3 document (e.g. wrong shape on the gitoid externalRef
+        # block, missing required field on a new package) would
+        # otherwise ship in the artefact bundle below.  Complementary
+        # to the next step which validates *semantic* correctness
+        # (does the gitoid actually point at anything real); this
+        # step pins *schema* correctness only.
+        run: |
+          set -e
+          # `[ -f "$f" ] || continue` makes the loop robust if the glob
+          # has no match (defensive only; the previous step already
+          # `ls`-fails the job in that case, but this decouples the
+          # two if a future maintainer reorders).
+          for f in omnibor.wolfssl-*.spdx.json; do
+            [ -f "$f" ] || continue
+            echo "Validating $f"
+            pyspdxtools --infile "$f"
+          done
+
+      - name: Bomsh provenance is end-to-end verifiable
+        # Three independent self-consistency checks on the bomsh
+        # provenance bundle.  The PERSISTENT-ID assertion above only
+        # proves the gitoid externalRef *exists*; none of these
+        # follow-up properties are guaranteed by it:
+        #
+        #   (A) every gitoid in the SPDX externalRefs resolves to a
+        #       blob present in omnibor/objects/<aa>/<rest>
+        #   (B) every blob in omnibor/objects/ round-trips through
+        #       sha1(b"blob <len>\0" + content) so the object store
+        #       is internally self-consistent (no bit-rot, no
+        #       truncation, no stray non-blob file under objects/)
+        #   (C) the gitoid recorded against the wolfSSL package equals
+        #       the git-blob hash of the actual library artefact that
+        #       `make bomsh` traced (the SBOM ties to the binary that
+        #       would actually ship)
+        #
+        # Without this, a future bomsh_sbom.py change that emits a
+        # plausibly-shaped but fictional gitoid (one that does not
+        # resolve in the ADG, or resolves but to the wrong artefact)
+        # would pass the existing PERSISTENT-ID assertion and ship a
+        # provenance bundle whose externalRef is a lie.
+        #
+        # The verifier logic lives in scripts/bomsh_verify.py so it can
+        # be unit-tested with synthetic fixtures (see the
+        # TestBomshProvenanceVerify class in scripts/test_gen_sbom.py)
+        # rather than only running here against a real bomsh trace.
+        run: python3 scripts/bomsh_verify.py
+
       # The full provenance bundle - the high-value artefact of the whole
       # PR, the one a CRA reviewer or downstream packager wants to download.
       # MUST be uploaded BEFORE the `make clean` step below, which deletes
@@ -1029,3 +1080,5 @@ jobs:
               exit 1
           fi
           test ! -d omnibor || (echo "omnibor/ not cleaned"; exit 1)
+          test ! -f _bomsh.artefact \
+            || (echo "_bomsh.artefact not cleaned"; exit 1)

Makefile.am

@@ -469,11 +469,17 @@ uninstall-sbom:
 CLEANFILES += $(SBOM_CDX) $(SBOM_SPDX) $(SBOM_SPDX_TV)
 
 # Bomsh (OmniBOR build artifact tracing + SBOM enrichment)
-BOMSH_RAWLOG_BASE = $(abs_builddir)/bomsh_raw_logfile
-BOMSH_RAWLOG      = $(BOMSH_RAWLOG_BASE).sha1
-BOMSH_CONF        = $(abs_builddir)/_bomsh.conf
-BOMSH_OMNIBORDIR  = $(abs_builddir)/omnibor
-BOMSH_SPDX_OUT    = omnibor.wolfssl-$(PACKAGE_VERSION).spdx.json
+BOMSH_RAWLOG_BASE      = $(abs_builddir)/bomsh_raw_logfile
+BOMSH_RAWLOG           = $(BOMSH_RAWLOG_BASE).sha1
+BOMSH_CONF             = $(abs_builddir)/_bomsh.conf
+BOMSH_OMNIBORDIR       = $(abs_builddir)/omnibor
+BOMSH_SPDX_OUT         = omnibor.wolfssl-$(PACKAGE_VERSION).spdx.json
+# Single-source-of-truth manifest of the library artefact bomtrace3
+# actually traced.  Written by the bomsh: recipe so downstream
+# verification (CI: `Bomsh provenance is end-to-end verifiable`) doesn't
+# have to re-derive the same WOLFSSL_LIB_DSO_BASENAMES priority order
+# in parallel and risk drift.
+BOMSH_ARTEFACT_MANIFEST = $(abs_builddir)/_bomsh.artefact
 bomshdir          = $(datadir)/doc/$(PACKAGE)
 
 .PHONY: bomsh install-bomsh uninstall-bomsh
@@ -520,6 +526,7 @@ bomsh:
 	    echo "      OmniBOR graph produced; SPDX enrichment skipped."; \
 	    exit 0; \
 	fi; \
+	printf '%s\n' "$$bomsh_artifact" > '$(BOMSH_ARTEFACT_MANIFEST)'; \
 	echo "Enriching SPDX with OmniBOR ExternalRefs (artifact: $$bomsh_artifact)..."; \
 	$(BOMSH_SBOM) \
 	    -b '$(BOMSH_OMNIBORDIR)' \
@@ -541,7 +548,7 @@ uninstall-bomsh:
 	-rm -rf '$(DESTDIR)$(bomshdir)/omnibor'
 	-rm -f '$(DESTDIR)$(bomshdir)/$(BOMSH_SPDX_OUT)'
 
-CLEANFILES += $(BOMSH_RAWLOG) $(BOMSH_RAWLOG_BASE).sha256 $(BOMSH_CONF) $(BOMSH_SPDX_OUT)
+CLEANFILES += $(BOMSH_RAWLOG) $(BOMSH_RAWLOG_BASE).sha256 $(BOMSH_CONF) $(BOMSH_SPDX_OUT) $(BOMSH_ARTEFACT_MANIFEST)
 
 # Hook SBOM/Bomsh cleanup into `make uninstall` so packagers don't leave
 # stale artefacts behind after install-sbom/install-bomsh.  uninstall-sbom

doc/SBOM.md

@@ -632,6 +632,35 @@ The raw logfile (`bomsh_raw_logfile.sha1`) and conf file (`_bomsh.conf`)
 are written to the build directory and removed by `make clean`.  The
 `omnibor/` tree is also removed by `make clean`.
 
+#### CI verifiability gates
+
+The bomsh CI job enforces three independent self-consistency properties
+on every PR, in addition to schema validation of the enriched SPDX
+through `pyspdxtools`:
+
+1. **Resolvability** — every `gitoid` listed in the SPDX `externalRefs`
+   resolves to a blob present at `omnibor/objects/<aa>/<rest>`.
+2. **Object-store integrity** — every blob in `omnibor/objects/`
+   round-trips through `sha1(b"blob <len>\0" + content)`, so a corrupt or
+   truncated object store is caught at PR time, not by a downstream
+   verifier weeks later.
+3. **Artefact correspondence** — the `gitoid` recorded against the
+   `wolfssl` SPDX package equals the git-blob hash of the actual
+   `libwolfssl.{so,dylib,a}` that `make bomsh` traced.  This is what
+   makes the SBOM a true attestation of the binary that would ship,
+   rather than a plausible-looking but fictional reference.
+
+If any of these fail, the PR fails — the bomsh provenance bundle that a
+CRA reviewer would download is never published with a broken bridge.
+
+The verifier itself lives at `scripts/bomsh_verify.py` (importable, with
+synthetic-fixture unit tests in `scripts/test_gen_sbom.py`).  Run it
+against any local `make bomsh` output with:
+
+```sh
+python3 scripts/bomsh_verify.py
+```
+
 ---
 
 ## 4. Combined workflow