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

.. py:module:: cyclonedx.model

.. autoapi-nested-parse::

   Uniform set of models to represent objects within a CycloneDX software bill-of-materials.

   You can either create a `cyclonedx.model.bom.Bom` yourself programmatically, or generate a `cyclonedx.model.bom.Bom`
   from a `cyclonedx.parser.BaseParser` implementation.



Submodules
----------

.. toctree::
   :maxdepth: 1

   /autoapi/cyclonedx/model/bom/index
   /autoapi/cyclonedx/model/bom_ref/index
   /autoapi/cyclonedx/model/component/index
   /autoapi/cyclonedx/model/component_evidence/index
   /autoapi/cyclonedx/model/contact/index
   /autoapi/cyclonedx/model/crypto/index
   /autoapi/cyclonedx/model/definition/index
   /autoapi/cyclonedx/model/dependency/index
   /autoapi/cyclonedx/model/impact_analysis/index
   /autoapi/cyclonedx/model/issue/index
   /autoapi/cyclonedx/model/license/index
   /autoapi/cyclonedx/model/lifecycle/index
   /autoapi/cyclonedx/model/release_note/index
   /autoapi/cyclonedx/model/service/index
   /autoapi/cyclonedx/model/tool/index
   /autoapi/cyclonedx/model/vulnerability/index


Classes
-------

.. autoapisummary::

   cyclonedx.model.DataFlow
   cyclonedx.model.DataClassification
   cyclonedx.model.Encoding
   cyclonedx.model.AttachedText
   cyclonedx.model.HashAlgorithm
   cyclonedx.model.HashType
   cyclonedx.model.ExternalReferenceType
   cyclonedx.model.XsUri
   cyclonedx.model.ExternalReference
   cyclonedx.model.Property
   cyclonedx.model.NoteText
   cyclonedx.model.Note
   cyclonedx.model.IdentifiableAction
   cyclonedx.model.Copyright


Package Contents
----------------

.. py:class:: DataFlow

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


   This is our internal representation of the dataFlowType simple type within the CycloneDX standard.

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


   .. py:attribute:: INBOUND
      :value: 'inbound'



   .. py:attribute:: OUTBOUND
      :value: 'outbound'



   .. py:attribute:: BI_DIRECTIONAL
      :value: 'bi-directional'



   .. py:attribute:: UNKNOWN
      :value: 'unknown'



.. py:class:: DataClassification(*, flow: DataFlow, classification: str)

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

   DataClassification might be deprecated since CycloneDX 1.5, but it is not deprecated in this library.
   In fact, this library will try to provide a compatibility layer if needed.

   .. note::
       See the CycloneDX Schema for dataClassificationType:
       https://cyclonedx.org/docs/1.7/xml/#type_dataClassificationType


   .. py:property:: flow
      :type: DataFlow


      Specifies the flow direction of the data.

      Valid values are: inbound, outbound, bi-directional, and unknown.

      Direction is relative to the service.

      - Inbound flow states that data enters the service
      - Outbound flow states that data leaves the service
      - Bi-directional states that data flows both ways
      - Unknown states that the direction is not known

      Returns:
          `DataFlow`



   .. py:property:: classification
      :type: str


      Data classification tags data according to its type, sensitivity, and value if altered, stolen, or destroyed.

      Returns:
          `str`



.. py:class:: Encoding

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


   This is our internal representation of the encoding simple type within the CycloneDX standard.

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


   .. py:attribute:: BASE_64
      :value: 'base64'



.. py:class:: AttachedText(*, content: str, content_type: str = DEFAULT_CONTENT_TYPE, encoding: Optional[Encoding] = None)

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

   .. note::
       See the CycloneDX Schema for hashType: https://cyclonedx.org/docs/1.7/xml/#type_attachedTextType


   .. py:attribute:: DEFAULT_CONTENT_TYPE
      :value: 'text/plain'



   .. py:property:: content_type
      :type: str


      Specifies the content type of the text. Defaults to text/plain if not specified.

      Returns:
          `str`



   .. py:property:: encoding
      :type: Optional[Encoding]


      Specifies the optional encoding the text is represented in.

      Returns:
          `Encoding` if set else `None`



   .. py:property:: content
      :type: str


      The attachment data.

      Proactive controls such as input validation and sanitization should be employed to prevent misuse of attachment
      text.

      Returns:
          `str`



.. py:class:: HashAlgorithm

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


   This is our internal representation of the hashAlg simple type within the CycloneDX standard.

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


   .. py:attribute:: BLAKE2B_256
      :value: 'BLAKE2b-256'



   .. py:attribute:: BLAKE2B_384
      :value: 'BLAKE2b-384'



   .. py:attribute:: BLAKE2B_512
      :value: 'BLAKE2b-512'



   .. py:attribute:: BLAKE3
      :value: 'BLAKE3'



   .. py:attribute:: MD5
      :value: 'MD5'



   .. py:attribute:: SHA_1
      :value: 'SHA-1'



   .. py:attribute:: SHA_256
      :value: 'SHA-256'



   .. py:attribute:: SHA_384
      :value: 'SHA-384'



   .. py:attribute:: SHA_512
      :value: 'SHA-512'



   .. py:attribute:: SHA3_256
      :value: 'SHA3-256'



   .. py:attribute:: SHA3_384
      :value: 'SHA3-384'



   .. py:attribute:: SHA3_512
      :value: 'SHA3-512'



   .. py:attribute:: STREEBOG_256
      :value: 'Streebog-256'



   .. py:attribute:: STREEBOG_512
      :value: 'Streebog-512'



.. py:class:: HashType(*, alg: HashAlgorithm, content: str)

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

   .. note::
       See the CycloneDX Schema for hashType: https://cyclonedx.org/docs/1.7/xml/#type_hashType


   .. py:method:: from_hashlib_alg(hashlib_alg: str, content: str) -> HashType
      :staticmethod:


      Deprecated — Alias of :func:`cyclonedx.contrib.hash.factories.HashTypeFactory.from_hashlib_alge`.

      Attempts to convert a hashlib-algorithm to our internal model classes.

      .. deprecated:: next
          Use ``cyclonedx.contrib.hash.factories.HashTypeFactory.from_hashlib_alg()`` instead.



   .. py:method:: from_composite_str(composite_hash: str) -> HashType
      :staticmethod:


      Deprecated — Alias of :func:`cyclonedx.contrib.hash.factories.HashTypeFactory.from_composite_str`.

      Attempts to convert a string which includes both the Hash Algorithm and Hash Value and represent using our
      internal model classes.

      .. deprecated:: next
          Use ``cyclonedx.contrib.hash.factories.HashTypeFactory.from_composite_str()`` instead.



   .. py:property:: alg
      :type: HashAlgorithm


      Specifies the algorithm used to create the hash.

      Returns:
          `HashAlgorithm`



   .. py:property:: content
      :type: str


      Hash value content.

      Returns:
          `str`



.. py:class:: ExternalReferenceType

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


   Enum object that defines the permissible 'types' for an External Reference according to the CycloneDX schema.

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


   .. py:attribute:: ADVERSARY_MODEL
      :value: 'adversary-model'



   .. py:attribute:: ADVISORIES
      :value: 'advisories'



   .. py:attribute:: ATTESTATION
      :value: 'attestation'



   .. py:attribute:: BOM
      :value: 'bom'



   .. py:attribute:: BUILD_META
      :value: 'build-meta'



   .. py:attribute:: BUILD_SYSTEM
      :value: 'build-system'



   .. py:attribute:: CERTIFICATION_REPORT
      :value: 'certification-report'



   .. py:attribute:: CHAT
      :value: 'chat'



   .. py:attribute:: CITATION
      :value: 'citation'



   .. py:attribute:: CODIFIED_INFRASTRUCTURE
      :value: 'codified-infrastructure'



   .. py:attribute:: COMPONENT_ANALYSIS_REPORT
      :value: 'component-analysis-report'



   .. py:attribute:: CONFIGURATION
      :value: 'configuration'



   .. py:attribute:: DIGITAL_SIGNATURE
      :value: 'digital-signature'



   .. py:attribute:: DISTRIBUTION
      :value: 'distribution'



   .. py:attribute:: DISTRIBUTION_INTAKE
      :value: 'distribution-intake'



   .. py:attribute:: DOCUMENTATION
      :value: 'documentation'



   .. py:attribute:: DYNAMIC_ANALYSIS_REPORT
      :value: 'dynamic-analysis-report'



   .. py:attribute:: ELECTRONIC_SIGNATURE
      :value: 'electronic-signature'



   .. py:attribute:: EVIDENCE
      :value: 'evidence'



   .. py:attribute:: EXPLOITABILITY_STATEMENT
      :value: 'exploitability-statement'



   .. py:attribute:: FORMULATION
      :value: 'formulation'



   .. py:attribute:: ISSUE_TRACKER
      :value: 'issue-tracker'



   .. py:attribute:: LICENSE
      :value: 'license'



   .. py:attribute:: LOG
      :value: 'log'



   .. py:attribute:: MAILING_LIST
      :value: 'mailing-list'



   .. py:attribute:: MATURITY_REPORT
      :value: 'maturity-report'



   .. py:attribute:: MODEL_CARD
      :value: 'model-card'



   .. py:attribute:: PATENT
      :value: 'patent'



   .. py:attribute:: PATENT_ASSERTION
      :value: 'patent-assertion'



   .. py:attribute:: PATENT_FAMILY
      :value: 'patent-family'



   .. py:attribute:: PENTEST_REPORT
      :value: 'pentest-report'



   .. py:attribute:: POAM
      :value: 'poam'



   .. py:attribute:: QUALITY_METRICS
      :value: 'quality-metrics'



   .. py:attribute:: RELEASE_NOTES
      :value: 'release-notes'



   .. py:attribute:: RFC_9166
      :value: 'rfc-9116'



   .. py:attribute:: RISK_ASSESSMENT
      :value: 'risk-assessment'



   .. py:attribute:: RUNTIME_ANALYSIS_REPORT
      :value: 'runtime-analysis-report'



   .. py:attribute:: SECURITY_CONTACT
      :value: 'security-contact'



   .. py:attribute:: STATIC_ANALYSIS_REPORT
      :value: 'static-analysis-report'



   .. py:attribute:: SOCIAL
      :value: 'social'



   .. py:attribute:: SOURCE_DISTRIBUTION
      :value: 'source-distribution'



   .. py:attribute:: SCM
      :value: 'vcs'



   .. py:attribute:: SUPPORT
      :value: 'support'



   .. py:attribute:: THREAT_MODEL
      :value: 'threat-model'



   .. py:attribute:: VCS
      :value: 'vcs'



   .. py:attribute:: VULNERABILITY_ASSERTION
      :value: 'vulnerability-assertion'



   .. py:attribute:: WEBSITE
      :value: 'website'



   .. py:attribute:: OTHER
      :value: 'other'



.. py:class:: XsUri(uri: str)

   Bases: :py:obj:`py_serializable.helpers.BaseHelper`


   Helper class that allows us to perform validation on data strings that are defined as xs:anyURI
   in CycloneDX schema.

   Developers can just use this via `str(XsUri('https://www.google.com'))`.

   .. note::
       See XSD definition for xsd:anyURI: http://www.datypic.com/sc/xsd/t-xsd_anyURI.html
       See JSON Schema definition for iri-reference: https://tools.ietf.org/html/rfc3987


   .. py:property:: uri
      :type: str



   .. py:method:: serialize(o: Any) -> str
      :classmethod:



   .. py:method:: deserialize(o: Any) -> XsUri
      :classmethod:



   .. py:method:: make_bom_link(serial_number: Union[uuid.UUID, str], version: int = 1, bom_ref: Optional[Union[str, bom_ref.BomRef]] = None) -> XsUri
      :classmethod:


      Generate a BOM-Link URI.

      Args:
          serial_number: The unique serial number of the BOM.
          version: The version of the BOM. The default version is 1.
          bom_ref: The unique identifier of the component, service, or vulnerability within the BOM.

      Returns:
          XsUri: Instance of XsUri with the generated BOM-Link URI.



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

      Check if the URI is a BOM-Link.

      Returns:
          `bool`



.. py:class:: ExternalReference(*, type: ExternalReferenceType, url: XsUri, comment: Optional[str] = None, hashes: Optional[collections.abc.Iterable[HashType]] = None, properties: Optional[collections.abc.Iterable[Property]] = None)

   This is our internal representation of an ExternalReference complex type that can be used in multiple places within
   a CycloneDX BOM document.

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


   .. py:property:: url
      :type: XsUri


      The URL to the external reference.

      Returns:
          `XsUri`



   .. py:property:: comment
      :type: Optional[str]


      An optional comment describing the external reference.

      Returns:
          `str` if set else `None`



   .. py:property:: type
      :type: ExternalReferenceType


      Specifies the type of external reference.

      There are built-in types to describe common references. If a type does not exist for the reference being
      referred to, use the "other" type.

      Returns:
          `ExternalReferenceType`



   .. py:property:: hashes
      :type: SortedSet[HashType]


      The hashes of the external reference (if applicable).

      Returns:
          Set of `HashType`



   .. 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:class:: Property(*, name: str, value: Optional[str] = None)

   This is our internal representation of `propertyType` complex type that can be used in multiple places within
   a CycloneDX BOM document.

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

   Specifies an individual property with a name and value.


   .. py:property:: name
      :type: str


      The name of the property.

      Duplicate names are allowed, each potentially having a different value.

      Returns:
          `str`



   .. py:property:: value
      :type: Optional[str]


      Value of this Property.

      Returns:
           `str`



.. py:class:: NoteText(*, content: str, content_type: Optional[str] = None, encoding: Optional[Encoding] = None)

   This is our internal representation of the Note.text complex type that can be used in multiple places within
   a CycloneDX BOM document.

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


   .. py:attribute:: DEFAULT_CONTENT_TYPE
      :type:  str
      :value: 'text/plain'



   .. py:property:: content
      :type: str


      Get the text content of this Note.

      Returns:
          `str` note content



   .. py:property:: content_type
      :type: Optional[str]


      Get the content-type of this Note.

      Defaults to 'text/plain' if one was not explicitly specified.

      Returns:
          `str` content-type



   .. py:property:: encoding
      :type: Optional[Encoding]


      Get the encoding method used for the note's content.

      Returns:
          `Encoding` if set else `None`



.. py:class:: Note(*, text: NoteText, locale: Optional[str] = None)

   This is our internal representation of the Note complex type that can be used in multiple places within
   a CycloneDX BOM document.

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

   @todo: Replace ``NoteText`` with ``AttachedText``?


   .. py:property:: text
      :type: NoteText


      Specifies the full content of the release note.

      Returns:
          `NoteText`



   .. py:property:: locale
      :type: Optional[str]


      Get the ISO locale of this Note.

      The ISO-639 (or higher) language code and optional ISO-3166 (or higher) country code.

      Examples include: "en", "en-US", "fr" and "fr-CA".

      Returns:
          `str` locale if set else `None`



.. py:class:: IdentifiableAction(*, timestamp: Optional[datetime.datetime] = None, name: Optional[str] = None, email: Optional[str] = None)

   This is our internal representation of the `identifiableActionType` complex type.

   .. note::
       See the CycloneDX specification: https://cyclonedx.org/docs/1.7/xml/#type_identifiableActionType


   .. py:property:: timestamp
      :type: Optional[datetime.datetime]


      The timestamp in which the action occurred.

      Returns:
          `datetime` if set else `None`



   .. py:property:: name
      :type: Optional[str]


      The name of the individual who performed the action.

      Returns:
          `str` if set else `None`



   .. py:property:: email
      :type: Optional[str]


      The email address of the individual who performed the action.

      Returns:
          `str` if set else `None`



.. py:class:: Copyright(*, text: str)

   This is our internal representation of the `copyrightsType` complex type.

   .. note::
       See the CycloneDX specification: https://cyclonedx.org/docs/1.7/xml/#type_copyrightsType


   .. py:property:: text
      :type: str


      Copyright statement.

      Returns:
          `str` if set else `None`