Pedigree captures the unique identity and evolution of a component, documenting its origin, modifications, and significant changes. CycloneDX enables organizations to maintain a detailed record of a component’s history, including commits, diffs, enhancements, defect fixes, and security patches. By connecting these details to the upstream source or original version of a component, CycloneDX provides a clear understanding of how and why a component has evolved, offering critical transparency for managing complex systems.
This capability is particularly useful in scenarios where components are forked, repackaged, or modified to meet specific requirements. By documenting these changes, pedigree establishes a clear chain of accountability and provides vital context for decisions in development, security, and compliance efforts. CycloneDX’s pedigree capabilities improve supply chain visibility, enabling organizations to mitigate risks and maintain confidence in their software components.
| Property | Usage Description |
|---|---|
| ancestors | Lists the components from which the current component is derived, establishing its lineage and origin. Alternative fields like descendants track components derived from the current one, while variants capture alternative versions. |
| commits | Tracks individual changes recorded in version control systems, offering a detailed history of modifications. These entries provide visibility into updates such as feature additions, defect fixes, or code refinements. |
| patches | Documents updates or fixes applied to a component to address defects or enhance functionality. These modifications improve security, stability, or performance and are essential for tracking incremental improvements. |
| diff | Highlights the differences between two component versions, showing what has been added, removed, or altered. This information is vital for understanding the impact and scope of changes, such as resolved issues or new features. |
| resolves | Links the component to specific issues, defects, or vulnerabilities it addresses. By connecting fixes to resolved problems, this field demonstrates the practical impact of updates. |
{
"$schema": "http://cyclonedx.org/schema/bom-1.6.schema.json",
"bomFormat": "CycloneDX",
"specVersion": "1.6",
"serialNumber": "urn:uuid:3e671687-395b-41f5-a30f-a58921a69b79",
"version": 1,
"components": [
{
"type": "library",
"group": "com.acme",
"name": "sample-library",
"version": "1.0.0",
"pedigree": {
"ancestors": [
{
"type": "library",
"group": "org.example",
"name": "sample-library",
"version": "1.0.0"
}
],
"commits": [
{
"uid": "7638417db6d59f3c431d3e1f261cc637155684cd",
"url": "https://location/to/7638417db6d59f3c431d3e1f261cc637155684cd",
"author": {
"timestamp": "2018-11-13T20:20:39+00:00",
"name": "John Doe",
"email": "[email protected]"
},
"committer": {
"timestamp": "2018-11-13T20:20:39+00:00",
"name": "Jane Doe",
"email": "[email protected]"
},
"message": "Initial commit"
}
],
"patches": [
{
"type": "unofficial",
"diff": {
"text": {
"contentType": "text/plain",
"encoding": "base64",
"content": "ZXhhbXBsZSBkaWZmIGhlcmU="
},
"url": "uri/to/changes.diff"
},
"resolves": [
{
"type": "enhancement",
"id": "JIRA-17240",
"description": "Great new feature that does something",
"source": {
"name": "Acme Org",
"url": "https://issues.acme.org/17240"
}
}
]
},
{
"type": "backport",
"diff": {
"text": {
"contentType": "text/plain",
"encoding": "base64",
"content": "ZXhhbXBsZSBkaWZmIGhlcmU="
},
"url": "uri/to/changes.diff"
},
"resolves": [
{
"type": "security",
"id": "CVE-2019-9997",
"name": "CVE-2019-9997",
"description": "Issue description here",
"source": {
"name": "NVD",
"url": "https://nvd.nist.gov/vuln/detail/CVE-2019-9997"
},
"references": [
"http://some/other/site-1",
"http://some/other/site-2"
]
},
{
"type": "defect",
"id": "JIRA-874319",
"description": "Description of fix here",
"source": {
"name": "Example Org",
"url": "https://issues.example.org/874319"
},
"references": [
"http://some/other/site-1",
"http://some/other/site-2"
]
}
]
}
]
}
}
]
}