cyclonedx.model.bom
===================

.. py:module:: cyclonedx.model.bom


Classes
-------

.. autoapisummary::

   cyclonedx.model.bom.TlpClassification
   cyclonedx.model.bom.DistributionConstraints
   cyclonedx.model.bom.BomMetaData
   cyclonedx.model.bom.Bom


Module Contents
---------------

.. py:class:: TlpClassification

   Bases: :py:obj:`str`, :py:obj:`enum.Enum`


   Enum object that defines the Traffic Light Protocol (TLP) classification that controls the sharing and distribution
   of the data that the BOM describes.

   .. note::
       Introduced in CycloneDX v1.7

   .. note::
       See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_tlpClassificationType


   .. py:attribute:: CLEAR
      :value: 'CLEAR'



   .. py:attribute:: GREEN
      :value: 'GREEN'



   .. py:attribute:: AMBER
      :value: 'AMBER'



   .. py:attribute:: AMBER_AND_STRICT
      :value: 'AMBER_AND_STRICT'



   .. py:attribute:: RED
      :value: 'RED'



.. py:class:: DistributionConstraints(*, tlp: Optional[TlpClassification] = None)

   Our internal representation of the `distributionConstraints` complex type.
   Conditions and constraints governing the sharing and distribution of the data or components described by this BOM.

   .. note::
       Introduced in CycloneDX v1.7

   .. note::
       See the CycloneDX Schema definition: https://cyclonedx.org/docs/1.7/xml/#type_metadata


   .. py:property:: tlp
      :type: TlpClassification


      The Traffic Light Protocol (TLP) classification that controls the sharing and distribution of the data that the
      BOM describes.

      Returns:
          `TlpClassification` enum value



.. py:class:: BomMetaData(*, tools: Optional[Union[collections.abc.Iterable[cyclonedx.model.tool.Tool], cyclonedx.model.tool.ToolRepository]] = None, authors: Optional[collections.abc.Iterable[cyclonedx.model.contact.OrganizationalContact]] = None, component: Optional[cyclonedx.model.component.Component] = None, supplier: Optional[cyclonedx.model.contact.OrganizationalEntity] = None, licenses: Optional[collections.abc.Iterable[cyclonedx.model.license.License]] = None, properties: Optional[collections.abc.Iterable[cyclonedx.model.Property]] = None, timestamp: Optional[datetime.datetime] = None, manufacturer: Optional[cyclonedx.model.contact.OrganizationalEntity] = None, lifecycles: Optional[collections.abc.Iterable[cyclonedx.model.lifecycle.Lifecycle]] = None, distribution_constraints: Optional[DistributionConstraints] = None, manufacture: Optional[cyclonedx.model.contact.OrganizationalEntity] = None)

   This is our internal representation of the metadata complex type within the CycloneDX standard.

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


   .. py:property:: timestamp
      :type: datetime.datetime


      The date and time (in UTC) when this BomMetaData was created.

      Returns:
          `datetime` instance in UTC timezone



   .. py:property:: tools
      :type: cyclonedx.model.tool.ToolRepository


      Tools used to create this BOM.

      Returns:
          :class:`ToolRepository` object.



   .. py:property:: authors
      :type: SortedSet[OrganizationalContact]


      The person(s) who created the BOM.

      Authors are common in BOMs created through manual processes.

      BOMs created through automated means may not have authors.

      Returns:
          Set of `OrganizationalContact`



   .. py:property:: component
      :type: Optional[cyclonedx.model.component.Component]


      The (optional) component that the BOM describes.

      Returns:
          `cyclonedx.model.component.Component` instance for this Bom Metadata.



   .. py:property:: supplier
      :type: Optional[cyclonedx.model.contact.OrganizationalEntity]


      The organization that supplied the component that the BOM describes.

      The supplier may often be the manufacturer, but may also be a distributor or repackager.

      Returns:
          `OrganizationalEntity` if set else `None`



   .. py:property:: licenses
      :type: cyclonedx.model.license.LicenseRepository


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

      Returns:
          Set of `LicenseChoice`



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

      Property names of interest to the general public are encouraged to be registered in the CycloneDX Property
      Taxonomy - https://github.com/CycloneDX/cyclonedx-property-taxonomy. Formal registration is OPTIONAL.

      Return:
          Set of `Property`



   .. py:property:: manufacturer
      :type: Optional[cyclonedx.model.contact.OrganizationalEntity]


      The organization that created the BOM.
      Manufacturer is common in BOMs created through automated processes. BOMs created through manual means may have
      `@.authors` instead.

      Returns:
          `OrganizationalEntity` if set else `None`



   .. py:property:: lifecycles
      :type: cyclonedx.model.lifecycle.LifecycleRepository


      An optional list of BOM lifecycle stages.

      Returns:
          Set of `Lifecycle`



   .. py:property:: distribution_constraints
      :type: Optional[DistributionConstraints]


      Conditions and constraints governing the sharing and distribution of the data or components described by this
      BOM.

      Returns:
          `DistributionConstraints` or `None`



   .. py:property:: manufacture
      :type: Optional[cyclonedx.model.contact.OrganizationalEntity]


      The organization that manufactured the component that the BOM describes.

      Returns:
          `OrganizationalEntity` if set else `None`



.. py:class:: Bom(*, components: Optional[collections.abc.Iterable[cyclonedx.model.component.Component]] = None, services: Optional[collections.abc.Iterable[cyclonedx.model.service.Service]] = None, external_references: Optional[collections.abc.Iterable[cyclonedx.model.ExternalReference]] = None, serial_number: Optional[uuid.UUID] = None, version: int = 1, metadata: Optional[BomMetaData] = None, dependencies: Optional[collections.abc.Iterable[cyclonedx.model.dependency.Dependency]] = None, vulnerabilities: Optional[collections.abc.Iterable[cyclonedx.model.vulnerability.Vulnerability]] = None, properties: Optional[collections.abc.Iterable[cyclonedx.model.Property]] = None, definitions: Optional[cyclonedx.model.definition.Definitions] = None)

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

   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.


   .. py:property:: serial_number
      :type: uuid.UUID


      Unique UUID for this BOM

      Returns:
          `UUID` instance
          `UUID` instance



   .. py:property:: version
      :type: int



   .. py:property:: metadata
      :type: 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.7/xml/#type_metadata



   .. py:property:: components
      :type: SortedSet[Component]


      Get all the Components currently in this Bom.

      Returns:
           Set of `Component` in this Bom



   .. py:property:: services
      :type: SortedSet[Service]


      Get all the Services currently in this Bom.

      Returns:
           Set of `Service` in this BOM



   .. py:property:: external_references
      :type: SortedSet[ExternalReference]


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

      Returns:
          Set of `ExternalReference`



   .. py:property:: vulnerabilities
      :type: SortedSet[Vulnerability]


      Get all the Vulnerabilities in this BOM.

      Returns:
           Set of `Vulnerability`



   .. py:property:: dependencies
      :type: SortedSet[Dependency]



   .. py:property:: properties
      :type: SortedSet[Property]


      Provides the ability to document properties in a name/value store. This provides flexibility to include data
      not officially supported in the standard without having to use additional namespaces or create extensions.
      Property names of interest to the general public are encouraged to be registered in the CycloneDX Property
      Taxonomy - https://github.com/CycloneDX/cyclonedx-property-taxonomy. Formal registration is OPTIONAL.

      Return:
          Set of `Property`



   .. py:property:: definitions
      :type: Optional[cyclonedx.model.definition.Definitions]


      The repository for definitions

      Returns:
          `Definitions`



   .. py:method:: get_component_by_purl(purl: Optional[packageurl.PackageURL]) -> Optional[cyclonedx.model.component.Component]

      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`

      .. deprecated:: next



   .. py:method:: get_urn_uuid() -> str

      Get the unique reference for this Bom.

      Returns:
          URN formatted UUID that uniquely identified this Bom instance.

      .. deprecated:: next



   .. py:method:: 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.

      .. deprecated:: next



   .. py:method:: 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`

      .. deprecated:: next
          Deprecated without any replacement.



   .. py:method:: has_vulnerabilities() -> bool

      Check whether this Bom has any declared vulnerabilities.

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

      .. deprecated:: next
          Deprecated without any replacement.



   .. py:method:: register_dependency(target: cyclonedx.model.dependency.Dependable, depends_on: Optional[collections.abc.Iterable[cyclonedx.model.dependency.Dependable]] = None) -> None


   .. py:method:: urn() -> str

      .. deprecated:: next
          Deprecated without any replacement.



   .. py:method:: 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`

      .. deprecated:: next
          Deprecated without any replacement.



