Skip to content

Latest commit

 

History

History
141 lines (102 loc) · 8.52 KB

README.md

File metadata and controls

141 lines (102 loc) · 8.52 KB
Raw

CBOMkit - the essentials for CBOMs

License Current Release

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 (aka 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.

CBOMkit Demo

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

Note

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

Deploy using the helm chart to a kubernetes environment.

# clone the repository 
git clone https://github.com/IBM/cbomkit
# deploy using helm
helm install cbomkit 
  --set postgresql.auth.username={POSTGRES_USER} 
  --set postgresql.auth.password={POSTGRES_PASSWORD} 
  ./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 ↩