SBOM - Software Bill of Materials

Created by Xinxiang Wang, Modified on Fri, 15 Dec, 2023 at 8:24 AM by Xinxiang Wang

vcn can identify, authenticate and notarize dependencies of the software assets.

Supported languages/environments

Language(s)/environment	Component scheme	Source	Package manager
Go	`gocom`	compiled binary
		directory with `go.sum` file
		directory with `*.go` file(s)
Python	`pythoncom`	`Pipfile.lock` file or directory containing this file	pipenv
		`poetry.lock` file or directory containing this file	poetry
		`requirements.txt` file or directory containing this file	pip
JVM (Java, Scala, Kotlin)	`javacom`	JAR file containing `pom.xml`	maven
.Net (C#, F#, Visual Basic)	`dotnetcom`	`*.sln` file or directory containing this file	NuGet
- C#, F# only		`*.csproj` file or directory containing this file
- Visual Basic only		`*.vbproj` file or directory containing this file
JavaScript	`nodecom`	`package-lock.json` file or directory containing this file	npm
Rust	`rustcom`	`Cargo.toml` file or directory containing this file	cargo
PHP	`phpcom`	`composer.lock` file or directory containing this file	composer
Docker image (RPM-based distro)		RPM database (`/var/lib/rpm/Packages`)	rpm
Docker image (Debian-based distro)		DPKG database (`/var/lib/dpkg`)	dpkg
Docker image (Alpine)		APK database (`/lib/apk/db/installed`)	apk

The column "Component scheme" is related to this section.

Working with builds

Resolving dependencies

vcn bom <asset> [bom options] [bom output options]

This command resolves the dependencies for the asset and prints out the list of dependencies.

Following bom options modify the behavior of this command:

Option	Default	Description
`--bom-file`		Name of the file to store dependencies for later processing by notarization process
`--github-token`	unset	If specified, `vcn` uses this OAuth GitHub token for querying extra data for Github packages. If not specified, `vcn` performs anonymous queries. Either authenticated or not, requests are subject to Github limits.

See output options for details about outputting BoM in standard formats.

Examples:

vcn bom immudb/immuclient vcn bom immudb-py --bom-spdx immudb-py.spdx vcn bom immudb-py/requirements.txt --bom-file .bom

Authentication

vcn a --bom <asset> [bom options] [bom output options]

This command resolves the dependencies for the asset, authenticates the dependencies, the asset, and prints out the list of dependencies with their trust levels.

If <asset> is specified as hash using --hash option, BOM gets loaded from the server.

Following bom options modify the behavior of this command:

Option	Default	Description
`--signerID`	current user	Signer ID to use for dependency and asset authentication. This isn't a BoM-specific options, but it has a special meaning for BoM
`--bom-trust-level`	`trusted`	Minimal accepted trust level for the dependencies (or its abbreviation), one of:
		`untrusted` (`unt`)
		`unsupported` (`uns`)
		`unknown` (`unk`)
		`trusted` (`t`)
`--bom-max-unsupported`	`0`	Max number of unsupported/unknown dependencies to accept, in percent. If number of unsupported/unknown dependencies doesn't exceed this threshold, authentication is considered successful
`--bom-deps-only`	`false` (unset)	Authenticate only the dependencies, do not authenticate the BoM source
`--bom-batch-size`	`100`	Send requests to server in batches of specified size
`--bom-what-includes`	`false` (unset)	See Looking up builds by dependency
`--github-token`	unset	If specified, `vcn` uses this OAuth GitHub token for querying extra data for Github packages. If not specified, `vcn` performs anonymous queries. Either authenticated or not, requests are subject to Github limits.
`--bom-diff-base`	unset	If specified, `vcn` retrieves the base BOM by specified hash and outputs the difference between two BOMs

Any of these options (except --signerID and --github-token) implies --bom mode.

See output options for details about outputting BoM in standard formats.

This command returns one of the following exit codes:

0 - success; all assets' statuses are trusted
1 - any dependency or BoM source is untrusted
2 - any dependency or BoM source is unknown and there are no untrusted or unsupported dependencies
3 - any dependency or BoM source is unsupported and there are no untrusted dependencies

Examples:

vcn a immudb/immuclient --signerID auditor --bom-deps-only vcn a immudb/cmd/immudb/ --bom-trust-level unknown --bom-spdx immudb.spdx --bom-file .bom vcn a immudb-py --bom-max-unsupported 12.5

Notarization

vcn n --bom <asset> [bom options] [bom output options]

This command resolves the dependencies for the asset, authenticates and notarizes the dependencies (only the unknown one, if --bom-force is not specified) and the asset, and prints out the list of dependencies with their trust levels.

Following options modify the behavior of this command:

Option	Default	Description
`--bom-signerID`	current user	Signer ID to use for dependency authentication
`--bom-force`	`false` (unset)	Force notarization of all dependencies regardless of their trust levels. If unset, only unsupported and unknown dependencies are notarized. Also forces cascade operation
`--bom-deps-only`	`false` (unset)	Notarize only the dependencies, do not notarize the BoM source
`--bom-hashes`		If specified, add assets with provided hashes as dependencies. These components must be trusted
`--bom-import-spdx`		If specified, import dependencies from specified SPDX tag-value file
`--bom-import-cdx-json`		If specified, import dependencies from specified CycloneDX JSON file
`--bom-import-cdx-xml`		If specified, import dependencies from specified CycloneDX XML file
`--bom-batch-size`	`100`	Send requests to server in batches of specified size
`--github-token`	unset	If specified, `vcn` uses this OAuth GitHub token for querying extra data for Github packages. If not specified, `vcn` performs anonymous queries. Either authenticated or not, requests are subject to Github limits.
`--bom-cascade`	`false` (unset)	See Cascade operations

Any of these options (except --github-token) implies --bom mode.

Examples:

vcn n immudb/immuclient --bom-signerID auditor --bom-deps-only vcn n immudb/immudb/cmd/immudb/ --bom-file .bom --attr version=v1.2.3 vcn n immudb-py --bom-force --bom-spdx immudb.spdx --attach immudb.spdx

Output options

User can specify one or several options to output BoM in different supported standard formats.

Option	Description
`--bom-spdx-tv`	Name of output SPDX tag-value file
`--bom-spdx-json`	Name of output SPDX JSON file
`--bom-spdx`	Name of output SPDX tag-value file (alias for `--bom-spdx-tv`)
`--bom-cdx-json`	Name of output CycloneDX JSON file
`--bom-cdx-xml`	Name of output CycloneDX XML file

Any of this options implies --bom mode.

Working with individual dependencies

vcn a|n|ut|us <scheme>://<name>@<version> | --hash <hash>

Individual components are authenticated/notarized/unsupported/untrusted as any other asset, but you need to specify either component hash with --hash option or component path in the form <scheme>://<name>@<version>. Scheme specifies the type of software component and should be the one from the supported types.

Examples:

vcn a gocom://golang.org/x/[email protected] vcn n --hash 691631371bfa886425c956999a4e998181036be260d7c0f179b3d2adde9b8353 vcn ut pythoncom://[email protected]

Looking up artifacts by dependency

vcn a --bom-what-includes (<scheme>://<name>@<version> | --hash <hash>)

This command lists all assets where specified component is used as a dependency. Component must be specified by hash with --hash option, or component path in the form <scheme>://<name>@<version>. Scheme specifies the type of software component, and should be the one from the supported types (except docker scheme).

Examples:

vcn a --bom-what-includes gocom://golang.org/x/[email protected] vcn a --bom-what-includes --hash 691631371bfa886425c956999a4e998181036be260d7c0f179b3d2adde9b8353

Support for containers

vcn <command> <scheme>://<image_or_container> [command options]

Supported schemes:

docker - Docker image ID or tag, requires running docker deamon
container - Docker container ID or tag, requires running docker deamon
image - container image in container registry/docker image/saved image in tarball.
- by default read image from remote registry, URL format: image://[<registry_server>/]image_tag. If <registry_server> is not specified, Docker Hub is used. By default vcn tries to connect to the registry using active Docker session, however user can always override it by using image-registry-user and image-registry-password/image-registry-password-file CLI parameters.
- if CLI parameter --image-docker-daemon is specified, image is taken from Docker daemon, so it is same as using docker URL scheme
- if CLI parameter --image-tar is specified, the image is read from tarball

For the image:// schema you can specify several additional options:

--image-platform - in case when remote registry is used, you can optionally specify the platform, eg. --image-platform linux/amd64. By default your local platform is used.
If you intend to scan images from a remote registry (Docker Hub) you need to provide --image-registry-user and --image-registry-password. Other options are explained in help files.

If asset is specified as TAR file which contains exported image, vcn processes it as image.

Examples:

vcn a --bom docker://alpine:latest --bom-spdx docker.spdx vcn a --bom container://magical_hoover vcn n --bom image://codenotary/immudb:1.3 --image-docker-daemon vcn n --bom image://my_registry.com/my_image --image-registry-user my_user --image-registry-password my_API_key vcn n --bom image://debian_11.tar --image-tar

Cascade operations

vcn notarize|untrust|unsupport [command options ...] --bom-cascade [--bom-force]

It is possible to automatically propagate the action on the asset to other assets that include the one being processed, by specifying --bom-cascade option.

When this option is specified, vcn shows the list of assets that include current one, which has a status, different from desired one, and requests the confirmation (unless --bom-force is specified) from the user.

Examples:

vcn n --hash 0fcc60c04098ec262fc7e6369f8b01cfddc99fd251bf1762cb2a3c0937ee29a6 --bom-cascade vcn untrust gocom://gopkg.in/[email protected] --bom-cascade --bom-force