Microsoft SBOM Tool

The files section is generated by traversing all directories and files located at the BuildDropPath provided to the tool. For every file found, the tool generates an SPDXID, a SHA1 hash, and a SHA256 hash. This section provides a granular inventory of the actual files present in the build drop.

"files": [
    {
      "fileName": "./sbom-tool-win-x64.exe",
      "SPDXID": "SPDXRef-File--sbom-tool-win-x64.exe-E55F25E239D8D3572D75D5CDC5CA24899FD4993F",
      "checksums": [
        {
          "algorithm": "SHA256",
          "checksumValue": "56624d8ab67ac0e323bcac0ae1ec0656f1721c6bb60640ecf9b30e861062aad5"
        },
        {
          "algorithm": "SHA1",
          "checksumValue": "e55f25e239d8d3572d75d5cdc5ca24899fd4993f"
        }
      ],
      "licenseConcluded": "NOASSERTION",
      "licenseInfoInFiles": [
        "NOASSERTION"
      ],
      "copyrightText": "NOASSERTION"
    }
  ]

If the sbom-tool detects an existing SPDX 2.2 SBOM within the project being scanned, it performs two actions:

1. It includes that SBOM file in the files section (often marked with "fileTypes": ["SPDX"]).
2. It adds an entry to the externalDocumentRefs section to link the current SBOM to the detected external document.

 "files": [
    {
      "fileName": "./manifest.spdx.json",
      "SPDXID": "SPDXRef-File--manifest.spdx.json-9E563530C733C814FC04FF5C61D8DC9FB4FD29CB",
      "checksums": [
        {
          "algorithm": "SHA256",
          "checksumValue": "63789f7d621728cb197dcc5655d7b18ab35f825b596496e633b61291cfa00f4b"
        },
        {
          "algorithm": "SHA1",
          "checksumValue": "9e563530c733c814fc04ff5c61d8dc9fb4fd29cb"
        }
      ],
      "licenseConcluded": "NOASSERTION",
      "licenseInfoInFiles": [
        "NOASSERTION"
      ],
      "copyrightText": "NOASSERTION",
      "fileTypes": [
        "SPDX"
      ]
    },
 ]

"externalDocumentRefs": [
    {
      "externalDocumentId": "DocumentRef-TEST.GIT-bd801c3b7553a08b6874d6bc129203c5a8a95a04-f3bca9cb-67f5-1320-d17e-188a244fc472-1.0-9e563530c733c814fc04ff5c61d8dc9fb4fd29cb",
      "spdxDocument": "https://sbom.microsoft/TEST.GIT/bd801c3b7553a08b6874d6bc129203c5a8a95a04/f3bca9cb-67f5-1320-d17e-188a244fc472/1.0/fa0d13e3-0136-4cc8-af85-622c04063a0f",
      "checksum": {
        "algorithm": "SHA1",
        "checksumValue": "9e563530c733c814fc04ff5c61d8dc9fb4fd29cb"
      }
    }
  ]

The packages section identifies software components used in the project by scanning the BuildComponentPath using component detection libraries.

To enable populating advanced license and package information via the ClearlyDefinedApi or custom implementations, you must set both the -pm and -li arguments to true when running the tool.

Supported ecosystems include:

• Cargo: via *.cargo-sbom.json, Cargo.toml, or Cargo.lock.
• Ruby: via gemfile.lock.
• Pip (Python): via setup.py, requirements.txt, or dist package METADATA. Requires Python 2/3 and internet connection.
• Maven: via pom.xml. Requires Maven.
• NPM: via package.json.
• NuGet: via project.assets.json, *.nupkg, *.nuspec, packages.config, or nuget.config.
• Linux (Debian, Alpine, Rhel, etc.): via syft.
• CocoaPods: via podfile.lock.
• Conda (Python): via conda-lock.yml or *.conda-lock.yml.
• Gradle: via *.lockfile. Requires Gradle 7 or prior.
• Go: via go list -m -json all or go mod graph. Fallback to go.mod/go.sum. Requires Go 1.11+.
• Yarn (v1, v2): via package.json and yarn.lock.
• Pnpm: via shrinkwrap.yaml or pnpm-lock.yaml.
• Poetry (Python): via poetry.lock.

"packages": [
    {
      "name": "Microsoft.VisualStudio.Threading.Analyzers",
      "SPDXID": "SPDXRef-Package-CCB741BD164B5B2F9771AD784B281D62BDB0E0707EE703E76AF22BFFB4503941",
      "downloadLocation": "NOASSERTION",
      "filesAnalyzed": false,
      "licenseConcluded": "MIT",
      "licenseDeclared": "MIT",
      "copyrightText": "NOASSERTION",
      "versionInfo": "17.7.30",
      "externalRefs": [
        {
          "referenceCategory": "PACKAGE-MANAGER",
          "referenceType": "purl",
          "referenceLocator": "pkg:nuget/Microsoft.VisualStudio.Threading.Analyzers@17.7.30"
        }
      ],
      "supplier": "Organization: Microsoft"
    }
]

To integrate the SBOM tool into a GitHub Actions workflow, you must download the tool executable, make it executable, and then run the generate command targeting your build output directory.

In a typical workflow, the SBOM generation step should occur after the build step but before the artifact upload step. This ensures the generated SBOM file is included in the uploaded build artifacts.

Key parameters for the generate command used in this integration:

• -b <path>: The build drop folder (the directory containing the binaries you want to scan).
• -bc <path>: The build components path (the directory containing project files like .csproj that hold dependency information).
• -pn <name>: Package name.
• -pv <version>: Package version.
• -ps <publisher>: Package publisher.
• -nsb <uri>: Namespace base URI.
• -V <verbosity>: Verbosity level (e.g., Verbose).

    - name: Generate SBOM
      run: |
        curl -Lo $RUNNER_TEMP/sbom-tool https://github.com/microsoft/sbom-tool/releases/latest/download/sbom-tool-linux-x64
        chmod +x $RUNNER_TEMP/sbom-tool
        $RUNNER_TEMP/sbom-tool generate -b ./buildOutput -bc . -pn Test -pv 1.0.0 -ps MyCompany -nsb https://sbom.mycompany.com -V Verbose