Workflow Integration

Once the BOMnipotent Server is up and running, you can begin uploading documents. A typical workflow begins with generating an SBOM, an inventory of what components your product contains. This step should be automatically triggered upon creating a new release. Then this inventory is scanned for known vulnerabilities. This should also be an automatic step, but it should be triggered periodically. If a vulnerability is discovered, it is time to analyse it. This task needs expertise, and thus cannot be done automatically. The result of this analysis is a CSAF document, which tells your users if and how they have to react to this new development.

This section contains instructions for an exemplary workflow for generating an SBOM using Syft , scanning it for vulnerabilities with Grype , and creating CSAF documents with secvisogram . Other programs exists for these tasks, and as long as they produce valid CycloneDX and CSAF json documents, they are compatible with BOMnipotent.

Subsections of Workflow Integration

SBOM Generation with Syft

A Software Bill of Material (SBOM) is a list of all software components used in your product. In the contex of supply chain security, it serves as a machine-readable list of items to compare to whenever a new vulnerability surfaces.

Several tools exist to automatically generate such an SBOM. This tutorial focuses on Anchore’s Syft, an open source command line tool.

Setup

The official Syft GitHub repo contains installation instructions. It is available via a shell script or via various package managers.

On some linux systems you may want to change the install path (the very last argument to the shell command) to “~/.local/bin”, because “/usr/local/bin” requires root permissions to modify.

Usage

The basic usage of Syft is:

syft <target> [options]

Additionally, some configuration can be made using environment variables.

Syft supports lockfiles, directories, container images and more as targets.

Lockfile

An example call looks like this:

​
SYFT_FORMAT_PRETTY=1 syft Cargo.lock --output cyclonedx-json=./sbom.cdx.json --source-name="BOMnipotent" --source-version="1.0.0"
SYFT_FORMAT_PRETTY=1 syft Cargo.lock -o cyclonedx-json=./sbom.cdx.json --source-name="BOMnipotent" --source-version="1.0.0"
Breakdown:

  • ‘SYFT_FORMAT_PRETTY=1’ is makes this call with an environment variable that tells Syft to use prettified output. This only serves to make the resulting json easier readable for humans. See here for a full list of configurations.
  • ‘syft’ cals the Syft program.
  • ‘Cargo.lock’ tells Syft to analyse the lockfile of the Rust ecosystem.
  • ‘–output cyclonedx-json=./sbom.cdx.json’ specifies that the output is to be stored in the CycloneDx JSON format in the file ‘./sbom.cdx.json’.
  • ‘–source-name=“BOMnipotent”’ explains to Syft that these are the sources for the BOMnipotent component, which it may not automatically detect in all cases.
    • The CycloneDX schema may not require a component name, but BOMnipotent does.
  • Likewise ‘–source-version=“1.0.0”’ tells Syft the current version of your project.
    • If you do not provide a version, BOMnipotent will try to use the timestamp as a version string instead.

Syft supports a wide range of ecosystems, which is listed on their GitHub repo .

Directory

Letting Syft loose on a whole directory is possible, but overdoes it in most situations. It will go through all subdirectories and collect everything that looks remotely like a lockfile, including all your test dependencies, development scripts and GitHub Actions.

​
syft . --output cyclonedx-json=./dev_env_sbom.cdx.json --source-name="BOMnipotent Development Environment" --source-version=1.2.3
syft . -o cyclonedx-json=./dev_env_sbom.cdx.json --source-name="BOMnipotent Development Environment" --source-version=1.2.3

Container

If you have a docker container exported as a ‘.tar’ file you can also specify that as a target:

​
syft container.tar --output cyclonedx-json=./container_sbom.cdx.json --source-name="BOMnipotent Container" --source-version=1.2.3
syft container.tar -o cyclonedx-json=./container_sbom.cdx.json --source-name="BOMnipotent Container" --source-version=1.2.3

For compiled languages the results will be vastly different, because most information about the components that went into compilation is lost. On the other hand, this SBOM contains information about the environment that your product may later run in.

Final remarks

When deciding on a target, it is important to think about the scope of your application: What do you ship to the customer? Up to which extend are you responsible for the supply chain of your product? If in doubt, there’s no harm in uploading more than one variant of a BOM, as long as product name or version are different.

Once your SBOM is generated, you can use BOMnipotent Client to upload it to BOMnipotent Server .

After that you can use Grype to periodically scan for vulnerabilities .

Vulnerability Detection with Grype

Once your SBOM is generated, it is time to continuously scan it for vulnerabilities. Note that some laws, for example the EU’s Cyber Resiliance Act, require that products are released without any known vulnerability. The first scan should therefore happen before a release.

There are several tools for scanning a product for supply chain vulnerabilities. This tutorial uses Anchore’s Grype, because it integrates well with Anchore’s Syft from the SBOM tutorial . Like Syft, Grype is an open source command line utility.

Setup

The official Grype GitHub repo contains installation instructions. Like for Syft, you may want to change the install path (the very last argument to the shell command) to ‘~/.local/bin’, because ‘/usr/local/bin’ requires root permissions to modify.

Usage

With an SBOM at hand, scanning for vulnerabilities is very easy:

​
grype sbom:./sbom.cdx.json --fail-on low
grype sbom:./sbom.cdx.json -f low
​
 ✔ Scanned for vulnerabilities     [2 vulnerability matches]  
   ├── by severity: 0 critical, 0 high, 2 medium, 0 low, 0 negligible
   └── by status:   2 fixed, 0 not-fixed, 0 ignored 
NAME    INSTALLED  FIXED-IN  TYPE        VULNERABILITY        SEVERITY 
ring    0.17.8     0.17.12   rust-crate  GHSA-4p46-pwfr-66x6  Medium    
rustls  0.23.15    0.23.18   rust-crate  GHSA-qg5g-gv98-5ffh  Medium
[0000] ERROR discovered vulnerabilities at or above the severity threshold

When running this command, Grype checks several vulnerability databases for matches with the components provided in the sbom. The ‘fail-on’ option specifies that it exits with a non-zero error code if any with severity ’low’ or higher is discovered.

The syntax to export a vulnerability report consumable by BOMnipotent is similar to Syft:

​
grype sbom:./sbom.cdx.json --output cyclonedx-json=./vuln.cdx.json
grype sbom:./sbom.cdx.json -o cyclonedx-json=./vuln.cdx.json

Grype integrates well with BOMnipotent. You can use the “bom get” command of BOMnipotent Client to directly print the contents of a BOM to the console output, and then pipe it to grype:

​
bomnipotent_client bom get <BOM-NAME> <BOM-VERSION> | grype --output cyclonedx-json=./vuln.cdx.json
bomnipotent_client bom get <BOM-NAME> <BOM-VERSION> | grype -o cyclonedx-json=./vuln.cdx.json