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

maltoolbox/language/step_expression_processor.py

@@ -0,0 +1,491 @@
+from __future__ import annotations
+import json
+import logging
+from typing import Any
+
+from maltoolbox.language.expression_chain import ExpressionsChain
+from maltoolbox.language.language_graph_lookup import get_var_expr_for_asset
+from maltoolbox.language.language_graph_asset import LanguageGraphAsset
+from maltoolbox.exceptions import (
+    LanguageGraphException,
+    LanguageGraphAssociationError,
+)
+
+logger = logging.getLogger(__name__)
+
+def process_attack_step_expression(
+    target_asset: LanguageGraphAsset,
+    step_expression: dict[str, Any]
+) -> tuple[
+            LanguageGraphAsset,
+            None,
+            str
+        ]:
+    """The attack step expression just adds the name of the attack
+    step. All other step expressions only modify the target
+    asset and parent associations chain.
+    """
+    return (
+        target_asset,
+        None,
+        step_expression['name']
+    )
+
+def process_set_operation_step_expression(
+    assets: dict[str, LanguageGraphAsset],
+    target_asset: LanguageGraphAsset,
+    expr_chain: ExpressionsChain | None,
+    step_expression: dict[str, Any],
+    lang_spec
+) -> tuple[
+        LanguageGraphAsset,
+        ExpressionsChain,
+        None
+    ]:
+    """The set operators are used to combine the left hand and right
+    hand targets accordingly.
+    """
+    lh_target_asset, lh_expr_chain, _ = process_step_expression(
+        assets,
+        target_asset,
+        expr_chain,
+        step_expression['lhs'],
+        lang_spec
+    )
+    rh_target_asset, rh_expr_chain, _ = process_step_expression(
+        assets,
+        target_asset,
+        expr_chain,
+        step_expression['rhs'],
+        lang_spec
+    )
+
+    assert lh_target_asset, (
+        f"No lh target in step expression {step_expression}"
+    )
+    assert rh_target_asset, (
+        f"No rh target in step expression {step_expression}"
+    )
+
+    if not lh_target_asset.get_all_common_superassets(rh_target_asset):
+        raise ValueError(
+            "Set operation attempted between targets that do not share "
+            f"any common superassets: {lh_target_asset.name} "
+            f"and {rh_target_asset.name}!"
+        )
+
+    new_expr_chain = ExpressionsChain(
+        type=step_expression['type'],
+        left_link=lh_expr_chain,
+        right_link=rh_expr_chain
+    )
+    return (
+        lh_target_asset,
+        new_expr_chain,
+        None
+    )
+
+def process_variable_step_expression(
+    assets: dict[str, LanguageGraphAsset],
+    target_asset: LanguageGraphAsset,
+    step_expression: dict[str, Any],
+    lang_spec
+) -> tuple[
+        LanguageGraphAsset,
+        ExpressionsChain,
+        None
+    ]:
+
+    var_name = step_expression['name']
+    var_target_asset, var_expr_chain = (
+        resolve_variable(assets, target_asset, var_name, lang_spec)
+    )
+
+    if var_expr_chain is None:
+        raise LookupError(
+            f'Failed to find variable "{step_expression["name"]}" '
+            f'for {target_asset.name}',
+        )
+
+    return (
+        var_target_asset,
+        var_expr_chain,
+        None
+    )
+
+def process_field_step_expression(
+    target_asset: LanguageGraphAsset,
+    step_expression: dict[str, Any]
+) -> tuple[
+        LanguageGraphAsset,
+        ExpressionsChain,
+        None
+    ]:
+    """Change the target asset from the current one to the associated
+    asset given the specified field name and add the parent
+    fieldname and association to the parent associations chain.
+    """
+    fieldname = step_expression['name']
+
+    if target_asset is None:
+        raise ValueError(
+            f'Missing target asset for field "{fieldname}"!'
+        )
+
+    new_target_asset = None
+    for association in target_asset.associations.values():
+        if (association.left_field.fieldname == fieldname and
+            target_asset.is_subasset_of(
+                association.right_field.asset)):
+            new_target_asset = association.left_field.asset
+
+        if (association.right_field.fieldname == fieldname and
+            target_asset.is_subasset_of(
+                association.left_field.asset)):
+            new_target_asset = association.right_field.asset
+
+        if new_target_asset:
+            new_expr_chain = ExpressionsChain(
+                type='field',
+                fieldname=fieldname,
+                association=association
+            )
+            return (
+                new_target_asset,
+                new_expr_chain,
+                None
+            )
+
+    raise LookupError(
+        f'Failed to find field {fieldname} on asset {target_asset.name}!',
+    )
+
+def process_transitive_step_expression(
+    assets: dict[str, LanguageGraphAsset],
+    target_asset: LanguageGraphAsset,
+    expr_chain: ExpressionsChain | None,
+    step_expression: dict[str, Any],
+    lang_spec
+) -> tuple[
+        LanguageGraphAsset,
+        ExpressionsChain,
+        None
+    ]:
+    """Create a transitive tuple entry that applies to the next
+    component of the step expression.
+    """
+    result_target_asset, result_expr_chain, _ = (
+        process_step_expression(
+            assets,
+            target_asset,
+            expr_chain,
+            step_expression['stepExpression'],
+            lang_spec
+        )
+    )
+    new_expr_chain = ExpressionsChain(
+        type='transitive',
+        sub_link=result_expr_chain
+    )
+    return (
+        result_target_asset,
+        new_expr_chain,
+        None
+    )
+
+def process_subType_step_expression(
+    assets: dict[str, LanguageGraphAsset],
+    target_asset: LanguageGraphAsset,
+    expr_chain: ExpressionsChain | None,
+    step_expression: dict[str, Any],
+    lang_spec
+) -> tuple[
+        LanguageGraphAsset,
+        ExpressionsChain,
+        None
+    ]:
+    """Create a subType tuple entry that applies to the next
+    component of the step expression and changes the target
+    asset to the subasset.
+    """
+    subtype_name = step_expression['subType']
+    result_target_asset, result_expr_chain, _ = (
+        process_step_expression(
+            assets,
+            target_asset,
+            expr_chain,
+            step_expression['stepExpression'],
+            lang_spec
+        )
+    )
+
+    if subtype_name not in assets:
+        raise LanguageGraphException(
+            f'Failed to find subtype {subtype_name}'
+        )
+
+    subtype_asset = assets[subtype_name]
+
+    if result_target_asset is None:
+        raise LookupError("Nonexisting asset for subtype")
+
+    if not subtype_asset.is_subasset_of(result_target_asset):
+        raise ValueError(
+            f'Found subtype {subtype_name} which does not extend '
+            f'{result_target_asset.name}, subtype cannot be resolved.'
+        )
+
+    new_expr_chain = ExpressionsChain(
+        type='subType',
+        sub_link=result_expr_chain,
+        subtype=subtype_asset
+    )
+    return (
+        subtype_asset,
+        new_expr_chain,
+        None
+    )
+
+def process_collect_step_expression(
+    assets: dict[str, LanguageGraphAsset],
+    target_asset: LanguageGraphAsset,
+    expr_chain: ExpressionsChain | None,
+    step_expression: dict[str, Any],
+    lang_spec
+) -> tuple[
+        LanguageGraphAsset,
+        ExpressionsChain | None,
+        str | None
+    ]:
+    """Apply the right hand step expression to left hand step
+    expression target asset and parent associations chain.
+    """
+    lh_target_asset, lh_expr_chain, _ = process_step_expression(
+        assets, target_asset, expr_chain, step_expression['lhs'], lang_spec
+    )
+
+    if lh_target_asset is None:
+        raise ValueError(
+            'No left hand asset in collect expression '
+            f'{step_expression["lhs"]}'
+        )
+
+    rh_target_asset, rh_expr_chain, rh_attack_step_name = (
+        process_step_expression(
+            assets, lh_target_asset, None, step_expression['rhs'], lang_spec
+        )
+    )
+
+    new_expr_chain = lh_expr_chain
+    if rh_expr_chain:
+        new_expr_chain = ExpressionsChain(
+            type='collect',
+            left_link=lh_expr_chain,
+            right_link=rh_expr_chain
+        )
+
+    return (
+        rh_target_asset,
+        new_expr_chain,
+        rh_attack_step_name
+    )
+
+def process_step_expression(
+    assets: dict[str, LanguageGraphAsset],
+    target_asset: LanguageGraphAsset,
+    expr_chain: ExpressionsChain | None,
+    step_expression: dict,
+    lang_spec
+) -> tuple[
+        LanguageGraphAsset,
+        ExpressionsChain | None,
+        str | None
+    ]:
+    """Recursively process an attack step expression.
+
+    Arguments:
+    ---------
+    target_asset        - The asset type that this step expression should
+                            apply to. Initially it will contain the asset
+                            type to which the attack step belongs.
+    expr_chain          - A expressions chain of linked of associations
+                            and set operations from the attack step to its
+                            parent attack step.
+                            Note: This was done for the parent attack step
+                            because it was easier to construct recursively
+                            given the left-hand first expansion of the
+                            current MAL language specification.
+    step_expression     - A dictionary containing the step expression.
+
+    Return:
+    ------
+    A tuple triplet containing the target asset, the resulting parent
+    associations chain, and the name of the attack step.
+
+    """
+    if logger.isEnabledFor(logging.DEBUG):
+        # Avoid running json.dumps when not in debug
+        logger.debug(
+            'Processing Step Expression:\n%s',
+            json.dumps(step_expression, indent=2)
+        )
+
+    result: tuple[
+        LanguageGraphAsset,
+        ExpressionsChain | None,
+        str | None
+    ]
+
+    match (step_expression['type']):
+        case 'attackStep':
+            result = process_attack_step_expression(
+                target_asset, step_expression
+            )
+        case 'union' | 'intersection' | 'difference':
+            result = process_set_operation_step_expression(
+                assets, target_asset, expr_chain, step_expression, lang_spec
+            )
+        case 'variable':
+            result = process_variable_step_expression(
+                assets, target_asset, step_expression, lang_spec
+            )
+        case 'field':
+            result = process_field_step_expression(
+                target_asset, step_expression
+            )
+        case 'transitive':
+            result = process_transitive_step_expression(
+                assets, target_asset, expr_chain, step_expression, lang_spec
+            )
+        case 'subType':
+            result = process_subType_step_expression(
+                assets, target_asset, expr_chain, step_expression, lang_spec
+            )
+        case 'collect':
+            result = process_collect_step_expression(
+                assets, target_asset, expr_chain, step_expression, lang_spec
+            )
+        case _:
+            raise LookupError(
+                f'Unknown attack step type: "{step_expression["type"]}"'
+            )
+    return result
+
+def reverse_expr_chain(
+        expr_chain: ExpressionsChain | None,
+        reverse_chain: ExpressionsChain | None
+    ) -> ExpressionsChain | None:
+    """Recursively reverse the associations chain. From parent to child or
+    vice versa.
+
+    Arguments:
+    ---------
+    expr_chain          - A chain of nested tuples that specify the
+                            associations and set operations chain from an
+                            attack step to its connected attack step.
+    reverse_chain       - A chain of nested tuples that represents the
+                            current reversed associations chain.
+
+    Return:
+    ------
+    The resulting reversed associations chain.
+
+    """
+    if not expr_chain:
+        return reverse_chain
+    match (expr_chain.type):
+        case 'union' | 'intersection' | 'difference' | 'collect':
+            left_reverse_chain = \
+                reverse_expr_chain(expr_chain.left_link, reverse_chain)
+            right_reverse_chain = \
+                reverse_expr_chain(expr_chain.right_link, reverse_chain)
+            if expr_chain.type == 'collect':
+                new_expr_chain = ExpressionsChain(
+                    type=expr_chain.type,
+                    left_link=right_reverse_chain,
+                    right_link=left_reverse_chain
+                )
+            else:
+                new_expr_chain = ExpressionsChain(
+                    type=expr_chain.type,
+                    left_link=left_reverse_chain,
+                    right_link=right_reverse_chain
+                )
+
+            return new_expr_chain
+
+        case 'transitive':
+            result_reverse_chain = reverse_expr_chain(
+                expr_chain.sub_link, reverse_chain)
+            new_expr_chain = ExpressionsChain(
+                type='transitive',
+                sub_link=result_reverse_chain
+            )
+            return new_expr_chain
+
+        case 'field':
+            association = expr_chain.association
+
+            if not association:
+                raise LanguageGraphException(
+                    "Missing association for expressions chain"
+                )
+
+            if not expr_chain.fieldname:
+                raise LanguageGraphException(
+                    "Missing field name for expressions chain"
+                )
+
+            opposite_fieldname = association.get_opposite_fieldname(
+                expr_chain.fieldname)
+            new_expr_chain = ExpressionsChain(
+                type='field',
+                association=association,
+                fieldname=opposite_fieldname
+            )
+            return new_expr_chain
+
+        case 'subType':
+            result_reverse_chain = reverse_expr_chain(
+                expr_chain.sub_link,
+                reverse_chain
+            )
+            new_expr_chain = ExpressionsChain(
+                type='subType',
+                sub_link=result_reverse_chain,
+                subtype=expr_chain.subtype
+            )
+            return new_expr_chain
+
+        case _:
+            msg = 'Unknown assoc chain element "%s"'
+            logger.error(msg, expr_chain.type)
+            raise LanguageGraphAssociationError(msg % expr_chain.type)
+
+def resolve_variable(
+    assets: dict[str, LanguageGraphAsset],
+    asset: LanguageGraphAsset,
+    var_name: str,
+    lang_spec
+) -> tuple:
+    """Resolve a variable for a specific asset by variable name.
+
+    Arguments:
+    ---------
+    asset       - a language graph asset to which the variable belongs
+    var_name    - a string representing the variable name
+
+    Return:
+    ------
+    A tuple containing the target asset and expressions chain required to
+    reach it.
+
+    """
+    if var_name not in asset.variables:
+        var_expr = get_var_expr_for_asset(asset.name, var_name, lang_spec)
+        target_asset, expr_chain, _ = process_step_expression(
+            assets, asset, None, var_expr, lang_spec
+        )
+        asset.own_variables[var_name] = (target_asset, expr_chain)
+        return (target_asset, expr_chain)
+    return asset.variables[var_name]

mal_toolbox-1.2.1.dist-info/RECORD

@@ -1,33 +0,0 @@
-mal_toolbox-1.2.1.dist-info/licenses/AUTHORS,sha256=zxLrLe8EY39WtRKlAY4Oorx4Z2_LHV2ApRvDGZgY7xY,127
-mal_toolbox-1.2.1.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-maltoolbox/__init__.py,sha256=649BOg_Bo4OazvePvnuF2tjM0q4VbyS2Fsz9em_KEtM,2132
-maltoolbox/__main__.py,sha256=aAm6NcZ-HtPmY9hfFlGNnTs5rydoI6NAc88RgXt1G9U,3515
-maltoolbox/exceptions.py,sha256=4rwqzu8Cgj0ShjUoCXP2yik-bJaqYqj6Y-0tqxHy4vs,1316
-maltoolbox/file_utils.py,sha256=IXA0cvyopjRFGGKqRPkRQ0RJOtKzq_XF13aHgcz-TFc,1911
-maltoolbox/model.py,sha256=bqYPYNW8MxuS2wUef51z6yjaA5F13YXbeicM2qaYUd4,18138
-maltoolbox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-maltoolbox/str_utils.py,sha256=zZXHOFfXguhpQQJ5nyGe1VGWchOkanQUc8viV7nhQho,639
-maltoolbox/attackgraph/__init__.py,sha256=l7dJ7jOqpcj7PdsOKZt1NuXlPyjd6vZYvcXlj8Kq09w,297
-maltoolbox/attackgraph/attackgraph.py,sha256=WBRwnVmQqwpjp3x_kSR8HH49MnlRIhF6tZ_r7nqTAJw,27162
-maltoolbox/attackgraph/node.py,sha256=7NAdEl40w6KMt_gKK1mP4SRAmmyCQGSTMaD-GHMNXHk,4186
-maltoolbox/attackgraph/analyzers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-maltoolbox/language/__init__.py,sha256=RTTfhnCYa5PRGJCgDAWLpLLAzNCvNMn91UHNiOXszbg,490
-maltoolbox/language/languagegraph.py,sha256=Tjqk5zv_37ghmepx8KBHPTH8tRlboaYcW836MiUS1d8,65140
-maltoolbox/language/compiler/__init__.py,sha256=Rbdeco6SWHyFw-VJfpxLRSZO3UMjJxPGenMR8OujVpA,15846
-maltoolbox/language/compiler/mal_lexer.py,sha256=TQvzEW7yCN0iY6Js5O6wCDFxSAE0_LAX4JVy96TnLro,14808
-maltoolbox/language/compiler/mal_parser.py,sha256=bVfYWRZyyhU-s2tJI-D_YwbVQkl3AHzdrD6LWM0BQbI,116108
-maltoolbox/patternfinder/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
-maltoolbox/patternfinder/attackgraph_patterns.py,sha256=jw6BlQHXLmiWm9xajLHbUZUWVQGM2qAgMHOs0Yo2YsE,5168
-maltoolbox/translators/__init__.py,sha256=7qbhjeu--s2A-O_031a7xzSq794iQlrrUxM8gE1LxH4,201
-maltoolbox/translators/networkx.py,sha256=v1JQAqO7st6-ktx5P3oy93DsL2SEUPly_3zcALv08o8,1352
-maltoolbox/translators/updater.py,sha256=mFmTT2GHCw6nsoHe_ChnvAHd5j6UxKnvAqLFDSziqC4,8566
-maltoolbox/visualization/__init__.py,sha256=7rrGclkGdP6LrxpfSh1esYFG_MnvnVruuEdUJI-DX-g,350
-maltoolbox/visualization/draw_io_utils.py,sha256=CgsD0HEFpxZ6ZIWtUZtMekdPB2Irtmvhz0TNEm7x1ig,14378
-maltoolbox/visualization/graphviz_utils.py,sha256=87B2pxRMrlmm2RHu0JM7nQRHWZD0Yt3zCmEwl8xUXdU,4709
-maltoolbox/visualization/neo4j_utils.py,sha256=R2Qm2gC5GDpfiPhhB3oymuBI2W580SRXGVtQuFRYiIA,3496
-maltoolbox/visualization/utils.py,sha256=EZWsxukO5hbRwGFW9GM9ZemKT-nYg-VMCup-SsntaQM,1480
-mal_toolbox-1.2.1.dist-info/METADATA,sha256=Nlsaw-sJu-Pqz6hWme_f6K-hryjFK8-QHYyMqfXBfWA,6696
-mal_toolbox-1.2.1.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mal_toolbox-1.2.1.dist-info/entry_points.txt,sha256=oqby5O6cUP_OHCm70k_iYPA6UlbTBf7se1i3XwdK3uU,56
-mal_toolbox-1.2.1.dist-info/top_level.txt,sha256=phqRVLRKGdSUgRY03mcpi2cmbbDo5YGjkV4gkqHFFcM,11
-mal_toolbox-1.2.1.dist-info/RECORD,,