Skip to content
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

[DRAFT] extraneous components and version range constraints #326

Closed
wants to merge 5 commits into from
Closed

[DRAFT] extraneous components and version range constraints #326

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
5 commits
Select commit Hold shift + click to select a range
d27a5c3
draft: JSON - extraneous comp and version range
jkowalleck Oct 22, 2023
d2c9080
docs
jkowalleck Oct 22, 2023
9b1c166
xml
jkowalleck Oct 23, 2023
310dff0
docs
jkowalleck Jan 16, 2024
3bcd875
docs
jkowalleck Jan 16, 2024
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
26 changes: 25 additions & 1 deletion schema/bom-1.6.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -892,6 +892,12 @@
"title": "Component Version",
"description": "The component version. The version should ideally comply with semantic versioning but is not enforced."
},
"versionRange": {
"$ref": "#/definitions/versionRange",
"title": "Component Version Range",
"description": "The component version range that may be provided to fulfill this capability.\nMAY only occur if property `isExtraneous` is set to 'true'.",
"$comment": "a rule is taking cate of the plausibility between `version`/`versionRange` and `isExtraneous`=='true'"
},
"description": {
"type": "string",
"title": "Component Description",
Expand All @@ -913,6 +919,12 @@
"description": "Specifies the scope of the component. If scope is not specified, 'required' scope SHOULD be assumed by the consumer of the BOM.",
"default": "required"
},
"isExtraneous": {
Copy link
Contributor

Choose a reason for hiding this comment

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

If the environment provides a component, then it is best to capture it under formulation instead of having such boolean flags.

Copy link
Member Author

Choose a reason for hiding this comment

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

why should it be under "formulation"?
form,ulation is build-time, while this domain here may also be runtime.

Copy link
Contributor

Choose a reason for hiding this comment

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

Wouldn't such runtime-only components not captured in an OBOM?

Copy link
Member Author

Choose a reason for hiding this comment

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

how would you make it clear in an obom, that the build result descibed in an SBOM needs windows 11 patch 23H2 on runtime? Or that it requires python 3.11 or later as an interpreter?
I dont know ... this is why this PR exists, to discuss these options and maube provide a solution :-)

read more here in the sectiopn "usecases" of #321

Copy link
Contributor

Choose a reason for hiding this comment

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

Thank you. I should've read the use cases first, which helped. I would have used two separate documents and linked them via external references. However, I see the appeal of having a single combined document for both SBOM and its operating environment. Perhaps component.type = "platform" indicates runtime without the need for the additional boolean flag?

"type": "boolean",
"title": "Component Is Extraneous",
"description": "Whether this component is extraneous.\nAn extraneous component is not part of an assembly, but are (expected to be) provided by the environment, regardless of the component's `scope`.",
"default": false
},
"hashes": {
"type": "array",
"title": "Component Hashes",
Expand Down Expand Up @@ -1037,7 +1049,19 @@
"title": "Signature",
"description": "Enveloped signature in [JSON Signature Format (JSF)](https://cyberphone.github.io/doc/security/jsf.html)."
}
}
},
"allOf": [
{
"$comment": "property `version` and `versionRange` MUST NOT exist at the same time.",
"not": { "required": ["version", "versionRange"] }
},
{
"$comment": "`version-range` MUST only be present, if `isExtraneous` is `true`",
"if": { "properties": { "isExtraneous": { "const": false } } },
"then": { "not": { "required": ["versionRange"] } },
"else": true
}
]
},
"swid": {
"type": "object",
Expand Down
39 changes: 33 additions & 6 deletions schema/bom-1.6.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -500,12 +500,24 @@ limitations under the License.
of the component. Examples: commons-lang3 and jquery</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="version" type="bom:versionType" minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>The component version. The version should ideally comply with semantic versioning
but is not enforced.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:choice>
<xs:element name="version" type="bom:versionType" minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>The component version. The version should ideally comply with semantic versioning
but is not enforced.</xs:documentation>
</xs:annotation>
</xs:element>
<xs:element name="versionRange" type="bom:versionRangeType" minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>The component version range that may be provided to fulfill this capability.
MAY only occur if attribute `isExtraneous` is set to `true`.</xs:documentation>
<!-- Attention:
Since XSD 1.1 `asserts` are mostly not implemented, there is currently no rule in this XSD
that is taking cate of the plausibility between `version`/`versionRange` and `isExtraneous`=='true'
-->
</xs:annotation>
</xs:element>
</xs:choice>
<xs:element name="description" type="xs:normalizedString" minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>Specifies a description for the component</xs:documentation>
Expand Down Expand Up @@ -667,12 +679,27 @@ limitations under the License.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:attribute name="isExtraneous" type="xs:boolean" default="false">
<xs:annotation>
<xs:documentation>
Whether this component is extraneous.
An extraneous component is not part of an assembly, but are (expected to be) provided by the environment, regardless of the component's `scope`.
</xs:documentation>
</xs:annotation>
</xs:attribute>
<xs:anyAttribute namespace="##any" processContents="lax">
<xs:annotation>
<xs:documentation>User-defined attributes may be used on this element as long as they
do not have the same name as an existing attribute used by the schema.</xs:documentation>
</xs:annotation>
</xs:anyAttribute>
<!-- Attention:
This would be formal, if the support for XSD1.1's `assert` was properly implemented in validators and tools digesting XML.
<xs:assert id="versionRange_requires_isExtraneous_eq_true"
test="if (versionRange) then (@isExtraneous eq 'true') else true()">
Child `versionRange` MAY only be present, if attribute `isExtraneous`=='true'.
</xs:assert>
-->
</xs:complexType>

<xs:complexType name="licenseType">
Expand Down
16 changes: 16 additions & 0 deletions ...rc/test/resources/1.6/informal-invalid-component-versionRange-non-extraneous-explicit.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,16 @@
<?xml version="1.0"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.6"
serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
>
<!--
this would be formal, if the support for XSD1.1's `assert` was properly implemented
in validators and tools digesting XML.
-->
<components>
<component type="library" isExtraneous="false">
<name>InvalidVersions</name>
<versionRange><![CDATA[>=9.0.0|<10.0.0]]></versionRange>
Copy link
Member Author

Choose a reason for hiding this comment

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

I just took the version-part of VERS.
maybe this was wrong, need to read the specs of verts again ...

<description>versionRange may only exist on extraneous components, set `isExtraneous` explicit</description>
</component>
</components>
</bom>
17 changes: 17 additions & 0 deletions ...rc/test/resources/1.6/informal-invalid-component-versionRange-non-extraneous-implicit.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,17 @@
<?xml version="1.0"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.6"
serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
>
<!--
this would be formal, if the support for XSD1.1's `assert` was properly implemented
in validators and tools digesting XML.
-->
<components>
<component type="library">
<!-- @isExtraneous defaults to `false` -->
<name>InvalidVersions</name>
<versionRange><![CDATA[>=9.0.0|<10.0.0]]></versionRange>
<description>versionRange may only exist on extraneous components, set `isExtraneous` implicit by default value</description>
</component>
</components>
</bom>
15 changes: 15 additions & 0 deletions tools/src/test/resources/1.6/invalid-component-version-and-range.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "library",
"name": "InvalidVersions",
"description": "may have `version` or `versionRange`, not both. This one does - it is invalid",
"version": "9.0.14",
"versionRange": ">=9.0.0|<10.0.0"
}
]
}
13 changes: 13 additions & 0 deletions tools/src/test/resources/1.6/invalid-component-version-and-range.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,13 @@
<?xml version="1.0"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.6"
serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
>
<components>
<component type="library" isExtraneous="false">
<name>InvalidVersions</name>
<version>9.0.14</version>
<versionRange><![CDATA[>=9.0.0|<10.0.0]]></versionRange>
<description>may have `version` or `versionRange`, not both. This one does - it is invalid</description>
</component>
</components>
</bom>
15 changes: 15 additions & 0 deletions tools/src/test/resources/1.6/invalid-component-versionRange-non-extraneous-explicit.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "library",
"name": "InvalidVersions",
"description": "versionRange may only exist on extraneous components, set `isExtraneous` explicit",
"isExtraneous": false,
"versionRange": ">=9.0.0|<10.0.0"
}
]
}
14 changes: 14 additions & 0 deletions tools/src/test/resources/1.6/invalid-component-versionRange-non-extraneous-implicit.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "library",
"name": "InvalidVersions",
"description": "versionRange may only exist on extraneous components, set `isExtraneous` implicit by default value",
"versionRange": ">=9.0.0|<10.0.0"
}
]
}
14 changes: 14 additions & 0 deletions tools/src/test/resources/1.6/valid-component-extraneous-no-version-information.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "library",
"name": "Foo",
"description": "extraneous without any version constraints",
"isExtraneous": true
}
]
}
11 changes: 11 additions & 0 deletions tools/src/test/resources/1.6/valid-component-extraneous-no-version-information.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,11 @@
<?xml version="1.0"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.6"
serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
>
<components>
<component type="library" isExtraneous="true">
<name>Foo</name>
<description>extraneous without any version constraints</description>
</component>
</components>
</bom>
15 changes: 15 additions & 0 deletions tools/src/test/resources/1.6/valid-component-extraneous-with-version.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "library",
"name": "Foo",
"description": "extraneous with version constraint",
"isExtraneous": true,
"version": "9.1.24"
}
]
}
12 changes: 12 additions & 0 deletions tools/src/test/resources/1.6/valid-component-extraneous-with-version.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<?xml version="1.0"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.6"
serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
>
<components>
<component type="library" isExtraneous="true">
<name>Foo</name>
<version>9.1.24</version>
<description>extraneous with version constraint</description>
</component>
</components>
</bom>
15 changes: 15 additions & 0 deletions tools/src/test/resources/1.6/valid-component-extraneous-with-versionRange.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,15 @@
{
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "library",
"name": "Foo",
"description": "extraneous with version range constraints",
"isExtraneous": true,
"versionRange": ">=9.0.0|<10.0.0"
}
]
}
12 changes: 12 additions & 0 deletions tools/src/test/resources/1.6/valid-component-extraneous-with-versionRange.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,12 @@
<?xml version="1.0"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.6"
serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1"
>
<components>
<component type="library" isExtraneous="true">
<name>Foo</name>
<versionRange><![CDATA[>=9.0.0|<10.0.0]]></versionRange>
<description>extraneous with version range constraints</description>
</component>
</components>
</bom>