Skip to content

feat: support for external components with version-ranges #586

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom
Merged
merged 25 commits into from
Apr 3, 2025
Merged

feat: support for external components with version-ranges #586

merged 25 commits into from
Apr 3, 2025

Conversation

@jkowalleck
Copy link
Member

@jkowalleck jkowalleck commented Feb 4, 2025 •
edited
Loading

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

  • 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)

@jkowalleck jkowalleck requested a review from a team as a code owner February 4, 2025 19:59
@jkowalleck jkowalleck marked this pull request as draft February 4, 2025 19:59
@jkowalleck jkowalleck changed the base branch from master to 1.7-dev February 4, 2025 19:59
@jkowalleck jkowalleck mentioned this pull request Feb 4, 2025
Closed
3 tasks
@jkowalleck jkowalleck added this to the 1.7 milestone Feb 4, 2025
jkowalleck
jkowalleck commented Feb 4, 2025
View reviewed changes
@jkowalleck jkowalleck mentioned this pull request Feb 4, 2025
Closed
ppkarwasz
ppkarwasz suggested changes Feb 5, 2025
View reviewed changes
Copy link
Contributor

@ppkarwasz ppkarwasz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

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.

@jkowalleck
draft: JSON - extraneous comp and version range
4aef005 
related to #321 #321

Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
docs
a6941df 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
xml
7ede07a 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
docs
84a9783 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
docs
7a52828 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck jkowalleck force-pushed the feat/extraneous-component branch from 3e1eb53 to 7a52828 Compare February 5, 2025 13:57
jkowalleck and others added 5 commits February 5, 2025 14:58
@jkowalleck @ppkarwasz
Update schema/bom-1.7.schema.json
d3e0ed5 
Co-authored-by: Piotr P. Karwasz <[email protected]>
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
wip
045a6de 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
wip
0971f02 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
wip
b12bd49 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
wip
2c00374 
Signed-off-by: Jan Kowalleck <[email protected]>
@raboof
Copy link

raboof commented Feb 6, 2025

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?

@raboof raboof mentioned this pull request Feb 6, 2025
Open
@jkowalleck
wip
db0b3b8 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
wip
d2e3053 
Signed-off-by: Jan Kowalleck <[email protected]>
@ppkarwasz
Copy link
Contributor

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
wip
401b245 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
wip
65ec962 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
Copy link
Member Author

jkowalleck commented Feb 6, 2025 •
edited
Loading

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
wip
959a82c 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck jkowalleck marked this pull request as ready for review February 8, 2025 13:59
@jkowalleck jkowalleck changed the title [WIP] feat: external components feat: external components Feb 8, 2025
@jkowalleck
Copy link
Member Author

jkowalleck commented Feb 8, 2025 •
edited
Loading

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 jkowalleck changed the title feat: external components feat: support for marking components as external Feb 8, 2025
@jkowalleck jkowalleck changed the title feat: support for marking components as external feat: support for external components with version-ranges Feb 8, 2025
@jkowalleck jkowalleck requested a review from mrutkows February 9, 2025 09:22
@jkowalleck
Copy link
Member Author

@stevespringett this one is ready for review

@jkowalleck
Copy link
Member Author

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

Public RFC period ends March 18, 2025

@jkowalleck jkowalleck added the RFC notice sent A public RFC notice was distributed to the CycloneDX mailing list for consideration label Feb 24, 2025
@jkowalleck
tests: revisit examples
7f73c1d 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck
dev-docs
ebe66bc 
Signed-off-by: Jan Kowalleck <[email protected]>
@jkowalleck jkowalleck mentioned this pull request Mar 21, 2025
Open
2 tasks
@jkowalleck jkowalleck added the promote to tc54 Promote to Ecma Technical Committee 54 label Mar 21, 2025
@jkowalleck jkowalleck added tc54 reviewed Ecma TC54 has reviewed the feature candidate tc54 accepted Ecma TC54 has accepted the feature candidate labels Apr 3, 2025
@jkowalleck
Copy link
Member Author

this was reviewed and accepted by TG54 on 2025-04-03

@jkowalleck jkowalleck requested review from ppkarwasz and stevespringett and removed request for ppkarwasz April 3, 2025 15:56
ppkarwasz
ppkarwasz approved these changes Apr 3, 2025
View reviewed changes
Copy link
Contributor

@ppkarwasz ppkarwasz left a comment

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

LGTM

@jkowalleck jkowalleck merged commit 2f1fb1e into 1.7-dev Apr 3, 2025
9 checks passed
@jkowalleck jkowalleck deleted the feat/extraneous-component branch April 3, 2025 16:23
@jkowalleck jkowalleck mentioned this pull request Apr 3, 2025
Merged
stevespringett added a commit that referenced this pull request Oct 21, 2025
@stevespringett
v1.7 (#511)
11c0e00 
## Fixed

* XML schema: add type for `ComponentData` sub-elements ([#600] via
[#601])
* JSON schema: added the correct `deprecated` mark for already
deprecated structures (via [a973a6b])

## Deprecated

* Deprecated various fields and structures related to _cryptographic
transparency_ - _CBOM_ . (via [#657])
Use the newly added structures and fields for detailing the information
instead.

## Changed

* Extended the scope of _formulations_. (via [#647])
From now on, _formulations_ may be used to describe how any referencable
object within the BOM came together, including components, services,
metadata, declarations, or the BOM itself.
  Before, it was restricted to components and services.

## Added

* Support for _external components_ with _version-ranges_ ([#321] via
[#586])
* Support for _multiple_ SPDX License Expressions alongside with other
licenses ([#454] via [#582])
* Support for _Streebog hashing algorithm_ ([#485] via [#525])
* Support for license expression _details and properties_ ([#549],
[#554] via [#599])
* Support for expressing BOM distribution constraints with the _Traffic
Light Protocol_ (TLP) in metadata ([#595] via [#604], [#653])
* Support for representing _patent information_ ([#596] via [#597])
* Support for _properties_ on external-references ([#608] via [#610])
* Support for _citations_ ([#630] via [#629])
* Support for detailing _cryptographic transparency_ information -
_CBOM_ ([#569] via [#657])

## Documentation

* Elaborated component classification "platform", explicitly expressed
that it includes just-in-time compilers and interpreters ([#233] via
[#647])
* Removed the term "optional" from the schema where the definition was
already unambiguous ([#616], [#649] via [#680])

## Test data

* Add test data for CycloneDX 1.7 implementations in XML, JSON, Protobuf


[#233]: #233
[#321]: #321
[#454]: #454
[#485]: #485
[#525]: #525
[#549]: #549
[#554]: #554
[#569]: #569
[#582]: #582
[#586]: #586
[#595]: #595
[#596]: #596
[#597]: #597
[#599]: #599
[#600]: #600
[#601]: #601
[#604]: #604
[#608]: #608
[#610]: #610
[#616]: #616
[#629]: #629
[#630]: #630
[#647]: #647
[#649]: #649
[#653]: #653
[#657]: #657
[#680]: #680
[a973a6b]:
a973a6b

----

- fixes #233
- fixes #321
- fixes #454
- fixes #485
- fixes #549
- fixes #554
- fixes #595
- fixes #596
- fixes #600
- fixes #608
- fixes #629
- fixes #616 
- fixes #649
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

@mrutkows mrutkows Awaiting requested review from mrutkows

@stevespringett stevespringett Awaiting requested review from stevespringett

1 more reviewer

@ppkarwasz ppkarwasz ppkarwasz approved these changes

Reviewers whose approvals may not affect merge requirements

Assignees

No one assigned

Labels

draft promote to tc54 Promote to Ecma Technical Committee 54 proposed core enhancement ready for review request for comment RFC notice sent A public RFC notice was distributed to the CycloneDX mailing list for consideration RFC vote accepted tc54 accepted Ecma TC54 has accepted the feature candidate tc54 reviewed Ecma TC54 has reviewed the feature candidate

Projects

None yet

Milestone

1.7

Development

Successfully merging this pull request may close these issues.

Feature: documenting external/extraneous dependencies

4 participants

@jkowalleck @raboof @ppkarwasz