A Software Package, as described in SPDX, refers to any unit of content that can be associated with a distribution of software. In this case it could be a library, SDK, Git Repo, Archive, Container Image or describe a collection of other Packages as well.
A Software Package will have maintainers and developers who release new versions of the package throughout its lifecycle to supply to their customers.
Overview
As an Asset a Software Package may hold many different SBOMs over its lifecycle, marked by the introduction of new releases and versions of the Software Package, using each ‘Release’ ( a cadence that tools like Github use) as an Event to capture the known SBOM at the time.
In this case there will be an SBOM to describe each Release as a collection of components with an associated version that can then be shared with consumers, who can verify the history of the Software Package as well as which versions should be deployed within their own environments, based on availability.
If a particular Software Package has constituent components composed of other Software Package Assets this would be tracked within the SBOM of the Supplied Software Package, ensuring full traceability across the Supply Chain.
An interesting implementation of the Software Package asset is as an internal baseline. In Microservice Architectures often a release contains 100s of different services that forms an entire congruent platform.
A release in this case would be the approved configuration of services and versions that forms a whole platform deployment which can then be individually referenced in a specific Software Deployment later on.
Downstream deployments can then always be tracked against a known ‘good’ configuration that has been supplied, tested and verified by an internal architecture or security team.
It is important to note that even in the case of open-source or more public commercial offerings certain patches or updates may need to be kept private to satisfy NDAs or protect commercial interests. The need for a controlled patch sharing mechanism is described later on.
Asset Owners
A Software Package is a Suppliers Description of a piece of Software and its releases.
There are two main owners of the Software Package:
-
Software Supplier (Commercial/Public Entity)
-
Platform/System Architect (Internal Product Owner and Designer)
Lifecycle
Types of Event
Release
A Release is the event used by a Supplier to provide an SBOM for their Software Package in DataTrails.
The Release attributes tracked in DataTrails should minimally represent the base information required by the NTIA standard and be recorded in two, separate, lists of attributes; Asset Attributes would track details about the latest release of the SBOM at the time of the event creation, the event attributes then track details about the release of the SBOM that is being submitted.
This is useful as older product lines or minor versions of a software may still need updating, you may wish to notify customers on these older versions about a new release for their product line complete with SBOM but still remind them what the latest version you encourage them to use is.
You should then add an attachment of the full SBOM File of the release being described within the event so that anyone who wishes to look back and see a particular version’s release and full SBOM will get the complete historical context if necessary.
By describing only the NTIA required information as direct attributes this keeps the complexity of the implementation to a minimum, Users can prove they have the correct provenance directly tracked and then the more detailed standardized SBOM can also be attached for those who need it; all while remaining relatively standards agnostic.
As the primary mechanism for sharing an SBOM for a Software Package a Release event is considered one of the few, if only, ‘mandatory’ events in the normal lifecycle of a Software Package in DataTrails.
Release Event Details
Optional Attributes:
N/A |
sbom_repo |
sbom_repo |
Link to the Git Repo of the Component |
N/A |
sbom_release_notes |
sbom_release_notes |
Link to the release notes of the release |
N/A |
sbom_license |
sbom_license |
The licensing used by the component (if specified) |
N/A |
N/A |
principal_declared |
Can be used to specify the individual who started the release for example if it was part of an automated build system, would be useful for ensuring a rich history |
N/A |
N/A |
sbom_exception |
If included value is always “true” (see Exception) |
N/A |
N/A |
sbom_vuln_reference |
If this release resolves a specific vulnerability you can highlight a shared Vulnerability reference number(s) |
Attachments:
SBOM file |
The SBOM file provided with that release in full (typically .xml) |
Release Notes (Optional) |
Copy of the Release Notes |
Release Event Example JSON:
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Release",
"arc_evidence": "Release",
"arc_description": "v4.1.5 Release - ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_hash": "a314fc2dc663ae7a6b6bc6787594057396e6b3f569cd50fd5ddb4d1bbafd2b6a"
"sbom_version": "v4.1.5",
"sbom_author": "The ACME Corporation",
"sbom_supplier": "Coyote Services, Inc.",
"sbom_uuid": "com.acme.rrd2013-ce-sp1-v4-1-5-0",
"sbom_license": "www.gnu.org/licenses/gpl.txt",
"principal_declared": {
"issuer": "job.idp.server/1234",
"subject": "bob@job"
},
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "ACME Roadrunner Detector 2013 Coyote Edition SP1 v4.1.5 SBOM",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
]
},
"asset_attributes": {
"arc_display_name": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"arc_display_type": "Software Package"
"arc_firmware_version": "4.1.5",
"sbom_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_hash": "a314fc2dc663ae7a6b6bc6787594057396e6b3f569cd50fd5ddb4d1bbafd2b6a"
"sbom_version": "4.1.5",
"sbom_author": "The ACME Corporation",
"sbom_supplier": "Coyote Services, Inc.",
"sbom_uuid": "com.acme.rrd2013-ce-sp1-v4-1-5-0",
"sbom_license": "www.gnu.org/licenses/gpl.txt"
}
}
Release Plan and Release Accepted
Release events can be optionally enhanced by using ‘Release Plan’ and ‘Release Accepted’ events alongside them.
Release Plan events demonstrate an intent to introduce a new release, it should describe which version you want to release and who wants to release it. A useful inclusion here is perhaps some release notes explaining what is being updated and why it should be updated.
Release Accepted events demonstrate an approval on a Release Plan to go forward, it may be that the plan details a need to introduce a fix for a specific vulnerability and the security team is needed to sign off the release going forward.
The inclusion of these two events are incredibly important in adding a richness to the story of a release, instead of releases occurring without context now a Supplier can not only detail their justification for a release but demonstrate an authoritative seal of approval on the release before it goes ahead.
These events are not essential to the process so can be forgone in a standard and minimal deployment but they are actively encouraged. As they should not affect the information about the latest Software Package Release there should be no included Asset Attributes, other NTIA attributes may also not be necessary or available until release (e.g. Component Hash).
The Key Attributes that should be recorded is are the version of the release that is being planned and accepted.
Release Plan Details
Optional Attributes:
Author Name |
sbom_planned_author |
The planned name of the Package Author |
Supplier Name |
sbom_planned_supplier |
The planned name of the Package Supplier |
Component Hash |
sbom_planned_hash |
The planned hash of the component files/installation (per version) |
Unique Identifier |
Typically the Asset ID of the package will suffice but can optionally be set with custom string (sbom_planned_uuid) |
The planned unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference instead |
N/A |
sbom_planned_license |
If there is an intended change to the license this may be needed |
N/A |
sbom_planned_vuln_reference |
If this release intends to resolve a specific vulnerability you can highlight a shared Vulnerability reference number(s) |
Attachments:
Event Attachment |
Description |
---|---|
SBOM file |
The SBOM file provided with that release in full (typically .xml) |
Change Request |
A document detailing the changes proposed with internal reference numbers to a ticketing system |
Release Plan Example JSON:
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Release Plan",
"arc_evidence": "Release Plan",
"arc_description": "v4.1.6 Release Plan - ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_planned_reference": "01234"
"sbom_planned_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_planned_hash": "a314fc2dc663ae7a6b6bc6787594057396e6b3f569cd50fd5ddb4d1bbafd2b6a"
"sbom_planned_version": "v4.1.6",
"sbom_planned_author": "The ACME Corporation",
"sbom_planned_supplier": "Coyote Services, Inc.",
"sbom_planned_uuid": "com.acme.rrd2013-ce-sp1-v4-1-6-0",
"sbom_planned_license": "www.gnu.org/licenses/gpl.txt",
"sbom_planned_date": "2021-06-30T09:00+0800",
"sbom_planned_captain": "bob@job"
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744e",
"arc_display_name": "ACME Roadrunner Detector 2013 Coyote Edition SP1 v4.1.6 SBOM",
"arc_hash_alg": "sha256",
"arc_hash_value": "017a4719c80b6fe911b091a7c05124b64eeece964e09c048ef8f9805daca547a"
}
]
}
}
Release Accepted Example
Optional Attributes:
Author Name |
sbom_accepted_author |
The accepted name of the Package Author |
Supplier Name |
sbom_accepted_supplier |
The accepted name of the Package Supplier |
Component Hash |
sbom_accepted_hash |
The accepted hash of the component files/installation (per version) |
Unique Identifier |
Typically the Asset ID of the package will suffice but can optionally be set with custom string (sbom_accepted_uuid) |
The accepted unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference instead |
N/A |
sbom_accepted_vuln_reference |
If this release intends to resolve a specific vulnerability you can highlight a shared Vulnerability reference number(s) |
Attachments:
Event Attachment |
Description |
---|---|
SBOM file |
The SBOM file provided with that release in full (typically .xml) |
Change Request |
A document detailing the changes proposed with internal reference numbers to a ticketing system |
Approval Document |
A document that contains an authorised signature |
Release Accepted Example JSON:
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Release Accepted",
"arc_evidence": "Release Accepted",
"arc_description": "v4.1.6 Release Accepted - ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_accepted_reference": "01234"
"sbom_accepted_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_accepted_hash": "a314fc2dc663ae7a6b6bc6787594057396e6b3f569cd50fd5ddb4d1bbafd2b6a"
"sbom_accepted_version": "v4.1.6",
"sbom_accepted_author": "The ACME Corporation",
"sbom_accepted_supplier": "Coyote Services, Inc.",
"sbom_accepted_uuid": "com.acme.rrd2013-ce-sp1-v4-1-6-0",
"sbom_accepted_license": "www.gnu.org/licenses/gpl.txt",
"sbom_accepted_date": "2021-06-30T09:00+0800",
"sbom_accepted_captain": "bob@job"
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744e",
"arc_display_name": "ACME Roadrunner Detector 2013 Coyote Edition SP1 v4.1.6 SBOM",
"arc_hash_alg": "sha256",
"arc_hash_value": "017a4719c80b6fe911b091a7c05124b64eeece964e09c048ef8f9805daca547a"
}
]
}
}
Exception
Another useful and supplemental flag, event attribute or even a whole event that may be considered is an ‘Exception’, when used in tandem with Release Plan and Accepted events the exception is a useful record of when an emergency has caused a release to be pushed without needing an initial approval or plan; say for example a day zero/highly critical vulnerability needs to be immediately answered in a matter of hours without relying on the traditional approval mechanism.
The exception class of release is typically unnecessary during normal operations, but in the unique cases where a break-glass procedure is made necessary it is useful to be aware of how to implement such an event for the sake of record keeping.
It should be noted that most customers would likely. use the Release Plan and Accepted events even during an emergency so may not need an ‘Exception’ event.
Patches
Patches are often supplied to customer in an Out-Of-Band procedure to address critical bugs or vulnerabilities with a temporary or short-term turnaround.
As a modification to the Software Package code it is important patches are captured in the release process and history of a Package, however as an often transient and asynchronous constituent of the Package history it is necessary to identify these patches in a separate cadence to direct releases while also letting users trace which version of the Package the patch is based on and modifies.
Some patches may also offer specific but critical resolutions that affect an end customer’s solution and their commercial output, which may be covered under an NDA that needs to be observed. This means that while all patches should be included in the Package History, specific patch SBOMs may only be shared with customers who need to know or see the SBOM history for their specific implementation of the Package.
How to reference patch levels in a deployment will be discussed in the Software Deployment section.
Patch
The standard ‘Patch’ event is a global event that details the release of a supplemental patch of a software to all customers without restriction.
The use and distribution of patches is unique per product, company and distribution so may not always be necessary as a Supplier may instead elect to do a full upgrade to remove complexity from their own Supply Chain without needing special references in place.
It is typically expected a Patch should contain its own SBOM separate to the Primary SBOM.
Private_Patch
A private patch is similar to a normal ‘Patch’ event but the event itself should use a unique identifier in the event type so that it can be shared only with a specific customer via ABAC or OBAC.
It is a common practice, when supplying commercial customers, that in the case of a specific issue or bug you may wish to release a hot-fix or patch to address their particular concern. The supply of these patches and the issues that caused them to be created may be covered under an NDA so while the supply of a private patch is intrinsically tied to the supply of the Software Package there is a need to filter out which customers can see which patches.
A private patch can use a unique reference in the event, typically a customer contract number is a good choice, to let OBAC control which customer will see the patch is available.
Patch Example
Vulnerability Disclosure and Update
During the lifecycle of a Software Package vulnerabilities may be discovered that need to be announced, correlated to an affected version and addressed in a timely fashion.
Proving this history and potentially even having SLAs tied to a Vulnerability Disclosure is a huge enhancement to the Lifecycle of the Package and its SBOM, as you are able to prove to consumers the transparency and responsiveness of your team as well as the robustness of your best practices.
The NTIA is currently discussing an appropriate Vulnerability disclosure mechanism acknowledging the need to declare if a known vulnerability in your constituent packages will actually affect a Package or not.
This discussion involves the need to first disclose knowledge of a vulnerability, and then potentially updating the status of the vulnerability after it has been investigated, that is why there are two separate events covering a Vulnerabilities.
In terms of standards around Vulnerabilities there exist two mechanisms, the first being investigated by the NTIA is VEX (Vulnerability Exploitability eXchange), which is still very nascent, but as a general template for Vulnerability Disclosure seems to a suitable minimum; VEX is expected to eventually be aligned with a more comprehensive standard called CSAF.
Vulnerability Disclosure and Update Example
Example Vulnerability Update JSON:
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Vulnerability Update",
"arc_evidence": "Vulnerability",
"arc_description": "CVE-2018-0171 Vulnerability Update",
"vuln_name": "Install Remote Code Execution Vulnerability",
"vuln_reference": "CSCvg76186",
"vuln_id": "CVE-2018-0171",
"vuln_category": "CVE",
"vuln_severity": "CRITICAL",
"vuln_status": "Known_not_affected",
"vuln_author": "robb@job",
"vuln_target_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1"
"vuln_target_version": "3.1.0<=v4.1.5",
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "ACME Roadrunner Detector 2013 Coyote Edition SP1 CVE-2018-0171 CSAF",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
]
}
}
End of Life (EOL)
At some point in the Asset’s Lifecycle an 'End of Life' or Deprecation that marks the Software Package as being no longer supported or directly usable, while this could be handled by simply turning off tracking against the asset, making it invisible, this would cause many to lose easy access to the history of the asset. When each customer may move at their own pace to upgrade or move away from a deprecated product the supply of history is still important to maintain.
Instead it would be preferable to make an ‘End of Life’ or Deprecation event so that when a customer or consumer of the package looks they can see that in the history of the Software Package and know to retire that implementation from their own deployments.
EOL and Deprecation Details
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "EOL",
"arc_evidence": "EOL",
"arc_description": "EOL - ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_eol_target_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_eol_target_version": "v4.1.5",
"sbom_eol_uuid": "com.acme.rrd2013-ce-sp1-v4-1-5-0",
"sbom_eol_target_date": "2021-07-30"
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "ACME Roadrunner Detector 2013 Coyote Edition SP1 v4.1.5 EOL Announcement",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
]
}
}