Software Package Profile

Sharing and Distributing a Software Bill of Materials with DataTrails

Overview

The DataTrails Software Package profile is a set of suggested Asset and Event attributes that enable the recording of an immutable and verifiable Software Bill of Materials (SBOM).

The NTIA describes a SBOM as “a formal record containing the details and supply chain relationships of various components used in building software.

Software Package Profile Asset Attributes

NTIA AttributeAsset AttributesMeaningRequirement
Author Namesbom_authorThe name of the Package AuthorRequired
Supplier Namesbom_supplierThe name of the Package SupplierRequired
Component Namesbom_component,(arc_display_name if appropriate)The name of the Software PackageRequired
Version Stringsbom_versionThe version of the Software PackageRequired
Unique Identifiersbom_uuidA unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference insteadRequired
N/Asbom_repoLink to the Git Repo of the ComponentOptional
N/Asbom_release_notesLink to the release notes of the package versionOptional
N/Asbom_licenseThe licensing used by the component (if specified)Optional

Note: Software Package Profile Attribute Namespace

The sbom_ prefix is used to designate attributes that are part of the profile. Some of these are interpreted by DataTrails and others are guidelines.

Public SBOM

In the API, you must express public as an asset attribute and have true as a property to make an SBOM public. The default is ‘false’. In the UI this is done by setting Attest Publicly to On.

Select Assets & Documents from the sidebar and then Add Custom Asset. Fill in the desired details. Set the Attest Publicly toggle to On.

Check Asset as Public

Create a YAML file with your desired Asset details. Set keyword public to true.

---
steps:
  - step:
      action: ASSETS_CREATE_IF_NOT_EXISTS
      description: Create an asset.
      asset_label: Publicly Attested Asset 
    selector: 
      - attributes: 
        - arc_display_name
    behaviours: 
      - RecordEvidence
    proof_mechanism: SIMPLE_HASH
    public: true
    attributes: 
      arc_display_name: Publicly Attested Asset 
      arc_display_type: Example
      arc_description: This example asset is publicly attested, so anyone with the link can access its details without signing in to DataTrails.
      some_custom_attribute: anything you like
    confirm: true

Create a JSON file with your desired Asset details. Set keyword public to true.

{
    "behaviours": ["RecordEvidence"],
    "attributes": {
        "arc_display_name": "Publicly Attested Asset",
        "arc_display_type": "Example",
        "arc_description": "This example asset is publicly attested, so anyone with the link can access its details without signing in to DataTrails."
    },
    "public": true
}

Software Package Profile Event Types and Attributes

Release Event

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.

Release Event Attribute Namespace

The sbom_ prefix is used to designate attributes that are part of the event and asset. Some of these are interpreted by DataTrails and others are guidelines

NTIA AttributeEvent AttributesMeaningRequirement
N/Aarc_display_typeTells DataTrails how to interpret EventRequired, must set to Release
Author Namesbom_authorThe name of the Package AuthorRequired
Supplier Namesbom_supplierThe name of the Package AuthorRequired
Component Namesbom_componentThe name of the PackageRequired
Version Stringsbom_versionThe version of the PackageRequired
Unique Identifiersbom_uuidA unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference insteadRequired
N/Asbom_repoLink to the Git Repo of the ComponentOptional
N/Asbom_release_notesLink to the release notes of the releaseOptional
N/Asbom_licenseThe licensing used by the component (if specified)Optional
N/Asbom_exceptionIf included value is always trueOptional
N/Asbom_vuln_referenceIf this release resolves a specific vulnerability you can highlight a shared Vulnerability reference number(s)Optional
NTIA AttributeAsset AttributesMeaningRequirement
Author Namesbom_authorThe name of the Package AuthorRequired
Supplier Namesbom_supplierThe name of the Package SupplierRequired
Component Namesbom_component,(arc_display_name if appropriate)The name of the Software PackageRequired
Version Stringsbom_versionThe version of the Software PackageRequired
Unique Identifiersbom_uuidA unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference insteadRequired
N/Asbom_repoLink to the Git Repo of the ComponentOptional
N/Asbom_release_notesLink to the release notes of the package versionOptional
N/Asbom_licenseThe licensing used by the component (if specified)Optional
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.

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. For example, it could include draft 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.

These events are not essential to the process so can be omitted in a standard or minimal deployment but they are actively encouraged. As they should not affect the information about the latest Software Package Release there should be no Asset Attributes included, other NTIA attributes may also not be necessary or not available until release (e.g. Component Hash).

The Key Attribute that should be recorded is the version of the release that is being planned and accepted.

Release Plan

Release Plan Event Attribute Namespace

The sbom_planned_ prefix is used to designate attributes that are part of the event. Some of these are interpreted by DataTrails and others are guidelines.

NTIA AttributeEvent AttributesMeaningRequirement
N/Aarc_display_typeTells DataTrails how to interpret EventRequired, must set to Release Plan
Component Namesbom_planned_componentThe planned name of the PackageRequired
Version Stringsbom_planned_versionThe planned version of the PackageRequired
N/Asbom_planned_referenceA reference number for the plan (such as internal change request number)Required
N/Asbom_planned_dateThe planned release dateRequired
N/Asbom_planned_captainThe planned Release Captain (a common term for someone who is responsible for performing a Release; someone like an Owner in Agile serves a different purpose but may also be used if appropriate). This is mandatory as it describes who should be responsible for the releaseRequired
Author Namesbom_planned_authorThe planned name of the Package AuthorOptional
Supplier Namesbom_planned_supplierThe planned name of the Package SupplierOptional
Component Hashsbom_planned_hashThe planned hash of the component files/installation (per version)Optional
Unique Identifiersbom_planned_uuidThe planned unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference insteadOptional
N/Asbom_planned_licenseIf there is an intended change to the license this may be neededOptional
N/Asbom_planned_vuln_referenceIf this release intends to resolve a specific vulnerability you can highlight a shared Vulnerability reference number(s)Optional

Release Accepted Event

Release Accepted Event Attribute Namespace

The sbom_accepted_ prefix is used to designate attributes that are part of the event. Some of these are interpreted by DataTrails and others are guidelines.

NTIA AttributeEvent AttributesMeaningRequirement
N/Aarc_display_typeTells DataTrails how to interpret EventRequired, must set to Release Accepted
Component Namesbom_accepted_componentThe accepted name of the PackageRequired
Version Stringsbom_accepted_versionThe accepted version of the PackageRequired
N/Asbom_accepted_referenceThe reference number of the associated planRequired
N/Asbom_accepted_dateThe accepted release dateRequired
N/Asbom_accepted_captainThe accepted Release Captain (a common term for someone who is responsible for performing a Release; someone like an Owner in Agile serves a different purpose but may also be used if appropriate). This is mandatory as it describes who should be responsible for the releaseRequired
N/Asbom_accepted_approverDescribes who has accepted the planRequired
Author Namesbom_accepted_authorThe accepted name of the Package AuthorOptional
Supplier Namesbom_accepted_supplierThe accepted name of the Package SupplierOptional
Component Hashsbom_accepted_hashThe accepted hash of the component files/installation (per version)Optional
Unique Identifiersbom_accepted_uuidThe accepted unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference insteadOptional
N/Asbom_accepted_vuln_referenceIf this release intends to resolve a specific vulnerability you can highlight a shared Vulnerability reference number(s)Optional

Patch Event

Patches are often supplied to customer in an Out-Of-Band procedure to address critical bugs or vulnerabilities, usually with a short-term turnaround that can be outside the normal release cadence.

It is typically expected a Patch should contain its own SBOM separate to the Primary SBOM.

Patch Event Attribute Namespace

The sbom_patch_ prefix is used to designate attributes that are part of the event. Some of these are interpreted by DataTrails and others are guidelines.

NTIA AttributeEvent AttributesMeaningRequirement
N/Aarc_display_typeTells DataTrails how to interpret EventRequired, must set to Patch
Component Namesbom_patch_target_componentThe component the Patch targetsRequired
Version Stringsbom_patch_versionThe version string of the PatchRequired
Author Namesbom_patch_authorThe name of the Patch AuthorRequired
Supplier Namesbom_patch_supplierThe name of the Patch SupplierRequired
Component Hashsbom_patch_hashThe hash of the Patch files/installation (per version)Required
Unique Identifiersbom_patch_uuidThe accepted unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference insteadRequired
N/Asbom_patch_target_versionThe version of the component the patch is targeted/built fromRequired
N/Asbom_patch_repoLink to the Git Repo/Fork/Branch of the Component (if different to the latest release repo)Optional
N/Asbom_patch_licenseThe licensing used by the component (if specified and different to the latest release license)Optional
N/Asbom_patch_vuln_referenceIf this patch resolves a specific vulnerability you can highlight a shared Vulnerability reference numberOptional

Vulnerability Disclosure and Update

These Event types are used for vulnerability management. The first is to disclose knowledge of a vulnerability and the second is to update the status of the vulnerability after investigation is complete.

Vulnerability Disclosure Event Attribute Namespace

The vuln_ prefix is used to designate attributes that are part of the event. All of these are interpreted by DataTrails.

Vulnerability Disclosure

Event AttributesMeaningRequirement
arc_display_typeTells DataTrails how to interpret EventRequired, must set to Vulnerability Disclosure
vuln_nameFriendly Name for the VulnerabilityRequired
vuln_referenceReference Number (e.g. internal tracking number), useful when there may be multiple updates to a vulnerability during an investigation and for referencing when a particular release is expected to solve a vulnerabilityRequired
vuln_idSpecific ID of Vulnerability (e.g CVE-2018-0171)Required
vuln_categoryType of Vulnerability (e.g. CVE)Required
vuln_severitySeverity of Vulnerability (e.g. HIGH)Required
vuln_statusWhether the Vulnerability actually affects your component or is being investigated (e.g Known_not_affected)Required
vuln_authorAuthor of Vulnerability DisclosureRequired
vuln_target_componentAffected ComponentRequired
vuln_target_versionAffected Version(s)Required

Vulnerability Update

Event AttributesMeaningRequirement
arc_display_typeTells DataTrails how to interpret EventRequired, must set to Vulnerability Update
vuln_nameFriendly Name for the VulnerabilityRequired
vuln_referenceReference Number (e.g. internal tracking number), useful when there may be multiple updates to a vulnerability during an investigation and for referencing when a particular release is expected to solve a vulnerabilityRequired
vuln_idSpecific ID of Vulnerability (e.g CVE-2018-0171)Required
vuln_categoryType of Vulnerability (e.g. CVE)Required
vuln_severitySeverity of Vulnerability (e.g. HIGH)Required
vuln_statusWhether the Vulnerability actually affects your component or is being investigated (e.g Known_not_affected)Required
vuln_authorAuthor of Vulnerability DisclosureRequired
vuln_target_componentAffected ComponentRequired
vuln_target_versionAffected Version(s)Required

EOL Event

EOL Event Attribute Namespace

The sbom_eol_ prefix is used to designate attributes that are part of the event. All of these are interpreted by DataTrails.

An event to mark the Package as End of Life.

NTIA AttributeEvent AttributesMeaningRequirement
N/Aarc_display_typeTells DataTrails how to interpret EventRequired, must set to EOL
Component Namesbom_eol_target_componentThe component the EOL targetsRequired
Version Stringsbom_eol_target_versionThe version string affected by the EOLRequired
Author Namesbom_eol_authorThe name of the EOL AuthorRequired
Unique Identifiersbom_eol_uuidThe accepted unique identifier for the Package, DataTrails provides a Unique ID per asset but it may be preferred to include an existing internal reference insteadRequired
N/Asbom_eol_target_dateThe date on which the EOL will be activeRequired