This is the multi-page printable view of this section. Click here to print.

Return to the regular view of this page.

Generate SBOM

A software bill of materials (SBOM) is a list of all the components, libraries, and other dependencies that make up a software application, along with information about the versions, licenses, and vulnerabilities associated with each component. They are formal, structured documents detailing the components of a software product and its supply chain relationships.

KubeClarity exposes SBOM generator integration settings via the values.yaml file.

OpenClarity content analyzer integrates with the following SBOM generators:

Trivy has an extensive vulnerability database, which includes CVEs from various sources such as NVD, Red Hat, and Debian. It can detect vulnerabilities in multiple programming languages, including Java, Python, and Ruby.

Syft’s vulnerability database is smaller and primarily focuses on detecting vulnerabilities in Python libraries.

KubeClarity, by default, enables Syft and CycloneDX gomod analyzers. To enable the Trivy scanner, edit the values. yaml file like this:

    analyzer:
      ## Space separated list of analyzers. (syft gomod)
      analyzerList: "syft gomod trivy"
      analyzerScope: "squashed"

      trivy:
        ## Enable trivy scanner, if true make sure to add it to list above  
        enabled: true
        timeout: "300"

SBOM database

KubeClarity automatically deploys an SBOM database pod and caches the generated SBOMs in the SBOM DB. The database is a lightweight SQLite DB that avoids persistent volume storage overheads. It stores and retrieves SBOM documents in a string format and serves as a caching function for rendering SBOM data. The DB does not store or query JSON objects to parse or query the SBOMs. However, it supports a gzip compression and base64 encoded storage to reduce memory footprint.

Here is the corresponding configuration snippet from the values.yaml file:

## KubeClarity SBOM DB Values

kubeclarity-sbom-db:
  ## Docker Image values.
  docker:
    ## Use to overwrite the global docker params
    ##
    imageName: ""

  ## Logging level (debug, info, warning, error, fatal, panic).
  logLevel: warning

  servicePort: 8080

  resources:
    requests:
      memory: "20Mi"
      cpu: "10m"
    limits:
      memory: "100Mi"
      cpu: "100m"

## End of KubeClarity SBOM DB Values

1 - Generate SBOM

To generate the Software Bill of Materials (SBOM), complete the following steps.

  1. Run the following command.

    kubeclarity-cli analyze <image/directory name> --input-type <dir|file|image(default)> -o <output file or stdout>

    For example:

    kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

    Example output:

    INFO[0000] Called syft analyzer on source registry:nginx:latest  analyzer=syft app=kubeclarity
INFO[0004] Skipping analyze unsupported source type: image  analyzer=gomod app=kubeclarity
INFO[0004] Sending successful results                    analyzer=syft app=kubeclarity
INFO[0004] Got result for job "syft"                     app=kubeclarity
INFO[0004] Got result for job "gomod"                    app=kubeclarity
INFO[0004] Skip generating hash in the case of image

  2. Verify that the ngnix.sbom file is generated and explore its contents as in below:

    head ngnix.sbom

    Example output:

    {
  "bomFormat": "CycloneDX",
  "specVersion": "1.4",
  "serialNumber": "urn:uuid:8cca2aa3-1aaa-4e8c-9d44-08e88b1df50d",
  "version": 1,
  "metadata": {
    "timestamp": "2023-05-19T16:27:27-07:00",
    "tools": [
      {
        "vendor": "kubeclarity",

  3. To run also the trivy scanner and merge the output into a single SBOM, run:

    ANALYZER_LIST="syft gomod trivy" kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

    Example output:

    INFO[0000] Called syft analyzer on source registry:nginx:latest  analyzer=syft app=kubeclarity
INFO[0004] Called trivy analyzer on source image nginx:latest  analyzer=trivy app=kubeclarity
INFO[0004] Skipping analyze unsupported source type: image  analyzer=gomod app=kubeclarity
INFO[0005] Sending successful results                    analyzer=syft app=kubeclarity
INFO[0005] Sending successful results                    analyzer=trivy app=kubeclarity
INFO[0005] Got result for job "trivy"                    app=kubeclarity
INFO[0005] Got result for job "syft"                     app=kubeclarity
INFO[0005] Got result for job "gomod"                    app=kubeclarity
INFO[0005] Skip generating hash in the case of image

Export scan results to backend

  1. To export CLI-generated results to the backend, from the left menu bar select Applications, then copy the ID from the KubeClarity UI. If your application is not listed yet, select + New Application, and create a new pod.

    Resource ID on the UI

  2. To export the generated SBOMs to a running KubeClarity backend pod, use the -e flag and the ID as the <application ID> value in the following command.

    BACKEND_HOST=<KubeClarity backend address> BACKEND_DISABLE_TLS=true kubeclarity-cli analyze <image> --application-id <application ID> -e -o <SBOM output file>

    For example:

    BACKEND_HOST=localhost:9999 BACKEND_DISABLE_TLS=true kubeclarity-cli analyze nginx:latest --application-id 23452f9c-6e31-5845-bf53-6566b81a2906 -e -o nginx.sbom

    Example output:

    INFO[0000] Called syft analyzer on source registry:nginx:latest  analyzer=syft app=kubeclarity
INFO[0004] Called trivy analyzer on source image nginx:latest  analyzer=trivy app=kubeclarity
INFO[0004] Skipping analyze unsupported source type: image  analyzer=gomod app=kubeclarity
INFO[0004] Sending successful results                    analyzer=syft app=kubeclarity
INFO[0004] Got result for job "syft"                     app=kubeclarity
INFO[0004] Got result for job "gomod"                    app=kubeclarity
INFO[0004] Sending successful results                    analyzer=trivy app=kubeclarity
INFO[0004] Got result for job "trivy"                    app=kubeclarity
INFO[0004] Skip generating hash in the case of image    
INFO[0004] Exporting analysis results to the backend: localhost:8080  app=kubeclarity

  3. Now you can see the exported results on the UI, on the Dashboard and the Packages pages.

    Exported results

Run multiple generators

You can list the content analyzers to use using the ANALYZER_LIST environment variable separated by a space (ANALYZER_LIST="<analyzer 1 name> <analyzer 2 name>"). For example:

ANALYZER_LIST="syft gomod" kubeclarity-cli analyze --input-type image nginx:latest -o nginx.sbom

OpenClarity content analyzer integrates with the following SBOM generators:

2 - Merging SBOM results

Different SBOM generators support different outputs, and the different vulnerability analyzers support different input SBOM formats. KubeClarity merges the output of multiple SBOM scanners and converts them into the format required by vulnerability scanners.

Multi-SBOM Integration Process

When multiple analyzers identify the same resources, KubeClarity handles them as a union and labels both analyzers as the source. Instead of attempting to merge the raw data produced by each generator, KubeClarity adds additional metadata to the generated SBOMs while keeping the raw data untouched, as reported by the analyzers.

KubeClarity can also merge SBOMs from various stages of a CI/CD pipeline into a single SBOM by layering and merging, for example, application dependency SBOM analysis from application build time can be augmented with the image dependencies analysis during the image build phase. The merged SBOMs serve as inputs to vulnerability scanners after proper formatting.

SBOM Integrations at Various CI/CD Stages

3 - SBOM output format

The kubeclarity-cli analyze command can format the resulting SBOM into different formats to integrate with another system. The supported formats are:

FormatConfiguration Name
CycloneDX JSON (default)cyclonedx-json
CycloneDX XMLcyclonedx-xml
SPDX JSONspdx-json
SPDX Tag Valuespdx-tv
Syft JSONsyft-json

CAUTION:

KubeClarity processes CycloneDX internally, the other formats are supported through a conversion. The conversion process can be lossy due to incompatibilities between formats, therefore in some cases not all fields/information are present in the resulting output.

To configure the kubeclarity-cli to use a format other than the default, the ANALYZER_OUTPUT_FORMAT environment variable can be used with the configuration name from above:

ANALYZER_OUTPUT_FORMAT="spdx-json" kubeclarity-cli analyze nginx:latest -o nginx.sbom