Working with SPDX

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

1. Introduction

The SPDX (Software Package Data Exchange) specification is a standard format for documenting the components, licenses, and copyrights 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. The specification for SPDX version 2.3 can be found here.

The following manual serves as a comprehensive guide for utilizing SPDX, specifically focusing on the submission of dependency lists (SBOM) in the SPDX JSON format through the Build API. This document aims to provide users with the necessary knowledge to effectively leverage SPDX 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 SPDX for submitting dependency lists in the SPDX 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 SPDX in conjunction with the Build API to submit dependency lists in the SPDX 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 | | SPDX | Software Package Data Exchange, a standard format for documenting the components, licenses, and copyrights of software packages. |

3. Project setup

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

1. A project must be set up in Ketryx

2. Either:

   1. A version must exist within the project, or

   2. A commit must be associated with the project

3. 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 SPDX JSON format.

4. Supported SPDX formats

Ketryx supports SPDX files in JSON format. Version 2.2 and 2.3 of the SPDX specification are supported.

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

1. syft

2. sbom-tool

3. GitHub

4. FOSSA

Please note that sfyt before version 0.86.0 did not generate a package record for the artifact described by the SPDX file. Ketryx uses this entry to properly identify top-level packages. If you are using syft to generate SPDX files, make sure to use version 0.86.0 or later.

GitHub currently does not – as of March 27th 2024 – export the relationships between packages and the artifact described by the SPDX file. This means that Ketryx will not be able to properly identify top-level packages. As a result, all packages will be considered top-level packages.

5. Submitting dependencies

Ketryx provides two ways to submit SPDX files. Once the SPDX 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 SPDX 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 SPDX 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 SPDX files. The GitHub Action is available in the GitHub Marketplace.

5.3 After submission

After submitting the SPDX 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 SPDX file. Direct and indirect dependencies of these packages are shown on the Dependencies tab of each individual dependency's detail page.

Ketryx uses the SPDX file's relationships list to determine the relationships between packages. If the SPDX file does not contain this information, Ketryx will not be able to determine the relationships between packages and will treat all packages as top-level packages.

Ketryx currently supports the following relationship types:

• DESCRIBES, used to describe the relationship between a package and the artifact described by the SPDX file. Mandatory if relationships are defined. Otherwise documentDescribes is used by Ketryx. If neither is present, all packages are considered top-level packages.

• CONTAINS, used by e.g. SPDX files describing a container image.

• DEPENDS_ON or DEPENDENCY_OF, used to describe dependencies between packages.

For Ketryx to display the transitive dependencies, the submitted SPDX file must contain transitive dependencies in the packages list and the necessary relationships in the relationships list (see note above) 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 SPDX 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 desireable 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. Cybersecurity

By default, Ketryx will parse the SPDX file and create corresponding dependencies as defined within these files. It extracts crucial information about software packages, including version, license, and advisory information (introduced in SPDX version 2.3), 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.

Starting with SPDX version 2.3, advisory information can be included in the SPDX file via the external reference field of category SECURITY and type ADVISORY. Ketryx will extract this information and display it on the SBOM > Vulnerabilities page of the project. The Vulnerabilities tab of each individual top-level dependency's detail page will show the advisories found in that dependency.