pyoaev 1.18.20__py3-none-any.whl

pyoaev/configuration/configuration.py

@@ -0,0 +1,188 @@
+import os
+import os.path
+from typing import Any, Dict, Optional
+
+import yaml
+from pydantic import BaseModel, Field
+
+from pyoaev.configuration.sources import DictionarySource, EnvironmentSource
+
+CONFIGURATION_TYPES = str | int | bool | Any | None
+
+
+def is_truthy(value: str) -> bool:
+    """Asserts whether a given string signals a "True" value
+
+    :param value: value to test
+    :type value: str
+
+    :return: whether the string represents True or not.
+    :rtype: bool
+    """
+    return value.lower() in ["yes", "true"]
+
+
+def is_falsy(value: str) -> bool:
+    """Asserts whether a given string signals a "False" value
+
+    :param value: value to test
+    :type value: str
+
+    :return: whether the string represents False or not.
+    :rtype: bool
+    """
+    return value.lower() in ["no", "false"]
+
+
+class ConfigurationHint(BaseModel):
+    """An individual configuration hint. This allows for specifying
+    where any given configuration key can be found, in env vars,
+    config files. Additionally, it may define a default value or
+    a discrete override value.
+    """
+
+    data: Optional[CONFIGURATION_TYPES] = Field(default=None)
+    """Override value; when set, getting the configuration value for
+        the key described in this instance returns this value.
+    """
+    env: Optional[str] = Field(default=None)
+    """Defines which env var should be read for getting the value
+    """
+    file_path: Optional[list[str]] = Field(default=None)
+    """Defines a JSON path (nested keys) to follow in the provided
+        config file for reaching the value.
+        
+        Example: ["toplevel", "subkey"] will hint for searching for 
+        the config key at { "toplevel": { "subkey": { "config_key"}}
+    """
+    is_number: Optional[bool] = Field(default=False)
+    """Hints at whteher the configuration value should be
+        interpreted as a number.
+    """
+    default: Optional[CONFIGURATION_TYPES] = Field(default=None)
+    """When defined, provides a default value for whenever none of the
+        hinted locations or the data field have a value.
+    """
+
+
+class Configuration:
+    """A configuration object providing ways to an interface for getting
+    configuration values. It should be provided with a collection of hints
+    to enable its behaviour.
+
+        :param config_hints: a dictionary of hints, for which the key is the
+            desired configuration key (e.g. "log_level") and the value is either
+            a dictionary of hints (see ConfigurationHint) or a standalone string.
+            In the latter case, the string will be interpreted as a default value.
+
+            Example:
+            .. code-block:: python
+                {
+                    "my_config_key": {
+                        "env" : "MY_CONFIG_VALUE_ENV_VAR",
+                        "file_path": ["first_level", "second_level"]
+                    },
+                    "my_other_config_key: "discrete value"
+                }
+        :type config_hints: Dict[str, dict | str]
+        :param config_values: dictionary of config values to preemptively load into the
+            Configuration object. The format of this dictionary should follow the patterns
+            chosen in the file_path property of ConfigurationHint object passed
+            as config_hints, defaults to None
+
+            Example:
+            .. code-block:: python
+                {
+                    "first_level": {
+                        "second_level": {
+                            "my_config_key": "some value"
+                        }
+                    }
+                }
+        :type config_values: dict (json), optional
+        :param config_file_path: path to the configuration file. The file should
+            contain a json structure that matches the format of the config_values param,
+            defaults to './config.yml' (relative path).
+        :type config_file_path: str
+    """
+
+    def __init__(
+        self,
+        config_hints: Dict[str, dict | str],
+        config_values: dict = None,
+        config_file_path: str = os.path.join(os.curdir, "config.yml"),
+    ):
+        self.__config_hints = {
+            key: (
+                ConfigurationHint(**value)
+                if isinstance(value, dict)
+                else ConfigurationHint(**{"default": value})
+            )
+            for key, value in config_hints.items()
+        }
+
+        file_contents = (
+            yaml.load(open(config_file_path), Loader=yaml.FullLoader)
+            if os.path.isfile(config_file_path)
+            else {}
+        )
+
+        self.__config_values = (config_values or {}) | file_contents
+
+    def get(self, config_key: str) -> CONFIGURATION_TYPES:
+        """Gets the value pointed to by the configuration key. If the key is defined
+        with actual hints (as opposed to a discrete value), it will use those hints to
+        potentially find a value. If the key was not defined as part of the supplied
+        config_hints, this will always return None.
+
+        :param config_key: the configuration key to search a value for.
+        :type config_key: str
+
+        :return: the value pointed to by the configuration key, or None if not found
+        :rtype: CONFIGURATION_TYPES
+        """
+        config = self.__config_hints.get(config_key)
+        if config is None:
+            return None
+
+        return self.__process_value_to_type(
+            config.data or self.__dig_config_sources_for_key(config), config.is_number
+        )
+
+    def set(self, config_key: str, value: CONFIGURATION_TYPES):
+        """Sets an arbitrary value in the Configuration object, for
+        the supplied configuration key, after which any request for the value
+        of that key will return this new value.
+
+        :param config_key: the configuration key to set a value for.
+        :type config_key: str
+        :param value: the new value to set for the configuration key.
+        :type value: CONFIGURATION_TYPES
+        """
+        if config_key not in self.__config_hints:
+            self.__config_hints[config_key] = ConfigurationHint(**{"data": value})
+        else:
+            self.__config_hints[config_key].data = value
+
+    @staticmethod
+    def __process_value_to_type(value: CONFIGURATION_TYPES, is_number_hint: bool):
+        if value is None:
+            return value
+        if isinstance(value, int) or is_number_hint:
+            return int(value)
+        if isinstance(value, str):
+            if is_truthy(value):
+                return True
+            if is_falsy(value):
+                return False
+            if len(value) == 0:
+                return None
+        return value
+
+    def __dig_config_sources_for_key(
+        self, config: ConfigurationHint
+    ) -> CONFIGURATION_TYPES:
+        result = EnvironmentSource.get(config.env) or DictionarySource.get(
+            config.file_path, self.__config_values
+        )
+        return result or config.default

pyoaev/configuration/sources.py

@@ -0,0 +1,44 @@
+import os
+
+
+class EnvironmentSource:
+    """A utility for fecthing a value in the env vars."""
+
+    @classmethod
+    def get(cls, env_var: str) -> str | None:
+        """Gets the value for the specified env var
+
+        :param env_var: the name of the env var to query
+        :type env_var: str
+
+        :return: value of the env var, or None if not found
+        :rtype: str | None
+        """
+        return os.getenv(env_var)
+
+
+class DictionarySource:
+    """A utility for fetching a value from within a JSON-like (nested dict) structure"""
+
+    # this is quite hacky
+    # it only strictly handles two levels of keys in a dict
+    @classmethod
+    def get(cls, config_key_path: list[str], source_dict: dict) -> str | None:
+        """Gets the value for the specified env var
+
+        :param config_key_path: the two-level dictionary path to the config key
+        :type config_key_path: list[str]
+        :param source_dict: JSON-like (nested dict) structure containing config values.
+        :type source_dict: dict
+
+        :return: value for the config key at specified path, or None if not found
+        :rtype: str | None
+        """
+        assert (
+            isinstance(config_key_path, list)
+            and len(config_key_path) == 2
+            and all([len(path_part) > 0 for path_part in config_key_path])
+        )
+        return source_dict.get(config_key_path[0], {config_key_path[1]: None}).get(
+            config_key_path[1]
+        )

pyoaev/contracts/__init__.py

@@ -0,0 +1,5 @@
+from .contract_builder import ContractBuilder  # noqa: F401,F403
+
+__all__ = [
+    "ContractBuilder",
+]

pyoaev/contracts/contract_builder.py

@@ -0,0 +1,44 @@
+from typing import List
+
+from pyoaev.contracts.contract_config import ContractElement, ContractOutputElement
+
+
+class ContractBuilder:
+    fields: List[ContractElement]
+    outputs: List[ContractOutputElement]
+
+    def __init__(self):
+        self.fields = []
+        self.outputs = []
+
+    def add_fields(self, fields: List[ContractElement]):
+        self.fields = self.fields + fields
+        return self
+
+    def add_outputs(self, outputs: List[ContractOutputElement]):
+        self.outputs = self.outputs + outputs
+        return self
+
+    def mandatory(self, element: ContractElement):
+        element.mandatory = True
+        self.fields.append(element)
+        return self
+
+    def optional(self, element: ContractElement):
+        element.mandatory = False
+        self.fields.append(element)
+        return self
+
+    def mandatory_group(self, elements: List[ContractElement]):
+        keys: List[str] = list(map(lambda iterable: iterable.key, elements))
+        for element in elements:
+            element.mandatory = True
+            element.mandatoryGroups = keys
+            self.fields.append(element)
+        return self
+
+    def build_fields(self) -> List[ContractElement]:
+        return self.fields
+
+    def build_outputs(self) -> List[ContractOutputElement]:
+        return self.outputs

pyoaev/contracts/contract_config.py

@@ -0,0 +1,292 @@
+import json
+from abc import ABC, abstractmethod
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import Dict, List
+
+from pyoaev import utils
+from pyoaev.contracts.contract_utils import ContractCardinality, ContractVariable
+from pyoaev.contracts.variable_helper import VariableHelper
+
+
+class SupportedLanguage(str, Enum):
+    fr: str = "fr"
+    en: str = "en"
+
+
+class ContractFieldType(str, Enum):
+    Text: str = "text"
+    Number: str = "number"
+    Tuple: str = "tuple"
+    Checkbox: str = "checkbox"
+    Textarea: str = "textarea"
+    Select: str = "select"
+    Article: str = "article"
+    Challenge: str = "challenge"
+    DependencySelect: str = "dependency-select"
+    Attachment: str = "attachment"
+    Team: str = "team"
+    Expectation: str = "expectation"
+    Asset: str = "asset"
+    AssetGroup: str = "asset-group"
+    Payload: str = "payload"
+
+
+class ContractOutputType(str, Enum):
+    Text: str = "text"
+    Number: str = "number"
+    Port: str = "port"
+    PortsScan: str = "portscan"
+    IPv4: str = "ipv4"
+    IPv6: str = "ipv6"
+    CVE: str = "cve"
+
+
+class ExpectationType(str, Enum):
+    text: str = "TEXT"
+    document: str = "DOCUMENT"
+    article: str = "ARTICLE"
+    challenge: str = "CHALLENGE"
+    manual: str = "MANUAL"
+    prevention: str = "PREVENTION"
+    detection: str = "DETECTION"
+    vulnerability: str = "VULNERABILITY"
+
+
+@dataclass
+class Expectation:
+    expectation_type: ExpectationType
+    expectation_name: str
+    expectation_description: str
+    expectation_score: int
+    expectation_expectation_group: bool
+
+
+@dataclass
+class LinkedFieldModel:
+    key: str
+    type: ContractFieldType
+
+
+@dataclass
+class ContractElement(ABC):
+    key: str
+    label: str
+    type: str = field(default="", init=False)
+    mandatoryGroups: List[str] = field(default_factory=list)
+    mandatoryConditionFields: List[str] = field(default_factory=list)
+    mandatoryConditionValues: Dict[str, any] = field(default_factory=list)
+    visibleConditionFields: List[str] = field(default_factory=list)
+    visibleConditionValues: Dict[str, any] = field(default_factory=list)
+    linkedFields: List[str] = field(default_factory=list)
+    mandatory: bool = False
+    readOnly: bool = False
+
+    @property
+    @abstractmethod
+    def get_type(self) -> str:
+        pass
+
+    def __post_init__(self):
+        self.type = self.get_type
+
+
+@dataclass
+class ContractCardinalityElement(ContractElement, ABC):
+    cardinality: str = ContractCardinality.One
+    defaultValue: List[str] = field(default_factory=list)
+
+
+@dataclass
+class ContractOutputElement(ABC):
+    type: str
+    field: str
+    labels: List[str]
+    isFindingCompatible: bool
+    isMultiple: bool
+
+
+@dataclass
+class ContractConfig:
+    type: str
+    expose: bool
+    label: dict[SupportedLanguage, str]
+    color_dark: str
+    color_light: str
+
+
+@dataclass
+class Contract:
+    contract_id: str
+    label: dict[SupportedLanguage, str]
+    fields: List[ContractElement]
+    outputs: List[ContractOutputElement]
+    config: ContractConfig
+    manual: bool
+    variables: List[ContractVariable] = field(
+        default_factory=lambda: [
+            VariableHelper.user_variable(),
+            VariableHelper.exercise_variable(),
+            VariableHelper.team_variable(),
+        ]
+        + VariableHelper.uri_variables()
+    )
+    contract_attack_patterns_external_ids: List[str] = field(default_factory=list)
+    contract_vulnerability_external_ids: List[str] = field(default_factory=list)
+    is_atomic_testing: bool = True
+    platforms: List[str] = field(default_factory=list)
+    external_id: str = None
+
+    def add_attack_pattern(self, var: str):
+        self.contract_attack_patterns_external_ids.append(var)
+
+    def add_vulnerability(self, var: str):
+        self.contract_vulnerability_external_ids.append(var)
+
+    def add_variable(self, var: ContractVariable):
+        self.variables.append(var)
+
+    def to_contract_add_input(self, source_id: str):
+        return {
+            "contract_id": self.contract_id,
+            "external_contract_id": self.external_id,
+            "injector_id": source_id,
+            "contract_manual": self.manual,
+            "contract_labels": self.label,
+            "contract_attack_patterns_external_ids": self.contract_attack_patterns_external_ids,
+            "contract_vulnerability_external_ids": self.contract_vulnerability_external_ids,
+            "contract_content": json.dumps(self, cls=utils.EnhancedJSONEncoder),
+            "is_atomic_testing": self.is_atomic_testing,
+            "contract_platforms": self.platforms,
+        }
+
+    def to_contract_update_input(self):
+        return {
+            "contract_manual": self.manual,
+            "contract_labels": self.label,
+            "contract_attack_patterns_external_ids": self.contract_attack_patterns_external_ids,
+            "contract_vulnerability_external_ids": self.contract_vulnerability_external_ids,
+            "contract_content": json.dumps(self, cls=utils.EnhancedJSONEncoder),
+            "is_atomic_testing": self.is_atomic_testing,
+            "contract_platforms": self.platforms,
+        }
+
+
+@dataclass
+class ContractTeam(ContractCardinalityElement):
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Team.value
+
+
+@dataclass
+class ContractText(ContractCardinalityElement):
+
+    defaultValue: str = ""
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Text.value
+
+
+def prepare_contracts(contracts):
+    return list(
+        map(
+            lambda c: {
+                "contract_id": c.contract_id,
+                "contract_labels": c.label,
+                "contract_attack_patterns_external_ids": c.contract_attack_patterns_external_ids,
+                "contract_content": json.dumps(c, cls=utils.EnhancedJSONEncoder),
+                "contract_platforms": c.platforms,
+            },
+            contracts,
+        )
+    )
+
+
+@dataclass
+class ContractTuple(ContractCardinalityElement):
+    def __post_init__(self):
+        super().__post_init__()
+        self.cardinality = ContractCardinality.Multiple
+
+    attachmentKey: str = None
+    contractAttachment: bool = attachmentKey is not None
+    tupleFilePrefix: str = "file :: "
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Tuple.value
+
+
+@dataclass
+class ContractTextArea(ContractCardinalityElement):
+
+    defaultValue: str = ""
+    richText: bool = False
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Textarea.value
+
+
+@dataclass
+class ContractCheckbox(ContractElement):
+
+    defaultValue: bool = False
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Checkbox.value
+
+
+@dataclass
+class ContractAttachment(ContractCardinalityElement):
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Attachment.value
+
+
+@dataclass
+class ContractExpectations(ContractCardinalityElement):
+    cardinality = ContractCardinality.Multiple
+    predefinedExpectations: List[Expectation] = field(default_factory=list)
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Expectation.value
+
+
+@dataclass
+class ContractSelect(ContractCardinalityElement):
+
+    choices: dict[str, str] = None
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Select.value
+
+
+@dataclass
+class ContractAsset(ContractCardinalityElement):
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Asset.value
+
+
+@dataclass
+class ContractAssetGroup(ContractCardinalityElement):
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.AssetGroup.value
+
+
+@dataclass
+class ContractPayload(ContractCardinalityElement):
+
+    @property
+    def get_type(self) -> str:
+        return ContractFieldType.Payload.value

pyoaev/contracts/contract_utils.py

@@ -0,0 +1,22 @@
+from dataclasses import dataclass, field
+from enum import Enum
+from typing import List
+
+
+class ContractCardinality(str, Enum):
+    One: str = "1"
+    Multiple: str = "n"
+
+
+class VariableType(str, Enum):
+    String: str = "String"
+    Object: str = "Object"
+
+
+@dataclass
+class ContractVariable:
+    key: str
+    label: str
+    type: VariableType
+    cardinality: ContractCardinality
+    children: List["ContractVariable"] = field(default_factory=list)