diff --git a/peps/pep-0770.rst b/peps/pep-0770.rst index 774460767b6..7ed0afcedec 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 ==========