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.

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

Add support for component pedigree #6

Open
stevespringett opened this Issue Jan 10, 2019 · 3 comments

Comments

Projects
None yet
1 participant
@stevespringett
Copy link
Member

stevespringett commented Jan 10, 2019

This is an enhancement proposal to the CycloneDX specification to support ancestors. This would be useful for forks of projects that have modifications in which the identification of the component has changed.

The modified flag can be used if the component metadata has not changed. For example, if Apache Tomcat was modified but the group, name, version, etc remained the same. If this data has been modified, it may be impossible to perform accurate analysis with the modified data.

The proposal is to add ancestors in which a component descends from. Ancestors is a list of 0-n components, so if a component used the Maven shade plugin for example, this would aggregate one or more components into a single one. In the following example, Apache Tomcat has been modified by Acme Inc.

With ancestors, it would be possible to track the origin of each component so that accurate analysis can be performed at each level of the tree.

For example:

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.1" version="1">
    <components>
        <component type="application">
            <publisher>Acme Inc</publisher>
            <group>com.acme</group>
            <name>tomcat-catalina</name>
            <version>9.0.14</version>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
            </licenses>
            <purl>pkg:maven/com.acme/tomcat-catalina@9.0.14?packaging=jar</purl>
            <modified>false</modified>
            <ancestors>
                <component type="application">
                    <publisher>Apache</publisher>
                    <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>
                </component>
            </ancestors>
        </component>
    </components>
</bom>
@stevespringett

This comment has been minimized.

Copy link
Member Author

stevespringett commented Jan 12, 2019

Another possibility is to support ancestors, descendants, and variants in a single pedigree node. For example:

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.1" version="1">
    <components>
        <component type="application">
            <publisher>Acme Inc</publisher>
            <group>com.acme</group>
            <name>tomcat-catalina</name>
            <version>9.0.14</version>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
            </licenses>
            <purl>pkg:maven/com.acme/tomcat-catalina@9.0.14?packaging=jar</purl>
            <modified>false</modified>
            <pedigree>
                <ancestors>
                    <component type="application">
                        <publisher>Apache</publisher>
                        <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>
                    </component>
                </ancestors>
                <descendants>
                    ...
                </descendants>
                <variants>
                    ...
                </variants>
            </pedigree>
        </component>
    </components>
</bom>

It's unknown if there are use cases that would require ancestors, descendants, and variants in the same pedigree. The XSD may define pedigree as a choice of one of the three, or the XSD may simply allow all three to be present - in the order specified in the example. Using pedigree in this way, the BOM could be used to represent the entire lineage from any viewpoint.

Ancestors:
Component(s) with the same lineage but pre-dates the parent component

Descendants:
Component(s) with the same lineage but post-dates the parent component

Variants:
Component(s) with the same lineage but it is not clear which came first

@stevespringett stevespringett added this to the 1.1 milestone Jan 12, 2019

@stevespringett

This comment has been minimized.

Copy link
Member Author

stevespringett commented Jan 12, 2019

In the event only one of ancestors, descendants, and variants are allowed, this markup could be simplified to:

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.1" version="1">
    <components>
        <component type="application">
            <publisher>Acme Inc</publisher>
            <group>com.acme</group>
            <name>tomcat-catalina</name>
            <version>9.0.14</version>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
            </licenses>
            <purl>pkg:maven/com.acme/tomcat-catalina@9.0.14?packaging=jar</purl>
            <modified>false</modified>
            <pedigree type="ancestors">
                <component type="application">
                    <publisher>Apache</publisher>
                    <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>
                </component>
            </pedigree>
        </component>
    </components>
</bom>

Also note, that since pedigree is an element within a component, every component could theoretically have its own. So it's possible to represent complex trees which would be representative of component being modified, distributed, modified again, distributed, etc. This model is very common with Linux distributions for example.

@stevespringett

This comment has been minimized.

Copy link
Member Author

stevespringett commented Feb 1, 2019

Although the second option is a bit more verbose (pedigree > ancestors > components) I think it offers the most flexibility and future-proof design.

For example, it would be possible to document every commit that lead to the creation of a given component with something like:

<?xml version="1.0" encoding="UTF-8"?>
<bom xmlns="http://cyclonedx.org/schema/bom/1.1" version="1">
    <components>
        <component type="application">
            <publisher>Acme Inc</publisher>
            <group>com.acme</group>
            <name>tomcat-catalina</name>
            <version>9.0.14</version>
            <licenses>
                <license>
                    <id>Apache-2.0</id>
                </license>
            </licenses>
            <purl>pkg:maven/com.acme/tomcat-catalina@9.0.14?packaging=jar</purl>
            <modified>false</modified>
            <pedigree>
                <ancestors>
                    <component type="application">
                        <publisher>Apache</publisher>
                        <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>
                    </component>
                </ancestors>
                <commits>
                    <commit>
                        <hash alg="sha-1">7638417db6d59f3c431d3e1f261cc637155684cd</hash>
                        <url>https://location/to/7638417db6d59f3c431d3e1f261cc637155684cd</url>
                        <author>
                            <timestamp>2014-11-07T22:01:45Z</timestamp>
                            <name>John Doe</name>
                            <email>jdoe@example.com</email>
                        </author>
                        <committer>
                            <timestamp>2014-11-07T22:01:45Z</timestamp>
                            <name>John Doe</name>
                            <email>jdoe@example.com</email>
                        </committer>
                        <message>Initial commit</message>
                    </commit>
                </commits>
            </pedigree>
        </component>
    </components>
</bom>

The above BOM describes a forked version of a Tomcat component. It identifies the component in which it originates from as well as the commits that make it different.

@stevespringett stevespringett changed the title Add ancestor support Add support for component pedigree Feb 6, 2019

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment