Skip to content

feat: add custom properties to external references #610

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

Open
wants to merge 1 commit into
base: 1.7-dev
Choose a base branch
from
Open

feat: add custom properties to external references #610

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
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
2 changes: 2 additions & 0 deletions schema/bom-1.7.proto
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -218,6 +218,8 @@ message ExternalReference {
optional string comment = 3;
// Optional integrity hashes for the external resource content
repeated Hash hashes = 4;
// Specifies optional, custom, properties
repeated Property properties = 5;
}

enum ExternalReferenceType {
Expand Down
6 changes: 6 additions & 0 deletions schema/bom-1.7.schema.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1827,6 +1827,12 @@
"items": {"$ref": "#/definitions/hash"},
"title": "Hashes",
"description": "The hashes of the external reference (if applicable)."
},
"properties": {
"type": "array",
"title": "Properties",
"description": "Provides the ability to document properties in a name-value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions. Unlike key-value stores, properties support duplicate names, each potentially having different values. Property names of interest to the general public are encouraged to be registered in the [CycloneDX Property Taxonomy](https://github.com/CycloneDX/cyclonedx-property-taxonomy). Formal registration is optional.",
"items": {"$ref": "#/definitions/property"}
}
}
},
Expand Down
10 changes: 10 additions & 0 deletions schema/bom-1.7.xsd
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -1597,6 +1597,16 @@ limitations under the License.
</xs:sequence>
</xs:complexType>
</xs:element>
<xs:element name="properties" type="bom:propertiesType" minOccurs="0" maxOccurs="1">
<xs:annotation>
<xs:documentation>Provides the ability to document properties in a name/value store.
This provides flexibility to include data not officially supported in the standard
without having to use additional namespaces or create extensions. Property names
of interest to the general public are encouraged to be registered in the
CycloneDX Property Taxonomy - https://github.com/CycloneDX/cyclonedx-property-taxonomy.
Formal registration is optional.</xs:documentation>
</xs:annotation>
</xs:element>
</xs:sequence>
<xs:attribute name="type" type="bom:externalReferenceType" use="required">
<xs:annotation>
Expand Down
30 changes: 30 additions & 0 deletions tools/src/test/resources/1.7/valid-external-reference-properties-1.7.json
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,30 @@
{
"$schema": "http://cyclonedx.org/schema/bom-1.7.schema.json",
"bomFormat": "CycloneDX",
"specVersion": "1.7",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "application",
"name": "dummy",
"description": "this component has an external reference with properties",
"externalReferences": [
{
"type": "component-analysis-report",
"url": "http://example.com/extref/component-analysis-report",
"properties": [
{
"name": "author",
"value": "John Doe"
},
{
"name": "timestamp",
"value": "2025-01-27T12:27:26Z"
}
]
}
]
}
]
}
23 changes: 23 additions & 0 deletions tools/src/test/resources/1.7/valid-external-reference-properties-1.7.textproto
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,23 @@
# proto-file: schema/bom-1.7.proto
# proto-message: Bom

spec_version: "1.7"
version: 1
serial_number: "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79"
components {
type: CLASSIFICATION_APPLICATION
name: "dummy"
description: "this component has an external reference with properties"
external_references {
type: EXTERNAL_REFERENCE_TYPE_COMPONENT_ANALYSIS_REPORT
url: "http://example.com/extref/component-analysis-report"
properties {
name: "author"
value: "John Doe"
}
properties {
name: "timestamp"
value: "2025-01-27T12:27:26Z"
}
}
}
18 changes: 18 additions & 0 deletions tools/src/test/resources/1.7/valid-external-reference-properties-1.7.xml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,18 @@
<?xml version="1.0"?>
<bom serialNumber="urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79" version="1" xmlns="http://cyclonedx.org/schema/bom/1.7">
<components>
<component type="application">
<name>dummy</name>
<description>this component has an external reference with properties</description>
<externalReferences>
<reference type="component-analysis-report">
<url>http://example.com/extref/component-analysis-report</url>
<properties>
<property name="author">John Doe</property>
Copy link
Contributor

Choose a reason for hiding this comment

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

This is confusing to me. What if the external source has a different value for author and timestamp?

Copy link

@gernot-h gernot-h Apr 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Sorry, but what exactly do you mean by "different values for author and timestamp"? This is an example for additional properties provided in the SBOM for this report. They might be added because this metadata isn't available from the external source or just because it saves us an additional query to the external server when I need this information when handling the SBOM.

Copy link
Contributor

Choose a reason for hiding this comment

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

Take externalReferences.type == bom. If there are differences in the value for properties (say author), then there is a question about source of truth. Caller has to make an additional query to the external server.

We use annotations attribute to add/store additional information about certain attributes. Any issues with that?

Copy link

@gernot-h gernot-h Apr 30, 2025 •
edited
Loading

Choose a reason for hiding this comment

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

Hmm, but how would how such additional information for an external reference differ from any other data points you provide for a component in your SBOM? Same problem would also apply for author or licenses or other properties of a component and most of them could usually also be looked up on a homepage or package repository. I think the idea of an SBOM is to document your understanding of your BOM in a central place, no-one protects you from providing wrong data there.

Regarding annotations: What we need is a machine-readable key/value store per external reference. Today, we mis-use the comment field of external references for storing such data, which obviously doesn't scale. I don't think using annotations would really improve that and also doesn't allow us to document these fields in our taxonomy.

<property name="timestamp">2025-01-27T12:27:26Z</property>
</properties>
</reference>
</externalReferences>
</component>
</components>
</bom>