pyoaev.apis.inject_expectation.model.expectation

Module Contents

class pyoaev.apis.inject_expectation.model.expectation.ExpectationTypeEnum

Bases: str, enum.Enum

Types of Expectations

Detection = 'DETECTION'
Prevention = 'PREVENTION'
Vulnerability = 'VULNERABILITY'
Other = 'other'
classmethod _missing_(value)
class pyoaev.apis.inject_expectation.model.expectation.ExpectationSignature(/, **data: Any)

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

type: pyoaev.signatures.types.SignatureTypes
value: str
class pyoaev.apis.inject_expectation.model.expectation.Expectation(*a, **kw)

Bases: 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_.

inject_expectation_id: uuid.UUID
inject_expectation_signatures: List[ExpectationSignature]
success_label: str = 'Success'
failure_label: str = 'Failure'
__api_client
update(success, sender_id, metadata)

Update the expectation object in OpenAEV with the supplied outcome.

Parameters:

  • success (bool) – whether the expectation was fulfilled (true) or not (false)

  • sender_id (string) – identifier of the collector that is updating the expectation

  • metadata (dict[string,string]) – arbitrary dictionary of additional data relevant to updating the expectation

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.

Parameters:

  • relevant_signature_types (list[SignatureType]) – filter of signature types that we want to consider. Only the signature types listed in this collection may be checked for matching.

  • alert_data (dict[SignatureTypes, dict]) – list of possibly relevant markers found in an alert.

Returns:

whether the alert matches the expectation signatures or not.

Return type:

bool

static match_fuzzy(tested: list[str], reference: str, threshold: int)

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

Parameters:

  • tested (list[str]) – list of strings candidate for fuzzy matching

  • reference (str) – the reference against which to try to fuzzy match

  • threshold (int) – string overlap percentage threshold above which to declare a match

Returns:

whether any of the candidate is a match against the reference

Return type:

bool

static match_simple(tested: list[str], reference: str)
A simple strict, case-sensitive string matching between a list of

candidates and a reference.

Parameters:

  • tested (list[str]) – list of strings candidate for fuzzy matching

  • reference (str) – the reference against which to try to fuzzy match

Returns:

whether any of the candidate is a match against the reference

Return type:

bool

class pyoaev.apis.inject_expectation.model.expectation.DetectionExpectation(*a, **kw)

Bases: Expectation

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

success_label: str = 'Detected'
failure_label: str = 'Not Detected'
class pyoaev.apis.inject_expectation.model.expectation.PreventionExpectation(*a, **kw)

Bases: Expectation

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

success_label: str = 'Prevented'
failure_label: str = 'Not Prevented'