feat(cra-kit): add cmake mode and embedded srcs-file/no-hash options#577
feat(cra-kit): add cmake mode and embedded srcs-file/no-hash options#577MarkAtwood wants to merge 29 commits into
Conversation
Self-contained cra-kit/ with glossary, fictional auditor packet, autotools/embedded SBOM scripts, and CI validation. Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>
Fail early when the wolfSSL tree version differs from the kit's pinned VERSION instead of a cryptic cp error, trap-clean the embedded temp defines file on all exit paths, add sh -n + shellcheck CI coverage for the scripts, and use the standard file:./ relative form in the product SBOM external references. Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>
Quote "$@" in gen-sbom --srcs (drop SC2068 disables), pass JSON paths to python via env var in validate.sh to prevent filename injection, and fail non-zero instead of warning when SBOM post-processing breaks. Rename the user_settings.h guard to CRA_KIT_USER_SETTINGS_H, clarify the serialNumber regex accepts v4 (product) and v5 (component) UUIDs, untrack the gitignored embedded sample SBOMs, document the SHA-512 CBOM omission, and note sample timestamp differences in SAMPLE-PROVENANCE.md. Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>
Plumb CRA_LICENSE_TEXT through generate-wolfssl-sbom.sh (gen-sbom/make sbom hard-fail on a LicenseRef-* override without it); scope the commercial relicense to the wolfssl package only; correct the stale pkg:generic PURL claim; validate the embedded output dir; regenerate pinned samples against gen-sbom 1.1 and re-pin product checksums. Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>
Add CRA_SBOM_MODE=cmake with WOLFSSL_BUILD_DIR for out-of-source builds. Add CRA_SBOM_SRCS_FILE and CRA_SBOM_NO_HASH for embedded path. Update auto-detection order: cmake (WOLFSSL_BUILD_DIR) > autotools > embedded.
|
Waiting on #574 and wolfSSL/wolfssl#10753 to merge before this is ready to land. Review welcome in the meantime. |
There was a problem hiding this comment.
Pull request overview
Adds a new wolfSSL CRA Kit (cra-kit/) with documentation, sample “auditor packet” SBOM artifacts, and helper scripts to generate/refresh/validate wolfSSL component SBOMs across autotools, cmake, and embedded workflows.
Changes:
- Introduces the CRA Kit docs, worked examples (product + component SBOMs), and manufacturer-side CRA filing templates.
- Adds SBOM generation/refresh/validation scripts, including cmake mode and embedded options (srcs-file + no-hash).
- Adds a GitHub Actions workflow to validate the CRA Kit auditor packet and shellcheck the scripts.
Reviewed changes
Copilot reviewed 41 out of 41 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| README.md | Adds top-level mention/entry point for the CRA Kit. |
| cra-kit/wolfssl-inc-auditor-packet/vulnerability-handling-process.md | Documents manufacturer-side vulnerability handling process. |
| cra-kit/wolfssl-inc-auditor-packet/technical-documentation-outline.md | Adds Annex VII technical documentation outline template. |
| cra-kit/wolfssl-inc-auditor-packet/support-period-policy.md | Adds support-period policy statement template. |
| cra-kit/wolfssl-inc-auditor-packet/README.md | Introduces manufacturer-side packet scope and status conventions. |
| cra-kit/wolfssl-inc-auditor-packet/eu-authorised-representative.md | Adds EU AR placeholder and guidance template. |
| cra-kit/wolfssl-inc-auditor-packet/declaration-of-conformity.template.md | Adds declaration of conformity template. |
| cra-kit/wolfssl-inc-auditor-packet/conformity-assessment-route.md | Documents conformity assessment route template. |
| cra-kit/wolfssl-inc-auditor-packet/classification-statement.md | Adds Annex III/IV classification statement template. |
| cra-kit/wolfssl-inc-auditor-packet/ce-marking-statement.md | Adds CE marking statement template. |
| cra-kit/wolfssl-inc-auditor-packet/00-INDEX.md | Index/mapping for manufacturer-side filings. |
| cra-kit/VERSION | Pins wolfSSL version used by samples/scripts. |
| cra-kit/user_settings.h | Provides demo embedded user_settings.h for SBOM generation. |
| cra-kit/SKILL.md | Adds an AI/agent execution playbook for the kit. |
| cra-kit/scripts/validate.sh | Adds validator for sample packet JSON + checksum/hash consistency (optional schema checks). |
| cra-kit/scripts/refresh-samples.sh | Adds sample regeneration + product checksum/hash pinning flow. |
| cra-kit/scripts/make-commercial-sample.sh | Adds derivation of commercial-license override samples from pinned GPL samples. |
| cra-kit/scripts/generate-wolfssl-sbom.sh | Adds main SBOM generator with autotools/cmake/embedded modes + watermarking. |
| cra-kit/scripts/generate-embedded-sbom.sh | Convenience wrapper to force embedded outputs into embedded sample dir. |
| cra-kit/ROADMAP.md | Adds “today vs roadmap” status for supply-chain artifacts. |
| cra-kit/README.md | Adds full CRA Kit documentation and usage guide. |
| cra-kit/presentations/SLIDE-OUTLINE.md | Adds presentation outline aligned with kit deliverables. |
| cra-kit/CRA-Supply-Chain-Glossary.md | Adds CRA + supply-chain glossary/cheat sheet for customers. |
| cra-kit/CRA-Compliance-Shortlist.md | Adds product-level CRA pillar shortlist and structural obligations section. |
| cra-kit/CRA-Cheat-Sheet.md | Adds “who provides what” cheat sheet + integration quick reference. |
| cra-kit/auditor-packet/wolfssl-component/wolfssl-5.9.1.spdx.json | Adds pinned wolfSSL component SPDX JSON sample. |
| cra-kit/auditor-packet/wolfssl-component/wolfssl-5.9.1.spdx | Adds pinned wolfSSL component SPDX tag-value sample. |
| cra-kit/auditor-packet/wolfssl-component/wolfssl-5.9.1.commercial.spdx.json | Adds commercial-license override SPDX JSON sample. |
| cra-kit/auditor-packet/wolfssl-component/wolfssl-5.9.1.commercial.cdx.json | Adds commercial-license override CycloneDX JSON sample. |
| cra-kit/auditor-packet/wolfssl-component/wolfssl-5.9.1.cdx.json | Adds pinned wolfSSL component CycloneDX JSON sample. |
| cra-kit/auditor-packet/wolfssl-component/wolfssl-5.9.1.cbom-draft.cdx.json | Adds draft CBOM-like CycloneDX cryptographic-asset sample. |
| cra-kit/auditor-packet/wolfssl-component/SAMPLE-PROVENANCE.md | Documents how pinned samples were produced. |
| cra-kit/auditor-packet/wolfssl-component/README-bomsh.md | Documents optional bomsh/OmniBOR inclusion guidance. |
| cra-kit/auditor-packet/wolfssl-component/omnibor.wolfssl-5.9.1.spdx.json.sample | Adds truncated sample of bomsh provenance output shape. |
| cra-kit/auditor-packet/wolfssl-component-embedded/README.md | Documents embedded SBOM scratch output generation. |
| cra-kit/auditor-packet/wolfssl-component-embedded/.gitignore | Gitignores embedded SBOM outputs. |
| cra-kit/auditor-packet/README.md | Introduces the sample auditor packet directory. |
| cra-kit/auditor-packet/product-acme-connect-gateway.spdx.json | Adds product SPDX sample referencing wolfSSL component SPDX. |
| cra-kit/auditor-packet/product-acme-connect-gateway.cdx.json | Adds product CycloneDX sample referencing wolfSSL component CDX. |
| cra-kit/auditor-packet/00-INDEX.md | Index for sample auditor packet contents and regeneration guidance. |
| .github/workflows/cra-kit.yml | Adds CI to run kit validation and shellcheck scripts on CRA Kit changes. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
When CRA_SBOM_SRCS_ONLY_FROM_FILE=true no demo srcs are added to $@, so passing --srcs "$@" fed --cdx-out as the first --srcs argument, causing argparse to error. Capture _srcs_flag before output flags are appended; emit it only when positional srcs are present.
cmake -L and -LA both exclude :STATIC (internal) cache entries, so CMAKE_PROJECT_VERSION:STATIC was never matched and the version mismatch check was dead code. Grep CMakeCache.txt directly instead.
…-54c) Makefile (two approaches) and CMake/compile_commands.json examples are tested. Zephyr, ESP-IDF, Keil, and IAR sections are stubs written from schema knowledge — marked unverified, need toolchain owners to validate.
Tested against a live Zephyr 3.7.0 + wolfssl workspace on EC2. compile_commands.json is generated at cmake configure time and contains 89 wolfssl lib sources (wolfcrypt/src/ + src/). Removes the "not tested" warning and adds the -DZEPHYR_EXTRA_MODULES flag.
Adds _auto_extract_srcs() to generate-wolfssl-sbom.sh. When CRA_SBOM_SRCS_FILE is not set, the embedded path now tries four methods in order: 1. compile_commands.json (CMake/Zephyr/ESP-IDF) via jq — triggered when WOLFSSL_BUILD_DIR is set; detects ESP-IDF managed_components layout automatically. 2. Makefile via CRA_SBOM_MAKEFILE_DIR — tries print-wolfssl-srcs target first, falls back to make -n grep. 3. Keil .uvprojx via CRA_SBOM_KEIL_PROJECT — handles both CMSIS Pack RTE and explicit FilePath layouts. 4. IAR .ewp via CRA_SBOM_IAR_PROJECT — resolves $PROJ_DIR$, skips excluded entries. All methods set CRA_SBOM_SRCS_ONLY_FROM_FILE=true automatically so the demo watermark is suppressed. Temp files are collected into a single global trap. SRCS-FILE-HOWTO.md gains an Automatic extraction subsection for each build system.
Makefile: add --no-print-directory to suppress make's Entering/Leaving directory banners, which leaked into the source list when the Makefile directory path contained "wolfssl". Keil CMSIS Pack: when the wolfSSL pack .pdsc is not installed locally (~/.arm/Packs/wolfSSL/), fall back to enumerating wolfcrypt/src/*.c and src/*.c from WOLFSSL_DIR. The full library is what the pack ships.
Generate auditor-ready SBOM packages for wolfSSH, wolfTPM, wolfMQTT, wolfHSM, wolfsentry, and wolfBoot. Each script mirrors the wolfssl SBOM workflow.
Wire in shared _cra-sbom-extract.sh for Keil/IAR/Makefile/compile_commands.json source extraction. NO_HASH deferred to SBOM-cgz (gen-sbom lacks --no-artifact-hash).
…srcs in wolftpm cmake+embedded modes
…fhsm-sbom.sh Fix broken --srcs-file call (gen-sbom only supports positional --srcs). NO_HASH deferred to SBOM-cgz.
generate-wolfssh: add missing _cra_auto_tempfiles init (SC2154). generate-wolfhsm: make CRA_SBOM_BUILD_DIR self-referential so shellcheck sees the sourced-helper use (SC2034). Rewrite pipefail probe as if-then; annotate the sourced-helper (SC1091) and intentional cd-fallback (SC2015) lines. shellcheck cra-kit/scripts/*.sh now exits 0.
jackctj117
left a comment
jackctj117
left a comment
There was a problem hiding this comment.
Skoll Multi-Scan Review
Modes: review + review-securityOverall recommendation: COMMENT
Findings: 6 total — 6 posted, 0 skipped
4 finding(s) posted as inline comments (see file-level comments below)
2 finding(s) not tied to a diff line (full detail below)
Posted findings
- [Medium] [review] compile_commands.json auto-extraction is over-inclusive (no src/ restriction) —
cra-kit/scripts/_cra-sbom-extract.sh:238-250 - [Low] [review+review-security] wolfHSM version parse: sed matches single '#' but comment documents '##' heading —
cra-kit/scripts/generate-wolfhsm-sbom.sh:82-89 - [Low] [review] wolfMQTT autotools path lacks the tree-vs-parsed version cross-check used elsewhere —
cra-kit/scripts/generate-wolfmqtt-sbom.sh:_run_autotools - [Info] [review-security] No C/crypto source changes; only a benign demo header and tooling/docs —
cra-kit/user_settings.h:1-13
Findings not tied to a diff line
SRCS-FILE-HOWTO claims ESP-IDF managed_components auto-detection that the code does not implement
File: cra-kit/SRCS-FILE-HOWTO.md:ESP-IDF Automatic extraction
Function: _cra_extract_srcs
Severity: Medium
Category: Documentation
The ESP-IDF "Automatic extraction" section states the script detects the ESP-IDF managed-component layout (managed_components/wolfssl__wolfssl/) automatically when WOLFSSL_DIR sources are not found under WOLFSSL_BUILD_DIR directly. No such fallback exists in _cra_extract_srcs (method 5) — it only does grep -F "$_cra_product_dir/" against WOLFSSL_DIR. For an ESP-IDF managed-component build the compiled wolfSSL sources live under \<project>/managed_components/wolfssl__wolfssl/, not under WOLFSSL_DIR, so the grep matches zero paths, the helper prints "compile_commands.json ... yielded no <product> sources" and returns 1. The documented ESP-IDF automatic path therefore fails rather than working as described.
Recommendation: Either implement the managed-component fallback (when the product-dir grep yields nothing, retry against */managed_components/wolfssl__wolfssl/* and */components/wolfssl/*), or amend the ESP-IDF section to say automatic extraction only works when compiled sources resolve under WOLFSSL_DIR and to fall back to manual CRA_SBOM_SRCS_FILE for managed components.
Referenced code: cra-kit/SRCS-FILE-HOWTO.md:ESP-IDF Automatic extraction (5 lines)
Unquoted source-list/license variable expansion breaks on paths containing spaces
File: cra-kit/scripts/generate-wolfssl-sbom.sh:430-460; cra-kit/scripts/generate-wolfhsm-sbom.sh:150-215
Function: _run_embedded
Severity: Info
Category: Logic
Several scripts assemble argument fragments into a single string and then rely on unquoted word-splitting to pass them to gen-sbom, e.g. _srcs_file_args="--srcs-file $CRA_SBOM_SRCS_FILE" followed by ${_srcs_file_args} (and similarly _hash_arg, _license_args). If a user-supplied CRA_SBOM_SRCS_FILE, CRA_LICENSE_TEXT, or output directory path contains spaces, the path is split across multiple argv entries and gen-sbom receives a truncated/incorrect filename. The scripts explicitly suppress ShellCheck SC2086 for these lines, so this is an intentional word-splitting design, but it is fragile for paths with whitespace. No security impact — the caller controls these paths.
Recommendation: Where user-supplied paths may contain spaces, prefer appending to the positional parameter array (set -- "$@" --srcs-file "$CRA_SBOM_SRCS_FILE") instead of building a single word-split string, to preserve paths with whitespace.
Referenced code: cra-kit/scripts/generate-wolfssl-sbom.sh:430-460; cra-kit/scripts/generate-wolfhsm-sbom.sh:150-153 (4 lines)
Review generated by Skoll
Summary
This PR extends the CRA Kit in two major ways:
1. Embedded SBOM mode (existing)
--mode embeddedflag forgenerate-wolfssl-sbom.sh: hashes source files instead of the installed libraryCRA_SBOM_NO_HASH=trueoption for customers who cannot share source listsCRA_SBOM_SRCS_FILEto supply a pre-built source list2. Auto-extraction of wolfSSL sources (new in this PR)
Four build-system auto-extraction methods, all requiring no
CRA_SBOM_SRCS_FILE:print-wolfssl-srcstarget or falls back tomake -ndry-run (CRA_SBOM_MAKEFILE_DIR)compile_commands.json(WOLFSSL_BUILD_DIR).uvprojx; CMSIS Pack or explicit FilePath (CRA_SBOM_KEIL_PROJECT).ewp, resolves$PROJ_DIR$(CRA_SBOM_IAR_PROJECT)All four methods verified end-to-end on EC2 (Ubuntu 24.04).
3. CRA Kit scripts for 6 additional wolfSSL products (new in this PR)
Standalone SBOM generation scripts for each product, following the same auditor-packet layout as the wolfssl script:
generate-wolfssh-sbom.shCRA_SBOM_MODE=embeddedhashessrc/*.c;CRA_SBOM_SRCS_FILEorcompile_commands.jsonoverridegenerate-wolftpm-sbom.shCRA_SBOM_MODE=embeddedhashes core + one HAL (CRA_TPM_HAL=st|espressif|...); host-only transports excludedgenerate-wolfmqtt-sbom.shCRA_SBOM_MODE=embeddedhashessrc/mqtt_*.c;CRA_SBOM_SRCS_FILEorcompile_commands.jsonoverridegenerate-wolfhsm-sbom.shWOLFSSL_DIR,WOLFHSM_DIRgenerate-wolfsentry-sbom.shGEN_SBOMorWOLFSSL_DIRgenerate-wolfboot-sbom.shmake -nfor source listEmbedded mode for wolfSSH/wolfTPM/wolfMQTT: wolfcrypt/wolfssl sources are intentionally excluded — they are covered by a separate
generate-wolfssl-sbom.shrun and referenced as a dependency component.For wolfTPM embedded,
CRA_TPM_HALselects exactly onehal/tpm_io_<platform>.cto include. Omitting it produces a warning and excludes the HAL (safe default — wrong HAL = wrong SBOM).All 6 scripts verified with
make sbomend-to-end on EC2. Embedded mode for wolfSSH (12 srcs), wolfTPM (12 srcs + HAL), wolfMQTT (8 srcs) verified locally.4. Documentation
SRCS-FILE-HOWTO.md: complete guide for all 6 build systems including manual and automatic extraction.Zephyr section verified on EC2 (89 sources,
native_simboard).Test plan
generate-wolfssl-sbom.shin embedded mode with each auto-extraction methodgenerate-{product}-sbom.shscripts in autotools mode (EC2)CRA_SBOM_MODE=embeddedpyspdxtools