Exchanging Data with Other Tools #

To share SBOM information with other tools, the vcn notarize and vcn authenticate commands offer a set of flags for importing and exporting SBOMs in a variety of formats.

Import from SPDX and CycloneDX #

When using vcn notarize to attest to an SBOM, you can import an SBOM from a file in one of the following formats:

SPDX (key-value pairs), using the --bom-import-spdx flag.
CycloneDX JSON, using the --bom-import-cdx-json flag.
CycloneDX XML, using the --bom-import-cdx-xml flag.

vcn notarize flags to import SBOM for notarization

vcn notarize [flags] ARG

--bom: auto-notarize asset dependencies and link dependencies to the asset
--bom-cascade: cascade the operation to all assets that include the asset being processed
--bom-cdx-json [string]: name of the file to output BOM in CycloneDX JSON format
--bom-cdx-xml [string]: name of the file to output BOM in CycloneDX XML format
--bom-debug: show extra debug info for BOM processing, also disable progress indicators
--bom-deps-only: notarize only the dependencies, not the asset
--bom-force: force notarization of untrusted dependencies, force cascade operation
--bom-hashes [strings]: hashes of the dependencies (disables automatic dependency resolution)
--bom-import-cdx-json [string]: name of the CycloneDX JSON to import BOM from
--bom-import-cdx-xml [string]: name of the CycloneDX XML to import BOM from
--bom-import-spdx [string]: name of the SPDX to import BOM from
--bom-signerID [string]: signerID to use for authenticating dependencies
--bom-spdx [string]: name of the file to output BOM in SPDX format

These flags allow you to import an SBOM generated by another tool. Rather than scanning an artifact to generate an SBOM, these flags will cause vcn to notarize the SBOM that you provide.

SBOM Output Flags
Note that the flags highlighted by this section are distinct from the flags that are used to control the SBOM output of vcn itself. The --bom-spdx, --bom-cdx-json, and --bom-cdx-xml flags, which are available to the vcn notarize and vcn authenticate commands, are used to specify the CLI tool’s output for both of these commands.

Export to SPDX or CycloneDX #

When using vcn authenticate to verify a software asset, the resulting SBOM can be exported to a file in one of the following formats:

SPDX (tag-value pairs), using the --bom-spdx-tv flag (or the --bom-spdx flag, which is available for backwards compatibility).
SPDX JSON, using the --bom-spdx-json flag.
CycloneDX JSON, using the --bom-cdx-json flag.
CycloneDX XML, using the –bom-cdx-xml` flag.

vcn authenticate flags to export authenticated SBOM

vcn authenticate [flags] ARG(s)

--bom: link asset to its dependencies from BOM
--bom-cdx-json [string]: name of the file to output BOM in CycloneDX JSON format
--bom-cdx-xml [string]: name of the file to output BOM in CycloneDX XML format
--bom-deps-only: authenticate only the dependencies, not the asset
--bom-diff-base [string]: hash of the artifact to diff the BOM against
--bom-max-unsupported [float]: max number (in %) of unsupported dependencies
--bom-spdx [string]: same as bom-spdx-tv (for backward compatibility)
--bom-spdx-json [string]: name of the file to output BOM in SPDX JSON format
--bom-spdx-tv [string]: name of the file to output BOM in SPDX tag-value format
--bom-trust-level [string]: min trust level: untrusted (unt) / unsupported (uns) / unknown (unk) / trusted (t) (default "trusted")
--bom-what-includes: output all assets that use the specified asset

The exported SBOM can then act as a report of the components comprising the software asset, with the trust level (and other relevant metadata) of each component.