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


Attributes
----------

.. autoapisummary::

   cyclonedx.model.HASH_ALG_VERSIONS
   cyclonedx.model.EXTREF_TYPE_VERSIONS


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


Functions
---------

.. autoapisummary::

   cyclonedx.model.is_hash_alg_supported
   cyclonedx.model.get_extref_type_for_version


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

   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:attribute:: flow
      :type:  DataFlow


   .. py:attribute:: classification
      :type:  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

   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:attribute:: content
      :type:  str


   .. py:attribute:: content_type
      :type:  str


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


.. 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:data:: HASH_ALG_VERSIONS
   :type:  dict[HashAlgorithm, set[cyclonedx.schema.SchemaVersion]]

.. py:function:: is_hash_alg_supported(alg: HashAlgorithm, version: cyclonedx.schema.SchemaVersion) -> bool

   Check if a hash algorithm is supported in a schema version.


.. py:class:: HashType

   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:attribute:: alg
      :type:  HashAlgorithm


   .. py:attribute:: content
      :type:  str


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


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

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

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



.. 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:data:: EXTREF_TYPE_VERSIONS
   :type:  dict[ExternalReferenceType, set[cyclonedx.schema.SchemaVersion]]

.. py:function:: get_extref_type_for_version(extref_type: ExternalReferenceType, version: cyclonedx.schema.SchemaVersion) -> ExternalReferenceType

   Get the appropriate external reference type for a schema version.

   Returns OTHER if the type is not supported in the given version.


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

   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.



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

      Check if the URI is a BOM-Link.



.. py:class:: ExternalReference

   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:attribute:: type
      :type:  ExternalReferenceType


   .. py:attribute:: url
      :type:  XsUri


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


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


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


.. py:class:: Property

   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:attribute:: name
      :type:  str


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


.. py:class:: NoteText

   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:  ClassVar[str]
      :value: 'text/plain'



   .. py:attribute:: content
      :type:  str


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


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


.. py:class:: Note

   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


   .. py:attribute:: text
      :type:  NoteText


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


.. py:class:: IdentifiableAction

   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:attribute:: timestamp
      :type:  Optional[datetime.datetime]


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


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


.. py:class:: Copyright

   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:attribute:: text
      :type:  str