sbomdebt 0.1.0
Determine technical debt for a SBOM
License: Apache-2.0
Requires Python: >=3.8
Keywords: security, tools, SBOM, DevSecOps, SPDX, CycloneDX, technical-debt

# SBOMDEBT

SBOMDEBT reports on the technical debt of the contents of an SBOM (Software Bill of Materials) by performing a number of checks. SBOMs are supported in a number of formats including
[SPDX](https://www.spdx.org) and [CycloneDX](https://www.cyclonedx.org).

## Installation

To install use the following command:

`pip install sbomdebt`

Alternatively, just clone the repo and install dependencies using the following command:

`pip install -U -r requirements.txt`

The tool requires Python 3 (3.8+). It is recommended to use a virtual python environment especially
if you are using different versions of python. `virtualenv` is a tool for setting up virtual python environments which
allows you to have all the dependencies for the tool set up in a single environment, or have different environments set
up for testing using different versions of Python.

## Usage

```
usage: sbomdebt [-h] [-i INPUT_FILE] [--updates UPDATES] [--verbose] [--debug] [-o OUTPUT_FILE] [-V]

SBOMDebt reports on the technical debt of a SBOM.

options:
  -h, --help            show this help message and exit
  -V, --version         show program's version number and exit

Input:
  -i INPUT_FILE, --input-file INPUT_FILE
                        name of SBOM file
  --updates UPDATES     minimum number of updated versions to report (default: 2)
  --verbose             verbose reporting

Output:
  --debug               add debug information
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        output filename (default: output to stdout)

```
					
## Operation

The `--input-file` option is used to specify the SBOM to be processed. The format of the SBOM is determined according to
the following filename conventions.

| SBOM      | Format   | Filename extension |
| --------- |----------|--------------------|
| SPDX      | TagValue | .spdx              |
| SPDX      | JSON     | .spdx.json         |
| SPDX      | YAML     | .spdx.yaml         |
| SPDX      | YAML     | .spdx.yml          |
| CycloneDX | JSON     | .json              |
| CycloneDX | XML      | .xml               |


The `--updates` option can be used to report packages with outstanding updates. The default value is 2 updates.

The `--verbose` option can be used to report the results of all the checks performed; the default is just report failed checks and summaries.

The `--output-file` option is used to control the destination of the output generated by the tool. The
default is to report to the console but can be stored in a file (specified using `--output-file` option).

### Package update checks

The checks for packages with outstanding updates are performed for packages within the following language ecosystems:

- dart
- go
- java
- javascript
- .net
- perl
- python
- r
- ruby
- rust
- swift

## Output File Format

The output file is in JSON format. The content depends on the contents of the SBOM and the specified command line options.

```bash
sbomdebt --input-file click.json --output-file click_analysis.json
```

```json
{
  "sbom": "<....>",
  "packages": [
    {
      "name": "click",
      "current_version": "8.0.3",
      "latest_version": "8.1.7",
      "latest_date": "2023-08-17T17:29:10.000Z",
      "updates": 9
    }
  ],
  "package_count": 1,
  "debt_count": 1,
  "ratio": 1.0
}
```

```bash
sbomdebt --input-file click.json --verbose --output-file click_analysis.json
```

The addition of the `--verbose` option, results in the JSON file containing details of the available updates.

```json
{
  "sbom": "/root/Documents/git_repo/sbom_workbench/datastore/sbom/click.spdx",
  "packages": [
    {
      "name": "click",
      "current_version": "8.0.3",
      "latest_version": "8.1.7",
      "latest_date": "2023-08-17T17:29:10.000Z",
      "updates": 9,
      "package_updates": [
        [
          "8.1.7",
          "2023-08-17T17:25:18.000Z"
        ],
        [
          "8.1.6",
          "2023-07-18T20:00:26.000Z"
        ],
        [
          "8.1.5",
          "2023-07-13T15:00:38.000Z"
        ],
        [
          "8.1.4",
          "2023-07-06T18:22:05.000Z"
        ],
        [
          "8.1.3",
          "2022-04-28T17:36:21.000Z"
        ],
        [
          "8.1.2",
          "2022-03-31T20:50:27.000Z"
        ],
        [
          "8.1.1",
          "2022-03-30T20:13:29.000Z"
        ],
        [
          "8.1.0",
          "2022-03-28T17:38:54.000Z"
        ],
        [
          "8.0.4",
          "2022-02-18T20:30:45.000Z"
        ]
      ]
    }
  ],
  "package_count": 1,
  "debt_count": 1,
  "ratio": 1.0
}
```

## Return Values

The following values are returned:

- -1 indicates SBOM file not specified
- 0 indicates debt has been calculated

## License

Licensed under the Apache 2.0 License.

## Limitations

The tool has the following limitations:

- The latest version checks are only performed in an environment where access to external systems is available.

- The latest version checks are only performed for components with a valid PURL

- Invalid SBOMs will result in unpredictable results.

## Feedback and Contributions

Bugs and feature requests can be made via GitHub Issues.