feat: publish project to PyPI

include:

  # $TBC_NAMESPACE is a group variable; can be globally overridden

  # Docker template

  - component: "$CI_SERVER_FQDN/$TBC_NAMESPACE/docker/gitlab-ci-docker@7"

  - component: "$CI_SERVER_FQDN/$TBC_NAMESPACE/docker/gitlab-ci-docker@8"

    inputs:

      healthcheck-disabled: true

      build-tool: buildah

      package-enabled: true

      publish-enabled: true

  # semantic-release template

  - component: "$CI_SERVER_FQDN/$TBC_NAMESPACE/semantic-release/gitlab-ci-semrel@3"

  - component: "$CI_SERVER_FQDN/$TBC_NAMESPACE/semantic-release/gitlab-ci-semrel@4"

    inputs:

      auto-release-enabled: true

# Dependency Track SBOM Scanner CLI

<img alt="Dependency Track SBOM Scanner logo" width="128px" src="https://gitlab.com/to-be-continuous/tools/dt-sbom-scanner/-/avatar">

[![pypi](https://img.shields.io/pypi/v/dt-sbom-scanner.svg)](https://pypi.org/project/dt-sbom-scanner/)

[![python](https://img.shields.io/pypi/pyversions/dt-sbom-scanner.svg)](https://pypi.org/project/dt-sbom-scanner/)

# Dependency Track SBOM Scanner

This project provides a CLI tool able to publish SBOM files to a [Dependency Track](https://docs.dependencytrack.org/) server.

## Get started

### Run SBOM Scanner CLI as a Python program

### Run SBOM Scanner as a Python program

`sbom-scanner` is a Python program and can be installed as a PyPI package. It requires Python 3.11 or higher and can be installed with the following command:

`dt-sbom-scanner` requires Python 3.12 or higher and can be installed using pip package manager:

```bash

# install from GitLab PyPI packages

pip install sbom-scanner --index-url https://gitlab.com/api/v4/projects/to-be-continuous%2Ftools%2Fdt-sbom-scanner/packages/pypi/simple --upgrade

pip install dt-sbom-scanner

```

Then it can be run as a Python program:

```bash

# obtain help

sbom-scanner --help

### Run SBOM Scanner CLI as a container

`sbom-scanner` can also be run as a container image using Docker or Podman.

`dt-sbom-scanner` can also be run as a container image using Docker or Podman.

```bash

# run from GitLab Container Registry

### Arguments

`sbom-scanner` accepts SBOM file patterns to publish (supports glob patterns) as multiple positional arguments.

`dt-sbom-scanner` accepts SBOM file patterns to publish (supports glob patterns) as multiple positional arguments.

If none is specified, the program will look for SBOM files matching `**/*.cyclonedx.json` and `**/*.cyclonedx.xml`.

## Project Path

Whenever a SBOM file is found, `sbom-scanner` uploads it to the Dependency Track server under a certain project.

Whenever a SBOM file is found, `dt-sbom-scanner` uploads it to the Dependency Track server under a certain project.

The target project is determined by evaluating the `--project-path` CLI option (or `$DEPTRACK_PROJECT_PATH` variable).

The project path is a sequence of elements separated by forward slashes `/` (although the separator is also configurable with the `--path-separator` CLI option).

- `#550e8400-e29b-41d4-a716-446655440000`: every SBOM found will be published to the project with UUID `550e8400-e29b-41d4-a716-446655440000`<br/>

  :information_source: as Dependency Track is only able to store one SBOM per project, this configuration is suitable only if exactly one SBOM file is found (otherwise each one will overwrite the previous one)

- `my-project@v1.1.0`: every SBOM found will be published to the project with name `my-project` and version `v1.1.0`<br/>

  :information_source: depending on your API key permissions, `sbom-scanner` might try to automatically create the project if it doesn't exist<br/>

  :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project if it doesn't exist<br/>

  :information_source: as in the previous example, this configuration is suitable only if exactly one SBOM file is found

- `#550e8400-e29b-41d4-a716-446655440000/my-project-{file_prefix}@{sbom_version}`: every SBOM found will be published to a project named `my-project-{file_prefix}` and version `{sbom_version}` (extracted from the SBOM file),

  direct child of project with UUID `550e8400-e29b-41d4-a716-446655440000`<br/>

  :information_source: depending on your API key permissions, `sbom-scanner` might try to automatically create the project if it doesn't exist

  :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project if it doesn't exist

- `acme-program@v2/acme-services@v1.3/acme-user-api@v1.3/acme-user-api-{file_prefix}`: complete project path only defined by project names and versions<br/>

  :information_source: depending on your API key permissions, `sbom-scanner` might try to automatically create the project and its ancestors if they don't exist

  :information_source: depending on your API key permissions, `dt-sbom-scanner` might try to automatically create the project and its ancestors if they don't exist

> :bulb: you may decide to overwrite the path separator (ex: double slash `//`) if you want your project names to contain slashes.

Since [4.13.0 version](https://docs.dependencytrack.org/changelog/#v4-13-0), Dependency Track supports the concept of [collection project](https://docs.dependencytrack.org/usage/collection-projects/).

A collection project won't be able to host a SBOM, however it will display all vulnerabilities and policy violations of its children.

`sbom-scanner` will set the collection logic with the `--parent-collection-logic` optional argument (default value is `ALL`).

`dt-sbom-scanner` will set the collection logic with the `--parent-collection-logic` optional argument (default value is `ALL`).

| `--parent-collection-logic` value | Dependency Track API value | Explanation |

| -------- | ------------------------------------ | --------------------- |

| `LATEST` | `AGGREGATE_LATEST_VERSION_CHILDREN`  | Parent project will collect metrics from direct children flagged as latest |

| `NONE`   | `NONE`                               | Parent project will behave like a normal project |

:information_source: since `sbom-scanner` does not update existing projects, collection logic will only be configured on the parent project created by `sbom-scanner`

:information_source: since `dt-sbom-scanner` does not update existing projects, collection logic will only be configured on the parent project created by `dt-sbom-scanner`

See [Dependency Track documentation about collection project](https://docs.dependencytrack.org/usage/collection-projects/) for more details.

## Developers

`sbom-scanner` is implemented in Python and relies on [Poetry](https://python-poetry.org/) for its packaging and dependency management.

`dt-sbom-scanner` is implemented in Python and relies on [Poetry](https://python-poetry.org/) for its packaging and dependency management.

```bash

# install dependencies

from cyclonedx.output import OutputFormat, make_outputter

from cyclonedx.schema import SchemaVersion

from sbom_scanner.AnsiColors import AnsiColors

from dt_sbom_scanner.AnsiColors import AnsiColors

def load_bom(file: Path) -> Bom: