Feature: documenting external/extraneous dependencies

[jkowalleck]

current state

CycloneDX allows describing components, and the dependency graph.
Each component can have exactly one version, no version range.
Components can be connected in a dependency graph.

feature

Make it possible to describe external dependencies that are not part of a shipped product,
like runtime environments, shared objects and dynamically linked libraries, operating system, hardware (architecture) etc.

use cases

It would enable identifying vendor locks, dependency to outdated external software, and enable DevOps better spec runtime environments.

• As a customer, I get delivered a software library that includes bundled dependencies. But some external dependencies are not bundled (maybe for legal purposes). These external dependencies need to be provided by the later runtime - by me, the customer.
  The SBOM I get handed out with said library should tell which externals are needed to provide/install, so that I know, how my licensing posture is.
  The extraneous dependencies are not version-locked, they may be in a range of compatible versions.
  — Or, in other words —
  As the author of a software library, I want to provide an SBOM that not only includes the bundled runtime-dependencies, but also the info which runtime-dependencies need to be provided by the user of my library.
• As a customer, I get delivered a CMS written in PHP. The software delivered contains a bundle of source code and (transitive) dependencies. It does not include the PHP runtime(php-fpm,php-executable, etc), nor required php-extensions and runtime libraries(libssl, etc). see the php/composer spec.
  The SBOM I get handed out with the product should tell which version range of PHP is required to run the software, and which version of required PHP-extensions are required to be installed/enabled. This would help identify risks with the product, that are implied by locks or depending on outdated external software.
• As a customer, I get delivered a Java program, that can only run properly on a certain range of JavaRuntimeEnvironment.
  The SBOM I get handed out should state this compatibility range.
• As a customer, I get delivered a binary that is only runnable on Apple's M1/M2 chips.
  The SBOM I get handed out should state the compatible hardware architecture.
• As a customer, I get delivered a tool, that depends on a certain shared-object or dynamically linked library, which is not part of the delivered package. It needs to be provided by me.
• As a software manufacturer, I build a product(assembly), which is dynamically linked against libSSL. Therefore, libSSL is a dependency of my product. For licensing reasons, I ship only my product and none of the dynamically linked dependencies.
  My SBOM must express these dependencies (name, version-range, distribution-options(download-URL)), so that my clients know what they need to provide, in order to run the software I've shipped.

possible solution

• Idea: a new boolean property of Component, to indicate the fact that something is not part of the assembly, but needs to be provided.
  ( "external"? "extraneous"? wording unclear)
  Alternative: add a new value for ComponenScope. Current values: { "required", "optional", "excluded"} -- see Feature: documenting external/extraneous dependencies #321 (comment)
  ❗ see discussion below

• add an optional property to Component that allowed documenting a version-range, instead of a disjunctive version.
  might utilize existing schema definition for "range", which uses the still unfinished purlspec's VERS: https://github.com/package-url/purl-spec/blob/version-range-spec/VERSION-RANGE-SPEC.rst

• unchanged: allow components to be vendor-less. Some externals need to be able to describe a product-class, instead of an exact product.

• document the following, and if possible, then formulate it in schema language:

  • add constraint, that a component's optional version MUST be omitted, if component's is "external"
  • add constraint, that a component's optional version-range MUST be omitted, if component's is not "external"
    reminder: a version-range can also be a value that matches only one exact version - like VERS:1.44.7

• might utilize new ComponentType "runtime" -- Feature Request: new ComponentType "runtime" #233

Followup

We might add to the authoritative guide, that a BOM for non-bundled/non-shipped MUST NOT have concrete version, but MAY have a version-range(which may match exactly one version), and MUST be flagged as "extraneous".
The same goes to BOMs with the $.metadata.lifecycles[].phase=design.
See CycloneDX/guides#29

Discussion

First of, the goal is to allow describing externals, this is not SBOM in the traditional way, this is about the capability of CycloneDX.

howto name?

options:

• external?
• extraneous?
• yet another option?

how mark "externals"

Question: Where to put a marker that signals the fact that something is external?
Is scope the best place to put this? No! What if something is eternal and optional at the same time?!
So it might be better to have a dedicated marker for that purpose.

Question: Which element/object to use?
The existing "Component" seams good, but might be just to broad.
Maybe use "Definitions"' child element, as soon as it is clear? see #321 (comment)

motivation / need

As requested by the community, and canned as tickets

• Feature Request: Include Python version in SBOM cyclonedx-python#597
• [FEATURE] library mode cyclonedx-node-npm#1259
• [FEATURE] library mode cyclonedx-node-yarn#252
• feat: document platform dependencies cyclonedx-php-composer#435
• The essence of [DRAFT] scope required may be another version #578
• Discussion: https://cyclonedx.slack.com/archives/CV062H2GH/p1696841514304089

As described by German Cybersecurity Agency BSI

• Technical Guideline TR-03183 ¶ 5.1

  [orig German] Für eine SBOM, die konform zu dieser Technischen Richtlinie ist, MUSS zumindest für jede zum Lieferumfang gehörende Komponente die rekursive Auflösung von Abhängigkeiten auf jedem Pfad mindestens bis einschließlich der ersten Komponente, die nicht mehr zum Lieferumfang gehört, durchgeführt werden (siehe Abschnitt 6.1.4)
  [transl English] For an SBOM that is compliant with this Technical Guideline, at least for each component that is part of the component included in the scope of supply, the recursive resolution of dependencies on each path at least up to and including the first out-of-scope component, be performed (see 6.1.4)

As a solution for the package registries

Package registries that (are planning to) provide SBOMS for libraries which do not include all their dependencies. These SBOMs pretend/predict the dependencies as "components" but in fact, the components are not packaged with these libraries, but need to be fetched additionally. It these package registries would make unresolved dependencies as "extraneous", that would be great.

[stevespringett]

A PR would be good. Or at a minimum, a prototype on this ticket describing a proposal. FYI, v1.6 has a new top-level element called definitions which are not included in the inventory of the BOM but can still be referenced. That may be useful here, although there are likely other ways to achieve this as well.

[jkowalleck]

[...] v1.6 has a new top-level element called definitions which are not included in the inventory of the BOM but can still be referenced.

Did not find "definitions" in the current (draft) state of 1.6-dev nor any of (the work-in-progress) branches that eventually will be merged into 1.6-dev.
As soon as it is there, I will see if it fits the idea. No rush.

[...] although there are likely other ways to achieve this as well.

👍 I might sketch out possible schema changes and new test cases based on "component".
This might not be best solution, but should help visualize the concept.

[stevespringett]

The definitions property is here: https://github.com/CycloneDX/specification/blob/1.6-dev-attestations/schema/bom-1.6.schema.json#L473

It currently only consists of standards, but can (and likely should) be expanded to include additional objects (e.g. licenses, components, services, etc)

[jkowalleck]

re: #321 (comment)

A PR would be good.

here is a sketch: #326