Working with CycloneDX

Manual for submitting dependencies via CycloneDX files using Ketryx Software Supply Chain Management

1. Introduction

CycloneDX is a standard format for documenting the components, licenses, and vulnerabilities of software packages. It is designed to facilitate the exchange of software bill of materials (SBOM) information between parties, enabling the identification and tracking of dependencies in software projects. You can find the official CycloneDX 1.5 specification online, and Ketryx also supports CycloneDX versions 1.4, and 1.6.

The following manual serves as a comprehensive guide for utilizing CycloneDX, specifically focusing on the submission of dependency lists (SBOM) in the CycloneDX JSON format through the Build API. This document aims to provide users with the necessary knowledge to effectively leverage CycloneDX for managing dependencies within software projects.

1.1 Purpose

The purpose of this manual is to equip users with the understanding and proficiency required to utilize CycloneDX for submitting dependency lists in the CycloneDX JSON format via the Build API. By following the guidelines outlined herein, users can streamline the management of dependencies in their software development processes.

1.2 Scope

This manual encompasses detailed instructions for utilizing CycloneDX in conjunction with the Build API to submit dependency lists in the CycloneDX JSON format. Topics such as project setup, API authentication and SBOM and vulnerability management are covered in different manuals, guides and references and are linked to in this document.

2. Terms and definitions

Acronym

Definition

CycloneDX (CDX)

A standard format for documenting the components, licenses, and vulnerabilities of software packages.

3. Project setup

To submit dependencies via the Build API using CycloneDX in JSON format, three prerequisites must be met:

A project must be set up in Ketryx
Either:
1. A version must exist within the project, or
2. A commit must be associated with the project
An API key must be created to authenticate requests

If you don't have a project set up, follow the instructions in MAN-03, section 3.

Once a projects exists, either a version must be created if one does not yet exist or a repository with commits must exist within the project. A version can be created on the Releases page of the project. To add a repository to a project, please see MAN-03, section 3.

To submit dependencies, you need to have the project ID, and version ID or name, or commit SHA handy. Project ID and version ID can be found in the URL when you navigate to the project or version in Ketryx. The version name is the one shown on the Releases page, while the ID is the one in the URL. The commit SHA can either be found on the History > Commits page of the project or in your version control system.

As a last step, an API key is required to authenticate the requests. Steps to creating an API key can be found in the API Authentication documentation.

Once you have a project set up, you can start using the Build API to submit dependencies in CycloneDX JSON format.

4. Supported CycloneDX formats

Ketryx supports CycloneDX files in JSON format. Version 1.4, 1.5, and 1.6 of the CycloneDX specification are supported.

Such CycloneDX files can be obtained or generated with a variety of tools, including, in no particular order:

5. Submitting dependencies

Ketryx provides two ways to submit CycloneDX files. Once the CycloneDX file has been submitted, the SBOM Review page in Ketryx will show the submitted dependencies for the version it was submitted for.

5.1. Via the Build API

To submit dependencies via the Build API, you first need to upload the CycloneDX file as a build artifact to the /build-artifact endpoint, followed by a POST request to the /builds endpoint. The request should include the project ID, version ID or name, or commit SHA, and the CycloneDX JSON payload. More details can be found in the Build API documentation.

5.2. Via the Ketryx GitHub Action

When using GitHub Actions, instead of using the Build API directly, you can use the Ketryx GitHub Action to automate the submission of CycloneDX files. The GitHub Action is available in the GitHub Marketplace.

5.3. After submission

After submitting the CycloneDX file, the dependencies will be processed by Ketryx. The dependencies will be displayed on the SBOM page of the project. Unless configured otherwise, the SBOM page shows the top-level packages contained in the CycloneDX file. Direct and indirect dependencies of these packages are shown on the Dependencies tab of each individual dependency's detail page.

For Ketryx to display the transitive dependencies, the submitted CycloneDX file must contain transitive dependencies in the packages list and the necessary relationships in the dependencies list for each dependency. If these are missing, Ketryx will not display the transitive dependencies.

5.4. Advanced configuration

Ketryx allows for advanced configuration of the CycloneDX processing. This includes the ability to have Ketryx treat direct and indirect dependencies of top-level packages as top-level dependencies. In effect, this means that all dependencies of a top-level package are shown as top-level packages on the SBOM page. As a result, all dependencies will have to be approved and put into a controlled state before a release can be approved.

This can be desirable if you want to ensure that all dependencies are controlled, not just the top-level packages. In case of some ecosystems, such as npm, this can however also result in a large number of dependencies being shown as top-level packages.

For more information, please refer to the Advanced Settings documentation.

6. Mapping CycloneDX data to item fields

New in 2.13.2

Ketryx offers a flexible mechanism to map data from an uploaded CycloneDX SBOM directly to custom fields on dependency items. This allows you to enrich dependency items with relevant information from the SBOM, such as component type, build properties, or SBOM metadata.

This mapping is configured via the CycloneDX field mapping advanced setting. Other settings, such as Custom item fields configuration and Item fields, are configured in the advanced settings on the organization level.

This requires dependencies as items to be enabled in the project. This is not yet enabled for all organizations by default. If you want to use this feature, please contact Ketryx support to enable it for your organization.

6.1. Configuration

The mapping is defined by a set of rules. Each rule specifies a source for the data within the CycloneDX document (using a JSONPath expression) and a target custom field.

JSONPath Context

JSONPath expressions are evaluated against a context object that contains both the component being processed and the root of the SBOM document.

$.component: Use this prefix to query fields within the current CycloneDX component. For example, $.component.name extracts the component's name.
$.doc: Use this prefix to access properties from the root of the CycloneDX document. For example, $.doc.metadata.timestamp extracts the SBOM's generation timestamp.

Mapping Rules

A mapping rule can have the following properties:

source (required): A JSONPath expression to extract the value.
target (required): An object specifying the customField name to map the value to.
description: A human-readable description of the rule.
appliesToVersion: An array of CycloneDX specification versions (e.g., ["1.5"]) to which the rule applies. If omitted, the rule applies to all supported versions.
enumMapping: A dictionary to translate source values to different target values, useful for SELECT custom fields.
defaultValue: A fallback value to use if the source expression yields no result.

6.2. Examples

Here are some examples of how to configure the mapping.

Example 1: Map component type and SBOM timestamp

This example demonstrates two basic mappings:

The component's type is mapped to a Software component type custom field.
The SBOM's generation timestamp is mapped to an SBOM generation date custom field.

First, define the custom fields in the Custom item fields configuration setting.

Custom item fields configuration

{
  "Software component type": {
    "type": "SHORT_TEXT",
    "isEditableInKetryx": true,
    "syncToExternalSystem": false
  },
  "SBOM generation date": {
    "type": "DATETIME",
    "isEditableInKetryx": true,
    "syncToExternalSystem": false
  }
}

Then, add the custom fields to the Dependency item type in the Item fields setting.

Item fields configuration

{
  "Dependency": {
    "addedFields": [
      { "kind": "CUSTOM", "name": "Software component type" },
      { "kind": "CUSTOM", "name": "SBOM generation date" }
    ]
  }
}

Finally, configure the mapping rules in the CycloneDX field mapping advanced setting.

CycloneDX field mapping configuration

{
  "mappingSchemaVersion": "1.0.0",
  "description": "Maps component type and SBOM generation date to custom fields.",
  "mappingRules": [
    {
      "description": "Map the component's type to the 'Software component type' custom field.",
      "source": "$.component.type",
      "target": {
        "customField": "Software component type"
      }
    },
    {
      "description": "Map the SBOM generation timestamp to the 'SBOM generation date' custom field.",
      "source": "$.doc.metadata.timestamp",
      "target": {
        "customField": "SBOM generation date"
      }
    }
  ]
}

Example 2: Transform values for a SELECT field

This example shows how to map the component type to a SELECT custom field, transforming the values using enumMapping.

First, define the Component Category custom field with its options.

Custom item fields configuration

{
  "Component Category": {
    "type": "SELECT",
    "options": [{ "value": "Software Library" }, { "value": "Software Framework" }, { "value": "Application" }],
    "isEditableInKetryx": true,
    "syncToExternalSystem": false
  }
}

Then, add the custom field to the Dependency item type.

Item fields configuration

{
  "Dependency": {
    "addedFields": [
      { "kind": "CUSTOM", "name": "Component Category" }
    ]
  }
}

Finally, set up the mapping rule with enumMapping.

CycloneDX field mapping configuration

{
  "mappingSchemaVersion": "1.0.0",
  "supportedVersions": ["1.4", "1.5", "1.6"],
  "mappingRules": [
    {
      "description": "Map the component's type to the 'Component Category' select field.",
      "source": "$.component.type",
      "target": {
        "customField": "Component Category"
      },
      "enumMapping": {
        "library": "Software Library",
        "framework": "Software Framework",
        "application": "Application"
      }
    }
  ]
}

Example 3: Map multiple values to a MULTI_SELECT field

This example extracts all external reference types and maps them to a MULTI_SELECT field.

First, define the Reference Types custom field.

Custom item fields configuration

{
  "Reference Types": {
    "type": "MULTI_SELECT",
    "isEditableInKetryx": true,
    "syncToExternalSystem": false,
    "options": [
      { "value": "advisories" },
      { "value": "bom" },
      { "value": "build-meta" },
      { "value": "configuration" },
      { "value": "distribution" },
      { "value": "issue-tracker" },
      { "value": "license" },
      { "value": "mailing-list" },
      { "value": "social" },
      { "value": "support" },
      { "value": "vcs" },
      { "value": "website" }
    ]
  }
}

Then, add the custom field to the Dependency item type.

Item fields configuration

{
  "Dependency": {
    "addedFields": [
      { "kind": "CUSTOM", "name": "Reference Types" }
    ]
  }
}

The mapping rule uses a wildcard in the JSONPath to get all types.

CycloneDX field mapping configuration

{
  "mappingSchemaVersion": "1.0.0",
  "supportedVersions": ["1.4", "1.5", "1.6"],
  "mappingRules": [
    {
      "description": "Map external reference types to a multi-select field.",
      "source": "$.component.externalReferences[*].type",
      "target": {
        "customField": "Reference Types"
      }
    }
  ]
}

Any manual changes made to the values of custom fields that are mapped through this setting will be overwritten the next time an SBOM is processed.

7. Cybersecurity

By default, Ketryx will parse the CycloneDX file and create corresponding dependencies as defined within these files. It extracts crucial information about software packages, including version, license, and vulnerability information, which pertains to any vulnerabilities associated with the software packages.

Ketryx will also check direct and indirect (transitive) dependencies for vulnerabilities. If a vulnerability is found, it will be displayed on the SBOM > Vulnerabilities page of the project. The Vulnerabilities tab of each individual top-level dependency's detail page will show the vulnerabilities found in that dependency and its dependencies.

To learn more on how to create a vulnerability impact assessment and generate a vulnerability report for a project, see the Vulnerability Management manual.

For a list of supported ecosystems that Ketryx can analyze for vulnerabilities, please refer to MAN-03, section 10.

PreviousVulnerability Management NextWorking with SPDX

Last updated 10 days ago

Was this helpful?