Skip to content

Commit c003219

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

43 files changed

Lines changed: 3828 additions & 0 deletions

Some content is hidden

Large Commits have some content hidden by default. Use the searchbox below for content that may be hidden.

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

Lines changed: 22 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,22 @@
1+
name: CRA Kit
2+
3+
on:
4+
push:
5+
paths:
6+
- 'cra-kit/**'
7+
- '.github/workflows/cra-kit.yml'
8+
pull_request:
9+
paths:
10+
- 'cra-kit/**'
11+
- '.github/workflows/cra-kit.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-kit/scripts/validate.sh

‎README.md‎

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

415415

416+
<br />
417+
418+
#### cra-kit (wolfSSL CRA 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-kit/CRA-Compliance-Shortlist.md), a
426+
[who provides what cheat sheet](cra-kit/CRA-Cheat-Sheet.md), full
427+
[glossary](cra-kit/CRA-Supply-Chain-Glossary.md), [AI playbook](cra-kit/SKILL.md), sample
428+
[customer-side auditor packet](cra-kit/auditor-packet/) (fictional Acme Connect
429+
Gateway), [manufacturer-side filings](cra-kit/wolfssl-inc-auditor-packet/) (what
430+
wolfSSL Inc. itself ships under CRA — classification, conformity assessment,
431+
declaration of conformity template, EU AR status, etc.), and helper scripts
432+
(`validate.sh` runs without building wolfSSL, with optional `cyclonedx-cli` /
433+
`pyspdxtools` schema validation). Regenerating component SBOMs requires a
434+
wolfSSL tree with SBOM support — see [cra-kit/README.md](cra-kit/README.md).
435+
436+
Please see the [cra-kit/README.md](cra-kit/README.md) for further
437+
usage and details.
438+
439+
416440
<br />
417441

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

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

Lines changed: 114 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,114 @@
1+
# wolfSSL CRA Supply Chain Cheat Sheet
2+
3+
**Who provides what** — **you** vs **wolfSSL**
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+
wolfSSL Inc. is itself a manufacturer under CRA for libraries it places on the EU market —
9+
see our [`security.txt`](https://www.wolfssl.com/.well-known/security.txt),
10+
[CVD policy](https://www.wolfssl.com/.well-known/vulnerability-disclosure-policy.txt),
11+
and our manufacturer-side filings in
12+
[`wolfssl-inc-auditor-packet/`](wolfssl-inc-auditor-packet/) for reference.
13+
14+
Requires a wolfSSL tree with SBOM support (`make sbom` / `scripts/gen-sbom`).
15+
`make sbom` also needs `pyspdxtools` (`pip install spdx-tools`).
16+
17+
**CRA Kit:** `wolfssl-examples/cra-kit/` · **AI playbook:** [SKILL.md](SKILL.md)
18+
**Product-level CRA shortlist (4 pillars):** [CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)
19+
20+
---
21+
22+
## CRA compliance shortlist (four pillars)
23+
24+
| Pillar | You | wolfSSL |
25+
|--------|-----|---------|
26+
| **1. Know your components** | Product SBOM + vuln process for whole product | Component SBOMs, advisories, updates — **this kit** |
27+
| **2. Secure boot** | Trusted firmware + update path | **wolfBoot** |
28+
| **3. Data in transfer** | Secure protocols for remote/cloud traffic | **TLS**, **SSH**, **MQTTS**, … |
29+
| **4. Vulnerability handling & reporting** | Published CVD policy + `security.txt`; 24h ENISA reporting (Art. 14); on-call coverage | Reference templates: wolfSSL [`security.txt`](https://www.wolfssl.com/.well-known/security.txt) + [CVD policy](https://www.wolfssl.com/.well-known/vulnerability-disclosure-policy.txt); advisories; CNA |
30+
31+
Detail: [CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)
32+
33+
---
34+
35+
## Who provides what (you vs wolfSSL)
36+
37+
| | **You (product manufacturer)** | **wolfSSL (library supplier)** |
38+
|---|-------------------------------|--------------------------------|
39+
| **Inventory** | **Product SBOM** — OS, apps, all third-party code | **Component SBOM** — wolfSSL only (SPDX + CycloneDX) |
40+
| **How you connect** | Nest or reference our files in your product SBOM | Ship `wolfssl-*.spdx.json` and `wolfssl-*.cdx.json` |
41+
| **Vulnerabilities** | Your process + owner for the shipped product | [Advisories](https://www.wolfssl.com/docs/security-vulnerabilities/) + [CVD policy](https://www.wolfssl.com/.well-known/vulnerability-disclosure-policy.txt) + [`security.txt`](https://www.wolfssl.com/.well-known/security.txt) |
42+
| **Optional build proof** | Only if your contract/auditor asks | `make bomsh` / OmniBOR (**Linux build host** only) |
43+
44+
**Worked example:** [`auditor-packet/`](auditor-packet/) — fictional *Acme Connect Gateway* + wolfSSL SBOMs nested.
45+
46+
---
47+
48+
## What auditors ask
49+
50+
| Question | Term | wolfSSL today |
51+
|----------|------|---------------|
52+
| What software is in the product? | **SBOM** | `make sbom` or `gen-sbom` → SPDX + CycloneDX |
53+
| What crypto is enabled in *your* build? | **CBOM** (path) | `wolfssl:build:*` in CycloneDX — not full `cryptographic-asset` yet |
54+
| How was the library binary built? | **Provenance** | `make bomsh` (**Linux** host, optional) |
55+
56+
*See glossary for SPDX vs CycloneDX, VEX, PURL, OmniBOR.*
57+
58+
---
59+
60+
## BOMs at a glance
61+
62+
| Name | Owner | wolfSSL today |
63+
|------|-------|---------------|
64+
| **Product SBOM** | **You** | — |
65+
| **Component SBOM** | **wolfSSL** (you nest) | **Yes** |
66+
| **CBOM** | **You** document; we signal config | **Partial** (build properties) |
67+
| **VEX** | **You** (+ scanner) | Advisories only |
68+
| **bomsh** | **wolfSSL** (optional) | **Yes**, Linux host only |
69+
70+
Details: [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) · roadmap: [ROADMAP.md](ROADMAP.md)
71+
72+
---
73+
74+
## Four decisions
75+
76+
| Question | Answer |
77+
|----------|--------|
78+
| Need **our own** SBOM? | **Yes** |
79+
| wolfSSL SBOM **enough alone**? | **No** — nest or reference in yours |
80+
| Need **bomsh** for CRA? | **Usually no** |
81+
| **SPDX** or **CycloneDX**? | **Both** — use what your tools consume |
82+
83+
---
84+
85+
## Beyond this kit (don't skip)
86+
87+
This kit covers **software transparency** only. Before placing your product on
88+
the EU market you also need:
89+
90+
| Obligation | Article | Action |
91+
|------------|---------|--------|
92+
| **EU Authorised Representative** | Art. 18 | Required if you're established outside the EU |
93+
| **Product class** (Annex III/IV) | — | Determines self-cert vs **Notified Body** — long queues |
94+
| **Conformity assessment + CE mark** | Art. 32, 30 | Module A or external review |
95+
| **Technical documentation** | Annex VII | Risk assessment, support-period commitment |
96+
| **Free security updates** | Art. 13(8) | 5+ year support period default |
97+
98+
Engage CRA counsel/consultant — these are legal/structural decisions, not
99+
artefacts. See [`CRA-Compliance-Shortlist.md`](CRA-Compliance-Shortlist.md)
100+
"Beyond this kit" for detail.
101+
102+
---
103+
104+
## What to read next
105+
106+
| Resource | File |
107+
|----------|------|
108+
| Full glossary | [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) |
109+
| Integration guide | [README.md](README.md) |
110+
| Sample auditor folder | [auditor-packet/](auditor-packet/) |
111+
| AI + scripts playbook | [SKILL.md](SKILL.md) |
112+
| Upstream SBOM reference (flags, formats, OmniBOR) | [wolfssl/doc/SBOM.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md) |
113+
114+
**Questions about this kit:** support@wolfssl.com · **Security reports:** see [`security.txt`](https://www.wolfssl.com/.well-known/security.txt)

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

Lines changed: 130 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,130 @@
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** work
7+
(SBOM, nesting, sample auditor folder), use the **[CRA 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](https://www.wolfssl.com/docs/security-vulnerabilities/), coordinated disclosure, updates — see wolfSSL [`security.txt`](https://www.wolfssl.com/.well-known/security.txt) and [CVD policy](https://www.wolfssl.com/.well-known/vulnerability-disclosure-policy.txt) |
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+
**CRA Kit focus:** pillar 1 — who provides what cheat sheet, glossary, scripts, [`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+
## 4. Handle vulnerabilities and report on time
48+
49+
CRA imposes **continuous** vulnerability handling obligations on manufacturers
50+
(Art. 13) and a hard **24-hour** reporting clock for actively exploited
51+
vulnerabilities (Art. 14). This is the only CRA pillar that requires **ongoing
52+
operational capacity**, not a one-time deliverable.
53+
54+
| **Your job (manufacturer)** | **wolfSSL can help** |
55+
|----------------------------|----------------------|
56+
| Publish a **Coordinated Vulnerability Disclosure (CVD) policy** and a working security contact (`security.txt` per RFC 9116) so researchers can reach you | Reference templates: wolfSSL's [`security.txt`](https://www.wolfssl.com/.well-known/security.txt) and [CVD policy](https://www.wolfssl.com/.well-known/vulnerability-disclosure-policy.txt) |
57+
| Operate a **vulnerability handling process** with named owners and stated response targets | wolfSSL [security advisories](https://www.wolfssl.com/docs/security-vulnerabilities/) for libraries you ship; wolfSSL is a CVE Numbering Authority |
58+
| Notify **ENISA within 24 hours** when a vulnerability in your product is **actively exploited** (Art. 14); follow up at 72 hours and a final report at 14 days | wolfSSL handles ENISA reporting for **wolfSSL libraries placed on the EU market by wolfSSL Inc.**; coordinate with us on shared advisories |
59+
| Maintain **on-call coverage** including weekends and holidays so the 24-hour clock can be met at any time | — |
60+
61+
This pillar is **not satisfied by SBOM artefacts alone** — it requires
62+
documented process, named owners, and on-call capacity. The 24-hour ENISA clock
63+
starts from your **awareness** of active exploitation, not from public disclosure.
64+
65+
---
66+
67+
## Beyond this kit (structural CRA obligations)
68+
69+
The four pillars above cover **software transparency**. A full CRA conformity
70+
assessment also requires structural obligations that **this kit does not
71+
cover** — flag these to your CRA consultant or counsel **before** assuming
72+
SBOMs alone make you ready:
73+
74+
| Obligation | Article | What it means |
75+
|------------|---------|---------------|
76+
| **EU Authorised Representative** | Art. 18 | Manufacturers established **outside** the EU must appoint a written-mandated representative **inside** the EU before placing a product on the EU market. Either contract a third-party AR service or use an existing EU subsidiary. |
77+
| **Product classification** | Annex III / IV | Determines whether conformity assessment is self-declared (default class) or requires a **Notified Body** (important / critical class). Notified-body queues are already long — if you may need one, get in queue early. |
78+
| **Conformity assessment + CE mark** | Art. 32, 30 | Module A (self-assessment) or external review per classification; CE marking before placing the product on the EU market. |
79+
| **Technical documentation** | Annex VII | Risk assessment, secure-design rationale, vulnerability handling process, support-period commitment — more than the SBOM. |
80+
| **Free security updates** | Art. 13(8) | Minimum 5-year support period for security updates by default (longer if the product's expected lifetime is longer). |
81+
| **Importer / distributor obligations** | Art. 19, 20 | If your product enters the EU via an importer or moves through distributors, additional obligations attach to those parties. |
82+
83+
These are **legal and structural decisions**, not artefacts you can generate
84+
from source code. wolfSSL ships SBOMs, security-policy templates, and the
85+
narrative in this kit; **you** appoint your EU AR, classify your product, run
86+
your conformity assessment, and produce your declaration of conformity. If
87+
you do not yet have a CRA consultant, engaging one for the
88+
classification + AR questions specifically is usually the highest-leverage
89+
early step.
90+
91+
**See how wolfSSL Inc. itself answers each of these.**
92+
[`wolfssl-inc-auditor-packet/`](wolfssl-inc-auditor-packet/) holds the
93+
manufacturer-side filings wolfSSL Inc. ships under CRA: Annex III/IV
94+
classification statement, conformity assessment route, declaration of
95+
conformity template, EU Authorised Representative status, support-period
96+
policy, vulnerability-handling process, technical documentation outline,
97+
and CE marking statement. Where decisions are made, they're stated; where
98+
they're in flight (EU AR appointment, public SLA), the gap is named.
99+
Adapt as a template for your own product.
100+
101+
---
102+
103+
## How this maps to the CRA Kit
104+
105+
| Shortlist pillar | Kit deliverable |
106+
|------------------|-----------------|
107+
| Know your components | Cheat sheet (who provides what), glossary, `auditor-packet/`, generate/validate scripts |
108+
| Secure boot | Out of scope for SBOM files — evaluate **wolfBoot** separately |
109+
| Data in transfer | Configure and document **your** protocol stack; wolfSSL ships crypto libraries, not your full product compliance |
110+
| Vulnerability handling & reporting | Outside scope of SBOM artefacts — see Art. 13/14 obligations above; wolfSSL's own [CVD policy](https://www.wolfssl.com/.well-known/vulnerability-disclosure-policy.txt) and [`security.txt`](https://www.wolfssl.com/.well-known/security.txt) are usable as reference templates |
111+
| Structural CRA obligations (EU AR, Annex III/IV, CE, technical docs, support period) | **Out of scope** for this kit — see "Beyond this kit" section above; engage CRA counsel or consultant |
112+
113+
**You will leave with (presentation Promise):**
114+
115+
1. **Who provides what** — [`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md)
116+
2. **Worked example** — [`auditor-packet/`](auditor-packet/)
117+
3. **Helper scripts + AI playbook** — product SBOM, nest wolfSSL, optional bomsh on **Linux CI** + [`SKILL.md`](SKILL.md)
118+
119+
---
120+
121+
## Related wolfSSL products (beyond this kit)
122+
123+
| Area | Product / doc |
124+
|------|----------------|
125+
| TLS / wolfCrypt | [wolfssl.com](https://www.wolfssl.com/) · upstream SBOM reference: [doc/SBOM.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md) |
126+
| Secure boot | [wolfBoot](https://www.wolfssl.com/products/wolfboot/) |
127+
| SSH | wolfSSH |
128+
| MQTT | wolfMQTT |
129+
130+
**Questions about this kit:** support@wolfssl.com · **Security reports:** see [`security.txt`](https://www.wolfssl.com/.well-known/security.txt)

0 commit comments

Comments
 (0)