cyclonedx.model.component

Classes

Commit

Our internal representation of the commitType complex type.

ComponentEvidence

Our internal representation of the componentEvidenceType complex type.

ComponentScope

Enum object that defines the permissable 'scopes' for a Component according to the CycloneDX schema.

ComponentType

Enum object that defines the permissible 'types' for a Component according to the CycloneDX schema.

Diff

Our internal representation of the diffType complex type.

PatchClassification

Enum object that defines the permissible `patchClassification`s.

Patch

Our internal representation of the patchType complex type.

Pedigree

Our internal representation of the pedigreeType complex type.

Swid

Our internal representation of the swidType complex type.

OmniborId

Helper class that allows us to perform validation on data strings that must conform to

Swhid

Helper class that allows us to perform validation on data strings that must conform to

Component

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

Module Contents

class cyclonedx.model.component.Commit(*, uid: str | None = None, url: cyclonedx.model.XsUri | None = None, author: cyclonedx.model.IdentifiableAction | None = None, committer: cyclonedx.model.IdentifiableAction | None = None, message: str | None = None)

Our internal representation of the commitType complex type.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/xml/#type_commitType

property uid: str | None

A unique identifier of the commit. This may be version control specific. For example, Subversion uses revision numbers whereas git uses commit hashes.

Returns:

str if set else None

property url: cyclonedx.model.XsUri | None

The URL to the commit. This URL will typically point to a commit in a version control system.

Returns:

XsUri if set else None

property author: cyclonedx.model.IdentifiableAction | None

The author who created the changes in the commit.

Returns:

IdentifiableAction if set else None

property committer: cyclonedx.model.IdentifiableAction | None

The person who committed or pushed the commit

Returns:

IdentifiableAction if set else None

property message: str | None

The text description of the contents of the commit.

Returns:

str if set else None

class cyclonedx.model.component.ComponentEvidence(*, licenses: Iterable[cyclonedx.model.license.License] | None = None, copyright: Iterable[cyclonedx.model.Copyright] | None = None)

Our internal representation of the componentEvidenceType complex type.

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

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/xml/#type_componentEvidenceType

property licenses: cyclonedx.model.license.LicenseRepository

Optional list of licenses obtained during analysis.

Returns:

Set of LicenseChoice

property copyright: SortedSet[Copyright]

Optional list of copyright statements.

Returns:

Set of Copyright

class cyclonedx.model.component.ComponentScope

Bases: str, enum.Enum

Enum object that defines the permissable ‘scopes’ for a Component according to the CycloneDX schema.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/#type_scope

REQUIRED = 'required'
OPTIONAL = 'optional'
EXCLUDED = 'excluded'
class cyclonedx.model.component.ComponentType

Bases: str, enum.Enum

Enum object that defines the permissible ‘types’ for a Component according to the CycloneDX schema.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/#type_classification

APPLICATION = 'application'
CONTAINER = 'container'
CRYPTOGRAPHIC_ASSET = 'cryptographic-asset'
DATA = 'data'
DEVICE = 'device'
DEVICE_DRIVER = 'device-driver'
FILE = 'file'
FIRMWARE = 'firmware'
FRAMEWORK = 'framework'
LIBRARY = 'library'
MACHINE_LEARNING_MODEL = 'machine-learning-model'
OPERATING_SYSTEM = 'operating-system'
PLATFORM = 'platform'
class cyclonedx.model.component.Diff(*, text: cyclonedx.model.AttachedText | None = None, url: cyclonedx.model.XsUri | None = None)

Our internal representation of the diffType complex type.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/xml/#type_diffType

property text: cyclonedx.model.AttachedText | None

Specifies the optional text of the diff.

Returns:

AttachedText if set else None

property url: cyclonedx.model.XsUri | None

Specifies the URL to the diff.

Returns:

XsUri if set else None

class cyclonedx.model.component.PatchClassification

Bases: str, enum.Enum

Enum object that defines the permissible `patchClassification`s.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/xml/#type_patchClassification

BACKPORT = 'backport'
CHERRY_PICK = 'cherry-pick'
MONKEY = 'monkey'
UNOFFICIAL = 'unofficial'
class cyclonedx.model.component.Patch(*, type: PatchClassification, diff: Diff | None = None, resolves: Iterable[cyclonedx.model.issue.IssueType] | None = None)

Our internal representation of the patchType complex type.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/xml/#type_patchType

property type: PatchClassification

Specifies the purpose for the patch including the resolution of defects, security issues, or new behavior or functionality.

Returns:

PatchClassification

property diff: Diff | None

The patch file (or diff) that show changes.

Returns:

Diff if set else None

property resolves: SortedSet[IssueType]

Optional list of issues resolved by this patch.

Returns:

Set of IssueType

class cyclonedx.model.component.Pedigree(*, ancestors: Iterable[Component] | None = None, descendants: Iterable[Component] | None = None, variants: Iterable[Component] | None = None, commits: Iterable[Commit] | None = None, patches: Iterable[Patch] | None = None, notes: str | None = None)

Our internal representation of the pedigreeType complex type.

Component pedigree is a way to document complex supply chain scenarios where components are created, distributed, modified, redistributed, combined with other components, etc. Pedigree supports viewing this complex chain from the beginning, the end, or anywhere in the middle. It also provides a way to document variants where the exact relation may not be known.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/xml/#type_pedigreeType

property ancestors: SortedSet['Component']

Describes zero or more components in which a component is derived from. This is commonly used to describe forks from existing projects where the forked version contains a ancestor node containing the original component it was forked from.

For example, Component A is the original component. Component B is the component being used and documented in the BOM. However, Component B contains a pedigree node with a single ancestor documenting Component A - the original component from which Component B is derived from.

Returns:

Set of Component

property descendants: SortedSet['Component']

Descendants are the exact opposite of ancestors. This provides a way to document all forks (and their forks) of an original or root component.

Returns:

Set of Component

property variants: SortedSet['Component']

Variants describe relations where the relationship between the components are not known. For example, if Component A contains nearly identical code to Component B. They are both related, but it is unclear if one is derived from the other, or if they share a common ancestor.

Returns:

Set of Component

property commits: SortedSet[Commit]

A list of zero or more commits which provide a trail describing how the component deviates from an ancestor, descendant, or variant.

Returns:

Set of Commit

property patches: SortedSet[Patch]

A list of zero or more patches describing how the component deviates from an ancestor, descendant, or variant. Patches may be complimentary to commits or may be used in place of commits.

Returns:

Set of Patch

property notes: str | None

Notes, observations, and other non-structured commentary describing the components pedigree.

Returns:

str if set else None

class cyclonedx.model.component.Swid(*, tag_id: str, name: str, version: str | None = None, tag_version: int | None = None, patch: bool | None = None, text: cyclonedx.model.AttachedText | None = None, url: cyclonedx.model.XsUri | None = None)

Our internal representation of the swidType complex type.

Note

See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.6/xml/#type_swidType

property tag_id: str

Maps to the tagId of a SoftwareIdentity.

Returns:

str

property name: str

Maps to the name of a SoftwareIdentity.

Returns:

str

property version: str | None

Maps to the version of a SoftwareIdentity.

Returns:

str if set else None.

property tag_version: int | None

Maps to the tagVersion of a SoftwareIdentity.

Returns:

int if set else None

property patch: bool | None

Maps to the patch of a SoftwareIdentity.

Returns:

bool if set else None

property text: cyclonedx.model.AttachedText | None

Specifies the full content of the SWID tag.

Returns:

AttachedText if set else None

property url: cyclonedx.model.XsUri | None

The URL to the SWID file.

Returns:

XsUri if set else None

class cyclonedx.model.component.OmniborId(id: str)

Bases: py_serializable.helpers.BaseHelper

Helper class that allows us to perform validation on data strings that must conform to https://www.iana.org/assignments/uri-schemes/prov/gitoid.

property id: str
classmethod serialize(o: Any) str

general purpose serializer

classmethod deserialize(o: Any) OmniborId

general purpose deserializer

classmethod json_normalize(o: Any, *, view: Type[py_serializable.ViewType] | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) Any | None

json specific normalizer

classmethod json_serialize(o: Any) str | Any

json specific serializer

classmethod json_denormalize(o: Any, *, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) Any

json specific denormalizer

Parameters:
  • tCls – the class that was desired to denormalize to

  • pCls – tha prent class - as context

classmethod json_deserialize(o: Any) Any

json specific deserializer

classmethod xml_normalize(o: Any, *, element_name: str, view: Type[py_serializable.ViewType] | None, xmlns: str | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) xml.etree.ElementTree.Element | Any | None

xml specific normalizer

classmethod xml_serialize(o: Any) str | Any

xml specific serializer

classmethod xml_denormalize(o: xml.etree.ElementTree.Element, *, default_ns: str | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) Any

xml specific denormalizer

classmethod xml_deserialize(o: str | Any) Any

xml specific deserializer

class cyclonedx.model.component.Swhid(id: str)

Bases: py_serializable.helpers.BaseHelper

Helper class that allows us to perform validation on data strings that must conform to https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html.

property id: str
classmethod serialize(o: Any) str

general purpose serializer

classmethod deserialize(o: Any) Swhid

general purpose deserializer

classmethod json_normalize(o: Any, *, view: Type[py_serializable.ViewType] | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) Any | None

json specific normalizer

classmethod json_serialize(o: Any) str | Any

json specific serializer

classmethod json_denormalize(o: Any, *, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) Any

json specific denormalizer

Parameters:
  • tCls – the class that was desired to denormalize to

  • pCls – tha prent class - as context

classmethod json_deserialize(o: Any) Any

json specific deserializer

classmethod xml_normalize(o: Any, *, element_name: str, view: Type[py_serializable.ViewType] | None, xmlns: str | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) xml.etree.ElementTree.Element | Any | None

xml specific normalizer

classmethod xml_serialize(o: Any) str | Any

xml specific serializer

classmethod xml_denormalize(o: xml.etree.ElementTree.Element, *, default_ns: str | None, prop_info: py_serializable.ObjectMetadataLibrary.SerializableProperty, ctx: Type[Any], **kwargs: Any) Any

xml specific denormalizer

classmethod xml_deserialize(o: str | Any) Any

xml specific deserializer

class cyclonedx.model.component.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.contact.OrganizationalEntity | 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.license.License] | 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, manufacturer: cyclonedx.model.contact.OrganizationalEntity | None = None, authors: Iterable[cyclonedx.model.contact.OrganizationalContact] | None = None, omnibor_ids: Iterable[OmniborId] | None = None, swhids: Iterable[Swhid] | None = None, crypto_properties: cyclonedx.model.crypto.CryptoProperties | None = None, tags: Iterable[str] | None = None, author: 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.6/#type_component

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

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 supplier: cyclonedx.model.contact.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 manufacturer: cyclonedx.model.contact.OrganizationalEntity | None

The organization that created the component. Manufacturer is common in components created through automated processes. Components created through manual means may have @.authors instead.

Returns:

OrganizationalEntity if set else None

property authors: SortedSet[OrganizationalContact]

The person(s) who created the component. Authors are common in components created through manual processes. Components created through automated means may have @.manufacturer instead.

Returns:

Iterable[OrganizationalContact] 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: cyclonedx.model.license.LicenseRepository

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 omnibor_ids: SortedSet[OmniborId]

Specifies the OmniBOR Artifact ID. The OmniBOR, if specified, MUST be valid and conform to the specification defined at: https://www.iana.org/assignments/uri-schemes/prov/gitoid

Returns:

Iterable[str] or None

property swhids: SortedSet[Swhid]

Specifies the Software Heritage persistent identifier (SWHID). The SWHID, if specified, MUST be valid and conform to the specification defined at: https://docs.softwareheritage.org/devel/swh-model/persistent-identifiers.html

Returns:

Iterable[Swhid] if set else 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

property crypto_properties: cyclonedx.model.crypto.CryptoProperties | None

Cryptographic assets have properties that uniquely define them and that make them actionable for further reasoning. As an example, it makes a difference if one knows the algorithm family (e.g. AES) or the specific variant or instantiation (e.g. AES-128-GCM). This is because the security level and the algorithm primitive (authenticated encryption) is only defined by the definition of the algorithm variant. The presence of a weak cryptographic algorithm like SHA1 vs. HMAC-SHA1 also makes a difference.

Returns:

CryptoProperties or None

property tags: SortedSet[str]

Textual strings that aid in discovery, search, and retrieval of the associated object. Tags often serve as a way to group or categorize similar or related objects by various attributes.

Returns:

Iterable[str]

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.

Returns:

BomRef

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