Skip to content

Add CRA Kit for customer SBOM integration #574

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
sameehj wants to merge 1 commit into
base: master
Choose a base branch
from
Open

Add CRA Kit for customer SBOM integration #574

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
22 changes: 22 additions & 0 deletions .github/workflows/cra-kit.yml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,22 @@
name: CRA Kit

on:
push:
paths:
- 'cra-kit/**'
- '.github/workflows/cra-kit.yml'
pull_request:
paths:
- 'cra-kit/**'
- '.github/workflows/cra-kit.yml'

jobs:
validate-auditor-packet:
runs-on: ubuntu-latest
steps:
- uses: actions/checkout@v4
- uses: actions/setup-python@v5
with:
python-version: '3.x'
- name: Validate pinned auditor packet
run: ./cra-kit/scripts/validate.sh
24 changes: 24 additions & 0 deletions README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -413,6 +413,30 @@ Please see the
for further usage and details.


<br />

#### cra-kit (wolfSSL CRA Kit)

This directory is **not** a TLS/crypto tutorial. It demonstrates how to
generate wolfSSL **component SBOMs** (SPDX + CycloneDX), nest them in a
**fictional product SBOM**, and understand optional **bomsh** build provenance
(Linux host only) for EU Cyber Resilience Act-style software transparency.

Includes a [CRA compliance shortlist](cra-kit/CRA-Compliance-Shortlist.md), a
[who provides what cheat sheet](cra-kit/CRA-Cheat-Sheet.md), full
[glossary](cra-kit/CRA-Supply-Chain-Glossary.md), [AI playbook](cra-kit/SKILL.md), sample
[customer-side auditor packet](cra-kit/auditor-packet/) (fictional Acme Connect
Gateway), [manufacturer-side filings](cra-kit/wolfssl-inc-auditor-packet/) (what
wolfSSL Inc. itself ships under CRA — classification, conformity assessment,
declaration of conformity template, EU AR status, etc.), and helper scripts
(`validate.sh` runs without building wolfSSL, with optional `cyclonedx-cli` /
`pyspdxtools` schema validation). Regenerating component SBOMs requires a
wolfSSL tree with SBOM support — see [cra-kit/README.md](cra-kit/README.md).

Please see the [cra-kit/README.md](cra-kit/README.md) for further
usage and details.


<br />

#### uefi-library (wolfCrypt UEFI boot module and test app)
Expand Down
114 changes: 114 additions & 0 deletions cra-kit/CRA-Cheat-Sheet.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,114 @@
# wolfSSL CRA Supply Chain Cheat Sheet

**Who provides what** — **you** vs **wolfSSL**
Print this page; use **[CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md)** for full definitions (SBOM, SPDX, CycloneDX, CBOM, VEX, bomsh, PURL, …).

**Not legal advice.** You are the **manufacturer** for your product on the EU market.
wolfSSL provides **component evidence** for the **wolfSSL library only**.
wolfSSL Inc. is itself a manufacturer under CRA for libraries it places on the EU market —
see our [`security.txt`](https://www.wolfssl.com/.well-known/security.txt),
[CVD policy](https://www.wolfssl.com/.well-known/vulnerability-disclosure-policy.txt),
and our manufacturer-side filings in
[`wolfssl-inc-auditor-packet/`](wolfssl-inc-auditor-packet/) for reference.

Requires a wolfSSL tree with SBOM support (`make sbom` / `scripts/gen-sbom`).
`make sbom` also needs `pyspdxtools` (`pip install spdx-tools`).

**CRA Kit:** `wolfssl-examples/cra-kit/` · **AI playbook:** [SKILL.md](SKILL.md)
**Product-level CRA shortlist (4 pillars):** [CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)

---

## CRA compliance shortlist (four pillars)

| Pillar | You | wolfSSL |
|--------|-----|---------|
| **1. Know your components** | Product SBOM + vuln process for whole product | Component SBOMs, advisories, updates — **this kit** |
| **2. Secure boot** | Trusted firmware + update path | **wolfBoot** |
| **3. Data in transfer** | Secure protocols for remote/cloud traffic | **TLS**, **SSH**, **MQTTS**, … |
| **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 |

Detail: [CRA-Compliance-Shortlist.md](CRA-Compliance-Shortlist.md)

---

## Who provides what (you vs wolfSSL)

| | **You (product manufacturer)** | **wolfSSL (library supplier)** |
|---|-------------------------------|--------------------------------|
| **Inventory** | **Product SBOM** — OS, apps, all third-party code | **Component SBOM** — wolfSSL only (SPDX + CycloneDX) |
| **How you connect** | Nest or reference our files in your product SBOM | Ship `wolfssl-*.spdx.json` and `wolfssl-*.cdx.json` |
| **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) |
| **Optional build proof** | Only if your contract/auditor asks | `make bomsh` / OmniBOR (**Linux build host** only) |

**Worked example:** [`auditor-packet/`](auditor-packet/) — fictional *Acme Connect Gateway* + wolfSSL SBOMs nested.

---

## What auditors ask

| Question | Term | wolfSSL today |
|----------|------|---------------|
| What software is in the product? | **SBOM** | `make sbom` or `gen-sbom` → SPDX + CycloneDX |
| What crypto is enabled in *your* build? | **CBOM** (path) | `wolfssl:build:*` in CycloneDX — not full `cryptographic-asset` yet |
| How was the library binary built? | **Provenance** | `make bomsh` (**Linux** host, optional) |

*See glossary for SPDX vs CycloneDX, VEX, PURL, OmniBOR.*

---

## BOMs at a glance

| Name | Owner | wolfSSL today |
|------|-------|---------------|
| **Product SBOM** | **You** | — |
| **Component SBOM** | **wolfSSL** (you nest) | **Yes** |
| **CBOM** | **You** document; we signal config | **Partial** (build properties) |
| **VEX** | **You** (+ scanner) | Advisories only |
| **bomsh** | **wolfSSL** (optional) | **Yes**, Linux host only |

Details: [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) · roadmap: [ROADMAP.md](ROADMAP.md)

---

## Four decisions

| Question | Answer |
|----------|--------|
| Need **our own** SBOM? | **Yes** |
| wolfSSL SBOM **enough alone**? | **No** — nest or reference in yours |
| Need **bomsh** for CRA? | **Usually no** |
| **SPDX** or **CycloneDX**? | **Both** — use what your tools consume |

---

## Beyond this kit (don't skip)

This kit covers **software transparency** only. Before placing your product on
the EU market you also need:

| Obligation | Article | Action |
|------------|---------|--------|
| **EU Authorised Representative** | Art. 18 | Required if you're established outside the EU |
| **Product class** (Annex III/IV) | — | Determines self-cert vs **Notified Body** — long queues |
| **Conformity assessment + CE mark** | Art. 32, 30 | Module A or external review |
| **Technical documentation** | Annex VII | Risk assessment, support-period commitment |
| **Free security updates** | Art. 13(8) | 5+ year support period default |

Engage CRA counsel/consultant — these are legal/structural decisions, not
artefacts. See [`CRA-Compliance-Shortlist.md`](CRA-Compliance-Shortlist.md)
"Beyond this kit" for detail.

---

## What to read next

| Resource | File |
|----------|------|
| Full glossary | [CRA-Supply-Chain-Glossary.md](CRA-Supply-Chain-Glossary.md) |
| Integration guide | [README.md](README.md) |
| Sample auditor folder | [auditor-packet/](auditor-packet/) |
| AI + scripts playbook | [SKILL.md](SKILL.md) |
| Upstream SBOM reference (flags, formats, OmniBOR) | [wolfssl/doc/SBOM.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md) |

**Questions about this kit:** support@wolfssl.com · **Security reports:** see [`security.txt`](https://www.wolfssl.com/.well-known/security.txt)
130 changes: 130 additions & 0 deletions cra-kit/CRA-Compliance-Shortlist.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,130 @@
# Shortlist towards CRA compliance

**Not legal advice.** The EU Cyber Resilience Act applies to **your product** as a whole.
wolfSSL helps on **specific pillars** below; you remain the **manufacturer** for market obligations.

This page is the **product-level shortlist** (what to do). For **software transparency** work
(SBOM, nesting, sample auditor folder), use the **[CRA Kit](README.md)** cheat sheet and
[`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md).

---

## 1. Know your software components

| **Your job (manufacturer)** | **wolfSSL can help** |
|----------------------------|----------------------|
| 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` |
| 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) |
| Own vulnerability **process**, owners, and fix timelines for **your** release | Nest or reference our component SBOM in yours — worked example: [`auditor-packet/`](auditor-packet/) |

**CRA Kit focus:** pillar 1 — who provides what cheat sheet, glossary, scripts, [`SKILL.md`](SKILL.md).

---

## 2. Implement secure boot

| **Your job (manufacturer)** | **wolfSSL can help** |
|----------------------------|----------------------|
| 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 |
| Align update mechanics with your **complaint / incident** procedures and required **timelines** under CRA | Integration with wolfSSL/wolfCrypt; see wolfBoot docs and support |

Secure boot is **product architecture**, not something an SBOM file alone satisfies.

---

## 3. Bring remote data processing and data-in-transfer up to compliance

CRA is **not only about software inventory** — it also concerns **data** moving between the device and the network.

| **Your job (manufacturer)** | **wolfSSL can help** |
|----------------------------|----------------------|
| Map **remote processing** and **connectivity** in your product (cloud, OTA, admin interfaces, telemetry) | Implementations of **state-of-the-art** secure protocols, for example: |
| 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 |
| 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) |

---

## 4. Handle vulnerabilities and report on time

CRA imposes **continuous** vulnerability handling obligations on manufacturers
(Art. 13) and a hard **24-hour** reporting clock for actively exploited
vulnerabilities (Art. 14). This is the only CRA pillar that requires **ongoing
operational capacity**, not a one-time deliverable.

| **Your job (manufacturer)** | **wolfSSL can help** |
|----------------------------|----------------------|
| 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) |
| 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 |
| 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 |
| Maintain **on-call coverage** including weekends and holidays so the 24-hour clock can be met at any time | — |

This pillar is **not satisfied by SBOM artefacts alone** — it requires
documented process, named owners, and on-call capacity. The 24-hour ENISA clock
starts from your **awareness** of active exploitation, not from public disclosure.

---

## Beyond this kit (structural CRA obligations)

The four pillars above cover **software transparency**. A full CRA conformity
assessment also requires structural obligations that **this kit does not
cover** — flag these to your CRA consultant or counsel **before** assuming
SBOMs alone make you ready:

| Obligation | Article | What it means |
|------------|---------|---------------|
| **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. |
| **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. |
| **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. |
| **Technical documentation** | Annex VII | Risk assessment, secure-design rationale, vulnerability handling process, support-period commitment — more than the SBOM. |
| **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). |
| **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. |

These are **legal and structural decisions**, not artefacts you can generate
from source code. wolfSSL ships SBOMs, security-policy templates, and the
narrative in this kit; **you** appoint your EU AR, classify your product, run
your conformity assessment, and produce your declaration of conformity. If
you do not yet have a CRA consultant, engaging one for the
classification + AR questions specifically is usually the highest-leverage
early step.

**See how wolfSSL Inc. itself answers each of these.**
[`wolfssl-inc-auditor-packet/`](wolfssl-inc-auditor-packet/) holds the
manufacturer-side filings wolfSSL Inc. ships under CRA: Annex III/IV
classification statement, conformity assessment route, declaration of
conformity template, EU Authorised Representative status, support-period
policy, vulnerability-handling process, technical documentation outline,
and CE marking statement. Where decisions are made, they're stated; where
they're in flight (EU AR appointment, public SLA), the gap is named.
Adapt as a template for your own product.

---

## How this maps to the CRA Kit

| Shortlist pillar | Kit deliverable |
|------------------|-----------------|
| Know your components | Cheat sheet (who provides what), glossary, `auditor-packet/`, generate/validate scripts |
| Secure boot | Out of scope for SBOM files — evaluate **wolfBoot** separately |
| Data in transfer | Configure and document **your** protocol stack; wolfSSL ships crypto libraries, not your full product compliance |
| 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 |
| 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 |

**You will leave with (presentation Promise):**

1. **Who provides what** — [`CRA-Cheat-Sheet.md`](CRA-Cheat-Sheet.md)
2. **Worked example** — [`auditor-packet/`](auditor-packet/)
3. **Helper scripts + AI playbook** — product SBOM, nest wolfSSL, optional bomsh on **Linux CI** + [`SKILL.md`](SKILL.md)

---

## Related wolfSSL products (beyond this kit)

| Area | Product / doc |
|------|----------------|
| TLS / wolfCrypt | [wolfssl.com](https://www.wolfssl.com/) · upstream SBOM reference: [doc/SBOM.md](https://github.com/wolfSSL/wolfssl/blob/master/doc/SBOM.md) |
| Secure boot | [wolfBoot](https://www.wolfssl.com/products/wolfboot/) |
| SSH | wolfSSH |
| MQTT | wolfMQTT |

**Questions about this kit:** support@wolfssl.com · **Security reports:** see [`security.txt`](https://www.wolfssl.com/.well-known/security.txt)
Loading
Loading