A library for producing CycloneDX SBOM (Software Bill of Materials) files.
Project description
Python Library for generating CycloneDX
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:
- Parser: Use a parser that suits your needs to automatically gather information about your environment or application
- Model: Internal models used to unify data from different parsers
- 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:
- Output to string (for you to do with as you require)
- 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 |
Y | Y | Y | Y | This is the root element and is supported with all it's defined attributes. |
/bom/metadata |
Y | Y | N/A | N/A |
timestamp and tools are currently supported
|
/bom/components |
Y | Y | Y | Y | |
/bom/components/component |
|||||
./author |
Y | Y | N/A | N/A | |
./name |
Y | Y | Y | Y | |
./version |
Y | Y | Y | Y | |
./purl |
Y | Y | Y | Y | |
./externalReferences |
Y | Y | Y | N/A | Not all Parsers have this information. It will be populated where there is information available. |
./hashes |
Y | Y | Y | Y |
These are supported when programmatically creating a Bom - these will not currently be
automatically populated when using a Parser.
|
Notes on Schema Support
- N/A is where the CycloneDX standard does not include this
- 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
Built Distribution
File details
Details for the file cyclonedx-python-lib-0.10.0.tar.gz.
File metadata
- Download URL: cyclonedx-python-lib-0.10.0.tar.gz
- Upload date:
- Size: 96.8 kB
- Tags: Source
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 645612e9f08513d96115eece19b64cce99e538929b3c99e77fac8b564acde2db |
|
| MD5 | 822ecf51964d8f3eb25db6ee684d47ef |
|
| BLAKE2b-256 | aecc6c158a3927b6924f9a0f3351ca6fbf5519fe9ad7231fc20b87abcb9c10fe |
Provenance
File details
Details for the file cyclonedx_python_lib-0.10.0-py3-none-any.whl.
File metadata
- Download URL: cyclonedx_python_lib-0.10.0-py3-none-any.whl
- Upload date:
- Size: 125.3 kB
- Tags: Python 3
- Uploaded using Trusted Publishing? No
- Uploaded via: twine/3.4.2 importlib_metadata/4.8.1 pkginfo/1.7.1 requests/2.26.0 requests-toolbelt/0.9.1 tqdm/4.62.3 CPython/3.9.7
File hashes
| Algorithm | Hash digest | |
|---|---|---|
| SHA256 | 3b799b0b97fde4c6399a839bd8bc87ff854ccaaad99e835203a8b081f2923147 |
|
| MD5 | ea332e191eb969f94114dfbe1d159dc5 |
|
| BLAKE2b-256 | ffbfbc1a2379e937b8d34c62112b6ee5cb7e09f2388fd14f9b34f1bdc3260a12 |
