Skip to content

Commit 20eb9b1

Browse files
sameehjsameehj
committed
Add CRA Evidence Kit for customer SBOM integration
Self-contained cra-evidence/ with glossary, Evidence Map, fictional auditor packet, autotools/embedded SBOM scripts, and CI validation. Signed-off-by: Sameeh Jubran <sameeh@wolfssl.com>
1 parent 9bc3022 commit 20eb9b1

31 files changed

Lines changed: 2015 additions & 0 deletions

‎.github/workflows/cra-evidence.yml‎

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: CRA Evidence Kit
2+
3+
on:
4+
push:
5+
paths:
6+
- 'cra-evidence/**'
7+
- '.github/workflows/cra-evidence.yml'
8+
pull_request:
9+
paths:
10+
- 'cra-evidence/**'
11+
- '.github/workflows/cra-evidence.yml'
12+
13+
jobs:
14+
validate-auditor-packet:
15+
runs-on: ubuntu-latest
16+
steps:
17+
- uses: actions/checkout@v4
18+
- uses: actions/setup-python@v5
19+
with:
20+
python-version: '3.x'
21+
- name: Validate pinned auditor packet
22+
run: ./cra-evidence/scripts/validate.sh

‎README.md‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -413,6 +413,26 @@ Please see the
413413
for further usage and details.
414414

415415

416+
<br />
417+
418+
#### cra-evidence (CRA / SBOM evidence kit)
419+
420+
This directory is **not** a TLS/crypto tutorial. It demonstrates how to
421+
generate wolfSSL **component SBOMs** (SPDX + CycloneDX), nest them in a
422+
**fictional product SBOM**, and understand optional **bomsh** build provenance
423+
(Linux host only) for EU Cyber Resilience Act-style software transparency.
424+
425+
Includes a [CRA compliance shortlist](cra-evidence/CRA-Compliance-Shortlist.md), an
426+
[Evidence Map cheat sheet](cra-evidence/CRA-Cheat-Sheet.md), full
427+
[glossary](cra-evidence/CRA-Supply-Chain-Glossary.md), [AI playbook](cra-evidence/SKILL.md), sample
428+
[auditor packet](cra-evidence/auditor-packet/), and helper scripts (`validate.sh`
429+
runs without building wolfSSL). Regenerating component SBOMs requires a wolfSSL
430+
tree with SBOM support — see [cra-evidence/README.md](cra-evidence/README.md).
431+
432+
Please see the [cra-evidence/README.md](cra-evidence/README.md) for further
433+
usage and details.
434+
435+
416436
<br />
417437

418438
#### uefi-library (wolfCrypt UEFI boot module and test app)

‎cra-evidence/CRA-Cheat-Sheet.md‎

Lines changed: 103 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,103 @@
1+
# wolfSSL CRA Supply Chain Cheat Sheet
2+
3+
**Evidence Map** — what **you** provide vs what **wolfSSL** provides
4+
Print this page; use **[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)** for full definitions (SBOM, SPDX, CycloneDX, CBOM, VEX, bomsh, PURL, …).
5+
6+
**Not legal advice.** You are the **manufacturer** for your product on the EU market.
7+
wolfSSL provides **component evidence** for the **wolfSSL library only**.
8+
9+
Requires a wolfSSL tree with SBOM support (`make sbom` / `scripts/gen-sbom`).
10+
`make sbom` also needs `pyspdxtools` (`pip install spdx-tools`).
11+
12+
**Kit:** `wolfssl-examples/cra-evidence/` · **AI playbook:** [SKILL.md](SKILL.md)
13+
**Product-level CRA shortlist (3 pillars):** [CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)
14+
15+
---
16+
17+
## CRA compliance shortlist (three pillars)
18+
19+
| Pillar | You | wolfSSL |
20+
|--------|-----|---------|
21+
| **1. Know your components** | Product SBOM + vuln process for whole product | Component SBOMs, advisories, updates — **this kit** |
22+
| **2. Secure boot** | Trusted firmware + update path | **wolfBoot** |
23+
| **3. Data in transfer** | Secure protocols for remote/cloud traffic | **TLS**, **SSH**, **MQTTS**, … |
24+
25+
Detail: [CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)
26+
27+
---
28+
29+
## Evidence Map (you vs wolfSSL)
30+
31+
| | **You (product manufacturer)** | **wolfSSL (library supplier)** |
32+
|---|-------------------------------|--------------------------------|
33+
| **Inventory** | **Product SBOM** — OS, apps, all third-party code | **Component SBOM** — wolfSSL only (SPDX + CycloneDX) |
34+
| **How you connect** | Nest or reference our files in your product SBOM | Ship `wolfssl-*.spdx.json` and `wolfssl-*.cdx.json` |
35+
| **Vulnerabilities** | Your process + owner for the shipped product | Advisories + [SECURITY-POLICY](https://github.com/wolfSSL/wolfssl/blob/master/SECURITY-POLICY.md) |
36+
| **Optional build proof** | Only if your contract/auditor asks | `make bomsh` / OmniBOR (**Linux build host** only) |
37+
38+
**Worked example:** [`auditor-packet/`](auditor-packet/) — fictional *Acme Connect Gateway* + wolfSSL SBOMs nested.
39+
40+
---
41+
42+
## Three questions auditors ask
43+
44+
| Question | Term | wolfSSL today |
45+
|----------|------|---------------|
46+
| What software is in the product? | **SBOM** | `make sbom` or `gen-sbom` → SPDX + CycloneDX |
47+
| What crypto is enabled in *your* build? | **CBOM** (path) | `wolfssl:build:*` in CycloneDX — not full `cryptographic-asset` yet |
48+
| How was the library binary built? | **Provenance** | `make bomsh` (**Linux** host, optional) |
49+
50+
*See glossary for SPDX vs CycloneDX, VEX, PURL, OmniBOR.*
51+
52+
---
53+
54+
## BOMs at a glance
55+
56+
| Name | Owner | wolfSSL today |
57+
|------|-------|---------------|
58+
| **Product SBOM** | **You** | — |
59+
| **Component SBOM** | **wolfSSL** (you nest) | **Yes** |
60+
| **CBOM** | **You** document; we signal config | **Partial** (build properties) |
61+
| **VEX** | **You** (+ scanner) | Advisories only |
62+
| **bomsh** | **wolfSSL** (optional) | **Yes**, Linux host only |
63+
64+
Details: [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) · roadmap: [ROADMAP.md](ROADMAP.md)
65+
66+
---
67+
68+
## Four decisions
69+
70+
| Question | Answer |
71+
|----------|--------|
72+
| Need **our own** SBOM? | **Yes** |
73+
| wolfSSL SBOM **enough alone**? | **No** — nest or reference in yours |
74+
| Need **bomsh** for CRA? | **Usually no** |
75+
| **SPDX** or **CycloneDX**? | **Both** — use what your tools consume |
76+
77+
---
78+
79+
## Friday plan (first week)
80+
81+
| When | Action |
82+
|------|--------|
83+
| **Today** | `make sbom` or `./scripts/generate-wolfssl-sbom.sh` |
84+
| **This week** | **Product SBOM** — nest wolfSSL (see `auditor-packet/`) |
85+
| **Before release** | Product SBOM in CI; vulnerability owner |
86+
| **If contract requires** | **bomsh** on **Linux CI** only (not macOS/Windows native) |
87+
| **With AI assistants** | Use [SKILL.md](SKILL.md) in Cursor / your agent — copy to `.cursor/skills/wolfssl-cra-evidence/` |
88+
89+
**bomsh:** optional Linux build trace; firmware can target any OS.
90+
91+
---
92+
93+
## What to read next
94+
95+
| Resource | File |
96+
|----------|------|
97+
| Full glossary | [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) |
98+
| Integration guide | [README.md](README.md) |
99+
| Sample auditor folder | [auditor-packet/](auditor-packet/) |
100+
| AI + scripts playbook | [SKILL.md](SKILL.md) |
101+
| Upstream deep dive | [wolfssl/doc/CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md) |
102+
103+
**Questions:** support@wolfssl.com

‎cra-evidence/CRA-Compliance-Shortlist.md‎

Lines changed: 72 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,72 @@
1+
# Shortlist towards CRA compliance
2+
3+
**Not legal advice.** The EU Cyber Resilience Act applies to **your product** as a whole.
4+
wolfSSL helps on **specific pillars** below; you remain the **manufacturer** for market obligations.
5+
6+
This page is the **product-level shortlist** (what to do). For **software transparency evidence**
7+
(SBOM, nesting, sample auditor folder), use the **[CRA Evidence Kit](README.md)** cheat sheet and
8+
[`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md).
9+
10+
---
11+
12+
## 1. Know your software components
13+
14+
| **Your job (manufacturer)** | **wolfSSL can help** |
15+
|----------------------------|----------------------|
16+
| Run a **survey** of every component in your embedded system or product: What is it? Who maintains it? Is it actively developed? How do you learn about vulnerabilities, fixes, and releases? | **Component SBOMs** (SPDX + CycloneDX) for wolfSSL libraries you ship — `make sbom` / `gen-sbom` |
17+
| Build and maintain a **product SBOM** for the whole thing you place on the EU market | **Continuous vulnerability management**: security advisories, coordinated disclosure, updates — see [SECURITY-POLICY](https://github.com/wolfSSL/wolfssl/blob/master/SECURITY-POLICY.md) |
18+
| Own vulnerability **process**, owners, and fix timelines for **your** release | Nest or reference our component SBOM in yours — worked example: [`auditor-packet/`](auditor-packet/) |
19+
20+
**Evidence Kit focus:** pillar 1 — Evidence Map, glossary, Friday plan, [`SKILL.md`](SKILL.md).
21+
22+
---
23+
24+
## 2. Implement secure boot
25+
26+
| **Your job (manufacturer)** | **wolfSSL can help** |
27+
|----------------------------|----------------------|
28+
| Treat secure boot as one of the **most influential actions** you can take now: firmware that boots **trusted**, with a defined path to **update** when needed | **[wolfBoot](https://www.wolfssl.com/products/wolfboot/)** — secure bootloader for embedded systems |
29+
| Align update mechanics with your **complaint / incident** procedures and required **timelines** under CRA | Integration with wolfSSL/wolfCrypt; see wolfBoot docs and support |
30+
31+
Secure boot is **product architecture**, not something an SBOM file alone satisfies.
32+
33+
---
34+
35+
## 3. Bring remote data processing and data-in-transfer up to compliance
36+
37+
CRA is **not only about software inventory** — it also concerns **data** moving between the device and the network.
38+
39+
| **Your job (manufacturer)** | **wolfSSL can help** |
40+
|----------------------------|----------------------|
41+
| Map **remote processing** and **connectivity** in your product (cloud, OTA, admin interfaces, telemetry) | Implementations of **state-of-the-art** secure protocols, for example: |
42+
| Use **current cryptography** and **secure protocols** for data in transfer; document what is enabled in **your** build | **TLS** (wolfSSL), **SSH** (wolfSSH), **MQTTS** (wolfMQTT), and related stacks |
43+
| Reflect enabled algorithms in **your** product documentation / SBOM / crypto inventory | Build properties in CycloneDX today (`wolfssl:build:*`); formal CBOM profile: **roadmap** — [ROADMAP.md](ROADMAP.md) |
44+
45+
---
46+
47+
## How this maps to the Evidence Kit
48+
49+
| Shortlist pillar | Kit deliverable |
50+
|------------------|-----------------|
51+
| Know your components | Cheat sheet (Evidence Map), glossary, `auditor-packet/`, generate/validate scripts |
52+
| Secure boot | Out of scope for SBOM files — evaluate **wolfBoot** separately |
53+
| Data in transfer | Configure and document **your** protocol stack; wolfSSL ships crypto libraries, not your full product compliance |
54+
55+
**You will leave with (presentation Promise):**
56+
57+
1. **Evidence Map** — [`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md)
58+
2. **Worked example** — [`auditor-packet/`](auditor-packet/)
59+
3. **Friday plan** — product SBOM, nest wolfSSL, optional bomsh on **Linux CI** + [`SKILL.md`](SKILL.md)
60+
61+
---
62+
63+
## Related wolfSSL products (beyond this kit)
64+
65+
| Area | Product / doc |
66+
|------|----------------|
67+
| TLS / wolfCrypt | [wolfssl.com](https://www.wolfssl.com/) · [doc/CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md) |
68+
| Secure boot | [wolfBoot](https://www.wolfssl.com/products/wolfboot/) |
69+
| SSH | wolfSSH |
70+
| MQTT | wolfMQTT |
71+
72+
**Questions:** support@wolfssl.com

‎cra-evidence/CRA-Customer-One-Pager.md‎

Lines changed: 3 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,3 @@
1+
# Renamed
2+
3+
This file is now **[CRA-Cheat-Sheet.md](CRA-Cheat-Sheet.md)** (CRA Supply Chain Cheat Sheet / Evidence Map).

‎cra-evidence/CRA-Supply-Chain-Glossary.md‎

Lines changed: 111 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,111 @@
1+
# CRA & Supply Chain Terminology — Customer Cheat Sheet
2+
3+
One-page reference for teams shipping products that include wolfSSL.
4+
**Not legal advice.** Map obligations to your product class and role with counsel.
5+
6+
This kit is **self-contained** in [wolfssl-examples `cra-evidence/`](https://github.com/wolfSSL/wolfssl-examples/tree/master/cra-evidence).
7+
Upstream wolfSSL integration detail (requires a wolfSSL source tree with SBOM support):
8+
9+
- [CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md)
10+
- [SBOM.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md)
11+
12+
CRA shortlist (3 pillars): [`CRA-Compliance-Shortlist.md`](CRA-Compliance-Shortlist.md) · Evidence Map: [`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md) · AI playbook: [`SKILL.md`](SKILL.md) · Worked example: [`auditor-packet/`](auditor-packet/)
13+
14+
---
15+
16+
## The big picture (30 seconds)
17+
18+
```mermaid
19+
flowchart LR
20+
subgraph you["Your company (manufacturer)"]
21+
PSBOM["Product SBOM\n(all components)"]
22+
end
23+
subgraph wolf["wolfSSL (component)"]
24+
WSBOM["wolfSSL SBOM\n(SPDX + CycloneDX)"]
25+
BOMSH["OmniBOR / bomsh\n(optional)"]
26+
end
27+
PSBOM -->|"references or contains"| WSBOM
28+
WSBOM -.->|"optional deeper proof"| BOMSH
29+
```
30+
31+
| Question | Short answer |
32+
|----------|--------------|
33+
| Do we need **our own** SBOM? | **Yes** — for the **whole product** you place on the EU market. |
34+
| Is wolfSSL’s SBOM enough by itself? | **No** (unless you only redistribute wolfSSL). Use it **inside** your product SBOM. |
35+
| Do we need **bomsh**? | **Usually no.** SBOM alone covers most CRA transparency needs; bomsh adds build traceability if you want it. |
36+
| SPDX or CycloneDX? | **Both are fine.** wolfSSL ships both; use whichever your tools expect (many teams keep both). |
37+
38+
---
39+
40+
## Glossary
41+
42+
| Term | Stands for / means | Plain English |
43+
|------|-------------------|---------------|
44+
| **CRA** | EU **Cyber Resilience Act** | EU law for products with digital elements: inventory, security, vulnerability handling. |
45+
| **SBOM** | **Software Bill of Materials** | Machine-readable “ingredients list” of software in a product (name, version, supplier, license, IDs, relationships). |
46+
| **Product SBOM** | — | **Yours:** every OSS/third-party component in the **shipped product**. |
47+
| **Component SBOM** | — | **wolfSSL’s:** inventory of **wolfSSL only** (`make sbom` or `gen-sbom`). |
48+
| **SPDX** | **Software Package Data Exchange** | A standard **format** for SBOMs (Linux Foundation). Files: `*.spdx.json`, `*.spdx`. |
49+
| **CycloneDX** | (project name) | Another standard **format** for SBOMs (OWASP ecosystem). File: `*.cdx.json`. |
50+
| **NTIA minimum elements** | US NTIA guidance | Checklist of what a “good” SBOM must include (supplier, name, version, unique ID, deps, author, timestamp). CRA practice aligns with this. |
51+
| **PURL** | **Package URL** | Standard ID like `pkg:generic/wolfssl@5.9.1` — helps tools match components. |
52+
| **CPE** | **Common Platform Enumeration** | Standard ID like `cpe:2.3:a:wolfssl:wolfssl:…` — used by many vulnerability databases. |
53+
| **VEX** | **Vulnerability Exploitability eXchange** | CycloneDX-side signal: “this CVE does/doesn’t apply to our build.” Often layered on top of SBOM in security tools. |
54+
| **CBOM** | **Cryptographic Bill of Materials** | Inventory of **crypto algorithms/keys/modules** (beyond generic SBOM). Today: `wolfssl:build:*` in CycloneDX; formal CBOM: see [`ROADMAP.md`](ROADMAP.md). |
55+
| **bomsh** | wolfSSL **make** target | Runs **OmniBOR** provenance: proves **how** the library binary was built from sources (**Linux host only**). |
56+
| **OmniBOR** | Omni **Bill of Resources** | Merkle DAG of build inputs/outputs; stored under `omnibor/`. |
57+
| **gitoid** | Git-object-style ID | Hash pointer (`gitoid:blob:sha1:…`) into the OmniBOR graph; appears in `omnibor.*.spdx.json`. |
58+
| **Manufacturer** | CRA role | Entity that places the product on the EU market — **owns** product SBOM and vulnerability process. |
59+
| **Integrator / OEM** | Industry term | You build a device/app containing wolfSSL → you typically act as **manufacturer** for your product. |
60+
| **externalDocumentRefs** | SPDX feature | Your product SPDX **points to** wolfSSL’s SPDX file without copying every file entry. |
61+
| **SOURCE_DATE_EPOCH** | Reproducible builds | Fixed timestamp so two `make sbom` runs produce **byte-identical** SBOMs (useful in CI/attestation). |
62+
63+
---
64+
65+
## wolfSSL artefacts (what we ship)
66+
67+
| Command | Outputs | Answers |
68+
|---------|---------|---------|
69+
| `make sbom` | `wolfssl-<ver>.spdx.json`, `.cdx.json`, `.spdx` | **What** is in wolfSSL (version, license, hashes, config flags). |
70+
| `make bomsh` *(optional)* | `omnibor/`, `omnibor.wolfssl-<ver>.spdx.json` | **How** wolfSSL was built (source → binary traceability). |
71+
72+
Embedded/custom builds: `scripts/gen-sbom` with **your** `user_settings.h` and source list — see kit
73+
[`scripts/generate-embedded-sbom.sh`](scripts/generate-embedded-sbom.sh) and upstream [SBOM.md §1](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md).
74+
75+
---
76+
77+
## Your checklist
78+
79+
1. **Product SBOM** in release CI (SPDX and/or CycloneDX).
80+
2. **wolfSSL component** — reference our SBOM (`externalDocumentRefs` / CycloneDX `bom` ref) or copy the package entry; link with `STATIC_LINK` / `DYNAMIC_LINK` / `CONTAINS`.
81+
3. **Match your build** — if `user_settings.h` or source set differs from stock, regenerate wolfSSL’s SBOM for **your** build.
82+
4. **Commercial license** — override GPL in SBOM (`SBOM_LICENSE_OVERRIDE`) or in **your** product SBOM entry for wolfSSL; see upstream [CRA.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/CRA.md).
83+
5. **Vulnerabilities** — document your process; wolfSSL disclosure: [SECURITY-POLICY.md](https://github.com/wolfSSL/wolfssl/blob/master/SECURITY-POLICY.md).
84+
6. **bomsh** — only if auditors or contracts ask for build-level proof beyond the SBOM (Linux CI).
85+
86+
---
87+
88+
## SPDX vs CycloneDX (same job, different tools)
89+
90+
| | **SPDX** | **CycloneDX** |
91+
|---|----------|----------------|
92+
| **Typical use** | License compliance, legal review, nested documents | Security scanners, VEX, commercial SBOM platforms |
93+
| **wolfSSL file** | `wolfssl-<ver>.spdx.json` | `wolfssl-<ver>.cdx.json` |
94+
| **Nesting wolfSSL** | `externalDocumentRefs` + relationship | Component + `externalReferences` type `bom` |
95+
96+
You do **not** choose “CRA format” — you provide an SBOM that meets NTIA-style expectations; SPDX and CycloneDX are both widely accepted encodings.
97+
98+
---
99+
100+
## Who provides what to an auditor
101+
102+
| Evidence | Provided by |
103+
|----------|-------------|
104+
| Product SBOM (full inventory) | **Customer** |
105+
| wolfSSL SBOM files | **wolfSSL** (customer integrates or references) |
106+
| OmniBOR / bomsh bundle | **wolfSSL** *(optional)* |
107+
| Vulnerability disclosure & advisories | **wolfSSL** ([security page](https://www.wolfssl.com/docs/security-vulnerabilities/)); **customer** owns product incident process |
108+
109+
---
110+
111+
*wolfSSL · Part of the [CRA Evidence Kit](README.md). Questions: support@wolfssl.com*

‎cra-evidence/EVIDENCE-MAP.md‎

Lines changed: 7 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,7 @@
1+
# Evidence Map → cheat sheet
2+
3+
The **Evidence Map** (what you provide vs what wolfSSL provides) is:
4+
5+
**[CRA-Cheat-Sheet.md](CRA-Cheat-Sheet.md)**
6+
7+
Full terminology: **[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)** · AI playbook: **[SKILL.md](SKILL.md)**

‎cra-evidence/GLOSSARY.md‎

Lines changed: 8 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,8 @@
1+
# Glossary
2+
3+
| Layer | File |
4+
|-------|------|
5+
| **CRA shortlist** (3 pillars) | **[CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)** |
6+
| **Evidence Map** (1-page cheat sheet) | **[CRA-Cheat-Sheet.md](CRA-Cheat-Sheet.md)** |
7+
| **Full glossary** (SBOM, SPDX, CycloneDX, CBOM, VEX, bomsh, …) | **[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)** |
8+
| **AI playbook** (Friday plan + scripts) | **[SKILL.md](SKILL.md)** |

0 commit comments

Comments
 (0)