From cc2c51c2f57fb85c5ab7ca256fb5b78bc290979b Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Wed, 8 Jan 2025 16:48:13 -0600 Subject: [PATCH 1/2] Move SBOM data recommendations, address review comments --- peps/pep-0770.rst | 85 +++++++++++++++++++++++++++++++---------------- 1 file changed, 56 insertions(+), 29 deletions(-) diff --git a/peps/pep-0770.rst b/peps/pep-0770.rst index 774460767b6..13c2f4247c1 100644 --- a/peps/pep-0770.rst +++ b/peps/pep-0770.rst @@ -101,8 +101,8 @@ package archive or information about the top-level software in the package that can't be encoded into Core Metadata but is relevant for the SBOM use-case ("software identifiers", "purpose", "support level", etc). -Zero-or-more SBOM documents per package ---------------------------------------- +Zero-or-more opaque SBOM documents +---------------------------------- Rather than requiring at most one included SBOM document per Python package, this PEP proposes that one or more SBOM documents may be included in a Python @@ -110,11 +110,17 @@ package. This means that code attempting to annotate a Python package with SBOM data may do so without being concerned about corrupting data already contained within other SBOM documents. -This decision also means this PEP is capable of supporting multiple SBOM -standards without favoring one, instead deferring support to SBOM consuming -tools. This decision also means that the merging of SBOM documents never needs -to be handled by Python tools, instead deferring this to SBOM consuming tools -who are better placed to handle cross-standard conversions. +Additionally, this PEP treats SBOM document data opaquely instead relying on +final end-users of the SBOM data to process the contained SBOM data. +This choice acknowledges that SBOM standards are an active area of development +where there is not yet (and may never be) a single definitive SBOM standard +and that SBOM standards can continue to evolve independent of Python packaging +standards. Already tools that consume SBOM documents support a multitude of +SBOM standards to handle this reality. + +These decisions mean this PEP is capable of supporting any SBOM standard +and does not favor one over the other, instead deferring the decision to +producing projects and tools and consuming user tooling. .. _770-spec: @@ -159,36 +165,20 @@ If an ``Sbom-File`` is listed in a :term:`Built Distribution`'s Core Metadata: * That file MUST be included in the :term:`distribution archive` at the - specified path relative to the root license directory. -* That file MUST be installed with the :term:`project` at that same relative - path. + specified path relative to the root SBOM directory. +* Installers MUST install the file with the :term:`project` at that same + relative path. * Inside the root SBOM directory, packaging tools MUST reproduce the directory structure under which the source files are located relative to the project root. The root SBOM directory is `specified in a later section <#770-spec-project-formats>`__. * Path delimiters MUST be the forward slash character (``/``), and parent directory indicators (``..``) MUST NOT be used. -* SBOM document contents MUST be UTF-8 encoded JSON according to :rfc:`8259`. -* SBOM document contents MUST use an SBOM standard, and for better - interoperability SHOULD be a well-known SBOM standard such as - `CycloneDX `_ or `SPDX `_. -* The "primary" component being described in included SBOM documents MUST be the - Python package. This is achieved in CycloneDX using the ``metadata.component`` - field and in SPDX using the ``DESCRIBES`` relationship. -* SBOM documents MUST include metadata for the timestamp when the SBOM document - was created. This information helps consuming tools understand the order that - multiple SBOM documents were created to untangle conflicts between various - stages building the Python package. -* SBOM documents SHOULD include metadata describing the tool creating the SBOM - document. This information helps users find which tool needs to be fixed in - the case of defects. For all newly-uploaded distribution archives that include one or more ``Sbom-File`` fields in their Core Metadata and declare a ``Metadata-Version`` -of ``2.5`` or higher, PyPI SHOULD validate that all specified files are present -in the distribution archives, are valid UTF-8 encoded JSON, and for well-known -SBOM standards provide the minimum required fields by those standards and this -PEP. +of ``2.5`` or higher, PyPI and other indices SHOULD validate that all files +specified with ``Sbom-File`` are present in the distribution archives. .. _770-spec-project-source-metadata: @@ -252,7 +242,7 @@ Examples of valid SBOM files declarations: sbom-files = ["bom.json"] [project] - sbom-files = ["sboms/openssl.cdx.json", "licenses/openssl.spdx.json"] + sbom-files = ["sboms/openssl.cdx.json", "sboms/openssl.spdx.json"] [project] sbom-files = ["sboms/*"] @@ -316,6 +306,36 @@ A few additions will be made to the existing specifications. relative to the ``sboms`` directory, and that any files in this directory MUST be copied from wheels by install tools. +SBOM data interoperability +-------------------------- + +This PEP treats data contained within SBOM documents as opaque, recognizing +that SBOM standards are an active area of development. However, there are some +considerations for SBOM data producers that when followed will improve the +interoperability and usability of SBOM data made available in Python packages: + +* SBOM documents SHOULD use a widely-accepted SBOM standard, such as + `CycloneDX `_ or `SPDX `_. +* SBOM documents SHOULD use UTF-8-encoded JSON (:rfc:`8259`) when available + for the SBOM standard in use. +* SBOM documents SHOULD include all required fields for the SBOM standard in + use. +* SBOM documents SHOULD include a "time of creation" and "creating tool" field + for the SBOM standard in use. This information is important for users + attempting to reconstruct different stages for a Python package being built. +* The primary component described by the SBOM document SHOULD be the top-level + software within the Python package (for example, + "pkg:pypi/pillow" for the "Pillow" package). +* All non-primary components SHOULD have one or more paths in the relationship + graph showing the relationship between components. If this information isn't + included, SCA tools might exclude components outside of the relationship graph. +* All software components SHOULD have a name, version, and one or more software + identifiers (PURL, CPE, download URL). + +PyPI and other indices MAY validate the contents of SBOM documents specified by +this PEP, but MUST NOT validate or reject data for unknown +SBOM standards, versions, or fields. + Backwards Compatibility ======================= @@ -400,6 +420,13 @@ Conditional project source SBOM files How can a project specify an SBOM file that is conditional? Under what circumstances would an SBOM document be conditional? +Selecting a single SBOM standard +-------------------------------- + +Should this PEP select a single SBOM standard instead of supporting any +SBOM standard? Selecting a single standard would potentially limit the +evolution of SBOM standards which is an active area of development. + References ========== From a56d61fda2df6f947572a6bcaa34175f36ce1ac8 Mon Sep 17 00:00:00 2001 From: Seth Michael Larson Date: Thu, 9 Jan 2025 08:12:38 -0600 Subject: [PATCH 2/2] Remove quotes from Pillow Co-authored-by: Hugo van Kemenade <1324225+hugovk@users.noreply.github.com> --- peps/pep-0770.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0770.rst b/peps/pep-0770.rst index 13c2f4247c1..7ed0afcedec 100644 --- a/peps/pep-0770.rst +++ b/peps/pep-0770.rst @@ -325,7 +325,7 @@ interoperability and usability of SBOM data made available in Python packages: attempting to reconstruct different stages for a Python package being built. * The primary component described by the SBOM document SHOULD be the top-level software within the Python package (for example, - "pkg:pypi/pillow" for the "Pillow" package). + "pkg:pypi/pillow" for the Pillow package). * All non-primary components SHOULD have one or more paths in the relationship graph showing the relationship between components. If this information isn't included, SCA tools might exclude components outside of the relationship graph.