Merge pull request #977 from mprpic/generate-sbom

Generate minimal SBOM

Author: mergify[bot]

docs/reference/config-reference.rst

@@ -20,6 +20,8 @@ For example `flash_attn.yaml`.
 
 .. autopydantic_model:: fromager.packagesettings.ProjectOverride
 
+.. autopydantic_model:: fromager.packagesettings.SbomSettings
+
 Global Settings
 ---------------
 

src/fromager/packagesettings/__init__.py

@@ -8,6 +8,7 @@
     PackageSettings,
     ProjectOverride,
     ResolverDist,
+    SbomSettings,
     VariantInfo,
 )
 from ._pbi import PackageBuildInfo
@@ -47,6 +48,7 @@
     "ProjectOverride",
     "RawAnnotations",
     "ResolverDist",
+    "SbomSettings",
     "Settings",
     "SettingsFile",
     "Template",

src/fromager/packagesettings/_models.py

@@ -29,6 +29,33 @@
 logger = logging.getLogger(__name__)
 
 
+class SbomSettings(pydantic.BaseModel):
+    """Global SBOM generation settings
+
+    ::
+
+      sbom:
+        supplier: "Organization: ExampleCo"
+        namespace: "https://www.example.com"
+        creators:
+          - "Organization: ExampleCo"
+    """
+
+    model_config = MODEL_CONFIG
+
+    supplier: str = "NOASSERTION"
+    """SPDX supplier field for the wheel package (e.g. ``Organization: ExampleCo``)"""
+
+    namespace: str = "https://spdx.org/spdxdocs"
+    """Base URL for the SPDX documentNamespace"""
+
+    creators: list[str] = Field(default_factory=list)
+    """Additional SPDX creator entries (e.g. ``Organization: ExampleCo``)
+
+    The fromager tool creator entry is always added automatically.
+    """
+
+
 class ResolverDist(pydantic.BaseModel):
     """Packages resolver dist
 
@@ -324,6 +351,14 @@ class PackageSettings(pydantic.BaseModel):
     download_source: DownloadSource = Field(default_factory=DownloadSource)
     """Alternative source download settings"""
 
+    purl: str | None = None
+    """Package URL (purl) override for SBOM generation
+
+    When set, this value is used instead of the default ``pkg:pypi/<name>@<version>``
+    purl. Useful for packages that are not on PyPI or are midstream forks.
+    Supports ``{name}`` and ``{version}`` format substitution.
+    """
+
     resolver_dist: ResolverDist = Field(default_factory=ResolverDist)
     """Resolve distribution version"""
 

src/fromager/packagesettings/_pbi.py

@@ -69,6 +69,11 @@ def variant(self) -> Variant:
         """Variant name"""
         return self._variant
 
+    @property
+    def purl(self) -> str | None:
+        """Package URL (purl) override for SBOM generation."""
+        return self._ps.purl
+
     @property
     def annotations(self) -> Annotations:
         """Get Package and variant annotations

src/fromager/packagesettings/_settings.py

@@ -13,7 +13,7 @@
 from pydantic import Field
 
 from .. import overrides
-from ._models import PackageSettings
+from ._models import PackageSettings, SbomSettings
 from ._pbi import PackageBuildInfo
 from ._typedefs import MODEL_CONFIG, GlobalChangelog, Package, Variant
 
@@ -37,6 +37,14 @@ class SettingsFile(pydantic.BaseModel):
     changelog: GlobalChangelog = Field(default_factory=dict)
     """Changelog entries"""
 
+    sbom: SbomSettings | None = None
+    """SBOM generation settings
+
+    When set, Fromager generates SPDX 2.3 SBOM documents and embeds
+    them in built wheels per PEP 770. When absent (default), no SBOMs
+    are generated.
+    """
+
     @classmethod
     def from_string(
         cls,
@@ -162,6 +170,11 @@ def max_jobs(self, jobs: int | None) -> None:
         self._pbi_cache.clear()
         self._max_jobs = jobs
 
+    @property
+    def sbom_settings(self) -> SbomSettings | None:
+        """Get global SBOM settings, or None if SBOM generation is disabled."""
+        return self._settings.sbom
+
     def variant_changelog(self) -> list[str]:
         """Get global changelog for current variant"""
         return list(self._settings.changelog.get(self.variant, []))

src/fromager/sbom.py

@@ -0,0 +1,140 @@
+"""Generate SPDX 2.3 SBOM documents for wheels built by Fromager.
+
+Produces minimal SPDX 2.3 JSON documents conforming to PEP 770 for
+embedding in the ``.dist-info/sboms/`` directory of built wheels.
+"""
+
+from __future__ import annotations
+
+import importlib.metadata
+import json
+import logging
+import pathlib
+import typing
+from datetime import UTC, datetime
+
+from packaging.requirements import Requirement
+from packaging.utils import canonicalize_name
+from packaging.version import Version
+
+if typing.TYPE_CHECKING:
+    from . import context
+
+logger = logging.getLogger(__name__)
+
+SBOM_FILENAME = "fromager.spdx.json"
+
+
+def _build_purl(
+    *,
+    package_name: str,
+    package_version: Version,
+    purl_override: str | None,
+) -> str:
+    """Build a package URL for the SBOM.
+
+    Returns ``pkg:pypi/<name>@<version>`` by default. If a purl override
+    is set in per-package settings, it is used instead with
+    ``str.format()`` substitution for ``{name}`` and ``{version}``.
+    """
+    if purl_override:
+        try:
+            return purl_override.format(name=package_name, version=package_version)
+        except (KeyError, ValueError) as err:
+            raise ValueError(
+                f"invalid purl template {purl_override!r}: "
+                "only {name} and {version} are supported"
+            ) from err
+    return f"pkg:pypi/{package_name}@{package_version}"
+
+
+def generate_sbom(
+    *,
+    ctx: context.WorkContext,
+    req: Requirement,
+    version: Version,
+) -> dict[str, typing.Any]:
+    """Generate a minimal SPDX 2.3 JSON document for a wheel.
+
+    The document contains the wheel as the primary package and a
+    DESCRIBES relationship from the document to the package.
+    """
+    sbom_settings = ctx.settings.sbom_settings
+    if sbom_settings is None:
+        raise RuntimeError("generate_sbom called but SBOM settings are not configured")
+
+    pbi = ctx.package_build_info(req)
+    name = canonicalize_name(req.name)
+    fromager_version = importlib.metadata.version("fromager")
+    timestamp = datetime.now(tz=UTC).strftime("%Y-%m-%dT%H:%M:%SZ")
+
+    creators = list(sbom_settings.creators)
+    creators.append(f"Tool: fromager-{fromager_version}")
+
+    namespace = f"{sbom_settings.namespace}/{name}-{version}.spdx.json"
+
+    package_entry: dict[str, typing.Any] = {
+        "SPDXID": "SPDXRef-wheel",
+        "name": name,
+        "versionInfo": str(version),
+        "downloadLocation": "NOASSERTION",
+        "supplier": sbom_settings.supplier,
+    }
+
+    purl = _build_purl(
+        package_name=name,
+        package_version=version,
+        purl_override=pbi.purl,
+    )
+    package_entry["externalRefs"] = [
+        {
+            "referenceCategory": "PACKAGE-MANAGER",
+            "referenceType": "purl",
+            "referenceLocator": purl,
+        }
+    ]
+
+    doc: dict[str, typing.Any] = {
+        "spdxVersion": "SPDX-2.3",
+        "dataLicense": "CC0-1.0",
+        "SPDXID": "SPDXRef-DOCUMENT",
+        "name": f"{name}-{version}",
+        "documentNamespace": namespace,
+        "creationInfo": {
+            "created": timestamp,
+            "creators": creators,
+        },
+        "packages": [package_entry],
+        "relationships": [
+            {
+                "spdxElementId": "SPDXRef-DOCUMENT",
+                "relationshipType": "DESCRIBES",
+                "relatedSpdxElement": "SPDXRef-wheel",
+            },
+        ],
+    }
+    return doc
+
+
+def write_sbom(
+    *,
+    sbom: dict[str, typing.Any],
+    dist_info_dir: pathlib.Path,
+) -> pathlib.Path:
+    """Write an SBOM document to the .dist-info/sboms/ directory.
+
+    Creates the sboms/ subdirectory if it does not already exist.
+    Returns the path to the written file.
+    """
+    sboms_dir = dist_info_dir / "sboms"
+    sboms_dir.mkdir(exist_ok=True)
+    # Fromager generates exactly one SBOM per wheel, so overwriting a
+    # previous fromager.spdx.json from an earlier run is expected.
+    # SBOMs from other tools (e.g. maturin's CycloneDX) use different
+    # filenames and are not affected.
+    sbom_path = sboms_dir / SBOM_FILENAME
+    with sbom_path.open("w", encoding="utf-8") as f:
+        json.dump(sbom, f, indent=2)
+        f.write("\n")
+    logger.info("wrote SBOM to %s", sbom_path)
+    return sbom_path

src/fromager/wheels.py

@@ -30,6 +30,7 @@
     packagesettings,
     requirements_file,
     resolver,
+    sbom,
     sources,
 )
 
@@ -44,6 +45,24 @@
 FROMAGER_BUILD_REQ_PREFIX = "fromager"
 
 
+def _log_existing_sboms(
+    req: Requirement,
+    dist_info_dir: pathlib.Path,
+) -> None:
+    """Log any existing SBOM files found in the wheel's .dist-info/sboms/ directory."""
+    sboms_dir = dist_info_dir / "sboms"
+    if not sboms_dir.is_dir():
+        return
+    sbom_files = sorted(sboms_dir.iterdir())
+    if sbom_files:
+        names = [f.name for f in sbom_files]
+        logger.info(
+            "%s: found existing SBOM files in wheel: %s",
+            req.name,
+            ", ".join(names),
+        )
+
+
 def _extra_metadata_elfdeps(
     ctx: context.WorkContext,
     req: Requirement,
@@ -182,6 +201,8 @@ def add_extra_metadata_to_wheels(
         if not dist_info_dir.is_dir():
             raise ValueError(f"{wheel_file} does not contain {dist_info_dir.name}")
 
+        _log_existing_sboms(req, dist_info_dir)
+
         data_to_add = overrides.find_and_invoke(
             req.name,
             "add_extra_metadata_to_wheels",
@@ -231,6 +252,15 @@ def add_extra_metadata_to_wheels(
         else:
             logger.debug("%s is a purelib wheel", req.name)
 
+        sbom_settings = ctx.settings.sbom_settings
+        if sbom_settings is not None:
+            sbom_doc = sbom.generate_sbom(
+                ctx=ctx,
+                req=req,
+                version=version,
+            )
+            sbom.write_sbom(sbom=sbom_doc, dist_info_dir=dist_info_dir)
+
         build_tag_from_settings = pbi.build_tag(version)
         build_tag = build_tag_from_settings if build_tag_from_settings else (0, "")
 

tests/conftest.py

@@ -5,6 +5,7 @@
 from click.testing import CliRunner
 
 from fromager import context, packagesettings
+from fromager.packagesettings import SbomSettings
 
 TESTDATA_PATH = pathlib.Path(__file__).parent.absolute() / "testdata"
 E2E_PATH = pathlib.Path(__file__).parent.parent.absolute() / "e2e"
@@ -82,6 +83,38 @@ def testdata_context(
     return ctx
 
 
+def make_sbom_ctx(
+    tmp_path: pathlib.Path,
+    sbom_settings: SbomSettings | None = None,
+    purl: str | None = None,
+) -> context.WorkContext:
+    """Create a minimal WorkContext with SBOM settings."""
+    settings_file = packagesettings.SettingsFile(sbom=sbom_settings)
+    settings = packagesettings.Settings(
+        settings=settings_file,
+        package_settings=[],
+        patches_dir=tmp_path / "patches",
+        variant="cpu",
+        max_jobs=None,
+    )
+    if purl is not None:
+        ps = packagesettings.PackageSettings.from_mapping(
+            "test-pkg",
+            {"purl": purl},
+            source="test",
+            has_config=True,
+        )
+        settings._package_settings[ps.name] = ps
+    return context.WorkContext(
+        active_settings=settings,
+        constraints_file=None,
+        patches_dir=tmp_path / "patches",
+        sdists_repo=tmp_path / "sdists-repo",
+        wheels_repo=tmp_path / "wheels-repo",
+        work_dir=tmp_path / "work-dir",
+    )
+
+
 @pytest.fixture
 def cli_runner(
     tmp_path: pathlib.Path,

tests/test_packagesettings.py

@@ -72,6 +72,7 @@
     },
     "name": "test-pkg",
     "has_config": True,
+    "purl": None,
     "project_override": {
         "remove_build_requires": ["cmake"],
         "update_build_requires": ["setuptools>=68.0.0", "torch"],
@@ -132,6 +133,7 @@
         "submodule_paths": [],
     },
     "has_config": True,
+    "purl": None,
     "project_override": {
         "remove_build_requires": [],
         "update_build_requires": [],
@@ -171,6 +173,7 @@
         "submodule_paths": [],
     },
     "has_config": True,
+    "purl": None,
     "project_override": {
         "remove_build_requires": [],
         "update_build_requires": [],