Developer Guide

Download Git sources

The official source code is hosted on GitHub: bootlin/sbom-cve-check

$ git clone https://github.com/bootlin/sbom-cve-check.git

Python virtual environment

The minimum supported version of Python is 3.10, as stated in the user guide.

We suggest creating a Python virtual environment to install the dependencies for development.

• To create a Python virtual environment:

$ python3 -m venv .venv

• Once it is created, you can activate it:

$ source .venv/bin/activate

• pip version 25.1 or later is required to install development tool dependencies, if needed, update it:

(.venv) $ pip install --upgrade pip

Documentation generation

The documentation sources are in docs. To build them using Sphinx, run the following commands:

• First create a Python virtual environment and update pip.

• Install the dependencies to generate this documentation in your Python virtual env:

(.venv) $ cd sbom-cve-check
(.venv) $ pip install --group docs

• You can now build the docs in HTML, from the docs directory:

(.venv) $ cd sbom-cve-check/docs
(.venv) $ make html

• The generated documentation will be available under docs/_build/html/index.html.

The command below, executed from the docs directory, could be used to watch for any file changes under the docs directory and rebuild the documentation automatically:

while sleep 1 ; do make clean; find -name '*.md' | entr -d make html ; done

Tool installation for development

For normal use of the tool, it should be installed as described in the user guide.

As an alternative, only the dependencies could be installed, and we could use the src/sbom-cve-check executable. But for development purposes, it is instead highly recommended to “install” the tool using the --editable flag:

(.venv) $ pip install -e .

For development purposes, to “install” it with all optional dependencies, run:

(.venv) $ pip install -e .[extra]

Linter and static analysis

First create a Python virtual environment, if not already done, and update pip.

Then, to install the tools, run:

(.venv) $ pip install --group lint

It may be necessary to install the various dependencies, for example using:

(.venv) $ pip install -e .[extra]
(.venv) $ pip install --group test

Ruff

This project uses the Ruff linter.

mypy

This project uses mypy for static type checking.

ty

This project also uses ty for static type checking.

pylint

This project does not enforce pylint rules. The use of this static analysis tool is optional. But it is recommended to run the following command to search for new warnings:

pylint -d "C0114,C0115,C0116,C0411,C0302,C0325" -d design src/

Tests

First create a Python virtual environment, if not already done, and update pip.

Then, install the tool with all optional dependencies if this is not already the case. For example run:

(.venv) $ pip install -e .[extra]

Then, to install the test tools, run:

(.venv) $ pip install --group test

To execute the test, run the following command from the tests directory:

pytest -v .

To execute the test with the coverage, run the following command from the tests directory:

pytest -v --run-slow --cov=sbom_cve_check --cov-config=../pyproject.toml .

Then, to generate the HTML report, execute:

coverage html

For test troubleshooting, is it possible to define the SBOM_CVE_CHECK_TEST_KEEP_TMP environment variable to 1. The temporary directories generated during the tests will not be deleted. Note: to use this environment variable, at least Python 3.12 is required.

Release process

To prepare a new release, follow these steps:

• Update the Changelog

  • Add relevant changes to CHANGELOG.md.

  • Remove the (Unreleased) suffix from the latest version entry.

• Update the Version

  • In src/sbom_cve_check/__init__.py, remove the .dev0 suffix from the current version.

• Create a Git Tag

  • Create an annotated Git tag using the format v1.X.Y.

• Push Changes

  • Push both the branch and the tag to the remote repository.

• Run GitHub Actions

  • Ensure the GitHub action is executed (if not already done) and verify that all checks pass.

• Create a GitHub Release

  • Create a GitHub release from the pushed tag.

  • For the release description follow this example.

• Upload to PyPI

  • Generate the distribution archives using:

    python3 -m build
    

  • Upload the archives to PyPI using:

    python3 -m twine upload dist/*
    

  For more details see the documentation.

• Verify Documentation Tagging

  • Ensure the documentation on Read the Docs has been automatically tagged for the created release: The tagged version should appear in the drop-down menu in the left panel.

• Prepare for Next Development Cycle

  • Increment the version in src/sbom_cve_check/__init__.py and append the .dev0 suffix.

  • Add the next version entry to CHANGELOG.md with the (Unreleased) suffix.

Roadmap & planned developments

The following features are intended to be developed in the medium term:

• Add support of Ubuntu CVE tracker repository

  • Automatically detect if a patch was backported

• Add CycloneDX (CDX) SBOM support as input.

• Add more export formats, like, for example, OpenVEX.

The following features are intended to be developed in the very long term:

• Allow to generate an SBOM (CDX or SPDX 3.0) as output even if the SBOM specified as input is in another format.