CBOMkit - the essentials for CBOMs

CBOMkit is a toolset for dealing with Cryptography Bill of Materials (CBOM). CBOMkit includes a

• CBOM Generation (CBOMkit-hyperion, CBOMkit-theia): Generate CBOMs from source code by scanning git repositories to find the used cryptography.
• CBOM Viewer (CBOMkit-coeus): Visualize a generated or uploaded CBOM and access comprehensive statistics.
• CBOM Compliance Check: Evaluate CBOMs created or uploaded against specified compliance policies and receive detailed compliance status reports.
• CBOM Database: Collect and store CBOMs into the database and expose this data through a RESTful API.

Quickstart

Starting the CBOMkit using docker-compose.

# clone the repository 
git clone https://github.com/IBM/cbomkit
# run the make command to start the docker compose 
make production

Alternatively, if you wish to use podman instead of docker, run the following:

# run the make command to start the docker compose using podman
make production ENGINE=podman

(This requires podman-compose to have been installed via pip3 install podman-compose).

Next steps:

• Enter a git url like https://github.com/keycloak/keycloak to generate a CBOM
• View your generated CBOM by selecting your previously scanned CBOM
• Drag and drop CBOM from the examples into the dropbox to view it

Note

By default, the service can be accessed at http://localhost:8001

Deploy using the helm chart to a kubernetes environment. Pass the domain suffix and the cbomkit database creds via helm parameters.

# clone the repository 
git clone https://github.com/IBM/cbomkit
# deploy using helm
helm install cbomkit \
  --set common.clusterDomain={CLUSTER_DOMAIN} \
  --set postgresql.auth.username={POSTGRES_USER} \
  --set postgresql.auth.password={POSTGRES_PASSWORD} \
  --set backend.tag=$(curl -s https://api.github.com/repos/IBM/cbomkit/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/') \
  --set frontend.tag=$(curl -s https://api.github.com/repos/IBM/cbomkit/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/') \
  ./chart

Architecture

The CBOMkit consists of three integral components: a web frontend, an API server, and a database.

Frontend and CBOMkit-coeus

The web frontend serves as an intuitive user interface for interacting with the API server. It offers a range of functionalities, including:

• Browsing the inventory of existing Cryptographic Bills of Materials (CBOMs)
• Initiating new scans to generate CBOMs
• Uploading existing CBOMs for visualization and analysis

CBOMkit-coeus

For enhanced flexibility, the frontend component can be deployed as a standalone version, known as the CBOMkit-coeus. This option allows for streamlined visualization and compliance analysis independent of the full CBOMkit suite.

# use this command if you want to run only the CBOMkit-coeus
make coeus

API Server

The API server functions as the central component of the CBOMkit, offering a comprehensive RESTful API (see OpenAPI specification) with the following key features:

Features

• Retrieve the most recent generated CBOMs
• Access stored CBOMs from the database using Package URLs (PURL)
• Execute targeted searches for scanned Git repositories utilizing specific algorithms (by name and Oid)
• Perform compliance checks for user-provided CBOMs against specified policies
• Conduct compliance assessments for stored or generated CBOMs against defined policies

Sample Query to Retrieve CBOM by Package URL

curl --request GET \
  --url 'http://localhost:8081/api/v1/cbom?purls=pkg:github/OddSource/java-license-manager'

In addition to the RESTful API, the server incorporates WebSocket integration, enabling:

• Initiation of CBOM generation through Git repository scanning
• Real-time progress updates during the scanning process, transmitted via WebSocket connection

Compliance

A critical component of the CBOMkit is its compliance checking mechanism for Cryptography Bills of Materials (CBOMs). The CBOM structure represents a hierarchical tree of cryptographic assets detected and used by an application. This standardized format facilitates the development and implementation of generalized policies to identify and flag violations in cryptographic usage.

The CBOMkit currently features a foundational quantum-safe compliance check. This initial implementation serves as a proof of concept and demonstrates the system's capability to evaluate cryptographic components against defined policies.

The compliance framework is designed with extensibility in mind, providing a solid platform for:

• Implementing additional compliance checks
• Enhancing existing verification processes
• Integrating custom compliance checks (external)

Configuration

Different deployment configurations utilize distinct sources for compliance verification.

Deployment	How is the compliance check performed?
coeus	A quantum-safe algorithm compliance check is natively implemented within the frontend. This integration allows for immediate, client-side assessment of basic quantum resistance criteria.
production	In the standard deployment, a core compliance service is integrated into the backend service. This implementation enables the execution of compliance checks via the RESTful API, providing a scalable and centralized approach to cryptographic policy verification.
ext-compliance	In advanced deployment scenarios, compliance evaluation is delegated to a dedicated external service. This service can invoked by the API server as needed. This configuration maintains the standard user experience for both the frontend and API of the CBOMkit, mirroring the functionality of the production configuration while allowing for more sophisticated or specialized compliance checks to be performed externally.

Scanning and CBOM Generation

The CBOMkit leverages advanced scanning technology to identify cryptographic usage within source code and generate Cryptography Bills of Materials (CBOMs). This scanning capability is provided by the CBOMkit-hyperion (Sonar Cryptography Plugin), an open-source tool developed by IBM.

Supported languages and libraries

The current scanning capabilities of the CBOMkit are defined by the Sonar Cryptography Plugin's supported languages and cryptographic libraries:

Language	Cryptographic Library	Coverage
Java	JCA	100%
	BouncyCastle (light-weight API)	100%1
Python	pyca/cryptography	100%

While the CBOMkit's scanning capabilities are currently bound to the Sonar Cryptography Plugin, the modular design of this plugin allows for potential expansion to support additional languages and cryptographic libraries in future updates.

Contribution Guidelines

If you'd like to contribute to CBOMkit, please take a look at our contribution guidelines. By participating, you are expected to uphold our code of conduct.

We use GitHub issues for tracking requests and bugs. For questions start a discussion using GitHub Discussions.

License

Apache License 2.0

Footnotes

1. We only cover the BouncyCastle light-weight API according to this specification ↩