pyoaev 1.18.20__py3-none-any.whl

docs/conf.py

@@ -0,0 +1,65 @@
+# Configuration file for the Sphinx documentation builder.
+#
+# This file only contains a selection of the most common options. For a full
+# list see the documentation:
+# https://www.sphinx-doc.org/en/master/usage/configuration.html
+
+# -- Path setup --------------------------------------------------------------
+
+# If extensions (or modules to document with autodoc) are in another directory,
+# add these directories to sys.path here. If the directory is relative to the
+# documentation root, use os.path.abspath to make it absolute, like shown here.
+#
+import os
+import sys
+
+sys.path.insert(0, os.path.abspath(".."))
+
+
+# -- Project information -----------------------------------------------------
+
+project = "OpenAEV client for Python"
+copyright = "2024, Filigran"
+author = "OpenAEV Project"
+
+# The full version, including alpha/beta/rc tags
+release = "1.10.1"
+
+master_doc = "index"
+
+autoapi_modules = {"pyoaev": {"prune": True}}
+
+pygments_style = "sphinx"
+
+# -- General configuration ---------------------------------------------------
+
+# Add any Sphinx extension module names here, as strings. They can be
+# extensions coming with Sphinx (named 'sphinx.ext.*') or your custom
+# ones.
+extensions = [
+    "sphinx.ext.autodoc",
+    "sphinx.ext.inheritance_diagram",
+    "autoapi.sphinx",
+    "sphinx_autodoc_typehints",
+]
+
+# Add any paths that contain templates here, relative to this directory.
+templates_path = ["_templates"]
+
+# List of patterns, relative to source directory, that match files and
+# directories to ignore when looking for source files.
+# This pattern also affects html_static_path and html_extra_path.
+exclude_patterns = ["_build", "Thumbs.db", ".DS_Store"]
+
+
+# -- Options for HTML output -------------------------------------------------
+
+# The theme to use for HTML and HTML Help pages.  See the documentation for
+# a list of builtin themes.
+#
+html_theme = "sphinx_rtd_theme"
+
+# Add any paths that contain custom static files (such as style sheets) here,
+# relative to this directory. They are copied after the builtin static files,
+# so a file named "default.css" will overwrite the builtin "default.css".
+html_static_path = ["_static"]

pyoaev/__init__.py

@@ -0,0 +1,26 @@
+# -*- coding: utf-8 -*-
+__version__ = "1.18.20"
+
+from pyoaev._version import (  # noqa: F401
+    __author__,
+    __copyright__,
+    __email__,
+    __license__,
+    __title__,
+)
+from pyoaev.client import OpenAEV  # noqa: F401
+from pyoaev.configuration import *  # noqa: F401,F403,F405
+from pyoaev.contracts import *  # noqa: F401,F403,F405
+from pyoaev.exceptions import *  # noqa: F401,F403,F405
+from pyoaev.signatures import *  # noqa: F401,F403,F405
+
+__all__ = [
+    "__author__",
+    "__copyright__",
+    "__email__",
+    "__license__",
+    "__title__",
+    "__version__",
+    "OpenAEV",
+]
+__all__.extend(exceptions.__all__)  # noqa: F405

pyoaev/_version.py

@@ -0,0 +1,6 @@
+__author__ = "Filigran team"
+__copyright__ = "Copyright 2025 Filigran"
+__email__ = "contact@filigran.io"
+__license__ = "Apache 2.0"
+__title__ = "python-openaev"
+__version__ = "1.18.20"

pyoaev/apis/__init__.py

@@ -0,0 +1,20 @@
+from .attack_pattern import *  # noqa: F401,F403
+from .collector import *  # noqa: F401,F403
+from .cve import *  # noqa: F401,F403
+from .document import *  # noqa: F401,F403
+from .endpoint import *  # noqa: F401,F403
+from .inject import *  # noqa: F401,F403
+from .inject_expectation import *  # noqa: F401,F403
+from .inject_expectation_trace import *  # noqa: F401,F403
+from .injector import *  # noqa: F401,F403
+from .injector_contract import *  # noqa: F401,F403
+from .kill_chain_phase import *  # noqa: F401,F403
+from .me import *  # noqa: F401,F403
+from .organization import *  # noqa: F401,F403
+from .payload import *  # noqa: F401,F403
+from .security_platform import *  # noqa: F401,F403
+from .tag import *  # noqa: F401,F403
+from .team import *  # noqa: F401,F403
+from .user import *  # noqa: F401,F403
+
+__all__ = [name for name in dir() if not name.startswith("_")]

pyoaev/apis/attack_pattern.py

@@ -0,0 +1,28 @@
+from typing import Any, Dict, List
+
+from pyoaev import exceptions as exc
+from pyoaev.base import RESTManager, RESTObject
+
+
+class AttackPattern(RESTObject):
+    _id_attr = "attack_pattern_id"
+
+
+class AttackPatternManager(RESTManager):
+    _path = "/attack_patterns"
+    _obj_cls = AttackPattern
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def upsert(
+        self,
+        attack_patterns: List[Dict[str, Any]],
+        ignore_dependencies: bool = False,
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        data = {
+            "attack_patterns": attack_patterns,
+            "ignore_dependencies": ignore_dependencies,
+        }
+        path = f"{self.path}/upsert"
+        result = self.openaev.http_post(path, post_data=data, **kwargs)
+        return result

pyoaev/apis/collector.py

@@ -0,0 +1,29 @@
+from typing import Any, Dict
+
+from pyoaev import exceptions as exc
+from pyoaev.base import RESTManager, RESTObject
+from pyoaev.mixins import CreateMixin, GetMixin, ListMixin, UpdateMixin
+from pyoaev.utils import RequiredOptional
+
+
+class Collector(RESTObject):
+    pass
+
+
+class CollectorManager(GetMixin, ListMixin, CreateMixin, UpdateMixin, RESTManager):
+    _path = "/collectors"
+    _obj_cls = Collector
+    _create_attrs = RequiredOptional(
+        required=(
+            "collector_id",
+            "collector_name",
+            "collector_type",
+            "collector_period",
+        )
+    )
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def get(self, collector_id: str, **kwargs: Any) -> Dict[str, Any]:
+        path = f"{self.path}/" + collector_id
+        result = self.openaev.http_get(path, **kwargs)
+        return result

pyoaev/apis/cve.py

@@ -0,0 +1,18 @@
+from typing import Any, Dict
+
+from pyoaev import exceptions as exc
+from pyoaev.base import RESTManager, RESTObject
+
+
+class Cve(RESTObject):
+    _id_attr = "cve_id"
+
+
+class CveManager(RESTManager):
+    _path = "/cves"
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def upsert(self, data: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]:
+        path = f"{self.path}/bulk"
+        result = self.openaev.http_post(path, post_data=data, **kwargs)
+        return result

pyoaev/apis/document.py

@@ -0,0 +1,29 @@
+from typing import Any, Dict
+
+from pyoaev import exceptions as exc
+from pyoaev.base import RESTManager, RESTObject
+
+
+class Document(RESTObject):
+    _id_attr = "document_id"
+
+
+class DocumentManager(RESTManager):
+    _path = "/documents"
+    _obj_cls = Document
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def download(self, document_id: str, **kwargs: Any) -> Dict[str, Any]:
+        path = f"{self.path}/" + document_id + "/file"
+        result = self.openaev.http_get(path, **kwargs)
+        return result
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def upsert(
+        self, document: Dict[str, Any], file: tuple, **kwargs: Any
+    ) -> Dict[str, Any]:
+        path = f"{self.path}/upsert"
+        result = self.openaev.http_post(
+            path, post_data=document, files={"file": file}, **kwargs
+        )
+        return result

pyoaev/apis/endpoint.py

@@ -0,0 +1,38 @@
+from typing import Any, Dict
+
+from pyoaev import exceptions as exc
+from pyoaev.base import RESTManager, RESTObject
+from pyoaev.utils import RequiredOptional
+
+
+class Endpoint(RESTObject):
+    _id_attr = "asset_id"
+
+
+class EndpointManager(RESTManager):
+    _path = "/endpoints"
+    _obj_cls = Endpoint
+    _create_attrs = RequiredOptional(
+        required=(
+            "endpoint_hostname",
+            "endpoint_platform",
+            "endpoint_arch",
+        ),
+        optional=(
+            "endpoint_mac_addresses",
+            "endpoint_ips",
+            "asset_external_reference",
+        ),
+    )
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def get(self, asset_id: str, **kwargs: Any) -> Dict[str, Any]:
+        path = f"{self.path}/" + asset_id
+        result = self.openaev.http_get(path, **kwargs)
+        return result
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def upsert(self, endpoint: Dict[str, Any], **kwargs: Any) -> Dict[str, Any]:
+        path = f"{self.path}/agentless/upsert"
+        result = self.openaev.http_post(path, post_data=endpoint, **kwargs)
+        return result

pyoaev/apis/inject.py

@@ -0,0 +1,29 @@
+from typing import Any, Dict
+
+from pyoaev import exceptions as exc
+from pyoaev.base import RESTManager, RESTObject
+
+
+class Inject(RESTObject):
+    _id_attr = None
+
+
+class InjectManager(RESTManager):
+    _path = "/injects"
+    _obj_cls = Inject
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def execution_callback(
+        self, inject_id: str, data: Dict[str, Any], **kwargs: Any
+    ) -> Dict[str, Any]:
+        path = f"{self.path}/execution/callback/{inject_id}"
+        result = self.openaev.http_post(path, post_data=data, **kwargs)
+        return result
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def execution_reception(
+        self, inject_id: str, data: Dict[str, Any], **kwargs: Any
+    ) -> Dict[str, Any]:
+        path = f"{self.path}/execution/reception/{inject_id}"
+        result = self.openaev.http_post(path, post_data=data, **kwargs)
+        return result

pyoaev/apis/inject_expectation/__init__.py

@@ -0,0 +1 @@
+from .inject_expectation import *  # noqa: F401,F403

pyoaev/apis/inject_expectation/inject_expectation.py

@@ -0,0 +1,118 @@
+from typing import Any, Dict
+
+from pyoaev import exceptions as exc
+from pyoaev.apis.inject_expectation.model import (
+    DetectionExpectation,
+    ExpectationTypeEnum,
+    PreventionExpectation,
+)
+from pyoaev.base import RESTManager, RESTObject
+from pyoaev.mixins import ListMixin, UpdateMixin
+from pyoaev.utils import RequiredOptional
+
+
+class InjectExpectation(RESTObject):
+    _id_attr = "inject_expectation_id"
+
+
+class InjectExpectationManager(ListMixin, UpdateMixin, RESTManager):
+    _path = "/injects/expectations"
+    _obj_cls = InjectExpectation
+    _update_attrs = RequiredOptional(required=("collector_id", "result", "is_success"))
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def expectations_assets_for_source(
+        self, source_id: str, expiration_time: int = None, **kwargs: Any
+    ) -> Dict[str, Any]:
+        path = f"{self.path}/assets/" + source_id
+        result = self.openaev.http_get(
+            path,
+            query_data=(
+                {"expiration_time": expiration_time} if expiration_time else None
+            ),
+            **kwargs,
+        )
+        return result
+
+    def expectations_models_for_source(self, source_id: str, **kwargs: Any):
+        """Returns all expectations from OpenAEV that have had no result yet
+            from the source_id (e.g. collector).
+
+        :param source_id: the identifier of the collector requesting expectations
+        :type source_id: str
+        :param kwargs: additional data to pass to the endpoint
+        :type kwargs: dict, optional
+
+        :return: a list of expectation objects
+        :rtype: list[DetectionExpectation|PreventionExpectation]
+        """
+        # TODO: we should implement a more clever mechanism to obtain
+        #   specialised Expectation instances rather than just if/elseing
+        #   through this list of possibilities.
+        expectations = []
+        for expectation_dict in self.expectations_assets_for_source(
+            source_id=source_id, **kwargs
+        ):
+            if (
+                expectation_dict["inject_expectation_type"]
+                == ExpectationTypeEnum.Detection.value
+            ):
+                expectations.append(
+                    DetectionExpectation(**expectation_dict, api_client=self)
+                )
+            elif (
+                expectation_dict["inject_expectation_type"]
+                == ExpectationTypeEnum.Prevention.value
+            ):
+                expectations.append(
+                    PreventionExpectation(**expectation_dict, api_client=self)
+                )
+            else:
+                expectations.append(
+                    PreventionExpectation(**expectation_dict, api_client=self)
+                )
+        return expectations
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def prevention_expectations_for_source(
+        self, source_id: str, **kwargs: Any
+    ) -> Dict[str, Any]:
+        path = f"{self.path}/prevention" + source_id
+        result = self.openaev.http_get(path, **kwargs)
+        return result
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def detection_expectations_for_source(
+        self, source_id: str, expiration_time: int = None, **kwargs: Any
+    ) -> Dict[str, Any]:
+        path = f"{self.path}/detection/" + source_id
+        result = self.openaev.http_get(
+            path,
+            query_data=(
+                {"expiration_time": expiration_time} if expiration_time else None
+            ),
+            **kwargs,
+        )
+        return result
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def update(
+        self,
+        inject_expectation_id: str,
+        inject_expectation: Dict[str, Any],
+        **kwargs: Any,
+    ) -> Dict[str, Any]:
+        path = f"{self.path}/{inject_expectation_id}"
+        result = self.openaev.http_put(path, post_data=inject_expectation, **kwargs)
+        return result
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def bulk_update(
+        self,
+        inject_expectation_input_by_id: Dict[str, Dict[str, Any]],
+        **kwargs: Any,
+    ) -> None:
+        path = f"{self.path}/bulk"
+        self.openaev.http_put(
+            path, post_data={"inputs": inject_expectation_input_by_id}, **kwargs
+        )

pyoaev/apis/inject_expectation/model/__init__.py

@@ -0,0 +1,7 @@
+from .expectation import (
+    DetectionExpectation,
+    ExpectationTypeEnum,
+    PreventionExpectation,
+)
+
+__all__ = ["DetectionExpectation", "ExpectationTypeEnum", "PreventionExpectation"]

pyoaev/apis/inject_expectation/model/expectation.py

@@ -0,0 +1,173 @@
+from enum import Enum
+from typing import List
+from uuid import UUID
+
+from pydantic import BaseModel
+from thefuzz import fuzz
+
+from pyoaev.signatures.signature_type import SignatureType
+from pyoaev.signatures.types import MatchTypes, SignatureTypes
+
+
+class ExpectationTypeEnum(str, Enum):
+    """Types of Expectations"""
+
+    Detection = "DETECTION"
+    Prevention = "PREVENTION"
+    Vulnerability = "VULNERABILITY"
+    Other = "other"
+
+    @classmethod
+    def _missing_(cls, value):
+        return cls.Other
+
+
+class ExpectationSignature(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: SignatureTypes
+    value: str
+
+
+class Expectation(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
+    inject_expectation_signatures: List[ExpectationSignature]
+
+    success_label: str = "Success"
+    failure_label: str = "Failure"
+
+    def __init__(self, *a, **kw):
+        super().__init__(*a, **kw)
+        self.__api_client = kw["api_client"]
+
+    def update(self, 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]
+        """
+        self.__api_client.update(
+            self.inject_expectation_id,
+            inject_expectation={
+                "collector_id": sender_id,
+                "result": (self.success_label if success else self.failure_label),
+                "is_success": success,
+                "metadata": metadata,
+            },
+        )
+
+    def match_alert(self, relevant_signature_types: list[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
+        """
+        relevant_expectation_signatures = [
+            signature
+            for signature in self.inject_expectation_signatures
+            if signature.type in [type.label for type in relevant_signature_types]
+        ]
+        if not any(relevant_expectation_signatures):
+            return False
+
+        for relevant_expectation_signature in relevant_expectation_signatures:
+            if not (
+                alert_signature_for_type := alert_data.get(
+                    relevant_expectation_signature.type.value
+                )
+            ):
+                return False
+
+            if alert_signature_for_type[
+                "type"
+            ] == MatchTypes.MATCH_TYPE_FUZZY and not self.match_fuzzy(
+                alert_signature_for_type["data"],
+                relevant_expectation_signature.value,
+                alert_signature_for_type["score"],
+            ):
+                return False
+            if alert_signature_for_type[
+                "type"
+            ] == MatchTypes.MATCH_TYPE_SIMPLE and not self.match_simple(
+                alert_signature_for_type["data"], relevant_expectation_signature.value
+            ):
+                return False
+
+        return True
+
+    @staticmethod
+    def match_fuzzy(tested: list[str], reference: str, threshold: int):
+        """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
+        """
+        actual_tested = [tested] if isinstance(tested, str) else tested
+        for value in actual_tested:
+            ratio = fuzz.ratio(value, reference)
+            if ratio >= threshold:
+                return True
+        return False
+
+    @staticmethod
+    def match_simple(tested: list[str], reference: str):
+        """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
+        """
+        return Expectation.match_fuzzy(tested, reference, threshold=100)
+
+
+class DetectionExpectation(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 PreventionExpectation(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"

pyoaev/apis/inject_expectation_trace.py

@@ -0,0 +1,36 @@
+from typing import Any, Dict, List
+
+from pyoaev import exceptions as exc
+from pyoaev.base import RESTManager, RESTObject
+from pyoaev.mixins import CreateMixin
+from pyoaev.utils import RequiredOptional
+
+
+class InjectExpectationTrace(RESTObject):
+    _id_attr = "inject_expectation_trace_id"
+
+
+class InjectExpectationTraceManager(CreateMixin, RESTManager):
+    _path = "/inject-expectations-traces"
+    _obj_cls = InjectExpectationTrace
+    _create_attrs = RequiredOptional(
+        required=(
+            "inject_expectation_trace_expectation",
+            "inject_expectation_trace_source_id",
+            "inject_expectation_trace_alert_name",
+            "inject_expectation_trace_alert_link",
+            "inject_expectation_trace_date",
+        ),
+    )
+
+    @exc.on_http_error(exc.OpenAEVUpdateError)
+    def bulk_create(
+        self, payload: Dict[str, List[Dict[str, str]]], **kwargs: Any
+    ) -> dict[str, Any]:
+        path = f"{self.path}/bulk"
+        result = self.openaev.http_post(
+            path,
+            post_data=payload,
+            **kwargs,
+        )
+        return result

pyoaev/apis/injector.py

@@ -0,0 +1,26 @@
+from pyoaev.base import RESTManager, RESTObject
+from pyoaev.mixins import CreateMixin, GetMixin, ListMixin, UpdateMixin
+from pyoaev.utils import RequiredOptional
+
+
+class Injector(RESTObject):
+    pass
+
+
+class InjectorManager(GetMixin, ListMixin, CreateMixin, UpdateMixin, RESTManager):
+    _path = "/injectors"
+    _obj_cls = Injector
+    _create_attrs = RequiredOptional(
+        required=(
+            "injector_id",
+            "injector_name",
+            "injector_type",
+            "injector_contracts",
+        ),
+        optional=(
+            "injector_custom_contracts",
+            "injector_category",
+            "injector_executor_commands",
+            "injector_executor_clear_commands",
+        ),
+    )