Skip to main content

A library for producing CycloneDX SBOM (Software Bill of Materials) files.

Project description

Python Library for generating CycloneDX

GitHub Workflow Status Python Version Support PyPI Version GitHub license GitHub issues GitHub forks GitHub stars


This CycloneDX module for Python can generate valid CycloneDX bill-of-material document containing an aggregate of all project dependencies.

This module is not designed for standalone use. If you're looking for a CycloneDX tool to run to generate (SBOM) software bill-of-materials documents, why not checkout:

Additionally, the following tool can be used as well (and this library was written to help improve it)

Additionally, you can use this module yourself in your application to programmatically generate SBOMs.

CycloneDX is a lightweight BOM specification that is easily created, human-readable, and simple to parse.

Installation

Install from pypi.org as you would any other Python module:

pip install cyclonedx-python-lib

Architecture

This module break out into three key areas:

  1. Parser: Use a parser that suits your needs to automatically gather information about your environment or application
  2. Model: Internal models used to unify data from different parsers
  3. Output: Choose and configure an output which allows you to define output format as well as the CycloneDX schema version

Parsing

You can use one of the parsers to obtain information about your project or environment. Available parsers:

Parser Class / Import Description
CondaListJsonParser from cyclonedx.parser.conda import CondaListJsonParser Parses input provided as a str that is output from conda list --json
CondaListExplicitParser from cyclonedx.parser.conda import CondaListExplicitParser Parses input provided as a str that is output from conda list --explicit or conda list --explicit --md5
Environment from cyclonedx.parser.environment import EnvironmentParser Looks at the packaged installed in your current Python environment.
PipEnvParser from cyclonedx.parser.pipenv import PipEnvParser Parses Pipfile.lock content passed in as a string.
PipEnvFileParser from cyclonedx.parser.pipenv import PipEnvFileParser Parses the Pipfile.lock file at the supplied path.
PoetryParser from cyclonedx.parser.poetry import PoetryParser Parses poetry.lock content passed in as a string.
PoetryFileParser from cyclonedx.parser.poetry import PoetryFileParser Parses the poetry.lock file at the supplied path.
RequirementsParser from cyclonedx.parser.requirements import RequirementsParser Parses a multiline string that you provide that conforms to the requirements.txt PEP-508 standard.
RequirementsFileParser from cyclonedx.parser.requirements import RequirementsFileParser Parses a file that you provide the path to that conforms to the requirements.txt PEP-508 standard.

Example

from cyclonedx.parser.environment import EnvironmentParser

parser = EnvironmentParser()

Notes on Requirements parsing

CycloneDX software bill-of-materials require pinned versions of requirements. If your requirements.txt does not have pinned versions, warnings will be recorded and the dependencies without pinned versions will be excluded from the generated CycloneDX. CycloneDX schemas (from version 1.0+) require a component to have a version when included in a CycloneDX bill of materials (according to schema).

If you need to use a requirements.txt in your project that does not have pinned versions an acceptable workaround might be to:

pip install -r requirements.txt
pip freeze > requirements-frozen.txt

You can then feed in the frozen requirements from requirements-frozen.txt or use the Environment parser one you have pip installed your dependencies.

Modelling

You can create a BOM Model from either a Parser instance or manually using the methods avaialbel directly on the Bom class.

The model also supports definition of vulnerabilities for output using the CycloneDX schema extension for Vulnerability Disclosures as of version 0.3.0.

Note: Known vulnerabilities associated with Components can be sourced from various data sources, but this library will not source them for you. Perhaps look at Jake if you're interested in this.

Example from a Parser

from cyclonedx.model.bom import Bom
from cyclonedx.parser.environment import EnvironmentParser

parser = EnvironmentParser()
bom = Bom.from_parser(parser=parser)

Generating Output

Once you have an instance of a Bom you can produce output in either JSON or XML against any of the supporting CycloneDX schema versions as you require.

We provide two helper methods:

  1. Output to string (for you to do with as you require)
  2. Output directly to a filename you provide
Example as JSON
from cyclonedx.output import get_instance, OutputFormat

outputter = get_instance(bom=bom, output_format=OutputFormat.JSON)
outputter.output_as_string()
Example as XML
from cyclonedx.output import get_instance, SchemaVersion

outputter = get_instance(bom=bom, schema_version=SchemaVersion.V1_2)
outputter.output_to_file(filename='/tmp/sbom-v1.2.xml')

Library API Documentation

The Library API Documentation is available online at https://cyclonedx.github.io/cyclonedx-python-lib/.

Schema Support

This library is a work in progress and complete support for all parts of the CycloneDX schema will come in future releases.

Here is a summary of the parts of the schema supported by this library:

Note: We refer throughout using XPath, but the same is true for both XML and JSON output formats.

XPath Support v1.3 Support v1.2 Support v1.1 Support v1.0 Notes
/bom YYYY This is the root element and is supported with all it's defined attributes.
/bom/metadata YYN/AN/A timestamp and tools are currently supported
/bom/components YYYY  
/bom/components/component
./author YYN/AN/A  
./name YYYY  
./version YYYY  
./purl YYYY  
./externalReferences YYYN/A Not all Parsers have this information. It will be populated where there is information available.
./hashes YYYY These are supported when programmatically creating a Bom - these will not currently be automatically populated when using a Parser.

Notes on Schema Support

  1. N/A is where the CycloneDX standard does not include this
  2. If the table above does not refer to an element, it is not currently supported

Python Support

We endeavour to support all functionality for all current actively supported Python versions. However, some features may not be possible/present in older Python versions due to their lack of support.

Changelog

See our CHANGELOG.

Copyright & License

CycloneDX Python Lib is Copyright (c) OWASP Foundation. All Rights Reserved.

Permission to modify and redistribute is granted under the terms of the Apache 2.0 license.

Release history Release notifications | RSS feed

Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

cyclonedx-python-lib-0.11.1.tar.gz (98.0 kB view hashes)

Uploaded Source

Built Distribution

cyclonedx_python_lib-0.11.1-py3-none-any.whl (127.7 kB view hashes)

Uploaded Python 3

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page