SPDX Tool

Dotnet tool for manipulating SPDX SBOM files

Installation

The following will add SpdxTool to a Dotnet tool manifest file:

dotnet new tool-manifest # if you are setting up this repo
dotnet tool install --local DemaConsulting.SpdxTool

The tool can then be executed by:

dotnet spdx-tool <arguments>

Usage

The following shows the command-line usage of SpdxTool:

Usage: spdx-tool [options] <command> [arguments]

Options:
  -h, --help                               Show this help message and exit
  -v, --version                            Show version information and exit
  -l, --log <log-file>                     Log output to file
  -s, --silent                             Silence console output
      --validate                           Perform self-validation
  -r, --result <file>                      Self-validation result file (.trx TRX or .xml JUnit XML)

Commands:
  help <command>                           Display extended help about a command
  add-package                              Add package to SPDX document (workflow only).
  add-relationship <spdx.json> <args>      Add relationship between elements.
  copy-package <spdx.json> <args>          Copy package between SPDX documents (workflow only).
  diagram <spdx.json> <mermaid.txt> [tools] Generate mermaid diagram.
  find-package <spdx.json> <criteria>      Find package ID in SPDX document
  get-version <spdx.json> <criteria>       Get the version of an SPDX package.
  hash <operation> <algorithm> <file>      Generate or verify hashes of files
  print <text>                             Print text to the console
  query <pattern> <program> [args]         Query program output for value
  rename-id <arguments>                    Rename an element ID in an SPDX document.
  run-workflow <workflow.yaml>             Runs the workflow file/url
  set-variable                             Set workflow variable (workflow only).
  to-markdown <spdx.json> <out.md> [args]  Create Markdown summary for SPDX document
  update-package                           Update package in SPDX document (workflow only).
  validate <spdx.json> [ntia]              Validate SPDX document for issues

A more detailed description of the usage can be found in the command-line documentation

Workflow YAML Files

The SpdxTool can be driven using workflow yaml files of the following format:

# Workflow parameters
parameters:
  parameter-name: value

# Workflow steps
steps:
- command: <command-name>
  inputs:
    <arguments mapping>

- command: <command-name>
  inputs:
    input1: value
    input2: ${{ parameter-name }}

A more detailed description of workflow YAML files can be found in the workflow documentation

Self Validation

Running self-validation produces a report containing the following information:

# DemaConsulting.SpdxTool

| Information         | Value                                              |
| :------------------ | :------------------------------------------------- |
| SpdxTool Version    | <version>                                          |
| Machine Name        | <machine-name>                                     |
| OS Version          | <os-version>                                       |
| DotNet Runtime      | <dotnet-runtime-version>                           |
| Time Stamp          | <timestamp>                                        |

✓ SpdxTool_AddPackage - Passed
✓ SpdxTool_AddRelationship - Passed
✓ SpdxTool_Validate - Passed
✓ SpdxTool_CopyPackage - Passed
✓ SpdxTool_Diagram - Passed
✓ SpdxTool_FindPackage - Passed
✓ SpdxTool_GetVersion - Passed
✓ SpdxTool_Hash - Passed
✓ SpdxTool_Ntia - Passed
✓ SpdxTool_Query - Passed
✓ SpdxTool_RenameId - Passed
✓ SpdxTool_RunNuGetWorkflow - Passed
✓ SpdxTool_ToMarkdown - Passed
✓ SpdxTool_UpdatePackage - Passed

Total Tests: 14
Passed: 14
Failed: 0

Validation Passed

Each test in the report proves a specific command works correctly:

• SpdxTool_AddPackage - add-package command adds a package with relationships to an SPDX file.
• SpdxTool_AddRelationship - add-relationship command adds a relationship between SPDX elements.
• SpdxTool_Validate - validate command accepts valid and rejects invalid SPDX files.
• SpdxTool_CopyPackage - copy-package command copies a package with relationships between SPDX files.
• SpdxTool_Diagram - diagram command generates a Mermaid diagram from an SPDX file.
• SpdxTool_FindPackage - find-package command locates a package by name in an SPDX file.
• SpdxTool_GetVersion - get-version command retrieves a package version from an SPDX file.
• SpdxTool_Hash - hash command generates and verifies file hashes.
• SpdxTool_Ntia - validate command enforces NTIA minimum SBOM element requirements.
• SpdxTool_Query - query command extracts values from program output.
• SpdxTool_RenameId - rename-id command renames an element identifier throughout an SPDX file.
• SpdxTool_RunNuGetWorkflow - run-workflow command executes a workflow from a NuGet package.
• SpdxTool_ToMarkdown - to-markdown command generates a Markdown summary from an SPDX file.
• SpdxTool_UpdatePackage - update-package command updates all fields of a package in an SPDX file.

For detailed descriptions of each validation test, see the User Guide.

On validation failure the tool will exit with a non-zero exit code.

This report may be useful in regulated industries requiring evidence of tool validation.

Contributing

We welcome contributions! Please see our Contributing Guide for details on:

• Setting up your development environment
• Coding standards and conventions
• Running tests and quality checks
• Submitting pull requests

Before contributing, please read our Code of Conduct.

Project Quality

This project maintains high code quality standards:

• ✓ Comprehensive unit test coverage
• ✓ Static code analysis with multiple analyzers
• ✓ Continuous integration with SonarCloud
• ✓ Self-validation system for tool correctness
• ✓ Warnings treated as errors
• ✓ EditorConfig for consistent code style
• ✓ Continuous Compliance: Compliance evidence generated automatically on every CI run, following the Continuous Compliance methodology

License

Copyright (c) DEMA Consulting. Licensed under the MIT License. See LICENSE for details.

By contributing to this project, you agree that your contributions will be licensed under the MIT License.

Additional Information

Additional information can be found at:

• Architecture Documentation
• MSBuild Integration
• SPDX Site
• GitHub CI
• Using with Microsoft SBOM Tool