mal-toolbox 0.0.27__py3-none-any.whl → 0.1.12__py3-none-any.whl

maltoolbox/attackgraph/node.py

@@ -2,47 +2,54 @@
 MAL-Toolbox Attack Graph Node Dataclass
 """
 
+from __future__ import annotations
+import copy
 from dataclasses import field, dataclass
-from typing import Any, List, Optional
+from typing import Any, Optional
 
-from maltoolbox.attackgraph.attacker import Attacker
+from . import Attacker
 
 @dataclass
 class AttackGraphNode:
-    id: str
+    """Node part of AttackGraph"""
     type: str
     name: str
-    ttc: dict
-    asset: Any = None
-    children: List['AttackGraphNode'] = field(default_factory=list)
-    parents: List['AttackGraphNode'] = field(default_factory=list)
+    ttc: Optional[dict] = None
+    id: Optional[int] = None
+    asset: Optional[Any] = None
+    children: list[AttackGraphNode] = field(default_factory=list)
+    parents: list[AttackGraphNode] = field(default_factory=list)
     defense_status: Optional[float] = None
     existence_status: Optional[bool] = None
     is_viable: bool = True
     is_necessary: bool = True
-    compromised_by: List['Attacker'] = field(default_factory=list)
-    extra: Optional[dict] = None
+    compromised_by: list[Attacker] = field(default_factory=list)
     mitre_info: Optional[str] = None
-    tags: Optional[List[str]] = None
-    observations: Optional[dict] = None
+    tags: list[str] = field(default_factory=lambda: [])
     attributes: Optional[dict] = None
-    attacker: Optional['Attacker'] = None
 
-    def to_dict(self):
-        node_dict = {
+    # Optional extra metadata for AttackGraphNode
+    extras: dict = field(default_factory=dict)
+
+    def to_dict(self) -> dict:
+        """Convert node to dictionary"""
+        node_dict: dict = {
             'id': self.id,
             'type': self.type,
             'name': self.name,
             'ttc': self.ttc,
-            'children': [child.id for child in self.children],
-            'parents': [parent.id for parent in self.parents],
-            'compromised_by': ['Attacker:' + attacker.id for attacker in \
+            'children': {},
+            'parents': {},
+            'compromised_by': [attacker.name for attacker in \
                 self.compromised_by]
         }
 
+        for child in self.children:
+            node_dict['children'][child.id] = child.full_name
+        for parent in self.parents:
+            node_dict['parents'][parent.id] = parent.full_name
         if self.asset is not None:
-            node_dict['asset'] = self.asset.metaconcept + ':' \
-                + str(self.asset.id)
+            node_dict['asset'] = str(self.asset.name)
         if self.defense_status is not None:
             node_dict['defense_status'] = str(self.defense_status)
         if self.existence_status is not None:
@@ -55,7 +62,122 @@ class AttackGraphNode:
             node_dict['mitre_info'] = str(self.mitre_info)
         if self.tags:
             node_dict['tags'] = str(self.tags)
-        if self.observations is not None:
-            node_dict['observations'] = self.observations
+        if self.extras:
+            node_dict['extras'] = self.extras
 
         return node_dict
+
+    def __repr__(self) -> str:
+        return str(self.to_dict())
+
+    def __deepcopy__(self, memo) -> AttackGraphNode:
+        """Deep copy an attackgraph node
+
+        The deepcopy will copy over node specific information, such as type,
+        name, etc., but it will not copy attack graph relations such as
+        parents, children, or attackers it is compromised by. These references
+        should be recreated when deepcopying the attack graph itself.
+
+        """
+
+        # Check if the object is already in the memo dictionary
+        if id(self) in memo:
+            return memo[id(self)]
+
+        copied_node = AttackGraphNode(
+            self.type,
+            self.name,
+            self.ttc,
+            self.id,
+            self.asset,
+            [],
+            [],
+            self.defense_status,
+            self.existence_status,
+            self.is_viable,
+            self.is_necessary,
+            [],
+            self.mitre_info,
+            [],
+            {},
+            {}
+        )
+
+        copied_node.tags = copy.deepcopy(self.tags, memo)
+        copied_node.attributes = copy.deepcopy(self.attributes, memo)
+        copied_node.extras = copy.deepcopy(self.extras, memo)
+
+        # Remember that self was already copied
+        memo[id(self)] = copied_node
+
+        return copied_node
+
+    def is_compromised(self) -> bool:
+        """
+        Return True if any attackers have compromised this node.
+        False, otherwise.
+        """
+        return len(self.compromised_by) > 0
+
+    def is_compromised_by(self, attacker: Attacker) -> bool:
+        """
+        Return True if the attacker given as an argument has compromised this
+        node.
+        False, otherwise.
+
+        Arguments:
+        attacker    - the attacker we are interested in
+        """
+        return attacker in self.compromised_by
+
+    def compromise(self, attacker: Attacker) -> None:
+        """
+        Have the attacker given as a parameter compromise this node.
+
+        Arguments:
+        attacker    - the attacker that will compromise the node
+        """
+        attacker.compromise(self)
+
+    def undo_compromise(self, attacker: Attacker) -> None:
+        """
+        Remove the attacker given as a parameter from the list of attackers
+        that have compromised this node.
+
+        Arguments:
+        attacker    - the attacker that we wish to remove from the compromised
+                      list.
+        """
+        attacker.undo_compromise(self)
+
+    def is_enabled_defense(self) -> bool:
+        """
+        Return True if this node is a defense node and it is enabled and not
+        suppressed via tags.
+        False, otherwise.
+        """
+        return self.type == 'defense' and \
+            'suppress' not in self.tags and \
+            self.defense_status == 1.0
+
+    def is_available_defense(self) -> bool:
+        """
+        Return True if this node is a defense node and it is not fully enabled
+        and not suppressed via tags. False otherwise.
+        """
+        return self.type == 'defense' and \
+            'suppress' not in self.tags and \
+            self.defense_status != 1.0
+
+    @property
+    def full_name(self) -> str:
+        """
+        Return the full name of the attack step. This is a combination of the
+        asset name to which the attack step belongs and attack step name
+        itself.
+        """
+        if self.asset:
+            full_name = self.asset.name + ':' + self.name
+        else:
+            full_name = str(self.id) + ':' + self.name
+        return full_name

maltoolbox/attackgraph/query.py

@@ -4,15 +4,20 @@ MAL-Toolbox Attack Graph Query Submodule
 This submodule contains functions that analyze the information present in the
 attack graph, but do not alter the structure or nodes in any way.
 """
-
+from __future__ import annotations
 import logging
+from typing import TYPE_CHECKING
+
+from .attackgraph import AttackGraph, Attacker
 
-from maltoolbox.attackgraph import attackgraph
-from maltoolbox.attackgraph import attacker
+if TYPE_CHECKING:
+    from .attackgraph import AttackGraphNode
 
 logger = logging.getLogger(__name__)
 
-def is_node_traversable_by_attacker(node, attacker) -> bool:
+def is_node_traversable_by_attacker(
+        node: AttackGraphNode, attacker: Attacker
+    ) -> bool:
     """
     Return True or False depending if the node specified is traversable
     for the attacker given.
@@ -22,33 +27,82 @@ def is_node_traversable_by_attacker(node, attacker) -> bool:
     attacker    - the attacker whose traversability we are interested in
     """
 
-    logger.debug(f'Evaluate if {node.id}, of type \'{node.type}\', is '\
-        f'traversable by Attacker {attacker.id}')
+    logger.debug(
+        'Evaluate if "%s"(%d), of type "%s", is traversable by Attacker '
+            '"%s"(%d)',
+        node.full_name,
+        node.id,
+        node.type,
+        attacker.name,
+        attacker.id
+    )
     if not node.is_viable:
+        logger.debug(
+            '"%s"(%d) is not traversable because it is non-viable',
+            node.full_name,
+            node.id,
+        )
         return False
 
     match(node.type):
         case 'or':
+            logger.debug(
+                '"%s"(%d) is traversable because it is viable and '
+                'of type "or".',
+                node.full_name,
+                node.id
+            )
             return True
 
         case 'and':
             for parent in node.parents:
                 if parent.is_necessary and \
-                    attacker not in parent.compromised_by:
+                    not parent.is_compromised_by(attacker):
                     # If the parent is not present in the attacks steps
                     # already reached and is necessary.
+                    logger.debug(
+                        '"%s"(%d) is not traversable because while it is '
+                        'viable, and of type "and", its necessary parent '
+                        '"%s(%d)" has not already been compromised.',
+                        node.full_name,
+                        node.id,
+                        parent.full_name,
+                        parent.id
+                    )
                     return False
+            logger.debug(
+                '"%s"(%d) is traversable because it is viable, '
+                'of type "and", and all of its necessary parents have '
+                'already been compromised.',
+                node.full_name,
+                node.id
+            )
             return True
 
-        case 'exist' | 'notExist' |  'defense':
+        case 'exist' | 'notExist' | 'defense':
+            logger.warning(
+                'Nodes of type "exist", "notExist", and "defense" are never '
+                'marked as traversable. However, we do not normally check '
+                'if they are traversable. Node "%s"(%d) of type "%s" was '
+                'checked for traversability.',
+                node.full_name,
+                node.id,
+                node.type
+            )
             return False
 
         case _:
-            logger.error(f'Unknown node type {node.type}.')
+            logger.error(
+                'Node "%s"(%d) has an unknown type "%s".',
+                node.full_name,
+                node.id,
+                node.type
+            )
             return False
 
-def get_attack_surface(graph: attackgraph.AttackGraph,
-    attacker: attacker.Attacker):
+def get_attack_surface(
+        attacker: Attacker
+    ) -> list[AttackGraphNode]:
     """
     Get the current attack surface of an attacker. This includes all of the
     viable children nodes of already reached attack steps that are of 'or'
@@ -56,21 +110,74 @@ def get_attack_surface(graph: attackgraph.AttackGraph,
     parents in the attack steps reached.
 
     Arguments:
-    graph       - the attack graph
     attacker    - the Attacker whose attack surface is sought
     """
-    logger.debug(f'Get the attack surface for Attacker {attacker.id}.')
+    logger.debug(
+        'Get the attack surface for Attacker "%s"(%d).',
+        attacker.name,
+        attacker.id
+    )
     attack_surface = []
     for attack_step in attacker.reached_attack_steps:
-        logger.debug('Determine attack surface stemming from '
-            f'{attack_step.id} for Attacker {attacker.id}.')
+        logger.debug(
+            'Determine attack surface stemming from '
+            '"%s"(%d) for Attacker "%s"(%d).',
+            attack_step.full_name,
+            attack_step.id,
+            attacker.name,
+            attacker.id
+        )
         for child in attack_step.children:
             if is_node_traversable_by_attacker(child, attacker) and \
                     child not in attack_surface:
                 attack_surface.append(child)
     return attack_surface
 
-def get_defense_surface(graph: attackgraph.AttackGraph):
+def update_attack_surface_add_nodes(
+        attacker: Attacker,
+        current_attack_surface: list[AttackGraphNode],
+        nodes: list[AttackGraphNode]
+    ) -> list[AttackGraphNode]:
+    """
+    Update the attack surface of an attacker with the new attack step nodes
+    provided to see if any of their children can be added.
+
+    Arguments:
+    attacker                - the Attacker whose attack surface is sought
+    current_attack_surface  - the current attack surface that we wish to
+                              expand
+    nodes                   - the newly compromised attack step nodes that we
+                              wish to see if any of their children should be
+                              added to the attack surface
+    """
+    logger.debug('Update the attack surface for Attacker "%s"(%d).',
+        attacker.name,
+        attacker.id)
+    attack_surface = current_attack_surface
+    for attack_step in nodes:
+        logger.debug(
+            'Determine attack surface stemming from "%s"(%d) '
+            'for Attacker "%s"(%d).',
+            attack_step.full_name,
+            attack_step.id,
+            attacker.name,
+            attacker.id
+        )
+        for child in attack_step.children:
+            is_traversable = is_node_traversable_by_attacker(child, attacker)
+            if is_traversable and child not in attack_surface:
+                logger.debug(
+                    'Add node "%s"(%d) to the attack surface of '
+                    'Attacker "%s"(%d).',
+                    child.full_name,
+                    child.id,
+                    attacker.name,
+                    attacker.id
+                )
+                attack_surface.append(child)
+    return attack_surface
+
+def get_defense_surface(graph: AttackGraph) -> list[AttackGraphNode]:
     """
     Get the defense surface. All non-suppressed defense steps that are not
     already fully enabled.
@@ -78,12 +185,10 @@ def get_defense_surface(graph: attackgraph.AttackGraph):
     Arguments:
     graph       - the attack graph
     """
-    logger.debug(f'Get the defense surface.')
-    return (node for node in graph.nodes if node.type == 'defense' and \
-        'suppress' not in node.tags and \
-        node.defense_status != 1.0)
+    logger.debug('Get the defense surface.')
+    return [node for node in graph.nodes if node.is_available_defense()]
 
-def get_enabled_defenses(graph: attackgraph.AttackGraph):
+def get_enabled_defenses(graph: AttackGraph) -> list[AttackGraphNode]:
     """
     Get the defenses already enabled. All non-suppressed defense steps that
     are already fully enabled.
@@ -91,8 +196,5 @@ def get_enabled_defenses(graph: attackgraph.AttackGraph):
     Arguments:
     graph       - the attack graph
     """
-    logger.debug(f'Get the enabled defenses.')
-    return (node for node in graph.nodes if node.type == 'defense' and \
-        'suppress' not in node.tags and \
-        node.defense_status == 1.0)
-
+    logger.debug('Get the enabled defenses.')
+    return [node for node in graph.nodes if node.is_enabled_defense()]

maltoolbox/default.conf

@@ -1,16 +1,17 @@
 [logging]
 output_dir = tmp
+log_level =
 log_file = %(output_dir)s/log.txt
-attackgraph_file = %(output_dir)s/attackgraph.json
-model_file = %(output_dir)s/model.json
-langspec_file = %(output_dir)s/langspec_file.json
+attackgraph_file = %(output_dir)s/attackgraph.yml
+model_file = %(output_dir)s/model.yml
+langspec_file = %(output_dir)s/langspec_file.yml
 
 [input]
 model_file =
 lang_spec_file =
 
 [neo4j]
-uri=
-username=
-password=
-dbname=
+uri =
+username =
+password =
+dbname =

maltoolbox/exceptions.py

@@ -0,0 +1,45 @@
+class MalToolboxException(Exception):
+    """Base exception for all other maltoolbox exceptions to inherit from."""
+    pass
+
+class LanguageGraphException(MalToolboxException):
+    """Base exception for all language-graph related exceptions."""
+    pass
+
+class LanguageGraphSuperAssetNotFoundError(LanguageGraphException):
+    """Asset's super asset not found in language graph during attack graph construction."""
+    pass
+
+class LanguageGraphAssociationError(LanguageGraphException):
+    """Error in building an association.
+
+    For example, right or left-hand side asset of association missing in
+    language graph.
+    """
+    pass
+
+class LanguageGraphStepExpressionError(LanguageGraphException):
+    """A target asset cannot be linked with for a step expression."""
+    pass
+
+class AttackGraphException(MalToolboxException):
+    """Base exception for all attack-graph related exceptions."""
+    pass
+
+class AttackGraphStepExpressionError(AttackGraphException):
+    """A target attack step cannot be linked with for a step expression."""
+    pass
+
+
+class ModelException(MalToolboxException):
+    """Base Exception for all Model related exceptions"""
+    pass
+
+
+class ModelAssociationException(ModelException):
+    """Exception related to associations in Model"""
+    pass
+
+class DuplicateModelAssociationError(ModelException):
+    """Associations should be unique as part of Model"""
+    pass

maltoolbox/file_utils.py

@@ -0,0 +1,66 @@
+"""Utily functions for file handling"""
+
+import json
+import yaml
+from python_jsonschema_objects.literals import LiteralValue
+
+def save_dict_to_json_file(filename: str, serialized_object: dict) -> None:
+    """Save serialized object to a json file.
+
+    Arguments:
+    filename        - the name of the output file
+    data            - dict to output as json
+    """
+
+    with open(filename, 'w', encoding='utf-8') as f:
+        json.dump(serialized_object, f, indent=4)
+
+
+def save_dict_to_yaml_file(filename: str, serialized_object: dict) -> None:
+    """Save serialized object to a yaml file.
+
+    Arguments:
+    filename        - the name of the output file
+    data            - dict to output as yaml
+    """
+
+    # Handle Literal values from jsonschema_objects
+    yaml.add_multi_representer(
+        LiteralValue,
+        lambda dumper, data: dumper.represent_data(data._value),
+        yaml.SafeDumper
+    )
+
+    with open(filename, 'w', encoding='utf-8') as f:
+        yaml.dump(serialized_object, f, Dumper=yaml.SafeDumper)
+
+
+def load_dict_from_yaml_file(filename: str) -> dict:
+    """Open json file and read as dict"""
+    with open(filename, 'r', encoding='utf-8') as file:
+        object_dict = yaml.safe_load(file)
+    return object_dict
+
+
+def load_dict_from_json_file(filename: str) -> dict:
+    """Open yaml file and read as dict"""
+    with open(filename, 'r', encoding='utf-8') as file:
+        object_dict = json.loads(file.read())
+    return object_dict
+
+
+def save_dict_to_file(filename: str, dictionary: dict) -> None:
+    """Save serialized object to json or yaml file
+    depending on file extension.
+
+    Arguments:
+    filename        - the name of the output file
+    dictionary      - the dict to save to the file
+    """
+
+    if filename.endswith(('.yml', '.yaml')):
+        save_dict_to_yaml_file(filename, dictionary)
+    elif filename.endswith('.json'):
+        save_dict_to_json_file(filename, dictionary)
+    else:
+        raise ValueError('Unknown file extension, expected json/yml/yaml')