Skip to content

Latest commit

 

History

History
208 lines (177 loc) · 7.1 KB

Readme_BOM.md

File metadata and controls

208 lines (177 loc) · 7.1 KB
Raw

Software Clearing Automation

In the very beginning there was no available format for a bill of material (SBOM), so we created our own format. But we still kept an eye on other existing SBOM formats. When CycloneDX released their SBOM format, version 1.3 we decided to use this format for all future use cases.

New SBOM Format (CycloneDX based)

Please see CycloneDX and especially CycloneDX SBOM specification for the original CycloneDX SBOM format. In this document we will only explain our enhancements and which properties are mandatory for our processing.

CaPyCLI supports CycloneDX only in JSON format.

CycloneDX SBOM Properties used by CaPyCLI

Key Description
bomFormat expected value is CycloneDX
specVersion expected value is 1.x
metadata/tools tool that created the SBOM
component/name name of the component
component/group (optional) group name
component/version component version
component/purl package-url
component/publisher (NOT YET EVALUATED)
component/description (NOT YET EVALUATED)
component/externalReferences/website component website
component/externalReferences/vcs source code / vcs URL
component/externalReferences/distribution (optional for source code url)
component/externalReferences/hashes (optional for src code SHA-1)

CaPyCLI CycloneDX SBOM Enhancements

CycloneDX SBOM format version 1.3 and later allow a custom key-value store. That is what we use for our CaPyCLI specific properties. We use either the official siemens namespace or the capycli namespace.

Key Description
siemens:sw360Id SW360 ID (of a release)
siemens:componentId id of a component, part of mapping
siemens:primaryLanguage programming language
siemens:filename name of a (source) file
siemens:profile profile/type of the SBOM
capycli:sourceFileType SW360 attachment type
capycli:sourceFileComment upload comment for SW360 attachment
capycli:mapResult mapping result

Example:

{
      "type": "library",
      "name": "joda-time",
      "version": "2.10.5",
      "scope": "required",
      "purl": "pkg:pkg:maven/joda-time/[email protected]",
      "externalReferences": [
        {
          "url": "https://github.com/JodaOrg/joda-time",
          "type": "website"
        },
        {
          "url": "https://github.com/JodaOrg/joda-time/archive/refs/tags/v2.10.5.zip",
          "type": "distribution",
          "comment": "source archive (download location)""
        }
      ],
      "properties": [
        {
          "name": "siemens:primaryLanguage",
          "value": "Java"
        },
        {
          "name": "ssiemens:sw360Id ",
          "value": "f9159fde78553c2ba192b7fa8e8c2033"
        }
      ]
    }

Open Issues

  • There is no clear definition on how the property group is used. Assume the package-url is pkg:npm/%40simpl/[email protected]. Is then group = @simpl and name = sishell-icons? Or is group = @simpl and name = @simpl/sishell-icons? We found evidence for both variants.
  • Is there a Python library to parse CycloneDX SBOMs? On GitHub we were not able to find code for that...

Original CaPyCLI SBOM Format (deprecated)

The format of the JSON SBOM file is a list of component objects. Each component object contains the fields

  • Name - name of the component (mandatory)
  • Version - version of the component (mandatory)
  • Language - programming language. Needed for example for the component tar to determine whether the C/C++, Java or JavaScript version is meant.
  • SourceUrl - informal URL of source download page
  • SourceFile - name of the source file
  • SourceFileUrl - URL directly pointing to source file
  • SourceFileHash - hash of the source file
  • SourceFileType - SW360 attachment type ("SOURCE" (default) or "SOURCE_SELF" (for self-made sources))
  • SourceFileComment - upload comment for SW360 attachment
  • BinaryFile - name of the binary file
  • BinaryFileUrl - URL of the binary file
  • BinaryFileHash - hash of the binary file
  • ProjectSite - project/component/community web site
  • RepositoryType - repository type (nuget, npm, maven, package-url)
  • RepositoryId - repository id (within the specified repository)
  • Sw360Id - if already known. Will be filled in when the release has been found on SW360

The more (meta) information is available, the better are the chances to find the component on SW360. We can search on SW360 directly for attachments (files) with a specific hash and we can also search for a repository id.

Some of the data is also required when a new component or release needs to be created on SW360:

Mandatory information for components

  • name
  • type (OSS or COTS)

Mandatory information for releases

  • name (of the component)
  • version
  • programming language
  • source code download URL
  • source code file
  • vendor

SBOM Example

Minimum information

[
  {
    "Name": "Tethys.Framework",
    "Version": "4.4.0",
    "Language": "C#",
    "SourceFileUrl": "https://github.com/tngraf/Tethys.Framework/archive/v99.4.0.zip",
    "SourceFile": "Tethys.Framework-4.4.0.zip",
  },
  { ... }
]

Full information

[
  {
    "Name": "Tethys.Framework",
    "Version": "4.4.0",
    "Language": "C#",
    "SourceUrl": "https://github.com/tngraf/Tethys.Framework/releases/tag/v4.4.0",
    "SourceFileUrl": "https://github.com/tngraf/Tethys.Framework/archive/v99.4.0.zip",
    "SourceFile": "Tethys.Framework.4.4.0.zip",
    "SourceFileHash": "08150815081508150815081508150815",
    "SourceFileType": "SOURCE",
    "SourceFileComment": "source archive verified by Development",
    "BinaryFile": "tethys.framework.4.4.0.nupkg",
    "BinaryFileHash": "7580CCDDA1E2DB1766E7627FCA508394A06A3DAF",
    "ProjectSite": "https://github.com/tngraf/Tethys.Framework",
    "RepositoryType": "nuget-id",
    "RepositoryId": "Tethys.Framework.4.4.0",
    "Sw360Id": "44ce6d4c8b1b84baa450f29e53001702"
  },
  { ... }
]

Filter Example

Minimum Information

{
  Components": [
    {
      "component": {
        "Name": "black"
      },
      "Mode": "remove"
    },
    {
      "component": {
        "Name": "sw360"
      },
      "Mode": "add"
    }
  ]
}