pyoaev.apis.inject_expectation.model.expectation
================================================

.. py:module:: pyoaev.apis.inject_expectation.model.expectation




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

.. py:class:: ExpectationTypeEnum

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


   Types of Expectations


   .. py:attribute:: Detection
      :value: 'DETECTION'



   .. py:attribute:: Prevention
      :value: 'PREVENTION'



   .. py:attribute:: Vulnerability
      :value: 'VULNERABILITY'



   .. py:attribute:: Other
      :value: 'other'



   .. py:method:: _missing_(value)
      :classmethod:



.. py:class:: ExpectationSignature(/, **data: Any)

   Bases: :py:obj:`pydantic.BaseModel`


   An expectation signature describes a known marker potentially
   found in alerting data in security software. For example, an
   expectation signature can be a process image name, a command
   line, or any other relevant piece of data.


   .. py:attribute:: type
      :type:  pyoaev.signatures.types.SignatureTypes


   .. py:attribute:: value
      :type:  str


.. py:class:: Expectation(*a, **kw)

   Bases: :py:obj:`pydantic.BaseModel`


   An expectation represents an expected outcome of a BAS run.
   For example, in the case of running an attack command line, the
   expectation may be that security software has _detected_ it, while
   another expectation may be that the attack was _prevented_.


   .. py:attribute:: inject_expectation_id
      :type:  uuid.UUID


   .. py:attribute:: inject_expectation_signatures
      :type:  List[ExpectationSignature]


   .. py:attribute:: success_label
      :type:  str
      :value: 'Success'



   .. py:attribute:: failure_label
      :type:  str
      :value: 'Failure'



   .. py:attribute:: __api_client


   .. py:method:: update(success, sender_id, metadata)

      Update the expectation object in OpenAEV with the supplied outcome.

      :param success: whether the expectation was fulfilled (true) or not (false)
      :type success: bool
      :param sender_id: identifier of the collector that is updating the expectation
      :type sender_id: string
      :param metadata: arbitrary dictionary of additional data relevant to updating the expectation
      :type metadata: dict[string,string]



   .. py:method:: match_alert(relevant_signature_types: list[pyoaev.signatures.signature_type.SignatureType], alert_data)

      Matches an alert's data against the current expectation signatures
      to see if the alert is relevant to the current expectation's inject,
      i.e. this alert was triggered by the execution of the inject to which
      belongs the expectation.

      :param relevant_signature_types: filter of signature types that we want to consider.
          Only the signature types listed in this collection may be checked for matching.
      :type relevant_signature_types: list[SignatureType]
      :param alert_data: list of possibly relevant markers found in an alert.
      :type alert_data: dict[SignatureTypes, dict]

      :return: whether the alert matches the expectation signatures or not.
      :rtype: bool



   .. py:method:: match_fuzzy(tested: list[str], reference: str, threshold: int)
      :staticmethod:


      Applies a fuzzy match against a known reference to a list of candidates

      :param tested: list of strings candidate for fuzzy matching
      :type tested: list[str]
      :param reference: the reference against which to try to fuzzy match
      :type reference: str
      :param threshold: string overlap percentage threshold above which to declare a match
      :type threshold: int

      :return: whether any of the candidate is a match against the reference
      :rtype: bool



   .. py:method:: match_simple(tested: list[str], reference: str)
      :staticmethod:


      A simple strict, case-sensitive string matching between a list of
          candidates and a reference.

      :param tested: list of strings candidate for fuzzy matching
      :type tested: list[str]
      :param reference: the reference against which to try to fuzzy match
      :type reference: str

      :return: whether any of the candidate is a match against the reference
      :rtype: bool



.. py:class:: DetectionExpectation(*a, **kw)

   Bases: :py:obj:`Expectation`


   An expectation that is specific to Detection, i.e. that is used
   by OpenAEV to assert that an inject's execution was detected.


   .. py:attribute:: success_label
      :type:  str
      :value: 'Detected'



   .. py:attribute:: failure_label
      :type:  str
      :value: 'Not Detected'



.. py:class:: PreventionExpectation(*a, **kw)

   Bases: :py:obj:`Expectation`


   An expectation that is specific to Prevention, i.e. that is used
   by OpenAEV to assert that an inject's execution was prevented.


   .. py:attribute:: success_label
      :type:  str
      :value: 'Prevented'



   .. py:attribute:: failure_label
      :type:  str
      :value: 'Not Prevented'