mal-toolbox 1.2.1__py3-none-any.whl → 2.1.0__py3-none-any.whl

maltoolbox/language/detector.py

@@ -0,0 +1,43 @@
+"""Detector functionality
+- A detector represent a logging rule on an attack step
+- It includes a context and a name
+"""
+
+
+from __future__ import annotations
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True, eq=True)
+class Detector:
+    name: str | None
+    context: Context
+    type: str | None
+    tprate: dict | None
+
+    def to_dict(self) -> dict:
+        return {
+            "context": self.context.to_dict(),
+            "name": self.name,
+            "type": self.type,
+            "tprate": self.tprate,
+        }
+
+
+class Context(dict):
+    """Context is part of detectors to provide meta data about attackers"""
+
+    def __init__(self, context) -> None:
+        super().__init__(context)
+        self._context_dict = context
+        for label, asset in context.items():
+            setattr(self, label, asset)
+
+    def to_dict(self) -> dict:
+        return {label: asset.name for label, asset in self.items()}
+
+    def __str__(self) -> str:
+        return str({label: asset.name for label, asset in self._context_dict.items()})
+
+    def __repr__(self) -> str:
+        return f"Context({self!s}))"

maltoolbox/language/expression_chain.py

@@ -0,0 +1,218 @@
+"""Expression chain functionality
+- Used to specify association paths and operations to reach children/parents of steps
+"""
+from __future__ import annotations
+from typing import TYPE_CHECKING
+import json
+import logging
+from typing import Any
+
+from maltoolbox.exceptions import LanguageGraphAssociationError, LanguageGraphException
+from maltoolbox.language.language_graph_assoc import LanguageGraphAssociation
+
+if TYPE_CHECKING:
+    from maltoolbox.language.languagegraph import LanguageGraph
+
+logger = logging.getLogger(__name__)
+
+class ExpressionsChain:
+    """A series of linked step expressions that specify the association path and
+    operations to take to reach the child/parent attack step.
+    """
+
+    def __init__(self,
+            type: str,
+            left_link: ExpressionsChain | None = None,
+            right_link: ExpressionsChain | None = None,
+            sub_link: ExpressionsChain | None = None,
+            fieldname: str | None = None,
+            association=None,
+            subtype=None
+        ):
+        self.type = type
+        self.left_link: ExpressionsChain | None = left_link
+        self.right_link: ExpressionsChain | None = right_link
+        self.sub_link: ExpressionsChain | None = sub_link
+        self.fieldname: str | None = fieldname
+        self.association: LanguageGraphAssociation | None = association
+        self.subtype: Any | None = subtype
+
+    def to_dict(self) -> dict:
+        """Convert ExpressionsChain to dictionary"""
+        match (self.type):
+            case 'union' | 'intersection' | 'difference' | 'collect':
+                return {
+                    self.type: {
+                        'left': self.left_link.to_dict()
+                                if self.left_link else {},
+                        'right': self.right_link.to_dict()
+                                 if self.right_link else {}
+                    },
+                    'type': self.type
+                }
+
+            case 'field':
+                if not self.association:
+                    raise LanguageGraphAssociationError(
+                        "Missing association for expressions chain"
+                    )
+                if self.fieldname == self.association.left_field.fieldname:
+                    asset_type = self.association.left_field.asset.name
+                elif self.fieldname == self.association.right_field.fieldname:
+                    asset_type = self.association.right_field.asset.name
+                else:
+                    raise LanguageGraphException(
+                        'Failed to find fieldname "%s" in association:\n%s' %
+                        (
+                            self.fieldname,
+                            json.dumps(self.association.to_dict(),
+                                indent=2)
+                        )
+                    )
+
+                return {
+                    self.association.name:
+                    {
+                        'fieldname': self.fieldname,
+                        'asset type': asset_type
+                    },
+                    'type': self.type
+                }
+
+            case 'transitive':
+                if not self.sub_link:
+                    raise LanguageGraphException(
+                        "No sub link for transitive expressions chain"
+                    )
+                return {
+                    'transitive': self.sub_link.to_dict(),
+                    'type': self.type
+                }
+
+            case 'subType':
+                if not self.subtype:
+                    raise LanguageGraphException(
+                        "No subtype for expressions chain"
+                    )
+                if not self.sub_link:
+                    raise LanguageGraphException(
+                        "No sub link for subtype expressions chain"
+                    )
+                return {
+                    'subType': self.subtype.name,
+                    'expression': self.sub_link.to_dict(),
+                    'type': self.type
+                }
+
+            case _:
+                msg = 'Unknown associations chain element %s!'
+                logger.error(msg, self.type)
+                raise LanguageGraphAssociationError(msg % self.type)
+
+    @classmethod
+    def _from_dict(cls,
+            serialized_expr_chain: dict,
+            lang_graph: LanguageGraph,
+        ) -> ExpressionsChain | None:
+        """Create ExpressionsChain from dict
+        Args:
+        serialized_expr_chain   - expressions chain in dict format
+        lang_graph              - the LanguageGraph that contains the assets,
+                                  associations, and attack steps relevant for
+                                  the expressions chain
+        """
+        if serialized_expr_chain is None or not serialized_expr_chain:
+            return None
+
+        if 'type' not in serialized_expr_chain:
+            logger.debug(json.dumps(serialized_expr_chain, indent=2))
+            msg = 'Missing expressions chain type!'
+            logger.error(msg)
+            raise LanguageGraphAssociationError(msg)
+
+        expr_chain_type = serialized_expr_chain['type']
+        match (expr_chain_type):
+            case 'union' | 'intersection' | 'difference' | 'collect':
+                left_link = cls._from_dict(
+                    serialized_expr_chain[expr_chain_type]['left'],
+                    lang_graph
+                )
+                right_link = cls._from_dict(
+                    serialized_expr_chain[expr_chain_type]['right'],
+                    lang_graph
+                )
+                new_expr_chain = ExpressionsChain(
+                    type=expr_chain_type,
+                    left_link=left_link,
+                    right_link=right_link
+                )
+                return new_expr_chain
+
+            case 'field':
+                assoc_name = list(serialized_expr_chain.keys())[0]
+                target_asset = lang_graph.assets[
+                    serialized_expr_chain[assoc_name]['asset type']]
+                fieldname = serialized_expr_chain[assoc_name]['fieldname']
+
+                association = None
+                for assoc in target_asset.associations.values():
+                    if assoc.contains_fieldname(fieldname) and \
+                            assoc.name == assoc_name:
+                        association = assoc
+                        break
+
+                if association is None:
+                    msg = 'Failed to find association "%s" with '\
+                        'fieldname "%s"'
+                    logger.error(msg, assoc_name, fieldname)
+                    raise LanguageGraphException(
+                        msg % (assoc_name, fieldname)
+                    )
+
+                new_expr_chain = ExpressionsChain(
+                    type='field',
+                    association=association,
+                    fieldname=fieldname
+                )
+                return new_expr_chain
+
+            case 'transitive':
+                sub_link = cls._from_dict(
+                    serialized_expr_chain['transitive'],
+                    lang_graph
+                )
+                new_expr_chain = ExpressionsChain(
+                    type='transitive',
+                    sub_link=sub_link
+                )
+                return new_expr_chain
+
+            case 'subType':
+                sub_link = cls._from_dict(
+                    serialized_expr_chain['expression'],
+                    lang_graph
+                )
+                subtype_name = serialized_expr_chain['subType']
+                if subtype_name in lang_graph.assets:
+                    subtype_asset = lang_graph.assets[subtype_name]
+                else:
+                    msg = 'Failed to find subtype %s'
+                    logger.error(msg, subtype_name)
+                    raise LanguageGraphException(msg % subtype_name)
+
+                new_expr_chain = ExpressionsChain(
+                    type='subType',
+                    sub_link=sub_link,
+                    subtype=subtype_asset
+                )
+                return new_expr_chain
+
+            case _:
+                msg = 'Unknown expressions chain type %s!'
+                logger.error(msg, serialized_expr_chain['type'])
+                raise LanguageGraphAssociationError(
+                    msg % serialized_expr_chain['type']
+                )
+
+    def __repr__(self) -> str:
+        return str(self.to_dict())

maltoolbox/language/language_graph_asset.py

@@ -0,0 +1,180 @@
+"""LanguageGraphAsset functionality
+- Represents an asset (type) defined in a MAL language
+"""
+
+from __future__ import annotations
+from typing import TYPE_CHECKING
+from dataclasses import dataclass, field
+from functools import cached_property
+from typing import Any
+
+from maltoolbox.language.language_graph_attack_step import LanguageGraphAttackStep
+
+if TYPE_CHECKING:
+    from maltoolbox.language.expression_chain import ExpressionsChain
+    from maltoolbox.language.language_graph_assoc import LanguageGraphAssociation
+
+@dataclass
+class LanguageGraphAsset:
+    """An asset type as defined in the MAL language"""
+
+    name: str
+    own_associations: dict[str, LanguageGraphAssociation] = \
+        field(default_factory=dict)
+    attack_steps: dict[str, LanguageGraphAttackStep] = \
+        field(default_factory=dict)
+    info: dict = field(default_factory=dict)
+    own_super_asset: LanguageGraphAsset | None = None
+    own_sub_assets: list[LanguageGraphAsset] = field(default_factory=list)
+    own_variables: dict = field(default_factory=dict)
+    is_abstract: bool | None = None
+
+    def to_dict(self) -> dict:
+        """Convert LanguageGraphAsset to dictionary"""
+        node_dict: dict[str, Any] = {
+            'name': self.name,
+            'associations': {},
+            'attack_steps': {},
+            'info': self.info,
+            'super_asset': self.own_super_asset.name
+                if self.own_super_asset else "",
+            'sub_assets': [asset.name for asset in self.own_sub_assets],
+            'variables': {},
+            'is_abstract': self.is_abstract
+        }
+
+        for fieldname, assoc in self.own_associations.items():
+            node_dict['associations'][fieldname] = assoc.to_dict()
+        for attack_step in self.attack_steps.values():
+            node_dict['attack_steps'][attack_step.name] = \
+                attack_step.to_dict()
+        for variable_name, (var_target_asset, var_expr_chain) in \
+                self.own_variables.items():
+            node_dict['variables'][variable_name] = (
+                var_target_asset.name,
+                var_expr_chain.to_dict()
+            )
+        return node_dict
+
+    def __repr__(self) -> str:
+        return f'LanguageGraphAsset(name: "{self.name}")'
+
+    def __hash__(self):
+        return id(self)
+
+    def is_subasset_of(self, target_asset: LanguageGraphAsset) -> bool:
+        """Check if an asset extends the target asset through inheritance.
+
+        Arguments:
+        ---------
+        target_asset    - the target asset we wish to evaluate if this asset
+                          extends
+
+        Return:
+        ------
+        True if this asset extends the target_asset via inheritance.
+        False otherwise.
+
+        """
+        current_asset: LanguageGraphAsset | None = self
+        while current_asset:
+            if current_asset == target_asset:
+                return True
+            current_asset = current_asset.own_super_asset
+        return False
+
+    @cached_property
+    def sub_assets(self) -> set[LanguageGraphAsset]:
+        """Return a list of all of the assets that directly or indirectly extend
+        this asset.
+
+        Return:
+        ------
+        A list of all of the assets that extend this asset plus itself.
+
+        """
+        subassets: list[LanguageGraphAsset] = []
+        for subasset in self.own_sub_assets:
+            subassets.extend(subasset.sub_assets)
+
+        subassets.extend(self.own_sub_assets)
+        subassets.append(self)
+
+        return set(subassets)
+
+    @cached_property
+    def super_assets(self) -> list[LanguageGraphAsset]:
+        """Return a list of all of the assets that this asset directly or
+        indirectly extends.
+
+        Return:
+        ------
+        A list of all of the assets that this asset extends plus itself.
+
+        """
+        current_asset: LanguageGraphAsset | None = self
+        superassets = []
+        while current_asset:
+            superassets.append(current_asset)
+            current_asset = current_asset.own_super_asset
+        return superassets
+
+    def associations_to(
+        self, asset_type: LanguageGraphAsset
+    ) -> dict[str, LanguageGraphAssociation]:
+        """Return dict of association types that go from self
+        to given `asset_type`
+        """
+        associations_to_asset_type = {}
+        for fieldname, association in self.associations.items():
+            if association in asset_type.associations.values():
+                associations_to_asset_type[fieldname] = association
+        return associations_to_asset_type
+
+    @cached_property
+    def associations(self) -> dict[str, LanguageGraphAssociation]:
+        """Return a list of all of the associations that belong to this asset
+        directly or indirectly via inheritance.
+
+        Return:
+        ------
+        A list of all of the associations that apply to this asset, either
+        directly or via inheritance.
+
+        """
+        associations = dict(self.own_associations)
+        if self.own_super_asset:
+            associations |= self.own_super_asset.associations
+        return associations
+
+    @property
+    def variables(
+            self
+        ) -> dict[str, tuple[LanguageGraphAsset, ExpressionsChain]]:
+        """Return a list of all of the variables that belong to this asset
+        directly or indirectly via inheritance.
+
+        Return:
+        ------
+        A list of all of the variables that apply to this asset, either
+        directly or via inheritance.
+
+        """
+        all_vars = dict(self.own_variables)
+        if self.own_super_asset:
+            all_vars |= self.own_super_asset.variables
+        return all_vars
+
+    def get_all_common_superassets(
+            self, other: LanguageGraphAsset
+        ) -> set[str]:
+        """Return a set of all common ancestors between this asset
+        and the other asset given as parameter
+        """
+        self_superassets = set(
+            asset.name for asset in self.super_assets
+        )
+        other_superassets = set(
+            asset.name for asset in other.super_assets
+        )
+        return self_superassets.intersection(other_superassets)

maltoolbox/language/language_graph_assoc.py

@@ -0,0 +1,147 @@
+"""LanguageGraphAssoc functionality
+- Represents an association (type) defined in a MAL language
+"""
+
+from __future__ import annotations
+from dataclasses import dataclass, field
+import logging
+from typing import Any
+
+from maltoolbox.exceptions import LanguageGraphAssociationError
+from maltoolbox.language.language_graph_asset import LanguageGraphAsset
+
+logger = logging.getLogger(__name__)
+
+
+def link_association_to_assets(
+    assoc: LanguageGraphAssociation,
+    left_asset: LanguageGraphAsset,
+    right_asset: LanguageGraphAsset,
+) -> None:
+    left_asset.own_associations[assoc.right_field.fieldname] = assoc
+    right_asset.own_associations[assoc.left_field.fieldname] = assoc
+
+
+@dataclass(frozen=True, eq=True)
+class LanguageGraphAssociationField:
+    """A field in an association"""
+
+    asset: LanguageGraphAsset
+    fieldname: str
+    minimum: int
+    maximum: int
+
+
+@dataclass(frozen=True, eq=True)
+class LanguageGraphAssociation:
+    """An association type between asset types as defined in the MAL language
+    """
+
+    name: str
+    left_field: LanguageGraphAssociationField
+    right_field: LanguageGraphAssociationField
+    info: dict = field(default_factory=dict, compare=False)
+
+    def to_dict(self) -> dict:
+        """Convert LanguageGraphAssociation to dictionary"""
+        assoc_dict = {
+            'name': self.name,
+            'info': self.info,
+            'left': {
+                'asset': self.left_field.asset.name,
+                'fieldname': self.left_field.fieldname,
+                'min': self.left_field.minimum,
+                'max': self.left_field.maximum
+            },
+            'right': {
+                'asset': self.right_field.asset.name,
+                'fieldname': self.right_field.fieldname,
+                'min': self.right_field.minimum,
+                'max': self.right_field.maximum
+            }
+        }
+
+        return assoc_dict
+
+    def __repr__(self) -> str:
+        return (
+            f'LanguageGraphAssociation(name: "{self.name}", '
+            f'left_field: {self.left_field}, '
+            f'right_field: {self.right_field})'
+        )
+
+    @property
+    def full_name(self) -> str:
+        """Return the full name of the association. This is a combination of the
+        association name, left field name, left asset type, right field name,
+        and right asset type.
+        """
+        full_name = '%s_%s_%s' % (
+            self.name,
+            self.left_field.fieldname,
+            self.right_field.fieldname
+        )
+        return full_name
+
+    def get_field(self, fieldname: str) -> LanguageGraphAssociationField:
+        """Return the field that matches the `fieldname` given as parameter.
+        """
+        if self.right_field.fieldname == fieldname:
+            return self.right_field
+        return self.left_field
+
+    def contains_fieldname(self, fieldname: str) -> bool:
+        """Check if the association contains the field name given as a parameter.
+
+        Arguments:
+        ---------
+        fieldname   - the field name to look for
+        Return True if either of the two field names matches.
+        False, otherwise.
+
+        """
+        if self.left_field.fieldname == fieldname:
+            return True
+        if self.right_field.fieldname == fieldname:
+            return True
+        return False
+
+    def contains_asset(self, asset: Any) -> bool:
+        """Check if the association matches the asset given as a parameter. A
+        match can either be an explicit one or if the asset given subassets
+        either of the two assets that are part of the association.
+
+        Arguments:
+        ---------
+        asset       - the asset to look for
+        Return True if either of the two asset matches.
+        False, otherwise.
+
+        """
+        if asset.is_subasset_of(self.left_field.asset):
+            return True
+        if asset.is_subasset_of(self.right_field.asset):
+            return True
+        return False
+
+    def get_opposite_fieldname(self, fieldname: str) -> str:
+        """Return the opposite field name if the association contains the field
+        name given as a parameter.
+
+        Arguments:
+        ---------
+        fieldname   - the field name to look for
+        Return the other field name if the parameter matched either of the
+        two. None, otherwise.
+
+        """
+        if self.left_field.fieldname == fieldname:
+            return self.right_field.fieldname
+        if self.right_field.fieldname == fieldname:
+            return self.left_field.fieldname
+
+        msg = ('Requested fieldname "%s" from association '
+               '%s which did not contain it!')
+        logger.error(msg, fieldname, self.name)
+        raise LanguageGraphAssociationError(msg % (fieldname, self.name))
+