feat: SBOM generation and OmniBOR build provenance (CRA compliance)

[MarkAtwood]

Summary

Adds two complementary supply chain transparency targets to the wolfSSL autotools build:

• make sbom — generates a Software Bill of Materials (SPDX 2.3 + CycloneDX 1.6) for EU Cyber Resilience Act (CRA) compliance
• make bomsh — generates an OmniBOR artifact dependency graph (cryptographic source-to-binary traceability) using the Bomsh project
• When both are run, make bomsh enriches the SPDX document with a PERSISTENT-ID gitoid ExternalRef, bridging component identity and build provenance in a single file

make sbom

Produces three files:

File	Format
wolfssl-<version>.cdx.json	CycloneDX 1.6 JSON
wolfssl-<version>.spdx.json	SPDX 2.3 JSON
wolfssl-<version>.spdx	SPDX 2.3 tag-value (validated by pyspdxtools)

SBOM contents: name, version, supplier, license (parsed from LICENSING at generation time), copyright, SHA-256 of installed library, CPE, PURL, download location, build configuration defines, and optional third-party dependency versions (liboqs, libz, libxmss, liblms).

Implementation: scripts/gen-sbom (Python 3, stdlib only) stages a make install into a temp directory, hashes the installed library, generates both formats, removes staging. configure.ac detects python3, pyspdxtools, and git via AC_PATH_PROG. make sbom fails with a clear error if either required tool is missing.

make bomsh

Runs a full clean rebuild under bomtrace3 (patched strace — userspace only, no kernel modifications) to produce an OmniBOR artifact graph in omnibor/. If bomsh_sbom.py is available and wolfssl-<version>.spdx.json exists, annotates the SPDX with a PERSISTENT-ID gitoid ExternalRef.

configure.ac detects bomtrace3, bomsh_create_bom.py, and bomsh_sbom.py via AC_PATH_PROG. The raw logfile and conf file are written to the build directory (not /tmp/) to avoid concurrent-build collisions. All generated files removed by make clean.

Install targets

make install-sbom     # installs SBOM files to $(datadir)/doc/wolfssl/
make install-bomsh    # installs omnibor/ and enriched SPDX to $(datadir)/doc/wolfssl/

Documentation

• doc/SBOM.md — unified reference covering both targets, combined workflow, all output files, implementation notes
• doc/CRA.md — product-integrator guide: how to incorporate wolfSSL's SBOM artefacts into a downstream product SBOM (SPDX ExternalDocumentRef, CycloneDX component reference), commercial license guidance, OmniBOR gitoid meaning, auditor handoff checklist, links to OpenSSF CRA and SBOM Everywhere SIG guidance
• INSTALL: sections 21 and 22
• README.md: brief SBOM/CRA and OmniBOR/Bomsh sections
• doc/include.am: SBOM.md and CRA.md added to dist_doc_DATA

Test plan

• ./autogen.sh && ./configure && make && make sbom — verify three SBOM files produced and SPDX validates
• make install-sbom / make uninstall-sbom — verify files install and remove cleanly
• make clean — verify all generated files removed
• With bomtrace3 and bomsh_create_bom.py in PATH: make sbom && make bomsh — verify omnibor/ produced and omnibor.wolfssl-<ver>.spdx.json contains PERSISTENT-ID gitoid ExternalRef
• Without bomtrace3 in PATH: make bomsh — verify clear error message, non-zero exit
• Without prior make sbom: make bomsh — verify OmniBOR graph produced, NOTE printed about missing SPDX, no failure

[Copilot]

Pull request overview

Adds build-integrated supply-chain transparency outputs to the Autotools build: SBOM generation (make sbom) and OmniBOR/Bomsh build provenance tracing (make bomsh) to support CRA-style compliance workflows.

Changes:

• Add scripts/gen-sbom Python generator for CycloneDX 1.6 + SPDX 2.3 JSON SBOM outputs (plus tag-value conversion via pyspdxtools).
• Wire new sbom, bomsh, and install/uninstall targets into Autotools (configure.ac, Makefile.am), with tool discovery via AC_PATH_PROG.
• Add end-user documentation (doc/SBOM.md, doc/CRA.md) and reference it from README.md/INSTALL.

Reviewed changes

Copilot reviewed 8 out of 8 changed files in this pull request and generated 8 comments.

Show a summary per file

File	Description
scripts/gen-sbom	New Python SBOM generator producing CycloneDX/SPDX JSON with optional dependency metadata.
Makefile.am	Adds sbom/bomsh targets, install/uninstall rules, and clean integration.
configure.ac	Detects required tools (python3, pyspdxtools, git, bomtrace3, bomsh scripts) and exports needed vars.
doc/include.am	Ships new docs in the dist tarball; cleans generated OmniBOR directory.
doc/SBOM.md	Primary documentation for SBOM + OmniBOR workflows and outputs.
doc/CRA.md	Downstream integrator guidance for CRA-oriented SBOM/provenance usage.
README.md	Adds brief pointers to the new SBOM/CRA and OmniBOR features.
INSTALL	Adds new sections documenting make sbom / make bomsh usage and prerequisites.

---

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

[github-actions]

MemBrowse Memory Report

No memory changes detected for:

• gcc-arm-cortex-m0plus
• gcc-arm-cortex-m3
• gcc-arm-cortex-m4
• gcc-arm-cortex-m4-baremetal
• gcc-arm-cortex-m4-crypto-only
• gcc-arm-cortex-m4-dtls13
• gcc-arm-cortex-m4-min-ecc
• gcc-arm-cortex-m4-openssl-compat
• gcc-arm-cortex-m4-pkcs7
• gcc-arm-cortex-m4-pq
• gcc-arm-cortex-m4-rsa-only
• gcc-arm-cortex-m4-sp-math
• gcc-arm-cortex-m4-tls12
• gcc-arm-cortex-m4-tls13
• gcc-arm-cortex-m7
• gcc-arm-cortex-m7-pq
• gcc-arm-cortex-m7-tls13
• linuxkm-pie
• linuxkm-standard
• stm32-sim-stm32h753

[Frauschi]

Note that we are in the process of removing liblms and libxmss (see #10292), which will simplify the dependency analysis in the python script.

[MarkAtwood]

Three CI failures to address:

1. bomsh integration (linux) — upstream repo restructured
The install step checks for .devcontainer/bomtrace3/ in the omnibor/bomsh repo, which no longer exists. Hit our own error string: bomsh repo layout changed; please update CI. Check the current bomsh repo layout and fix the install step.

2. SBOM integration (linux) — liboqs-dev not in apt
E: Unable to locate package liboqs-dev — that package isn't in Ubuntu 24.04's default repos. Either build liboqs from source in CI, use a PPA, or make that step conditional.

3. Windows Build Test (x64) — tcp bind failed
Build succeeded (0 errors), runtime fails with wolfSSL error: tcp bind failed. Looks like port contention on the Windows runner. Please check if this also fails on master — if so it's pre-existing and not our bug, and we can ignore it.

PRB-master-job failure appears to be a reporting artifact (no test results found), not a real failure.

[Frauschi]

3. Windows Build Test (x64) — tcp bind failed

FYI, this will be resolved with #10387

[wolfSSL-Fenrir-bot]

Fenrir Automated Review — PR #10343

No scan targets match the changed files in this PR. Review skipped.

[sameehj]

retest this please

[MarkAtwood]

Pre-merge self-review

Ran a structured pre-merge review across scripts/gen-sbom, scripts/test_gen_sbom.py, .github/workflows/sbom.yml, Makefile.am, and the docs. Five commits result, each listing its closed findings in the trailer:

test(sbom): expand coverage; CI hard-requires pcpp
fix(sbom): correctness fixes in gen-sbom
build(sbom): Makefile.am hygiene
ci(sbom): pin deps, harden token, partial-clone bomsh
docs(sbom): correct NTIA/SPDX claims; fix broken anchor

Real defects fixed (fix(sbom))

1. parse_options_h URL corruption. re.split(r'/\*|//', raw)[0] truncated PACKAGE_URL "https://..." at the first // inside the URL, emitting PACKAGE_URL = "https: in the SBOM wolfssl:build:* properties. Replaced with a string-literal-aware state machine.
2. detect_license missed the canonical FSF preamble. or\s+(any\s+)?later failed on or (at your option) any later version (the FSF GPLv2 preamble used in millions of upstream COPYING files); silently mis-detected as GPL-X.0-only. Broadened with a sentence-bounded filler match.
3. Empty --lib accepted. A misconfigured build pointing --lib at /dev/null or an empty .a silently emitted the well-known empty-file SHA-256 (e3b0c44…b855) as the wolfSSL component checksum; both SPDX and CDX validators accepted it. Hard-fail gate on size 0 with an actionable error; --srcs zero-byte placeholders get a soft warning (cross-compile setups legitimately use them).

Coverage gaps closed (test(sbom))

+42 tests covering detect_license (had zero tests), sha256_file's chunked-read path (the loop body wasn't exercised by the only existing empty-file vector), all four SBOM document generators (generate_cdx / generate_spdx / cdx_dep_component / spdx_dep_package), and the LicenseRef-without-license-text CLI rejection. Independent oracles throughout — SPDX licence list, hashlib one-shot SHA-256, CDX 1.6 / SPDX 2.3 schema field semantics.

TestParseUserSettings.setUp previously called self.skipTest on missing pcpp. The unit job didn't install pcpp, so 9 standalone-path tests silently skipped on every PR run. Now hard-fails with an actionable install hint, and the unit job installs pcpp==1.30.*.

Build hygiene (build(sbom))

Five Makefile.am improvements — none changes user-facing behaviour for any correct invocation; each closes a specific failure mode:

• bomsh artifact glob quoted for spaces in abs_builddir
• SOURCE_DATE_EPOCH only exported when git log -1 --format=%ct returned non-empty (silent shallow-clone case)
• --license-override / --license-text only passed when set (decouples Makefile from gen-sbom's argparse default)
• install-bomsh switched from a two-tar pipeline (which masked source-side errors due to POSIX sh's pipeline exit-status semantics) to cp -R src/. dst/
• uninstall-hook depends on uninstall-sbom + uninstall-bomsh instead of duplicating their bodies

CI hardening (ci(sbom))

pcpp==1.30.* pinned, permissions: contents: read at workflow level (defence-in-depth — workflow does no API writes), git clone --filter=blob:none for the bomsh fetch (saves ~10s per run; pinned SHA makes blob filter safe).

Doc corrections (docs(sbom))

• README.md previously said "Both produce SPDX 2.3 + CycloneDX 1.6 JSON validated against NTIA minimum elements". Neither path runs an NTIA-minimum-elements checker. Only make sbom runs pyspdxtools (SPDX-spec, not NTIA-specific). Corrected.
• doc/CRA.md named ntia-conformance-checker as enforcing SPDX §10.1 hasExtractedLicensingInfos; it does not (that is pyspdxtools' job). Corrected with explicit text on what ntia-conformance-checker actually validates so a reader cannot be misled into running a malformed LicenseRef SBOM through the wrong tool and getting a false pass.
• doc/SBOM.md anchor link #3-make-bomsh resolved to the wrong section; fixed to the GFM auto-anchor for §3.1.

Re the Copilot inline review

The Copilot review raised 8 concerns. 7 are addressed: the NOASSERTION CDX wording in SBOM.md §2.4, make bomsh → make sbom rebuild ordering, hardcoded library paths replaced with the WOLFSSL_LIB_DSO_BASENAMES glob, scripts/gen-sbom added to EXTRA_DIST, trap-based staging cleanup, and removing the hardcoded licenseListVersion.

The remaining concern — install-bomsh using a non-INSTALL_DATA copy mechanism — is unchanged in intent (this round uses cp -R rather than the previous tar pipeline for clean error propagation but did not adopt find ... | xargs $(INSTALL_DATA)). The OmniBOR tree is a directory of content-addressed binary objects; using $(INSTALL_DATA) per-file is the more automakey approach but adds complexity for a directory whose layout is meant to be preserved verbatim. Open to revisiting if maintainers prefer.

Acknowledgement

@sameehj — the standalone --user-settings / --srcs entry point, SPDX 2.3 LicenseRef compliance, library-discovery glob, and CI workflow shape this PR from "works on my machine" into a production-ready, embedded-customer-friendly tool. The test infrastructure you built was solid. Thanks.

cc @Frauschi for visibility — make clean removes both the doxygen artefacts and BOMSH_OMNIBORDIR via doc/include.am's clean-local:.

[sameehj]

retest this please

[sameehj]

retest this please

[dgarske]

Skoll Code Review

Scan type: reviewOverall recommendation: COMMENT
Findings: 4 total — 4 posted, 0 skipped
3 finding(s) posted as inline comments (see file-level comments below)

Posted findings

• [Medium] make sbom does not thread --dep-version; liboqs/zlib version becomes NOASSERTION without pkg-config — Makefile.am:409-475 (sbom target)
• [Low] Redundant/dead branch logic in FIPS product bucket computation — scripts/gen-advisory:product_model (FIPS block)
• [Low] Duplicate pkg-config invocation per dependency — scripts/gen-sbom:cdx_dep_component / spdx_dep_package
• [Info] Executable-bit inconsistency between gen-sbom (755) and gen-advisory (644) — scripts/gen-advisory:1

Review generated by Skoll

[MarkAtwood]

Good catch on the --dep-version gap. Yes, let's expose a SBOM_DEP_VERSIONS make variable so autotools packagers without pkg-config can still record dep versions.

@sameehj can you pick this up along with the other Skoll findings?

[MarkAtwood]

@dgarske Merge conflicts resolved — rebased the branch onto current master (the only content conflict was the codespell ignore_words_list; kept both additions). Verified on the rebased head: full build, make sbom producing all three 5.9.2 artifacts, and both script test suites (162 + 57 tests) pass. Ready for re-review.

[rlm2002]

Skoll Code Review

Scan type: reviewOverall recommendation: COMMENT
Findings: 10 total — 6 posted, 4 skipped
4 finding(s) posted as inline comments (see file-level comments below)

Posted findings

• [Medium] make bomsh fails late (after full traced rebuild) when python3/pyspdxtools are missing — Makefile.am:bomsh target (recipe ~ lines added for bomsh:)
• [Medium] Empty English CVE description produces an invalid CSAF note (text minLength 1) with exit 0 — scripts/gen-advisory:generate_csaf / parse_record
• [Low] SBOM/advisory CI jobs are gated to the wolfssl org, so fork PRs get no test signal — .github/workflows/sbom.yml, .github/workflows/advisory.yml (every job)
• [Low] Unquoted $(ENABLED_LIBZ)/$(ENABLED_LIBOQS) can break make sbom if ever empty — Makefile.am:sbom recipe (--dep-libz/--dep-liboqs)
• [Low] csaf_validate.mjs has no direct unit coverage — scripts/csaf_validate.mjs:1-83
• [Low] No unit coverage for _bucket_for unknown-state hard-fail — scripts/gen-advisory:_bucket_for; scripts/test_gen_advisory.py

Skipped findings

• [Info] make clean leaves the empty advisories/out directory behind
• [Info] BOMSH_OMNIBORDIR cleanup placed in doc/include.am clean-local
• [Low] bomsh_verify object-store integrity always hashes with SHA-1 but accepts SHA-256-length blob paths
• [Info] load_cve_record fetches from cveawg.mitre.org while comments reference cve.org

Review generated by Skoll

[MarkAtwood]

retest this please

[MarkAtwood]

rerun tests

[douzzer]

Retest this please
(lost logs)

[MarkAtwood]

retest this please

Request was for conflicts to be fixed.
They are.

[SparkiDev]

weird control chars, hard tabs, CRs, trailing whitespace:
./scripts/sbom.am:116:»@test -n "$(PYTHON3)" || {
./scripts/sbom.am:117:» echo "ERROR: 'python3' not found in PATH. Cannot generate SBOM.";
./scripts/sbom.am:118:» exit 1; }
./scripts/sbom.am:119:»@test -n "$(PYSPDXTOOLS)" || {
./scripts/sbom.am:120:» echo "ERROR: 'pyspdxtools' not found (pip install spdx-tools).";
./scripts/sbom.am:121:» exit 1; }
./scripts/sbom.am:122:»@test -f "$(SBOM_GEN)" || {
./scripts/sbom.am:123:» echo "ERROR: gen-sbom not found. Vendor scripts/gen-sbom, or re-run:";
./scripts/sbom.am:124:» echo " make sbom WOLFSSL_DIR=/path/to/wolfssl";
./scripts/sbom.am:125:» exit 1; }
[...and more...]
sort: /tmp/workspace/PRB-multi-test-script/wolfssl/.wolfssl_known_macro_extras:1083: disorder: _ABI64

[rlm2002]

Please resolve merge conflicts.