Add external references support

[stevespringett]

This is an enhancement proposal to the CycloneDX specification to support external references.

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.1" version="1">
    <components>
        <component type="application">
            <group>org.apache.tomcat</group>
            <name>tomcat-catalina</name>
            <version>9.0.14</version>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
            </licenses>
            <purl>pkg:maven/org.apache.tomcat/tomcat-catalina@9.0.14?packaging=jar</purl>
            <modified>false</modified>
            <externalReferences>
                <reference type="vcs">
                    <url>https://github.com/apache/tomcat.git</url>
                    <comment>Repo containing all Tomcat components</comment>
                </reference>
                <reference type="issue-tracker">
                    <url>https://bz.apache.org/bugzilla/</url>
                </reference>
                <reference type="website">
                    <url>http://tomcat.apache.org/</url>
                </reference>
                <reference type="spdx">
                    <url>http://location/to/spdx.rdf</url>
                </reference>
            </externalReferences>
        </component>
    </components>
</bom>

I envision several built-in types including:

• vcs (Version Control System)
• issue-tracker
• website
• advisories
• spdx
• mailing-list
• social
• chat (IRC, Slack, MS Teams, etc)
• docs
• support
• download
• license (the URL containing the full text of the license - necessary for non-standard types)
• other (a catch-all)

Some of these can be automatically obtained from a combonents NuGet or pom.xml for example and can aid in various types of manual assessment as well as future automated assessment. Future types can possibly include:

• Consumption of per-project vulnerability intelligence (via advisories)
• Project health analysis (via issue-tracker and vcs)
• Consumption of externally defined BOMs (via SPDX)

[msymons]

As it stands, the RFC defines external references for components. Would it be possible to also have references for the BOM as a whole?

Thus, issue-tracker would reference the project issue tracker URL. This gives the potential for automatically generating issues based on BOM analysis.

If the above makes sense, I suggest that "build-system" (ciManagement) should also be included. This will allow automatic linking back to the where the BOM was generated (eg, Jenkins), One use case: investigate why a BOM has not been updated for a week.

[stevespringett]

Thats a really good idea and use-case.

[msymons]

Glad you like it!

I know that the CycloneDX specification is supposed to be lightweight... but another useful component reference (although I can only really speak from the perspective of Maven) would be "scope". ie, test, compile, etc,

Currently, default behaviour in BOM generation is to exclude test scope. This gives the benefit that downstream analysis is not "polluted" by components that are not part of deliverables... but the disadvatgae that one is not keeping track of use of an 8 year old version of seleniumHQ (or whatever).

The exact same challenge also affects commercial tools, many of which cannot tell the difference between scopes, meaning that it is easier to just exclude them entirely (or perform a whole bunch of manual triage).

By including scope in the BOM it would then be possible for downstream tools to analysis everything in a project, and provide the opportunity to apply different policies depending on the scope. eg:

• component with license x is banned if "scope = compile" but allowed if "scope = test".
• component with any scope might be covered by policies that deal with operational risk (component age)
• etc

[stevespringett]

Scope is already part of the specification. Refer to https://github.com/CycloneDX/specification/blob/master/schema/bom-1.0.xsd#L46

The definition of scope currently is limited to 'required' and 'optional'. I think adding a 'test' scope would be a good addition.
https://github.com/CycloneDX/specification/blob/master/schema/bom-1.0.xsd#L155

I do not think any of the implementations (maven, npm, pypi, nuget) actually use it or populate it this field. This is likely an enhancement that should be made to each of the implementations.

[stevespringett]

On second though, I think an 'excluded' value for scope makes more sense, since components could be excluded for all kinds of reasons, including unit and integration tests.

#9

[stevespringett]

Included in CycloneDX 1.1

[lock]

This thread has been automatically locked since there has not been any recent activity after it was closed. Please open a new issue for related bugs.