Metadata-Version: 2.4
Name: sbomscan
Version: 0.1.0
Summary: Software Bill of Material (SBOM) vulnerability scanner
Home-page: https://github.com/anthonyharrison/sbomscan
Author: Anthony Harrison
Author-email: anthony.p.harrison@gmail.com
Maintainer: Anthony Harrison
Maintainer-email: anthony.p.harrison@gmail.com
License: Apache-2.0
Keywords: security,tools,SBOM,DevSecOps,SPDX,CycloneDX,vulnerability,scanner
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Natural Language :: English
Classifier: Operating System :: OS Independent
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Programming Language :: Python :: 3.13
Classifier: Programming Language :: Python :: 3.14
Classifier: Programming Language :: Python :: Implementation :: CPython
Classifier: Programming Language :: Python :: Implementation :: PyPy
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
Requires-Dist: lib4sbom>=0.10.4
Requires-Dist: requests
Requires-Dist: sbom2doc
Requires-Dist: tldextract
Dynamic: author
Dynamic: author-email
Dynamic: classifier
Dynamic: description
Dynamic: description-content-type
Dynamic: home-page
Dynamic: keywords
Dynamic: license
Dynamic: license-file
Dynamic: maintainer
Dynamic: maintainer-email
Dynamic: requires-dist
Dynamic: requires-python
Dynamic: summary

# SBOMSCAN

The SBOMSCAN is a free, open source tool to scan a SBOM (Software Bill of Materials) in either [SPDX](https://www.spdx.org) and [CycloneDX](https://www.cyclonedx.org) format for reported vulnerabilities. It identifies vulnerabilities with any compoonent in the SBOM which has a valid PURL identifier.

The application uses the (Vulnerablecode database)[https://public.vulnerablecode.io/].

## Installation

To install use the following command:

`pip install sbomscan`

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

`pip install -U -r requirements.txt`

The tool requires Python 3 (3.10+). 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

```bash
usage: sbomscan [-h] [-i INPUT_FILE] [--url URL] [-d] [--format {text,json,markdown}] [-o OUTPUT_FILE] [-V]

SBOMscan scans a Software Bill of Materials for vulnerabilities

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
                        filename of SBOM
  --url URL             endpoint for vulnerability database

Output:
  -d, --debug           add debug information
  --format {text,json,markdown}
                        specify format of vulnerability report (default: text)
  -o OUTPUT_FILE, --output-file OUTPUT_FILE
                        output filename (default: output to stdout)
```

## Operation

The `--input-file` option is used to identify the SBOM to be scanned for vulnerabilities. Both SPDX and CycloneDX SBOMs are supported.

The `--url` option is used to identify the endppoint of the vulnerability database. If this option is not specified, a public instance of the database is used. This requires an API key which can be obtained from [here](https://public.vulnerablecode.io/account/request_api_key/). The API key must be stored in a environment variable called VULNCODE.

The `--format` option is used to specify the format of the output. Currently JSON and Markdown are supported.

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) if the `--format` option is used.

## Example output

```bash
╭───────────────────╮
│ SBOM Scan Summary │
╰───────────────────╯
┏━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┓
┃ Item               ┃ Details                                                                ┃
┡━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┩
│ Scan Date          │ 2026-05-29T19:20:35Z                                                   │
│ SBOM File          │ xxxxxxxxx                                                              │
│ SBOM Type          │ cyclonedx                                                              │
│ Number of Packages │ 1532                                                                   │
│ Number of PURLs    │ 1529                                                                   │
└────────────────────┴────────────────────────────────────────────────────────────────────────┘
╭─────────────────╮
│ Vulnerabilities │
╰─────────────────╯
┏━━━━━━━━━━━━━━━━━━┳━━━━━━━━━┳━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━┳━━━━━━━━┳━━━━━━━━━━━━┳━━━━━━━━━━┳━━━━━━━━━━━━━━━━━━┳━━━━━━━━━━━━━━━━━┓
┃ Package          ┃ Version ┃ Vulnerability                            ┃ Source ┃ CVSS Score ┃ Severity ┃ EPSS Probability ┃ EPSS Percentile ┃
┡━━━━━━━━━━━━━━━━━━╇━━━━━━━━━╇━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━╇━━━━━━━━╇━━━━━━━━━━━━╇━━━━━━━━━━╇━━━━━━━━━━━━━━━━━━╇━━━━━━━━━━━━━━━━━┩
│ ansi-regex       │ 4.1.1   │ CVE-2021-3807                            │ NVD    │ 7.5 (v3.1) │ HIGH     │ 0.00397          │ 0.74348         │
│ axios            │ 1.11.0  │ GHSA-43fc-jf86-j433                      │ GITHUB │ 7.5 (v3.1) │ HIGH     │ 0.00067          │ 0.20669         │
│ fast-xml-parser  │ 4.4.1   │ CVE-2026-27942                           │ NVD    │ 2.7 (v4)   │ LOW      │ 0.00056          │ 0.17594         │
└──────────────────┴─────────┴──────────────────────────────────────────┴────────┴────────────┴──────────┴──────────────────┴─────────────────┘
```

## Example JSON format

The following is an extract for

```json
{
  "sbom_scan_summary": [
    {
      "item": "Scan Date",
      "details": "2026-05-29T18:32:55Z"
    },
    {
      "item": "SBOM File",
      "details": "xxxxxx"
    },
    {
      "item": "SBOM Type",
      "details": "cyclonedx"
    },
    {
      "item": "Number of Packages",
      "details": "1532"
    },
    {
      "item": "Number of PURLs",
      "details": "1529"
    }
  ],
  "vulnerabilities": [
    {
      "package": "ansi-regex",
      "version": "4.1.1",
      "vulnerability": "CVE-2021-3807",
      "source": "NVD",
      "cvss_score": "7.5 (v3.1)",
      "severity": "HIGH",
      "epss_probability": "0.00397",
      "epss_percentile": "0.74348"
    },
    {
      "package": "axios",
      "version": "1.11.0",
      "vulnerability": "GHSA-43fc-jf86-j433",
      "source": "GITHUB",
      "cvss_score": "7.5 (v3.1)",
      "severity": "HIGH",
      "epss_probability": "0.00067",
      "epss_percentile": "0.20669"
    },
    {
      "package": "fast-xml-parser",
      "version": "4.4.1",
      "vulnerability": "CVE-2026-27942",
      "source": "NVD",
      "cvss_score": "2.7 (v4)",
      "severity": "LOW",
      "epss_probability": "0.00056",
      "epss_percentile": "0.17594"
    },
    ....
```

## Example Markdown format


Item | Details
| -------- | --------
Scan Date | 2026-05-29T18:42:28Z
SBOM File | xxxx
SBOM Type | cyclonedx
Number of Packages | 1532
Number of PURLs | 1529

# Vulnerabilities

Package | Version | Vulnerability | Source | CVSS Score | Severity | EPSS Probability | EPSS Percentile
| -------- | -------- | -------- | -------- | -------- | -------- | -------- | --------
ansi-regex | 4.1.1 | CVE-2021-3807 | NVD | 7.5 (v3.1) | HIGH | 0.00397 | 0.74348
axios | 1.11.0 | GHSA-43fc-jf86-j433 | GITHUB | 7.5 (v3.1) | HIGH | 0.00067 | 0.20669
fast-xml-parser | 4.4.1 | CVE-2026-27942 | NVD | 2.7 (v4) | LOW | 0.00056 | 0.17594


## Licence

Licenced under the Apache 2.0 Licence.

## Limitations

This tool only processes components in the SBOM with a valid PURL identifier.

Network access is required to access the vulnerability database. If this is not available, a limited amount of package metadata will be included.

## Feedback and Contributions

Bugs and feature requests can be made via GitHub Issues.
