cyclonedx.model.component

Module Contents

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.
Component	This is our internal representation of a Component within a Bom.

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.4/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

__eq__(other: object) → bool

Return self==value.

__lt__(other: Any) → bool

Return self<value.

__hash__() → int

Return hash(self).

__repr__() → str

Return repr(self).

class cyclonedx.model.component.ComponentEvidence(*, licenses: Iterable[cyclonedx.model.LicenseChoice] | 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.4/xml/#type_componentEvidenceType

property licenses: SortedSet[LicenseChoice]

Optional list of licenses obtained during analysis.

Returns:

Set of LicenseChoice

property copyright: SortedSet[Copyright]

Optional list of copyright statements.

Returns:

Set of Copyright

__eq__(other: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

__repr__() → str

Return repr(self).

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.3/#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.3/#type_classification

APPLICATION = 'application'

CONTAINER = 'container'

DEVICE = 'device'

FILE = 'file'

FIRMWARE = 'firmware'

FRAMEWORK = 'framework'

LIBRARY = 'library'

OPERATING_SYSTEM = 'operating-system'

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.4/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

__eq__(other: object) → bool

Return self==value.

__lt__(other: Any) → bool

Return self<value.

__hash__() → int

Return hash(self).

__repr__() → str

Return repr(self).

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.4/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.4/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.

Note

Refer to https://en.wikipedia.org/wiki/Diff.

Returns:

Diff if set else None

property resolves: SortedSet[IssueType]

Optional list of issues resolved by this patch.

Returns:

Set of IssueType

__eq__(other: object) → bool

Return self==value.

__lt__(other: Any) → bool

Return self<value.

__hash__() → int

Return hash(self).

__repr__() → str

Return repr(self).

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.4/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

__eq__(other: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

__repr__() → str

Return repr(self).

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.4/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

__eq__(other: object) → bool

Return self==value.

__hash__() → int

Return hash(self).

__repr__() → str

Return repr(self).

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.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.