That is why DataTrails defines another type of asset alongside the Software Package, that is a Software Deployment. A Software Deployment is a live capture of the specific implementation of a Software Package in a specific environment, using many of the same attributes as the Software Package but following a different lifecycle with different events.
Overview
The key difference between a Software Package and a Software Deployment is that a Deployment tracks the implementation lifecycle of a Software Package in a specific environment, instead of the general lifecycle of a Supplied SBOM.
To contextualise this distinction, instead of creating a new ‘Release’ you would instead Upgrade or Rollback the version of the Deployment, referencing a specific Release in a corresponding Software Package Asset; additionally, if your upgrade involves a specific patch level, you could combine the two.
Using Rollback instead of Upgrade also means that you can trace when a specific Deployment goes to a lower version instead, a common operational event that may happen in response to a major bug in the latest release package or for many other reasons.
This separation of lifecycles is incredibly powerful for auditing; allowing consumers to react to vulnerability disclosures, new releases or patches both at their own pace and also with traceability built in without being forced into unwanted upgrades or functional loss through feature deprecation.
As the Software Deployment is an implementation of the Package it should contain extra Asset Attributes that refer to or link the Deployment to both the package it represents and the environment it is deployed in.
While a Software Package should always track a forward momentum of releases being made, the Deployment can track the reality of what a customer is actually using whether they move backwards with a version or forwards in a specific environment.
Asset Owners
A Software Deployment tracks the specific implementation of a Software Package in a consumer’s environment.
There are two main owners of a Software Deployment:
-
End Consumer
-
Software Operator (e.g. Linux Admin)
Lifecycle
Types of Event
Upgrade/Rollback
In the case of the Software Deployment its main event is either an Upgrade or Rollback. These events track the same information as required by the basic NTIA attributes for a release in the Event Attributes but have some added contexts, referencing the Software Package that is deployed and any patches that may also be included.
Similar to Release the Event Attributes being recorded should always match the current SBOM of the version that is being upgraded or rolled-back. Where this differs though is that the Asset Attributes should replicate the same information, as the primary view of the Asset should always match the most recent event in its history.
As the primary events for tracking the version of SBOM deployed in an Environment these are the only types considered truly mandatory in the Software Deployment Asset Lifecycle.
Upgrade/Rollback Details
Mandatory Attributes:
NTIA Attribute Name |
Asset Attribute |
Event Attribute |
Description |
---|---|---|---|
Author Name |
sbom_author |
sbom_upgrade/rollback_author |
The name of the Package Author |
Supplier Name |
sbom_supplier |
sbom_upgrade/rollback_supplier |
The name of the Package Supplier |
Component Name |
sbom_component, (arc_display_name if appropriate) |
sbom_upgrade/rollback_component |
The name of the Package |
Version String |
sbom_version, arc_firmware_version |
sbom_upgrade/rollback_version |
The version of the Package |
Component Hash |
sbom_hash |
sbom_upgrade/rollback_hash |
The hash of the component files/installation (per version) |
Unique Identifier |
Typically the Asset ID of the package will suffice but can optionally set with custom string (sbom_uuid) |
Typically the Asset ID of the package will suffice but can optionally be set with custom string (sbom_upgrade/rollback_uuid) |
A 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_environment |
sbom_upgrade_environment |
The Deployment Environment |
Optional Attributes:
N/A |
sbom_primary_contact |
N/A |
If the environment belongs to a particular team or operator it may be preferable to name that user |
N/A |
sbom_patch_level |
sbom_patch_level |
If the environment is being patched you may wish to indicate the patch reference here |
N/A |
sbom_repo |
sbom_repo |
Link to the Git Repo of the Component |
N/A |
sbom_release_notes |
sbom_upgrade/rollback_release_notes |
Link to the release notes of the release |
N/A |
sbom_license |
sbom_upgrade/rollback_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 upgrade/rollback for example if it was part of an automated build system, would be useful for ensuring a rich history |
N/A |
N/A |
sbom_upgrade/rollback__exception |
If included value is always “true” |
N/A |
N/A |
sbom_upgrade/rollback_vuln_reference |
If this release resolves a specific vulnerability you can highlight a shared Vulnerability reference number(s) |
Attachments:
Asset/Event Attachment |
Description |
---|---|
SBOM file |
The SBOM file provided with that release in full (typically .xml) |
Patch SBOM File |
If a Patch is specified you may wish to include the SBOM of the patch as well |
Example Upgrade JSON:
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Upgrade",
"arc_evidence": "Upgrade",
"arc_description": "v4.1.6 Upgrade - Production - ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_upgrade_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_upgrade_environment": "Production"
"sbom_upgrade_hash": "a314fc2dc663ae7a6b6bc6787594057396e6b3f569cd50fd5ddb4d1bbafd2b6a"
"sbom_upgrade_version": "v4.1.6",
"sbom_upgrade_author": "The ACME Corporation",
"sbom_upgrade_supplier": "Coyote Services, Inc.",
"sbom_upgrade_uuid": "com.acme.rrd2013-ce-sp1-v4-1-6-0",
"sbom_upgrade_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.6 Upgrade 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.6",
"sbom_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_hash": "a314fc2dc663ae7a6b6bc6787594057396e6b3f569cd50fd5ddb4d1bbafd2b6a"
"sbom_primary_contact": "bob@job"
"sbom_version": "4.1.6",
"sbom_environment": "Production"
"sbom_author": "The ACME Corporation",
"sbom_supplier": "Coyote Services, Inc.",
"sbom_uuid": "com.acme.rrd2013-ce-sp1-v4-1-6-0",
"sbom_license": "www.gnu.org/licenses/gpl.txt",
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "ACME Roadrunner Detector 2013 Coyote Edition SP1 v4.1.6 SBOM",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
]
}
}
Example Rollback JSON:
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Upgrade",
"arc_evidence": "Upgrade",
"arc_description": "v4.1.5 Rollback - Production - ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_rollback_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_rollback_environment": "Production"
"sbom_rollback_hash": "a314fc2dc663ae7a6b6bc6787594057396e6b3f569cd50fd5ddb4d1bbafd2b6a"
"sbom_rollback_version": "v4.1.5",
"sbom_rollback_author": "The ACME Corporation",
"sbom_rollback_supplier": "Coyote Services, Inc.",
"sbom_rollback_uuid": "com.acme.rrd2013-ce-sp1-v4-1-5-0",
"sbom_rollback_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 Rollback 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_primary_contact": "bob@job"
"sbom_version": "4.1.5",
"sbom_environment": "Production"
"sbom_author": "The ACME Corporation",
"sbom_supplier": "Coyote Services, Inc.",
"sbom_uuid": "com.acme.rrd2013-ce-sp1-v4-1-6-0",
"sbom_license": "www.gnu.org/licenses/gpl.txt"
}
}
Upgrade/Rollback Plan and Upgrade/Rollback Accepted
These are supplemental events that add far more richness to the lifecycle of a Deployment. It could be argued that these Plan and Accepted events are more essential fo Software Deployments than Packages as the active nature of the environment means changes to what is deployed will have much more immediate consequences.
Upgrade/Rollback Plan events demonstrate an intent to introduce change the deployed version, it should describe which version you want to upgrade/rollback and who wants to perform the upgrade/rollback. A useful inclusion here is perhaps some release notes explaining what is being updated and why it should be updated.
Upgrade/Rollback Accepted events demonstrate an approval on an Upgrade 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 or a common practice in a live production environment is the need for executive approvals.
Note that both Upgrade and Rollback use the same sbom_planned_*
and sbom_accepted_*
cadence, this is because the plan represents an intended change in version, the name of the event (being either Upgrade or Rollback) indicates which direction the version is changing.
Upgrade/Rollback Plan Details
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Upgrade Plan",
"arc_evidence": "Upgrade Plan",
"arc_description": "v4.1.6 Upgrade Plan - Production - 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"
}
]
}
}
Upgrade/Rollback Accepted Details
The exception flag on an upgrade or rollback 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 Upgrade/Rollback Plan and Upgrade/Rollback events even during an emergency for more careful and precise change management so may not need an directly ‘Exception’ event.
However, as deployments have an inherent live and time-critical component to them an Exception is an important consideration to include. It is not uncommon during a production outage for decisions to be made with limited, emergency approvals to resolve an issue, these should be carefully tracked as part of any change management on a Deployment.
Vulnerability Disclosure
During the lifecycle of a Software Deployment vulnerabilities may be announced from a correlated Software Package.
Proving this history and having SLAs tied to a Vulnerability Disclosure (such as one mandated by an internal security team) is a huge enhancement to the Lifecycle of the Deployment and its SBOM.
During any audit pen-test of an environment it can then be demonstrated 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 you or not.
This mechanism called VEX (Vulnerability Exploitability eXchange) is still very nascent but as a general template for Vulnerability Disclosure seems appropriate enough to follow as it gives consumers the opportunity to justify their decision for ignoring a particular disclosure; a key factor when considering the need for transparency in the audit of an environment.
This follows the same cadence as the release Vulnerability Disclosure Mechanism but should be tailored to reflect the specific implementation of the software in this environment.
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"
}
]
}
}
Installation/Decommission
As a deployment has more inherent tangibility than a Software Package these events should more clearly bookend the lifecycle of a Software Deployment, marking the inception of a Deployment when installed and when it is no longer used it should be considered uninstalled.
This makes clear to any observer what Deployments are currently active, have been active and the history of the estate from cradle to grave,
As a deployment may already exist these events are optional, however if a new installation is performed, or a Deployment is removed Users are encouraged to make use of them to add richness to the lifecycle of their Deployments.
As events 'Installation' is effectively the first ‘Upgrade/Rollback’ event in the lifecycle of the deployment, it should track the exact same information as any normal Upgrade/Rollback but may use a more targeted, installation focused SBOM (similar to the Corpus Tag in the SWID standard which only records the footprint of the installation package).
Decommission, a term more representative of the end of a Software Deployment’s lifecycle, in this case is analogous with the 'End of Life' event in the Software Package asset definition. It should mark the removal, disuse or uninstallation of the deployment in the environment it describes so that anyone auditing the environments can see what should be decommissioned or removed already.
Installation Details
Mandatory Attributes:
NTIA Attribute Name |
Asset Attribute |
Event Attribute |
Description |
---|---|---|---|
Author Name |
sbom_author |
sbom_installation_author |
The name of the Package Author |
Supplier Name |
sbom_supplier |
sbom_installation_supplier |
The name of the Package Supplier |
Component Name |
sbom_component, (arc_display_name if appropriate) |
sbom_installation_component |
The name of the Package |
Version String |
sbom_version, arc_firmware_version |
sbom_installation_version |
The version of the Package |
Component Hash |
sbom_hash |
sbom_installation_hash |
The hash of the component files/installation (per version) |
Unique Identifier |
Typically the Asset ID of the package will suffice but can optionally set with custom string (sbom_uuid) |
Typically the Asset ID of the package will suffice but can optionally be set with custom string (sbom_installation_uuid) |
A unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference instead |
Optional Attributes:
N/A |
sbom_repo |
sbom_installation_repo |
Link to the Git Repo of the Component |
N/A |
sbom_release_notes |
sbom_installation_release_notes |
Link to the release notes of the release |
N/A |
sbom_license |
sbom_installation_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 |
Attachments:
Asset/Event Attachment |
Description |
---|---|
SBOM file |
The SBOM file provided with that release/installation medium in full (typically .xml) |
Release Notes (Optional) |
Copy of the Release Notes |
Example Installation JSON:
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Installation",
"arc_evidence": "Installation - Production - ACME Roadrunner Detector 2013 Coyote Edition SP1",
"arc_description": "v4.1.5 Production Installation",
"sbom_installation_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_installation_hash": "a314fc2dc663ae7a6b6bc6787594057396e6b3f569cd50fd5ddb4d1bbafd2b6a"
"sbom_installation_version": "v4.1.5",
"sbom_installation_author": "The ACME Corporation",
"sbom_installation_supplier": "Coyote Services, Inc.",
"sbom_installation_uuid": "com.acme.rrd2013-ce-sp1-v4-1-5-0",
"sbom_installation_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"
}
}
Decommission Details
Mandatory Attributes:
NTIA Attribute Name |
Asset Attribute |
Event Attribute |
Description |
---|---|---|---|
Component Name |
N/A |
sbom_decommission_component |
The component the Decommission targets |
Version String |
N/A |
sbom_decommission_version |
The version string affected by the Decommission |
Author Name |
N/A |
sbom_decommission_author |
The name of the Decommission Author |
Unique Identifier |
N/A |
Typically the Asset ID of the package will suffice but can optionally be set with custom string (sbom_decommission_uuid) |
A 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_decommission_target_date |
sbom_decommission_target_date |
The date on which the Decommission will be active |
N/A |
sbom_decommission_status |
sbom_decommission_status |
The status of the decommission (e.g. Planned, Deprecated, Decommissioning, Decommissioned) |
N/A |
sbom_environment |
sbom_decommission_environment |
The Deployment Environment being decommissioned |
Attachments
Event Attachment |
Description |
---|---|
Decommission Announcement/Documentation |
Copy of the Decommission Announcement |
Example Decommission JSON:
{
"operation": "Record",
"behaviour": "RecordEvidence",
"event_attributes": {
"arc_display_type": "Decommission",
"arc_evidence": "Decommission",
"arc_description": "Decommission - Production - ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_decommission_component": "ACME Roadrunner Detector 2013 Coyote Edition SP1",
"sbom_decommission_version": "v4.1.5",
"sbom_decommission_uuid": "com.acme.rrd2013-ce-sp1-v4-1-5-0",
"sbom_decommission_target_date": "2021-07-30",
"sbom_decommission_status": "Planned"
"sbom_decommission_environment": "Production"
"arc_attachments": [
{
"arc_attachment_identity": "blobs/1754b920-cf20-4d7e-9d36-9ed7d479744d",
"arc_display_name": "ACME Roadrunner Detector 2013 Coyote Edition SP1 v4.1.5 Production Decommission Announcement",
"arc_hash_alg": "sha256",
"arc_hash_value": "01ba4719c80b6fe911b091a7c05124b64eeece964e09c058ef8f9805daca546b"
}
]
},
"asset_attributes": {
"sbom_decommission_target_date": "2021-07-30",
"sbom_decommission_status": "Planned"
"sbom_environment": "Decommission(Production)"
}
}