feat: support for external components with version-ranges

[jkowalleck]

As discussed in ticket #321, this PR adds the following abilities:

• mark components as external

  Determine whether this component is external.
  An external component is one that is not part of an assembly, but is expected to be provided by the environment, regardless of the component's @scope. This setting can be useful for distinguishing which components are bundled with the product and which can be relied upon to be present in the deployment environment.
  This may be set to true for runtime components only. For /metadata/component, it must be set to false.

• external components may have version-ranges instead of a specific version

  For an external component, this specifies the accepted version range.
  The value must adhere to the Package URL Version Range syntax (vers), as defined at https://github.com/package-url/purl-spec/blob/master/VERSION-RANGE-SPEC.rst.
  May only be used if .isExternal is set to true.
  Must be used exclusively, either 'version' or 'versionRange', but not both.

fixes #321

---

Note

this one supersedes #326 <-- read there for more background and previous discussions

implementing with components, because the objects referenced/required are actually used at runtime and therefore are considered a "component".

Sketch/proposal for #321 -- WORK IN PROGRESS

• sketch JSON schema
  • properties and assert
  • test cases
• sketch XML schema
  • elements & attributes.
    no asserts - this would require XSD1.1 which is not broadly implemented, yet.
  • test cases
• sketch ProtoBuff schema
  • fields
  • test cases

---

Note

ALL FEEDBACK IS WELCOME! Yes, everything.
but some might not be resolved in this very PR, but in the authoritative guides. See #586 (comment)

[ppkarwasz]

Looks good to me, although I think we should clarify better, when isExtraneous is used.

For example I don't think isExtraneous makes sense in $.metadata.component even if versionRange is used.
Also, in a CycloneDX VDR/VEX document, isExtraneous does not make sense.

[raboof]

This is great!

I guess it would be good to make explicit that you should not include hashes for extraneous components? Also, since different versions may have different transitive dependencies, does that mean no transitive dependencies should be listed for extraneous components? Or is it OK to keep listing those (as long as they're also marked extraneous) and leave it up to the downstream consumer of the sbom to drop no-longer-relevant extraneous components as needed?

[ppkarwasz]

Also, since different versions may have different transitive dependencies, does that mean no transitive dependencies should be listed for extraneous components? Or is it OK to keep listing those (as long as they're also marked extraneous) and leave it up to the downstream consumer of the sbom to drop no-longer-relevant extraneous components as needed?

I thought about dropping transitive dependencies too, but some usages require to have at least a draft of what transitive dependencies could appear.

For example we could link a CycloneDX SBOM to a CycloneDX VEX. In order to know, which CVEs published by dependencies will be analyzed in the VEX, we need to provide an approximate list of transitive dependencies. While commercial manufacturers might be required to answer questions like "Is my Java application vulnerable to this Go CVE", OSS projects will certainly not answer questions beyond the dependencies listed in the SBOM.

[jkowalleck]

regarding transitive dependencies, hashes and such.

nope. hashes CAN be used, even for extraneous dependencies.
Imagine the following: you need a specific version of a dependency provided. Of course you may add hashes for that version.
Regarding transitive dependencies, you CAN omit them.

all is a MAY/CAN -- not a MUST.

[jkowalleck]

thank you all for the early review and the interesting questions and remarks. 👍

If they were technical, then they are about to be addressed in this PR.
If they were use-case related, they may be addressed in CycloneDX/guides#29. Remember: CycloneDX is a document standard, the individual best practices and alike are addressed in the authoritative guides.

more questions and remarks are very welcome - better here in the PR or in the issue #321 than else where.

[jkowalleck]

for the record:

I found that the word "external" is better fitting for what this is all about.
("extraneous" seams to have a second/alternative meaning that i was not aware of, when i write tis ticket originally.)

therefore, I propose to use "external". adapted in this PR

[jkowalleck]

refined the wordings based on your feedback.
revisited all changes and test cases.
I think this one is out of the WIP phase :) ready for review

[jkowalleck]

@stevespringett this one is ready for review

[jkowalleck]

RFC notice sent.
https://groups.io/g/CycloneDX/message/305
https://cyclonedx.slack.com/archives/CVA0G10FN/p1739854336258159

Public RFC period ends March 18, 2025