pyoaev 1.18.20__py3-none-any.whl

pyoaev/contracts/variable_helper.py

@@ -0,0 +1,124 @@
+from pyoaev.contracts.contract_utils import (
+    ContractCardinality,
+    ContractVariable,
+    VariableType,
+)
+
+USER = "user"
+EXERCISE = "exercise"
+TEAMS = "teams"
+COMCHECK = "comcheck"
+PLAYER_URI = "player_uri"
+CHALLENGES_URI = "challenges_uri"
+SCOREBOARD_URI = "scoreboard_uri"
+LESSONS_URI = "lessons_uri"
+
+
+class VariableHelper:
+    @staticmethod
+    def user_variable():
+        return ContractVariable(
+            key=USER,
+            label="User that will receive the injection",
+            type=VariableType.String,
+            cardinality=ContractCardinality.One,
+            children=[
+                ContractVariable(
+                    key=USER + ".id",
+                    label="Id of the user in the platform",
+                    type=VariableType.String,
+                    cardinality=ContractCardinality.One,
+                ),
+                ContractVariable(
+                    key=USER + ".email",
+                    label="Email of the user",
+                    type=VariableType.String,
+                    cardinality=ContractCardinality.One,
+                ),
+                ContractVariable(
+                    key=USER + ".firstname",
+                    label="Firstname of the user",
+                    type=VariableType.String,
+                    cardinality=ContractCardinality.One,
+                ),
+                ContractVariable(
+                    key=USER + ".lastname",
+                    label="Lastname of the user",
+                    type=VariableType.String,
+                    cardinality=ContractCardinality.One,
+                ),
+                ContractVariable(
+                    key=USER + ".lang",
+                    label="Lang of the user",
+                    type=VariableType.String,
+                    cardinality=ContractCardinality.One,
+                ),
+            ],
+        )
+
+    @staticmethod
+    def exercise_variable():
+        return ContractVariable(
+            key=EXERCISE,
+            label="Exercise of the current injection",
+            type=VariableType.Object,
+            cardinality=ContractCardinality.One,
+            children=[
+                ContractVariable(
+                    key=EXERCISE + ".id",
+                    label="Id of the exercise in the platform",
+                    type=VariableType.String,
+                    cardinality=ContractCardinality.One,
+                ),
+                ContractVariable(
+                    key=EXERCISE + ".name",
+                    label="Name of the exercise",
+                    type=VariableType.String,
+                    cardinality=ContractCardinality.One,
+                ),
+                ContractVariable(
+                    key=EXERCISE + ".description",
+                    label="Description of the exercise",
+                    type=VariableType.String,
+                    cardinality=ContractCardinality.One,
+                ),
+            ],
+        )
+
+    @staticmethod
+    def team_variable():
+        return ContractVariable(
+            key=TEAMS,
+            label="List of team name for the injection",
+            type=VariableType.String,
+            cardinality=ContractCardinality.Multiple,
+        )
+
+    @staticmethod
+    def uri_variables():
+        return [
+            ContractVariable(
+                key=PLAYER_URI,
+                label="Player interface platform link",
+                type=VariableType.String,
+                cardinality=ContractCardinality.One,
+            ),
+            ContractVariable(
+                key=CHALLENGES_URI,
+                label="Challenges interface platform link",
+                type=VariableType.String,
+                cardinality=ContractCardinality.One,
+            ),
+            ContractVariable(
+                key=SCOREBOARD_URI,
+                label="Scoreboard interface platform link",
+                type=VariableType.String,
+                cardinality=ContractCardinality.One,
+            ),
+            ContractVariable(
+                key=LESSONS_URI,
+                label="Lessons learned interface platform link",
+                type=VariableType.String,
+                cardinality=ContractCardinality.One,
+            ),
+        ]

pyoaev/daemons/__init__.py

@@ -0,0 +1,4 @@
+from .base_daemon import BaseDaemon
+from .collector_daemon import CollectorDaemon
+
+__all__ = ["BaseDaemon", "CollectorDaemon"]

pyoaev/daemons/base_daemon.py

@@ -0,0 +1,131 @@
+from abc import ABC, abstractmethod
+from inspect import signature
+from types import FunctionType
+
+from pyoaev.client import OpenAEV
+from pyoaev.configuration import Configuration
+from pyoaev.exceptions import OpenAEVError
+from pyoaev.utils import logger
+
+
+class BaseDaemon(ABC):
+    """A base class for implementing a kind of daemon that periodically polls
+    a given callback.
+
+    :param configuration: configuration to provide the daemon
+        (allowing for looking up values within the callback for example)
+    :type configuration: Configuration
+    :param callback: a method or function to periodically call, defaults to None.
+    :type callback: callable, optional
+    :param logger: a logger object, to log events. if not supplied, a default logger
+        will be spawned to provide this functionality.
+    :type logger: Any
+    :param api_client: an API client that will provide connectivity with other systems.
+    :type api_client: Any
+    """
+
+    def __init__(
+        self,
+        configuration: Configuration,
+        callback: callable = None,
+        logger=None,
+        api_client=None,
+    ):
+        self._configuration = configuration
+        self._callback = callback
+        self.api = api_client or BaseDaemon.__get_default_api_client(
+            url=self._configuration.get("openaev_url"),
+            token=self._configuration.get("openaev_token"),
+        )
+
+        # logging
+        # compatibility layer: in order for older configs to still work, search for legacy names
+        actual_log_level = (
+            self._configuration.get("log_level")
+            or self._configuration.get("collector_log_level")
+            or self._configuration.get("injector_log_level")
+            or "info"
+        )
+        actual_log_name = (
+            self._configuration.get("name")
+            or self._configuration.get("collector_name")
+            or self._configuration.get("injector_name")
+            or "daemon"
+        )
+        self.logger = logger or BaseDaemon.__get_default_logger(
+            actual_log_level.upper(),
+            actual_log_name,
+        )
+
+    @abstractmethod
+    def _setup(self):
+        """A run-once method that inheritors must implement. This serves to instantiate
+        all useful objects and functionality for the implementor to run.
+        """
+        pass
+
+    @abstractmethod
+    def _start_loop(self):
+        """Starts the daemon's main execution loop. Implementors should implement
+        the main execution logic in here.
+        """
+        pass
+
+    def _try_callback(self):
+        """Tries to call the configured callback. Note that if any error is thrown,
+        it is immediately swallowed (but still logged) allowing the collector to keep
+        running. This is useful for any transient issue (e.g. API endpoint down...).
+        """
+        try:
+            # this is some black magic to allow injecting the collector daemon instance
+            # into an arbitrary callback that has a specific argument name
+            # this allow for avoiding subclassing the CollectorDaemon class just to provide the callback
+            # Example:
+            #
+            # def standalone_func(collector):
+            #   collector.api.call_openaev()
+            #
+            # CollectorDaemon(config=<pyboas.configuration.Configuration>, standalone_func).start()
+            if (
+                isinstance(self._callback, FunctionType)
+                and "collector" in signature(self._callback).parameters
+            ):
+                self._callback(collector=self)
+            else:
+                self._callback()
+        except Exception as err:  # pylint: disable=broad-except
+            self.logger.error(f"Error calling: {err}")
+
+    def start(self):
+        """Start the daemon. This will run the implementor's run-once setup method and
+        follow-up with the main execution loop. Note that at this point, if there is no
+        configured callback, the method will abort and kill the daemon.
+        """
+        if self._callback is None:
+            raise OpenAEVError("This daemon has no configured callback.")
+        self._setup()
+        self._start_loop()
+
+    def set_callback(self, callback: callable):
+        """Configures a callback to call in the main execution loop. If the callback
+        was not provided in the daemon's ctor, this should be set before calling start().
+        """
+        self._callback = callback
+
+    def get_id(self):
+        """Returns the daemon instance's ID contained in configuration. Configuration
+        must define any of these keys: `id`, `collector_id`, `injector_id`.
+        """
+        return (
+            self._configuration.get("id")
+            or self._configuration.get("collector_id")
+            or self._configuration.get("injector_id")
+        )
+
+    @classmethod
+    def __get_default_api_client(cls, url, token):
+        return OpenAEV(url=url, token=token)
+
+    @classmethod
+    def __get_default_logger(cls, log_level, name):
+        return logger(log_level)(name)

pyoaev/daemons/collector_daemon.py

@@ -0,0 +1,91 @@
+import sched
+import time
+
+from pyoaev import Configuration
+from pyoaev.daemons import BaseDaemon
+from pyoaev.utils import PingAlive
+
+DEFAULT_PERIOD_SECONDS = 60
+
+
+class CollectorDaemon(BaseDaemon):
+    """Implementation of a daemon of Collector type. Note that it requires
+    specific configuration keys to run its setup.
+    `collector_icon_filepath`: relative path to an icon image (preferably PNG)
+    `collector_id`: unique identifier for the collector (UUIDv4)
+    `collector_period`: time to wait in seconds between each loop execution; note
+    that this time is added to the time the loop takes to run, so the actual total
+    time between each loop start is time_of_loop+period.
+    """
+
+    def __init__(
+        self,
+        configuration: Configuration,
+        callback: callable = None,
+        logger=None,
+        api_client=None,
+        collector_type=None,
+    ):
+        super().__init__(configuration, callback, logger, api_client)
+        if collector_type is None:
+            raise ValueError("Must define a value for collector type")
+        self.collector_type = collector_type
+
+    def _setup(self):
+        if self._configuration.get("collector_period") is None:
+            self._configuration.set("collector_period", DEFAULT_PERIOD_SECONDS)
+        icon_path = self._configuration.get("collector_icon_filepath")
+        icon_name = self._configuration.get("collector_id") + ".png"
+        with open(icon_path, "rb") as icon_file_handle:
+            collector_icon = (icon_name, icon_file_handle, "image/png")
+            document = self.api.document.upsert(document={}, file=collector_icon)
+            if self._configuration.get("collector_platform") is not None:
+                security_platform = self.api.security_platform.upsert(
+                    {
+                        "asset_name": self._configuration.get("collector_name"),
+                        "asset_external_reference": self._configuration.get(
+                            "collector_id"
+                        ),
+                        "security_platform_type": self._configuration.get(
+                            "collector_platform"
+                        ),
+                        "security_platform_logo_light": document.get("document_id"),
+                        "security_platform_logo_dark": document.get("document_id"),
+                    }
+                )
+            else:
+                security_platform = {}
+            security_platform_id = security_platform.get("asset_id")
+            config = {
+                "collector_id": self._configuration.get("collector_id"),
+                "collector_name": self._configuration.get("collector_name"),
+                "collector_type": self.collector_type,
+                "collector_period": self._configuration.get("collector_period"),
+                "collector_security_platform": security_platform_id,
+            }
+        with open(icon_path, "rb") as icon_file_handle:
+            collector_icon = (icon_name, icon_file_handle, "image/png")
+            self.api.collector.create(config, collector_icon)
+
+        PingAlive(self.api, config, self.logger, "collector").start()
+
+    def _start_loop(self):
+        scheduler = sched.scheduler(time.time, time.sleep)
+        delay = self._configuration.get("collector_period")
+        self._try_callback()
+        scheduler.enter(
+            delay=delay,
+            priority=1,
+            action=self.__schedule,
+            argument=(scheduler, self._try_callback, delay),
+        )
+        scheduler.run()
+
+    def __schedule(self, scheduler, callback, delay):
+        callback()
+        scheduler.enter(
+            delay=delay,
+            priority=1,
+            action=self.__schedule,
+            argument=(scheduler, callback, delay),
+        )

pyoaev/exceptions.py

@@ -0,0 +1,219 @@
+import functools
+from typing import TYPE_CHECKING, Any, Callable, Optional, Type, TypeVar, Union, cast
+
+
+class OpenAEVError(Exception):
+    def __init__(
+        self,
+        error_message: Union[str, bytes] = "",
+        response_code: Optional[int] = None,
+        response_body: Optional[bytes] = None,
+    ) -> None:
+        Exception.__init__(self, error_message)
+        # Http status code
+        self.response_code = response_code
+        # Full http response
+        self.response_body = response_body
+        try:
+            # if we receive str/bytes we try to convert to unicode/str to have
+            # consistent message types (see #616)
+            if TYPE_CHECKING:
+                assert isinstance(error_message, bytes)
+            self.error_message = error_message.decode()
+        except Exception:
+            if TYPE_CHECKING:
+                assert isinstance(error_message, str)
+            self.error_message = error_message
+
+    def __str__(self) -> str:
+        # Start with the provided error message
+        message = self.error_message
+
+        # List of generic HTTP status messages that indicate we should look deeper
+        generic_messages = (
+            "Internal Server Error",
+            "Bad Request",
+            "Not Found",
+            "Unauthorized",
+            "Forbidden",
+            "Service Unavailable",
+            "Gateway Timeout",
+            "Unknown error",
+            "Validation Failed",
+        )
+
+        # Only try to extract from response body if message is truly generic
+        # Don't override if we already have a specific error message
+        if (
+            not message or (message in generic_messages and len(message) < 30)
+        ) and self.response_body is not None:
+            try:
+                import json
+
+                body = self.response_body.decode(errors="ignore")
+                data = json.loads(body)
+                extracted_msg = None
+
+                if isinstance(data, dict):
+                    # Try various common error fields
+                    if "error" in data:
+                        err = data.get("error")
+                        if isinstance(err, dict) and "message" in err:
+                            extracted_msg = err.get("message")
+                        elif isinstance(err, str):
+                            extracted_msg = err
+                    elif "message" in data:
+                        extracted_msg = data.get("message")
+                    elif "execution_message" in data:
+                        extracted_msg = data.get("execution_message")
+                    elif "detail" in data:
+                        extracted_msg = data.get("detail")
+                    elif "errors" in data:
+                        errs = data.get("errors")
+                        if isinstance(errs, list) and errs:
+                            # Join any messages in the list
+                            parts = []
+                            for item in errs:
+                                if isinstance(item, dict) and "message" in item:
+                                    parts.append(str(item.get("message")))
+                                else:
+                                    parts.append(str(item))
+                            extracted_msg = "; ".join(parts)
+                        elif isinstance(errs, dict):
+                            # Handle nested validation errors structure
+                            if "children" in errs:
+                                validation_errors = []
+                                children = errs.get("children", {})
+                                for field, field_errors in children.items():
+                                    if (
+                                        isinstance(field_errors, dict)
+                                        and "errors" in field_errors
+                                    ):
+                                        field_error_list = field_errors.get(
+                                            "errors", []
+                                        )
+                                        if field_error_list:
+                                            for err_msg in field_error_list:
+                                                validation_errors.append(
+                                                    f"{field}: {err_msg}"
+                                                )
+                                if validation_errors:
+                                    base_msg = data.get("message", "Validation Failed")
+                                    extracted_msg = (
+                                        f"{base_msg}: {'; '.join(validation_errors)}"
+                                    )
+                            else:
+                                # Try to get any string representation
+                                parts = []
+                                for key, value in errs.items():
+                                    if value:
+                                        parts.append(f"{key}: {value}")
+                                if parts:
+                                    extracted_msg = "; ".join(parts)
+                        elif isinstance(errs, str):
+                            extracted_msg = errs
+
+                # Use extracted message if it's better than what we have
+                if extracted_msg and extracted_msg not in generic_messages:
+                    message = str(extracted_msg)
+                elif not message:
+                    # Last resort: use the raw body
+                    message = body[:500]
+
+            except json.JSONDecodeError:
+                # Not JSON, use raw text if we don't have a good message
+                if not message or message in generic_messages:
+                    try:
+                        decoded = self.response_body.decode(errors="ignore")[:500]
+                        if decoded and decoded not in generic_messages:
+                            message = decoded
+                    except Exception:
+                        pass
+            except Exception:
+                pass
+
+        # Final fallback
+        if not message:
+            message = "Unknown error"
+
+        # Clean up the message - remove extra whitespace and newlines
+        message = " ".join(message.split())
+
+        if self.response_code is not None:
+            return f"{self.response_code}: {message}"
+        return f"{message}"
+
+
+class OpenAEVAuthenticationError(OpenAEVError):
+    pass
+
+
+class OpenAEVHttpError(OpenAEVError):
+    pass
+
+
+class OpenAEVParsingError(OpenAEVError):
+    pass
+
+
+class RedirectError(OpenAEVError):
+    pass
+
+
+class OpenAEVHeadError(OpenAEVError):
+    pass
+
+
+class OpenAEVGetError(OpenAEVError):
+    pass
+
+
+class OpenAEVUpdateError(OpenAEVError):
+    pass
+
+
+class OpenAEVListError(OpenAEVError):
+    pass
+
+
+class OpenAEVCreateError(OpenAEVError):
+    pass
+
+
+class ConfigurationError(OpenAEVError):
+    pass
+
+
+# For an explanation of how these type-hints work see:
+# https://mypy.readthedocs.io/en/stable/generics.html#declaring-decorators
+#
+# The goal here is that functions which get decorated will retain their types.
+__F = TypeVar("__F", bound=Callable[..., Any])
+
+
+def on_http_error(error: Type[Exception]) -> Callable[[__F], __F]:
+    def wrap(f: __F) -> __F:
+        @functools.wraps(f)
+        def wrapped_f(*args: Any, **kwargs: Any) -> Any:
+            try:
+                return f(*args, **kwargs)
+            except OpenAEVHttpError as e:
+                raise error(e.error_message, e.response_code, e.response_body) from e
+
+        return cast(__F, wrapped_f)
+
+    return wrap
+
+
+# Export manually to keep mypy happy
+__all__ = [
+    "ConfigurationError",
+    "OpenAEVAuthenticationError",
+    "OpenAEVHttpError",
+    "OpenAEVParsingError",
+    "RedirectError",
+    "OpenAEVHeadError",
+    "OpenAEVListError",
+    "OpenAEVGetError",
+    "OpenAEVUpdateError",
+]