Skip to content

Commit 36f044c

Browse files
mprpiccodex
andcommitted
feat(sbom): merge Maturin components into wheel SBOM
Import non-excluded CycloneDX components from Maturin-generated wheel SBOMs into Fromager's canonical SPDX document. Relate bundled components to the wheel with CONTAINS, normalize local PURLs, and preserve the original CycloneDX files. Closes: #965 Co-Authored-By: OpenAI Codex <noreply@openai.com> Signed-off-by: Martin Prpič <mprpic@redhat.com>
1 parent 52457f1 commit 36f044c

5 files changed

Lines changed: 821 additions & 5 deletions

File tree

‎docs/reference/files.md‎

Lines changed: 33 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -114,6 +114,39 @@ The following example shows `graph.json` file for the top-level dependency `whee
114114
}
115115
```
116116

117+
## Wheel SBOMs
118+
119+
When SBOM generation is enabled, Fromager writes the canonical SPDX 2.3
120+
document to `.dist-info/sboms/fromager.spdx.json`. During source builds,
121+
CycloneDX SBOMs generated by Maturin are read from the same directory and
122+
their components are merged into the canonical SPDX document. Each imported
123+
component is related to the wheel with `CONTAINS`; the CycloneDX dependency
124+
graph is not copied. Nested target components are included, while components
125+
with CycloneDX scope `excluded` are omitted because they are not shipped
126+
runtime dependencies. Local `file://` download qualifiers are removed from
127+
imported PURLs because those paths are only meaningful in the build
128+
environment.
129+
130+
A CycloneDX root with a PyPI PURL matching the wheel's normalized name and
131+
version is associated with the wheel package, so auditwheel components are not
132+
attached to the upstream source. The original CycloneDX files are preserved,
133+
and the SPDX document records a `comment` naming the CycloneDX files it merged.
134+
135+
Maturin must be version 1.12.0 or newer and must be built with its `sbom`
136+
feature enabled. Fromager does not enable that Maturin feature automatically.
137+
For example, a packaging environment can pass Maturin's
138+
`MATURIN_SETUP_ARGS` with a feature set that includes `sbom`. The exact
139+
feature set depends on the platform and packaging environment.
140+
141+
This merge is applied to wheels processed by Fromager's source-build path.
142+
Downloaded prebuilt wheels retain any native SBOM files, but are not guaranteed
143+
to receive a merged Fromager SPDX document until they go through a separate
144+
post-download processing path.
145+
146+
```{versionchanged} 0.96.0
147+
Maturin CycloneDX SBOMs are merged into the canonical Fromager SPDX SBOM.
148+
```
149+
117150
## Output Directories
118151

119152
During the wheel building process, fromager generates multiple output directories namely `sdists-repo`, `wheels-repo` and `work-dir`. These directories contain important information related to the wheel build.

‎src/fromager/sbom.py‎

Lines changed: 264 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,13 +10,14 @@
1010
import json
1111
import logging
1212
import pathlib
13+
import re
1314
import typing
1415
from datetime import UTC, datetime
1516

1617
from packageurl import PackageURL
1718
from packaging.requirements import Requirement
1819
from packaging.utils import NormalizedName, canonicalize_name
19-
from packaging.version import Version
20+
from packaging.version import InvalidVersion, Version
2021

2122
if typing.TYPE_CHECKING:
2223
from . import context
@@ -181,6 +182,268 @@ def generate_sbom(
181182
return doc
182183

183184

185+
# CycloneDX hash algorithm names mapped to their SPDX equivalents.
186+
_CYCLONEDX_HASH_TO_SPDX = {
187+
"SHA-1": "SHA1",
188+
"SHA-224": "SHA224",
189+
"SHA-256": "SHA256",
190+
"SHA-384": "SHA384",
191+
"SHA-512": "SHA512",
192+
"SHA3-224": "SHA3-224",
193+
"SHA3-256": "SHA3-256",
194+
"SHA3-384": "SHA3-384",
195+
"SHA3-512": "SHA3-512",
196+
"BLAKE2B-256": "BLAKE2b-256",
197+
"BLAKE2B-384": "BLAKE2b-384",
198+
"BLAKE2B-512": "BLAKE2b-512",
199+
}
200+
201+
202+
def _clean_purl(purl: str) -> str:
203+
"""Drop local ``file://`` download qualifiers, which are build-only paths."""
204+
try:
205+
parsed = PackageURL.from_string(purl)
206+
except ValueError:
207+
return purl
208+
qualifiers = dict(parsed.qualifiers or {})
209+
if not qualifiers.get("download_url", "").startswith("file://"):
210+
return purl
211+
del qualifiers["download_url"]
212+
return PackageURL(
213+
type=parsed.type,
214+
namespace=parsed.namespace,
215+
name=parsed.name,
216+
version=parsed.version,
217+
qualifiers=qualifiers or None,
218+
subpath=parsed.subpath,
219+
).to_string()
220+
221+
222+
def _iter_components(
223+
component: dict[str, typing.Any],
224+
) -> typing.Iterator[dict[str, typing.Any]]:
225+
"""Yield a component and all of its nested sub-components."""
226+
yield component
227+
for nested in component.get("components", []):
228+
yield from _iter_components(nested)
229+
230+
231+
def _component_key(component: dict[str, typing.Any]) -> str:
232+
"""Return a stable identity used to deduplicate components across files."""
233+
purl = component.get("purl")
234+
if purl:
235+
return _clean_purl(purl)
236+
return "\x00".join(component.get(field, "") for field in ("type", "group", "name"))
237+
238+
239+
def _versions_match(left: str, right: str) -> bool:
240+
try:
241+
return Version(left) == Version(right)
242+
except InvalidVersion:
243+
return left == right
244+
245+
246+
def _matches_wheel(
247+
component: dict[str, typing.Any],
248+
wheel: dict[str, typing.Any],
249+
) -> bool:
250+
"""True if a CycloneDX root is the wheel itself (e.g. an auditwheel root).
251+
252+
Such a root is folded into ``SPDXRef-wheel`` so its native dependencies are
253+
not attached to the upstream source.
254+
"""
255+
purl = component.get("purl")
256+
if not purl:
257+
return False
258+
try:
259+
parsed = PackageURL.from_string(purl)
260+
except ValueError:
261+
return False
262+
if parsed.type != "pypi" or not parsed.name or not parsed.version:
263+
return False
264+
return canonicalize_name(parsed.name) == canonicalize_name(
265+
wheel["name"]
266+
) and _versions_match(parsed.version, wheel["versionInfo"])
267+
268+
269+
def _cyclonedx_license(component: dict[str, typing.Any]) -> str | None:
270+
"""Return the component's declared license as an SPDX expression.
271+
272+
CycloneDX allows either a single SPDX ``expression`` (already valid SPDX,
273+
passed through unchanged) or a list of license objects. cargo/maturin always
274+
emit exactly one entry. A list with multiple entries has undefined AND/OR
275+
semantics, so we warn and skip it rather than guess a relationship. A named
276+
(non-SPDX) license has no valid SPDX identifier and is likewise skipped.
277+
"""
278+
licenses = component.get("licenses", [])
279+
if not licenses:
280+
return None
281+
if len(licenses) > 1:
282+
logger.warning(
283+
"component %s has %d license entries with undefined AND/OR "
284+
"semantics; skipping license",
285+
component.get("purl") or component.get("name"),
286+
len(licenses),
287+
)
288+
return None
289+
entry = licenses[0]
290+
expression = entry.get("expression")
291+
if expression:
292+
return str(expression)
293+
license_info = entry.get("license")
294+
if isinstance(license_info, dict):
295+
identifier = license_info.get("id")
296+
return str(identifier) if identifier else None
297+
return None
298+
299+
300+
def _cyclonedx_checksums(component: dict[str, typing.Any]) -> list[dict[str, str]]:
301+
"""Convert a component's hashes into SPDX checksum entries."""
302+
checksums = []
303+
for entry in component.get("hashes", []):
304+
algorithm = _CYCLONEDX_HASH_TO_SPDX.get(entry.get("alg", "").upper())
305+
content = entry.get("content")
306+
if algorithm and content:
307+
checksums.append({"algorithm": algorithm, "checksumValue": content})
308+
return checksums
309+
310+
311+
def _cyclonedx_package(
312+
component: dict[str, typing.Any],
313+
spdx_id: str,
314+
) -> dict[str, typing.Any]:
315+
"""Build an SPDX package entry from a CycloneDX component."""
316+
purl = component.get("purl")
317+
purl = _clean_purl(purl) if purl else None
318+
package: dict[str, typing.Any] = {
319+
"SPDXID": spdx_id,
320+
"name": component.get("name") or purl or component.get("bom-ref") or "unknown",
321+
"versionInfo": component.get("version") or "NOASSERTION",
322+
"downloadLocation": "NOASSERTION",
323+
"supplier": "NOASSERTION",
324+
}
325+
if purl:
326+
package["externalRefs"] = [
327+
{
328+
"referenceCategory": "PACKAGE-MANAGER",
329+
"referenceType": "purl",
330+
"referenceLocator": purl,
331+
}
332+
]
333+
checksums = _cyclonedx_checksums(component)
334+
if checksums:
335+
package["checksums"] = checksums
336+
license_expression = _cyclonedx_license(component)
337+
if license_expression:
338+
package["licenseDeclared"] = license_expression
339+
scope = component.get("scope")
340+
if scope and scope != "required":
341+
package["comment"] = f"CycloneDX scope: {scope}"
342+
return package
343+
344+
345+
def _spdx_id(component: dict[str, typing.Any], used_ids: set[str]) -> str:
346+
"""Build a readable, unique SPDXID from the component name and version.
347+
348+
SPDXIDs allow only ``A-Za-z0-9.-``; other characters (e.g. cargo's ``_``)
349+
are replaced with ``-``. Distinct components can share a name and version
350+
(e.g. a crate and its library target), so a numeric suffix disambiguates
351+
collisions to keep every SPDXID unique.
352+
"""
353+
name = component.get("name") or "unknown"
354+
version = component.get("version") or "unknown"
355+
base = re.sub(r"[^A-Za-z0-9.-]", "-", f"SPDXRef-{name}-{version}")
356+
candidate = base
357+
suffix = 1
358+
while candidate in used_ids:
359+
suffix += 1
360+
candidate = f"{base}-{suffix}"
361+
used_ids.add(candidate)
362+
return candidate
363+
364+
365+
def _iter_all_components(
366+
cyclonedx: dict[str, typing.Any],
367+
) -> typing.Iterator[tuple[dict[str, typing.Any], bool]]:
368+
"""Yield every ``(component, is_root)`` pair in a CycloneDX document."""
369+
root = cyclonedx.get("metadata", {}).get("component")
370+
if root:
371+
for component in _iter_components(root):
372+
yield component, component is root
373+
for component in cyclonedx.get("components", []):
374+
for nested in _iter_components(component):
375+
yield nested, False
376+
377+
378+
def merge_cyclonedx_sboms(
379+
*,
380+
sbom: dict[str, typing.Any],
381+
sboms_dir: pathlib.Path,
382+
) -> None:
383+
"""Merge Maturin CycloneDX components into a Fromager SPDX document.
384+
385+
Each non-excluded component becomes an SPDX package linked to the wheel with
386+
``CONTAINS``. A CycloneDX root matching the wheel is folded into
387+
``SPDXRef-wheel``. Local ``file://`` download qualifiers are stripped from
388+
PURLs. The CycloneDX dependency graph is not copied and the original files
389+
are left in place.
390+
"""
391+
if not sboms_dir.is_dir():
392+
return
393+
394+
wheel = next(
395+
(p for p in sbom["packages"] if p.get("SPDXID") == "SPDXRef-wheel"), None
396+
)
397+
packages = sbom["packages"]
398+
relationships = sbom["relationships"]
399+
used_ids = {p["SPDXID"] for p in packages}
400+
key_to_id: dict[str, str] = {}
401+
contained: set[str] = set()
402+
merged_files: list[str] = []
403+
404+
for sbom_path in sorted(sboms_dir.iterdir()):
405+
if not sbom_path.is_file() or sbom_path.name == SBOM_FILENAME:
406+
continue
407+
try:
408+
cyclonedx = json.loads(sbom_path.read_text(encoding="utf-8"))
409+
except (OSError, json.JSONDecodeError) as err:
410+
logger.warning("could not read SBOM file %s: %s", sbom_path, err)
411+
continue
412+
if not isinstance(cyclonedx, dict) or cyclonedx.get("bomFormat") != "CycloneDX":
413+
continue
414+
merged_files.append(sbom_path.name)
415+
416+
for component, is_root in _iter_all_components(cyclonedx):
417+
if component.get("scope") == "excluded":
418+
continue
419+
420+
if is_root and wheel is not None and _matches_wheel(component, wheel):
421+
spdx_id = "SPDXRef-wheel"
422+
else:
423+
key = _component_key(component)
424+
spdx_id = key_to_id.get(key, "")
425+
if not spdx_id:
426+
spdx_id = _spdx_id(component, used_ids)
427+
key_to_id[key] = spdx_id
428+
packages.append(_cyclonedx_package(component, spdx_id))
429+
430+
if spdx_id != "SPDXRef-wheel" and spdx_id not in contained:
431+
contained.add(spdx_id)
432+
relationships.append(
433+
{
434+
"spdxElementId": "SPDXRef-wheel",
435+
"relationshipType": "CONTAINS",
436+
"relatedSpdxElement": spdx_id,
437+
}
438+
)
439+
440+
if merged_files:
441+
sbom["comment"] = (
442+
"Includes components merged from CycloneDX SBOM(s): "
443+
+ ", ".join(sorted(merged_files))
444+
)
445+
446+
184447
def write_sbom(
185448
*,
186449
sbom: dict[str, typing.Any],

‎src/fromager/wheels.py‎

Lines changed: 4 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -262,6 +262,10 @@ def add_extra_metadata_to_wheels(
262262
req=req,
263263
version=version,
264264
)
265+
sbom.merge_cyclonedx_sboms(
266+
sbom=sbom_doc,
267+
sboms_dir=dist_info_dir / "sboms",
268+
)
265269
sbom.write_sbom(sbom=sbom_doc, dist_info_dir=dist_info_dir)
266270

267271
build_tag_from_settings = pbi.build_tag(version)

0 commit comments

Comments
 (0)