cyclonedx.model.component ========================= .. py:module:: cyclonedx.model.component Classes ------- .. autoapisummary:: cyclonedx.model.component.Commit cyclonedx.model.component.ComponentScope cyclonedx.model.component.ComponentType cyclonedx.model.component.Diff cyclonedx.model.component.PatchClassification cyclonedx.model.component.Patch cyclonedx.model.component.Pedigree cyclonedx.model.component.Swid cyclonedx.model.component.OmniborId cyclonedx.model.component.Swhid cyclonedx.model.component.Component Module Contents --------------- .. py:class:: Commit(*, uid: Optional[str] = None, url: Optional[cyclonedx.model.XsUri] = None, author: Optional[cyclonedx.model.IdentifiableAction] = None, committer: Optional[cyclonedx.model.IdentifiableAction] = None, message: Optional[str] = None) Our internal representation of the `commitType` complex type. .. note:: See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_commitType .. py:property:: uid :type: Optional[str] 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` .. py:property:: url :type: Optional[cyclonedx.model.XsUri] The URL to the commit. This URL will typically point to a commit in a version control system. Returns: `XsUri` if set else `None` .. py:property:: author :type: Optional[cyclonedx.model.IdentifiableAction] The author who created the changes in the commit. Returns: `IdentifiableAction` if set else `None` .. py:property:: committer :type: Optional[cyclonedx.model.IdentifiableAction] The person who committed or pushed the commit Returns: `IdentifiableAction` if set else `None` .. py:property:: message :type: Optional[str] The text description of the contents of the commit. Returns: `str` if set else `None` .. py:class:: ComponentScope Bases: :py:obj:`str`, :py:obj:`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.7/xml/#type_scope .. py:attribute:: REQUIRED :value: 'required' .. py:attribute:: OPTIONAL :value: 'optional' .. py:attribute:: EXCLUDED :value: 'excluded' .. py:class:: ComponentType Bases: :py:obj:`str`, :py:obj:`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.7/xml/#type_classification .. py:attribute:: APPLICATION :value: 'application' .. py:attribute:: CONTAINER :value: 'container' .. py:attribute:: CRYPTOGRAPHIC_ASSET :value: 'cryptographic-asset' .. py:attribute:: DATA :value: 'data' .. py:attribute:: DEVICE :value: 'device' .. py:attribute:: DEVICE_DRIVER :value: 'device-driver' .. py:attribute:: FILE :value: 'file' .. py:attribute:: FIRMWARE :value: 'firmware' .. py:attribute:: FRAMEWORK :value: 'framework' .. py:attribute:: LIBRARY :value: 'library' .. py:attribute:: MACHINE_LEARNING_MODEL :value: 'machine-learning-model' .. py:attribute:: OPERATING_SYSTEM :value: 'operating-system' .. py:attribute:: PLATFORM :value: 'platform' .. py:class:: Diff(*, text: Optional[cyclonedx.model.AttachedText] = None, url: Optional[cyclonedx.model.XsUri] = None) Our internal representation of the `diffType` complex type. .. note:: See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_diffType .. py:property:: text :type: Optional[cyclonedx.model.AttachedText] Specifies the optional text of the diff. Returns: `AttachedText` if set else `None` .. py:property:: url :type: Optional[cyclonedx.model.XsUri] Specifies the URL to the diff. Returns: `XsUri` if set else `None` .. py:class:: PatchClassification Bases: :py:obj:`str`, :py:obj:`enum.Enum` Enum object that defines the permissible `patchClassification`s. .. note:: See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_patchClassification .. py:attribute:: BACKPORT :value: 'backport' .. py:attribute:: CHERRY_PICK :value: 'cherry-pick' .. py:attribute:: MONKEY :value: 'monkey' .. py:attribute:: UNOFFICIAL :value: 'unofficial' .. py:class:: Patch(*, type: PatchClassification, diff: Optional[Diff] = None, resolves: Optional[collections.abc.Iterable[cyclonedx.model.issue.IssueType]] = None) Our internal representation of the `patchType` complex type. .. note:: See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_patchType .. py:property:: type :type: PatchClassification Specifies the purpose for the patch including the resolution of defects, security issues, or new behavior or functionality. Returns: `PatchClassification` .. py:property:: diff :type: Optional[Diff] The patch file (or diff) that show changes. .. note:: Refer to https://en.wikipedia.org/wiki/Diff. Returns: `Diff` if set else `None` .. py:property:: resolves :type: SortedSet[IssueType] Optional list of issues resolved by this patch. Returns: Set of `IssueType` .. py:class:: Pedigree(*, ancestors: Optional[collections.abc.Iterable[Component]] = None, descendants: Optional[collections.abc.Iterable[Component]] = None, variants: Optional[collections.abc.Iterable[Component]] = None, commits: Optional[collections.abc.Iterable[Commit]] = None, patches: Optional[collections.abc.Iterable[Patch]] = None, notes: Optional[str] = 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.7/xml/#type_pedigreeType .. py:property:: ancestors :type: 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` .. py:property:: descendants :type: 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` .. py:property:: variants :type: 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` .. py:property:: commits :type: 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` .. py:property:: patches :type: 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` .. py:property:: notes :type: Optional[str] Notes, observations, and other non-structured commentary describing the components pedigree. Returns: `str` if set else `None` .. py:class:: Swid(*, tag_id: str, name: str, version: Optional[str] = None, tag_version: Optional[int] = None, patch: Optional[bool] = None, text: Optional[cyclonedx.model.AttachedText] = None, url: Optional[cyclonedx.model.XsUri] = None) Our internal representation of the `swidType` complex type. .. note:: See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_swidType .. py:property:: tag_id :type: str Maps to the tagId of a SoftwareIdentity. Returns: `str` .. py:property:: name :type: str Maps to the name of a SoftwareIdentity. Returns: `str` .. py:property:: version :type: Optional[str] Maps to the version of a SoftwareIdentity. Returns: `str` if set else `None`. .. py:property:: tag_version :type: Optional[int] Maps to the tagVersion of a SoftwareIdentity. Returns: `int` if set else `None` .. py:property:: patch :type: Optional[bool] Maps to the patch of a SoftwareIdentity. Returns: `bool` if set else `None` .. py:property:: text :type: Optional[cyclonedx.model.AttachedText] Specifies the full content of the SWID tag. Returns: `AttachedText` if set else `None` .. py:property:: url :type: Optional[cyclonedx.model.XsUri] The URL to the SWID file. Returns: `XsUri` if set else `None` .. py:class:: OmniborId(id: str) Bases: :py:obj:`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. .. py:property:: id :type: str .. py:method:: serialize(o: Any) -> str :classmethod: .. py:method:: deserialize(o: Any) -> OmniborId :classmethod: .. py:class:: Swhid(id: str) Bases: :py:obj:`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. .. py:property:: id :type: str .. py:method:: serialize(o: Any) -> str :classmethod: .. py:method:: deserialize(o: Any) -> Swhid :classmethod: .. py:class:: Component(*, name: str, type: ComponentType = ComponentType.LIBRARY, mime_type: Optional[str] = None, bom_ref: Optional[Union[str, cyclonedx.model.bom_ref.BomRef]] = None, supplier: Optional[cyclonedx.model.contact.OrganizationalEntity] = None, publisher: Optional[str] = None, group: Optional[str] = None, version: Optional[str] = None, description: Optional[str] = None, scope: Optional[ComponentScope] = None, hashes: Optional[collections.abc.Iterable[cyclonedx.model.HashType]] = None, licenses: Optional[collections.abc.Iterable[cyclonedx.model.license.License]] = None, copyright: Optional[str] = None, purl: Optional[packageurl.PackageURL] = None, external_references: Optional[collections.abc.Iterable[cyclonedx.model.ExternalReference]] = None, properties: Optional[collections.abc.Iterable[cyclonedx.model.Property]] = None, release_notes: Optional[cyclonedx.model.release_note.ReleaseNotes] = None, cpe: Optional[str] = None, swid: Optional[Swid] = None, pedigree: Optional[Pedigree] = None, components: Optional[collections.abc.Iterable[Component]] = None, evidence: Optional[cyclonedx.model.component_evidence.ComponentEvidence] = None, modified: bool = False, manufacturer: Optional[cyclonedx.model.contact.OrganizationalEntity] = None, authors: Optional[collections.abc.Iterable[cyclonedx.model.contact.OrganizationalContact]] = None, omnibor_ids: Optional[collections.abc.Iterable[OmniborId]] = None, swhids: Optional[collections.abc.Iterable[Swhid]] = None, crypto_properties: Optional[cyclonedx.model.crypto.CryptoProperties] = None, tags: Optional[collections.abc.Iterable[str]] = None, author: Optional[str] = None) Bases: :py:obj:`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.7/xml/#type_component .. py:method:: for_file(absolute_file_path: str, path_for_bom: Optional[str]) -> Component :staticmethod: Deprecated — Wrapper of :func:`cyclonedx.contrib.component.builders.ComponentBuilder.make_for_file`. Helper method to create a Component that represents the provided local file as a Component. .. deprecated:: next Use ``cyclonedx.contrib.component.builders.ComponentBuilder.make_for_file()`` instead. .. py:property:: type :type: ComponentType Get the type of this Component. Returns: Declared type of this Component as `ComponentType`. .. py:property:: mime_type :type: Optional[str] 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` .. py:property:: supplier :type: Optional[cyclonedx.model.contact.OrganizationalEntity] 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` .. py:property:: manufacturer :type: Optional[cyclonedx.model.contact.OrganizationalEntity] 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` .. py:property:: authors :type: 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` .. py:property:: publisher :type: Optional[str] The person(s) or organization(s) that published the component Returns: `str` if set else `None` .. py:property:: group :type: Optional[str] 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` .. py:property:: name :type: str The name of the component. This will often be a shortened, single name of the component. Examples: `commons-lang3` and `jquery`. Returns: `str` .. py:property:: description :type: Optional[str] Get the description of this Component. Returns: `str` if set, else `None`. .. py:property:: scope :type: Optional[ComponentScope] 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` .. py:property:: hashes :type: SortedSet[HashType] Optional list of hashes that help specify the integrity of this Component. Returns: Set of `HashType` .. py:property:: licenses :type: cyclonedx.model.license.LicenseRepository A optional list of statements about how this Component is licensed. Returns: Set of `LicenseChoice` .. py:property:: copyright :type: Optional[str] An optional copyright notice informing users of the underlying claims to copyright ownership in a published work. Returns: `str` or `None` .. py:property:: cpe :type: Optional[str] 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` .. py:property:: purl :type: Optional[packageurl.PackageURL] 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` .. py:property:: omnibor_ids :type: 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` .. py:property:: swhids :type: 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` .. py:property:: swid :type: Optional[Swid] Specifies metadata and content for ISO-IEC 19770-2 Software Identification (SWID) Tags. Returns: `Swid` if set else `None` .. py:property:: pedigree :type: Optional[Pedigree] 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` .. py:property:: external_references :type: SortedSet[ExternalReference] Provides the ability to document external references related to the component or to the project the component describes. Returns: Set of `ExternalReference` .. py:property:: properties :type: 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` .. py:property:: components :type: 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` .. py:property:: evidence :type: Optional[cyclonedx.model.component_evidence.ComponentEvidence] Provides the ability to document evidence collected through various forms of extraction or analysis. Returns: `ComponentEvidence` if set else `None` .. py:property:: release_notes :type: Optional[cyclonedx.model.release_note.ReleaseNotes] Specifies optional release notes. Returns: `ReleaseNotes` or `None` .. py:property:: crypto_properties :type: Optional[cyclonedx.model.crypto.CryptoProperties] 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` .. py:property:: tags :type: 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]` .. py:property:: author :type: Optional[str] The person(s) or organization(s) that authored the component. Returns: `str` if set else `None` .. py:property:: modified :type: bool .. py:property:: version :type: Optional[str] 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` .. py:property:: bom_ref :type: 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` .. py:method:: get_all_nested_components(include_self: bool = False) -> set[Component] .. py:method:: get_pypi_url() -> str