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 private and public 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.

Warning

The CBOMkit service does not build any repository prior to scanning. For Java repositories in particular, this means that we cannot rely on any build results (class files, jars) that could improve the scanning result. This potentially reduces completeness and accuracy of the findings since some Java symbols may not be resolved. For better results, use the sonar-cryptography-plugin together with SonarQube or CBOMkit-action embedded in a pipeline definition that builds the code before scanning.

Quickstart

Starting the CBOMkit using docker-compose.

# clone the repository 
git clone https://github.com/cbomkit/cbomkit
cd 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 or a package url (PURL) like pkg:maven/io.quarkus/quarkus-core@3.18.1 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/cbomkit/cbomkit
cd 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/cbomkit/cbomkit/releases/latest | grep '"tag_name":' | sed -E 's/.*"([^"]+)".*/\1/') \
  --set frontend.tag=$(curl -s https://api.github.com/repos/cbomkit/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
• 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 project identifier

curl --request GET \
  --url 'http://localhost:8081/api/v1/cbom/pkg:github%2Fkeycloak%2Fkeycloak@<commit_hash>'

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)

External Compliance Evaluation

CBOMkit supports the use of Open Policy Agent (OPA) as an external compliance evaluation service. OPA evaluates compliance based on user-defined policies written in its declarative policy language, Rego.

In CBOMkit, you can configure OPA as an external compliance compliance service using either:

• the environment variable CBOMKIT_OPA_API_BASE, or
• the configuration key cbomkit.ext-policies.opa-api-base in application.properties.

If either option is specified, it must contain the base URL of a running OPA instance. If the variable or property is unset, or if CBOMkit cannot connect to OPA, the system automatically falls back to its built-in internal compliance service.

The internal compliance service implements a fixed “quantum-safe policy.” This built-in policy checks the quantum safety of asymmetric algorithms using whitelists of algorithm OIDs and names.

Policy Definition in OPA

CBOMkit provides a sample Rego policy, quantum_safe.rego, which replicates the behavior of the internal compliance service. A Rego policy file begins with a package declaration and defines one or more rules. All CBOMkit policies must start with:

package policies

Each rule includes:

• A header, = A conditional expression (the logic), and
• A JSON object to be returned when the condition is satisfied.

For compliance evaluation, OPA executes these rules on the set of CBOM components. By convention, a rule header should follow this format:

<policy_name>.findings contains finding if ...

The <policy_name> identifies the policy being evaluated. It must match the policy name configured in the CBOMkit front end through the environment variable VUE_APP_POLICY_NAME. By default, this is "quantum_safe", the predefined policy included in quantum_safe.rego.

When running CBOMkit as a Docker application via make ext-compliance (see below), the OPA container is automatically configured with this default policy file.

Findings Format

Each policy must produce a JSON list named findings, which CBOMkit expects in OPA’s evaluation response. Every finding object must contain at least these three attributes:

{
  "bom-ref": "string",         # The UUID of the matching component (usually component["bom-ref"])
  "result": "string",          # One of ["quantum-safe", "quantum-vulnerable", "na", "unknown"]
  "rule": "string",            # The name of the rule
  "property": "string",        # Optional: the relevant CBOM property name
  "value": "string" or numeric # Optional: the property’s value
}

If any mandatory attribute of a finding is missing, the evaluation will fail, and CBOMkit will revert to its internal compliance service. The result value conveys the rule’s outcome. NA indicates that the rule does not apply to a certain component (for example, symmetric algorithms in the predefined "quantum_safe" policy). "property" and "value" are optional and used when rendering compliance details in the CBOMkit interface.

Evaluation Results

A compliance policy acts as a knowledge base defining what is compliant or non-compliant. If a component does not match any rule, no finding is produced; CBOMkit then marks the component as "unknown".

The overall compliance status is considered not quantum-safe if any component is marked "quantum-vulnerable." Conversely, if no "quantum-vulnerable" components are found, or if no rule matches and hence no findings are generated, the CBOM is assumed to be quantum-safe.

Note

This same “quantum-safe” result will also occur for a non-empty CBOM if OPA cannot locate the specified policy or if no policy is configured at all.

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.

Handling of Credentials

When a new scan of a GitHub repository is started, CBOMkit generates a temporary local clone of the repository. The frontend enables users to provide GitHub credentials (either a username and password or a personal access token). These credentials are not logged or stored; instead, they are directly forwarded to JGit to facilitate the cloning process. After the scan completes - regardless of whether it succeeds or fails - the temporary local clone is deleted.

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%
Go	crypto (standard library)	100%2
	golang.org/x/crypto	Partial3

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 ↩

2. All packages under crypto are covered except crypto/x509 ↩

3. Covers golang.org/x/crypto/hkdf, golang.org/x/crypto/pbkdf2, and golang.org/x/crypto/sha3 ↩