cyclonedx.model.component
Classes
Our internal representation of the commitType complex type. |
|
Our internal representation of the componentEvidenceType complex type. |
|
Enum object that defines the permissable 'scopes' for a Component according to the CycloneDX schema. |
|
Enum object that defines the permissible 'types' for a Component according to the CycloneDX schema. |
|
Our internal representation of the diffType complex type. |
|
Enum object that defines the permissible `patchClassification`s. |
|
Our internal representation of the patchType complex type. |
|
Our internal representation of the pedigreeType complex type. |
|
Our internal representation of the swidType complex type. |
|
Helper class that allows us to perform validation on data strings that must conform to |
|
Helper class that allows us to perform validation on data strings that must conform to |
|
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
- 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.
Note
Refer to https://en.wikipedia.org/wiki/Diff.
- Returns:
Diff if set else None
- 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 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 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_pypi_url() str