bomctl is format-agnostic Software Bill of Materials (SBOM) tooling, which is intended to bridge the gap between SBOM generation and SBOM analysis tools. It focuses on supporting more complex SBOM operations on multiple SBOM files that represent systems by being opinionated on only supporting the NTIA minimum fields or other fields supported by protobom.

Try bomctl in our gitpod playground

[!NOTE] This is an experimental project under active development. We'd love feedback on the concept, scope, and architecture!

Features

Work with multiple SBOMs in tree structures (through external references)
Fetch and push SBOMs using multiple supported protocols
Leverage a .netrc file to handle authentication
Manage SBOMs using a persistent database cache
FUTURE - Manipulate SBOMs with commands like diff, split, and redact
FUTURE - Interface with other OpenSSF projects and services like GUAC and Sigstore

Join our Community

#bomctl on OpenSSF Slack
OpenSSF Security Tooling Working Group Meeting - Every other Friday at 11am Eastern / 8am Pacific

Installation

Homebrew

brew tap bomctl/bomctl && brew install bomctl

Container Images

Container images for bomctl can be found on Docker Hub.

docker run bomctl/bomctl:latest --help

Install From Source

To install bomctl, you need the following:

Go
Git
One of:
- Make
- Task

Clone the bomctl repository

git clone https://github.com/bomctl/bomctl.git
cd bomctl

Build using `make` or `task`

Commands

bomctl stores SBOMs in a cache database, this allows more complex cross SBOM document operations to exist. This is a fundemental concept; files are not directly modified, the cache is.

bomctl uses the protobom library to store the SBOM component graph in an SBOM agnostic format. When you interact with the bomctl cache, you are interacting with the protobom library.

SBOMs are read and loaded into the cache
- fetch
- import
Operations are performed on the cached SBOMs
- alias
- list
- merge
- tag
SBOMs are outputted out of the cache
- export
- push

Alias

Edit the alias for an SBOM document.

[!NOTE] An SBOM document can only have a single alias and each alias must be globally unique.

bomctl alias [command]

Subcommands:
  list        List all alias definitions
  remove      Remove the alias for a specific document
  set         Set the alias for a specific document

Flags:
  -h, --help   help for alias

Export

Export stored SBOM(s) to filesystem

bomctl export [flags] SBOM_ID...

Flags:
  -e, --encoding CHOICE    Output encoding ('xml' supported for CycloneDX formats only) [json, xml] (default json)
  -f, --format CHOICE      Output format [original, spdx, spdx-2.3, cyclonedx, cyclonedx-1.0, cyclonedx-1.1, cyclonedx-1.2, cyclonedx-1.3, cyclonedx-1.4, cyclonedx-1.5, cyclonedx-1.6] (default original)
  -h, --help               help for export
  -o, --output-file FILE   Path to output file

Fetch

Ability to retrieve SBOM files over several protocols and web APIs, including HTTPS, OCI, Git, GitHub, and GitLab.

bomctl fetch [flags] SBOM_URL...

Flags:
      --alias string       Readable identifier to apply to document
  -h, --help               help for fetch
      --netrc              Use .netrc file for authentication to remote hosts
  -o, --output-file FILE   Path to output file
      --tag stringArray    Tag(s) to apply to document (can be specified multiple times)

This includes recursive loading of external references in an SBOM to other SBOMs and placing them into the persistent cache. If SBOMs are access controlled, a user's .netrc file can be used to authenticate.

The following example will fetch this CycloneDX SBOM that represents a container image and will then recursively fetch an externally referenced SBOM that represents an application within the container image.

bomctl fetch https://raw.githubusercontent.com/bomctl/bomctl-playground/main/examples/bomctl-container-image/bomctl_bomctl_v0.3.0.cdx.json

Alternatively, use the following syntax to directly fetch the most recent dependency graph SBOM of a GitHub repository (In this case, the bomctl repository). This syntax works for both public and private repositories, although credentials will need to be provided via --netrc to access a private repo.

bomctl fetch https://github.com/bomctl/bomctl

An SBOM may also be fetched from a GitLab repository through the DependencyListExport web API by using the following URL format. Authorization for this command is configured by assigning the value of your GitLab token to the BOMCTL_GITLAB_TOKEN environment variable.

bomctl fetch https://www.gitlab.com/PROJECT/REPOSITORY@BRANCH

Import

Import SBOM files from either standard input or the local file system.

bomctl import [flags] { - | FILE...}

Flags:
      --alias stringArray   Readable identifier(s) to apply to imported document(s) (specify multiple times for multiple documents)
  -h, --help                help for import
      --tag stringArray     Tag(s) to apply to all imported documents (can be specified multiple times)

Link

Edit links between documents and/or nodes

bomctl link [command]

Subcommands:
  add         Add a link from a document or node to a document
  clear       Remove all links from specified documents and nodes
  list        List the links of a document or node
  remove      Remove specified links from a document or node

Flags:
  -h, --help          help for link
  -t, --type CHOICE   Type referenced by SRC_ID [node, document] (default node)

List

List cached SBOM documents.

bomctl list [flags] SBOM_ID...

Aliases:
  list, ls

Flags:
  -h, --help              help for list
      --tag stringArray   Tag(s) used to filter documents (can be specified multiple times)

Merge

Merge specified cached SBOM documents.

bomctl merge [flags] DOCUMENT_ID...

Flags:
      --alias string      Readable identifier to apply to merged document
  -h, --help              help for merge
  -n, --name string       Name of merged document
      --tag stringArray   Tag(s) to apply to merged document (can be specified multiple times)

Push

Push stored SBOM file to remote URL or filesystem

bomctl push [flags] SBOM_ID DEST_PATH

Flags:
  -e, --encoding CHOICE   Output encoding ('xml' supported for CycloneDX formats only) [json, xml] (default json)
  -f, --format CHOICE     Output format [original, spdx, spdx-2.3, cyclonedx, cyclonedx-1.0, cyclonedx-1.1, cyclonedx-1.2, cyclonedx-1.3, cyclonedx-1.4, cyclonedx-1.5, cyclonedx-1.6] (default original)
  -h, --help              help for push
      --netrc             Use .netrc file for authentication to remote hosts
      --tree              Recursively push all SBOMs in external reference tree

An SBOM may be pushed as a package to a GitLab repository through the Generic Package Registry web API by using the following URL format. Authorization for this command is configured by assigning the value of your GitLab token to the BOMCTL_GITLAB_TOKEN environment variable.

bomctl push SBOM_ID_OR_ALIAS https://www.gitlab.com/PROJECT/REPOSITORY#PACKAGE_NAME@PACKAGE_VERSION

Tag

Edit the tags of an SBOM document.

bomctl tag [command]

Subcommands:
  add         Add tags to a document
  clear       Clear all tags from a document
  list        List the tags of a document

Bomctl

Install / Use

README

Features

Join our Community

Installation

Homebrew

Container Images

Install From Source

Clone the bomctl repository

Build using `make` or `task`

Commands

Alias

Export

Fetch

Import

Link

List

Merge

Push

Tag

Bomctl

Install / Use

README

Features

Join our Community

Installation

Homebrew

Container Images

Install From Source

Clone the bomctl repository

Build using make or task

Commands

Alias

Export

Fetch

Import

Link

List

Merge

Push

Tag

Build using `make` or `task`