cyclonedx.output

Set of classes and methods for outputting our libraries internal Bom model to CycloneDX documents in varying formats and according to different versions of the CycloneDX schema standard.

Submodules

• cyclonedx.output.json
• cyclonedx.output.xml

Package Contents

Classes

Bom	This is our internal representation of a bill-of-materials (BOM).
Component	This is our internal representation of a Component within a Bom.
OutputFormat	str(object='') -> str
SchemaVersion	str(object='') -> str
BaseOutput	Helper class that provides a standard way to create an ABC using

Functions

get_instance(→ BaseOutput)

Helper method to quickly get the correct output class/formatter.

Attributes

LATEST_SUPPORTED_SCHEMA_VERSION

class cyclonedx.output.Bom(*, components: Iterable[cyclonedx.model.component.Component] | None = None, services: Iterable[cyclonedx.model.service.Service] | None = None, external_references: Iterable[cyclonedx.model.ExternalReference] | None = None, serial_number: uuid.UUID | None = None, version: int = 1, metadata: BomMetaData | None = None, dependencies: Iterable[cyclonedx.model.dependency.Dependency] | None = None, vulnerabilities: Iterable[cyclonedx.model.vulnerability.Vulnerability] | None = None)

This is our internal representation of a bill-of-materials (BOM).

You can either create a cyclonedx.model.bom.Bom yourself programmatically, or generate a cyclonedx.model.bom.Bom from a cyclonedx.parser.BaseParser implementation.

Once you have an instance of cyclonedx.model.bom.Bom, you can pass this to an instance of cyclonedx.output.BaseOutput to produce a CycloneDX document according to a specific schema version and format.

property serial_number: uuid.UUID

Unique UUID for this BOM

Returns:

UUID instance UUID instance

property metadata: BomMetaData

Get our internal metadata object for this Bom.

Returns:

Metadata object instance for this Bom.

Note

See the CycloneDX Schema for Bom metadata: https://cyclonedx.org/docs/1.3/#type_metadata

property components: SortedSet[Component]

Get all the Components currently in this Bom.

Returns:

Set of Component in this Bom

property services: SortedSet[Service]

Get all the Services currently in this Bom.

Returns:

Set of Service in this BOM

property external_references: SortedSet[ExternalReference]

Provides the ability to document external references related to the BOM or to the project the BOM describes.

Returns:

Set of ExternalReference

property vulnerabilities: SortedSet[Vulnerability]

Get all the Vulnerabilities in this BOM.

Returns:

Set of Vulnerability

property version: int

property dependencies: SortedSet[Dependency]

static from_parser(parser: cyclonedx.parser.BaseParser) → Bom

Create a Bom instance from a Parser object.

Args:

parser (cyclonedx.parser.BaseParser): A valid parser instance.

Returns:

cyclonedx.model.bom.Bom: A Bom instance that represents the valid data held in the supplied parser.

get_component_by_purl(purl: packageurl.PackageURL | None) → cyclonedx.model.component.Component | None

Get a Component already in the Bom by its PURL

Args:

purl:

An instance of packageurl.PackageURL to look and find Component.

Returns:

Component or None

get_urn_uuid() → str

Get the unique reference for this Bom.

Returns:

URN formatted UUID that uniquely identified this Bom instance.

has_component(component: cyclonedx.model.component.Component) → bool

Check whether this Bom contains the provided Component.

Args:

component:

The instance of cyclonedx.model.component.Component to check if this Bom contains.

Returns:

bool - True if the supplied Component is part of this Bom, False otherwise.

_get_all_components() → Set[cyclonedx.model.component.Component]

get_vulnerabilities_for_bom_ref(bom_ref: cyclonedx.model.bom_ref.BomRef) → SortedSet[Vulnerability]

Get all known Vulnerabilities that affect the supplied bom_ref.

Args:

bom_ref: BomRef

Returns:

SortedSet of Vulnerability

has_vulnerabilities() → bool

Check whether this Bom has any declared vulnerabilities.

Returns:

bool - True if this Bom has at least one Vulnerability, False otherwise.

register_dependency(target: cyclonedx.model.dependency.Dependable, depends_on: Iterable[cyclonedx.model.dependency.Dependable] | None = None) → None

urn() → str

validate() → bool

Perform data-model level validations to make sure we have some known data integrity prior to attempting output of this Bom

Returns:

bool

__eq__(other: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

__repr__() → str

Return repr(self).

class cyclonedx.output.Component(*, name: str, type: ComponentType = ComponentType.LIBRARY, mime_type: str | None = None, bom_ref: str | cyclonedx.model.bom_ref.BomRef | None = None, supplier: cyclonedx.model.OrganizationalEntity | None = None, author: str | None = None, publisher: str | None = None, group: str | None = None, version: str | None = None, description: str | None = None, scope: ComponentScope | None = None, hashes: Iterable[cyclonedx.model.HashType] | None = None, licenses: Iterable[cyclonedx.model.LicenseChoice] | None = None, copyright: str | None = None, purl: packageurl.PackageURL | None = None, external_references: Iterable[cyclonedx.model.ExternalReference] | None = None, properties: Iterable[cyclonedx.model.Property] | None = None, release_notes: cyclonedx.model.release_note.ReleaseNotes | None = None, cpe: str | None = None, swid: Swid | None = None, pedigree: Pedigree | None = None, components: Iterable[Component] | None = None, evidence: ComponentEvidence | None = None, modified: bool = False, namespace: str | None = None, license_str: str | None = None)

Bases: cyclonedx.model.dependency.Dependable

This is our internal representation of a Component within a Bom.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.3/#type_component

property type: ComponentType

Get the type of this Component.

Returns:

Declared type of this Component as ComponentType.

property mime_type: str | None

Get any declared mime-type for this Component.

When used on file components, the mime-type can provide additional context about the kind of file being represented such as an image, font, or executable. Some library or framework components may also have an associated mime-type.

Returns:

str if set else None

property bom_ref: cyclonedx.model.bom_ref.BomRef

An optional identifier which can be used to reference the component elsewhere in the BOM. Every bom-ref MUST be unique within the BOM.

If a value was not provided in the constructor, a UUIDv4 will have been assigned.

Returns:

BomRef

property supplier: cyclonedx.model.OrganizationalEntity | None

The organization that supplied the component. The supplier may often be the manufacture, but may also be a distributor or repackager.

Returns:

OrganizationalEntity if set else None

property author: str | None

The person(s) or organization(s) that authored the component.

Returns:

str if set else None

property publisher: str | None

The person(s) or organization(s) that published the component

Returns:

str if set else None

property group: str | None

The grouping name or identifier. This will often be a shortened, single name of the company or project that produced the component, or the source package or domain name. Whitespace and special characters should be avoided.

Examples include: apache, org.apache.commons, and apache.org.

Returns:

str if set else None

property name: str

The name of the component.

This will often be a shortened, single name of the component.

Examples: commons-lang3 and jquery.

Returns:

str

property version: str | None

The component version. The version should ideally comply with semantic versioning but is not enforced.

This is NOT optional for CycloneDX Schema Version < 1.4 but was agreed to default to an empty string where a version was not supplied for schema versions < 1.4

Returns:

Declared version of this Component as str or None

property description: str | None

Get the description of this Component.

Returns:

str if set, else None.

property scope: ComponentScope | None

Specifies the scope of the component.

If scope is not specified, ‘required’ scope should be assumed by the consumer of the BOM.

Returns:

ComponentScope or None

property hashes: SortedSet[HashType]

Optional list of hashes that help specify the integrity of this Component.

Returns:

Set of HashType

property licenses: SortedSet[LicenseChoice]

A optional list of statements about how this Component is licensed.

Returns:

Set of LicenseChoice

property copyright: str | None

An optional copyright notice informing users of the underlying claims to copyright ownership in a published work.

Returns:

str or None

property cpe: str | None

Specifies a well-formed CPE name that conforms to the CPE 2.2 or 2.3 specification. See https://nvd.nist.gov/products/cpe

Returns:

str if set else None

property purl: packageurl.PackageURL | None

Specifies the package-url (PURL).

The purl, if specified, must be valid and conform to the specification defined at: https://github.com/package-url/purl-spec

Returns:

PackageURL or None

property swid: Swid | None

Specifies metadata and content for ISO-IEC 19770-2 Software Identification (SWID) Tags.

Returns:

Swid if set else None

property modified: bool

property pedigree: Pedigree | None

Component pedigree is a way to document complex supply chain scenarios where components are created, distributed, modified, redistributed, combined with other components, etc.

Returns:

Pedigree if set else None

property external_references: SortedSet[ExternalReference]

Provides the ability to document external references related to the component or to the project the component describes.

Returns:

Set of ExternalReference

property properties: SortedSet[Property]

Provides the ability to document properties in a key/value store. This provides flexibility to include data not officially supported in the standard without having to use additional namespaces or create extensions.

Return:

Set of Property

property components: SortedSet['Component']

A list of software and hardware components included in the parent component. This is not a dependency tree. It provides a way to specify a hierarchical representation of component assemblies, similar to system -> subsystem -> parts assembly in physical supply chains.

Returns:

Set of Component

property evidence: ComponentEvidence | None

Provides the ability to document evidence collected through various forms of extraction or analysis.

Returns:

ComponentEvidence if set else None

property release_notes: cyclonedx.model.release_note.ReleaseNotes | None

Specifies optional release notes.

Returns:

ReleaseNotes or None

static for_file(absolute_file_path: str, path_for_bom: str | None) → Component

Helper method to create a Component that represents the provided local file as a Component.

Args:

absolute_file_path:

Absolute path to the file you wish to represent

path_for_bom:

Optionally, if supplied this is the path that will be used to identify the file in the BOM

Returns:

Component representing the supplied file

get_all_nested_components(include_self: bool = False) → Set[Component]

get_pypi_url() → str

__eq__(other: object) → bool

Return self==value.

__lt__(other: Any) → bool

Return self<value.

__hash__() → int

Return hash(self).

__repr__() → str

Return repr(self).

get_namespace() → str | None

Get the namespace of this Component.

Returns:

Declared namespace of this Component as str if declared, else None.

class cyclonedx.output.OutputFormat

Bases: str, enum.Enum

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

JSON: str = 'Json'

XML: str = 'Xml'

class cyclonedx.output.SchemaVersion

Bases: str, enum.Enum

str(object=’’) -> str str(bytes_or_buffer[, encoding[, errors]]) -> str

Create a new string object from the given object. If encoding or errors is specified, then the object must expose a data buffer that will be decoded using the given encoding and error handler. Otherwise, returns the result of object.__str__() (if defined) or repr(object). encoding defaults to sys.getdefaultencoding(). errors defaults to ‘strict’.

V1_0: str = 'V1Dot0'

V1_1: str = 'V1Dot1'

V1_2: str = 'V1Dot2'

V1_3: str = 'V1Dot3'

V1_4: str = 'V1Dot4'

to_version() → str

Return as a version string - e.g. 1.4

Returns:

str version

cyclonedx.output.LATEST_SUPPORTED_SCHEMA_VERSION

class cyclonedx.output.BaseOutput(bom: cyclonedx.model.bom.Bom, **kwargs: int)

Bases: abc.ABC

Helper class that provides a standard way to create an ABC using inheritance.

abstract property schema_version: cyclonedx.schema.SchemaVersion

property generated: bool

_chained_components(container: cyclonedx.model.bom.Bom | cyclonedx.model.component.Component) → Iterable[cyclonedx.model.component.Component]

get_bom() → cyclonedx.model.bom.Bom

set_bom(bom: cyclonedx.model.bom.Bom) → None

abstract generate(force_regeneration: bool = False) → None

abstract output_as_string() → str

output_to_file(filename: str, allow_overwrite: bool = False) → None

cyclonedx.output.get_instance(bom: cyclonedx.model.bom.Bom, output_format: cyclonedx.schema.OutputFormat = OutputFormat.XML, schema_version: cyclonedx.schema.SchemaVersion = LATEST_SUPPORTED_SCHEMA_VERSION) → BaseOutput

Helper method to quickly get the correct output class/formatter.

Pass in your BOM and optionally an output format and schema version (defaults to XML and latest schema version).

Parameters:

• bom – Bom

• output_format – OutputFormat

• schema_version – SchemaVersion

Returns: