mal-toolbox 1.0.4__py3-none-any.whl → 1.0.6__py3-none-any.whl

{mal_toolbox-1.0.4.dist-info → mal_toolbox-1.0.6.dist-info}/METADATA

@@ -1,8 +1,8 @@
 Metadata-Version: 2.4
 Name: mal-toolbox
-Version: 1.0.4
+Version: 1.0.6
 Summary: A collection of tools used to create MAL models and attack graphs.
-Author-email: Andrei Buhaiu <buhaiu@kth.se>, Joakim Loxdal <loxdal@kth.se>, Nikolaos Kakouros <nkak@kth.se>, Jakob Nyberg <jaknyb@kth.se>, Giuseppe Nebbione <nebbione@kth.se>
+Author-email: Andrei Buhaiu <buhaiu@kth.se>, Joakim Loxdal <loxdal@kth.se>, Nikolaos Kakouros <nkak@kth.se>, Jakob Nyberg <jaknyb@kth.se>, Giuseppe Nebbione <nebbione@kth.se>, Sandor Berglund <sandor@kth.se>
 License: Apache Software License
 Project-URL: Homepage, https://github.com/mal-lang/mal-toolbox
 Project-URL: Bug Tracker, https://github.com/mal-lang/mal-toolbox/issues
@@ -23,6 +23,8 @@ Requires-Dist: antlr4-tools
 Requires-Dist: antlr4-python3-runtime
 Requires-Dist: docopt
 Requires-Dist: PyYAML
+Provides-Extra: dev
+Requires-Dist: pytest; extra == "dev"
 Dynamic: license-file
 
 # MAL Toolbox overview
@@ -30,23 +32,15 @@ Dynamic: license-file
 MAL Toolbox is a collection of python modules to help developers create and work with
 MAL ([Meta Attack Language](https://mal-lang.org/)) models and attack graphs.
 
-Attack graphs can be used to run simulations (see MAL Simulator) or analysis.
+Attack graphs can be used to run simulations in [MAL Simulator](https://github.com/mal-lang/mal-simulator) or run your own custom analysis on.
 
-[Documentation](https://mal-lang.org/mal-toolbox/index.html)(Work in progress)
+- [MAL Toolbox Documentation](https://mal-lang.org/mal-toolbox/index.html)
+- [MAL Toolbox tutorial](https://github.com/mal-lang/mal-toolbox-tutorial)
 
 ## The Language Module
 
 The language module provides various tools to process MAL languages.
 
-### The Language Specification Submodule
-
-The language specification submodule provides functions to load the
-specification from a .mar archive(`load_language_specification_from_mar`) or a
-JSON file(`load_language_specification_from_json`). This specification will
-then be used to generate python classes representing the assets and
-associations of the language and to determine the attack steps for each asset
-when generating the attack graph.
-
 ## The Model Module
 
 With a MAL language a Model (a MAL instance model) can be created either
@@ -70,12 +64,6 @@ nodes related and the asset field which will contain the object in the model
 instance to which this attack step belongs to, if this information is
 available.
 
-## Ingestors Module
-
-The ingestors module contains various tools that can make use of the instance
-model or attack graph. Currently the Neo4J ingestor is the only one available
-and it can be used to visualise the instance model and the attack graph.
-
 
 # Usage
 
@@ -98,6 +86,11 @@ logging:
   model_file: "logs/model.yml"
   langspec_file: "logs/langspec_file.yml"
   langgraph_file: "logs/langspec_file.yml"
+neo4j:
+  uri: None
+  username: None
+  password: None
+  dbname: None
 ```
 
 Alternatively, you can use the `MALTOOLBOX_CONFIG`
@@ -124,25 +117,66 @@ You can use the maltoolbox cli to:
 Command-line interface for MAL toolbox operations
 
 Usage:
-    maltoolbox attack-graph generate [options] <model_file> <lang_file>
     maltoolbox compile <lang_file> <output_file>
+    maltoolbox generate-attack-graph [--graphviz] <model_file> <lang_file>
     maltoolbox upgrade-model <model_file> <lang_file> <output_file>
+    maltoolbox visualize-model <model_file> <lang_file>
 
 Arguments:
     <model_file>    Path to JSON instance model file.
     <lang_file>     Path to .mar or .mal file containing MAL spec.
     <output_file>   Path to write the result of the compilation (yml/json).
 
+Options:
+  -h --help         Show this screen.
+  -g --graphviz     Visualize with graphviz
+
 Notes:
     - <lang_file> can be either a .mar file (generated by the older MAL
-      compiler) or a .mal file containing the DSL written in MAL.
+      compiler) or a .mal file containing the DSL written in MAL.```
 ```
 
 ## Code examples / Tutorial
 
-To find code examples and tutorials, visit the
+To find more code examples and tutorials, visit the
 [MAL Toolbox Tutorial](https://github.com/mal-lang/mal-toolbox-tutorial/tree/main) repository.
 
+### Load a language
+```python
+
+from maltoolbox.language import LanguageGraph
+
+# Will load the MAL language (.mal/.mar) or a saved language graph (yml/json)
+lang_graph = LanguageGraph.load_from_file(lang_file_path)
+
+```
+
+### Generate a model
+```python
+from maltoolbox.model import Model
+
+# Create an empty model
+instance_model = Model("Example Model", lang_graph)
+
+# Create and add assets of type supported by the MAL language
+asset1 = instance_model.add_asset('Application', 'Application1')
+asset2 = instance_model.add_asset('Application', 'Application2')
+
+# Create association between the assets
+asset1.add_associated_assets('appExecutedApps', asset2)
+```
+
+## Generate an attack graph
+
+```python
+
+from maltoolbox.attackgraph import AttackGraph
+
+attack_graph = AttackGraph(lang_graph, model)
+
+```
+
+
 # Tests
 There are unit tests inside of ./tests.
 Before running the tests, make sure to install the requirements in ./tests/requirements.txt with `python -m pip install -r ./tests/requirements.txt`.

{mal_toolbox-1.0.4.dist-info → mal_toolbox-1.0.6.dist-info}/RECORD

@@ -1,17 +1,17 @@
-mal_toolbox-1.0.4.dist-info/licenses/AUTHORS,sha256=zxLrLe8EY39WtRKlAY4Oorx4Z2_LHV2ApRvDGZgY7xY,127
-mal_toolbox-1.0.4.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
-maltoolbox/__init__.py,sha256=Rw4utlzsR268vbMpZlmp3bDGJ80U0CWHiEXKOePe3jU,2043
-maltoolbox/__main__.py,sha256=A9jsYy94l1grHeSR3G3Ddn8Xg_nOihMSj1zZtVnYPSI,2974
+mal_toolbox-1.0.6.dist-info/licenses/AUTHORS,sha256=zxLrLe8EY39WtRKlAY4Oorx4Z2_LHV2ApRvDGZgY7xY,127
+mal_toolbox-1.0.6.dist-info/licenses/LICENSE,sha256=xx0jnfkXJvxRnG63LTGOxlggYnIysveWIZ6H3PNdCrQ,11357
+maltoolbox/__init__.py,sha256=oQl_SJyw4c6_IgOfO7SgV5jQQ1S2bVFBSazP9DZShqU,2158
+maltoolbox/__main__.py,sha256=euRQktG-HLvL1wJEj98RLnkNuDWsjBjfBOovCpqxFGw,3392
 maltoolbox/exceptions.py,sha256=0YjPx2v1yYumZ2o7pVZ1s_jS-GAb3Ng979KEFhROSNY,1399
 maltoolbox/file_utils.py,sha256=fYG3UsvPQcU0ES_WI3nLfuzSZgc0jtE4IAxdMGgs9aA,1876
-maltoolbox/model.py,sha256=xTK2jUr0Gz5pPVhdjh78zO5G46nV8N2ciIt6M5SwcGU,16058
+maltoolbox/model.py,sha256=0z0S0SH4lkslsAxPNxb7exfmNwBPXM_BK0Oujo899a4,18139
 maltoolbox/py.typed,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 maltoolbox/attackgraph/__init__.py,sha256=m_81AjzwXONdclcW_R7mF2f8p-4DvoSRVfQ3Nyh7fak,298
-maltoolbox/attackgraph/attackgraph.py,sha256=I2jms_X1rRLkmvkmc0z3zQAa_TnO4xA7ulPliRl5kOo,26930
-maltoolbox/attackgraph/node.py,sha256=Z2sdzXhPel9h7ySxP9fjgd1exVmpRbvRySVtLpI1_BM,3904
+maltoolbox/attackgraph/attackgraph.py,sha256=uN4QiWQ8eu_nGpUZSNXaSUkw-lDYdlEmvUIEs5mevz4,27348
+maltoolbox/attackgraph/node.py,sha256=F48FgCeYQFEiAq1HswjOnHImYSSRINZpHDvUZP0FqRk,4265
 maltoolbox/attackgraph/analyzers/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 maltoolbox/language/__init__.py,sha256=TsTTryEyjChwHN1o5F2BSUlFsAss2N6J0H0-nzvXiD8,489
-maltoolbox/language/languagegraph.py,sha256=XWqVzHlf7EMWSkN3fQ-b6zA0pf_ysi_74YseAXAvSbs,71274
+maltoolbox/language/languagegraph.py,sha256=fNQRSDE_XKQMGgxZe75kpBbLpqjhDD5guAmmx9nSZR0,72143
 maltoolbox/language/compiler/__init__.py,sha256=JQyAgDwJh1pU7AmuOhd1-d2b2PYXpgMVPtxnav8QHVc,15872
 maltoolbox/language/compiler/mal_lexer.py,sha256=BeifykDAt4PloRASOaLzBgWF35ev_zgD8lXMIsSHykc,12063
 maltoolbox/language/compiler/mal_parser.py,sha256=sUoaE43l2VKg-Dou30mk2wlVS1FvdOREwHNIyFe4IkY,114699
@@ -20,10 +20,11 @@ maltoolbox/patternfinder/attackgraph_patterns.py,sha256=jgW7UG1yBJ08jvuokdpSiHm7
 maltoolbox/translators/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
 maltoolbox/translators/securicad.py,sha256=F_rndv2JyKxfHAXPwf2RrdiFPnemJVArYUpVsFP6QQk,6997
 maltoolbox/translators/updater.py,sha256=UZPnx22udROiocCcSmtrgUJUupkjktkxl-M7rhBxUPc,8660
-maltoolbox/visualization/__init__.py,sha256=47DEQpj8HBSa-_TImW-5JCeuQeRkm5NMpJWZG3hSuFU,0
+maltoolbox/visualization/__init__.py,sha256=wEPJBVXOgN4PCewjzCWcl6qFAaZS5SKm-8I89UJ89h4,253
 maltoolbox/visualization/graphviz_utils.py,sha256=dfQhPL6Z2hvlMFpThsDr-5tm4Pa22SGHEiXw5ym9JJc,3906
-mal_toolbox-1.0.4.dist-info/METADATA,sha256=SbesLITkX_biOanT4o22POBe74UNEjZWBLOJY1P2xS0,5382
-mal_toolbox-1.0.4.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
-mal_toolbox-1.0.4.dist-info/entry_points.txt,sha256=oqby5O6cUP_OHCm70k_iYPA6UlbTBf7se1i3XwdK3uU,56
-mal_toolbox-1.0.4.dist-info/top_level.txt,sha256=phqRVLRKGdSUgRY03mcpi2cmbbDo5YGjkV4gkqHFFcM,11
-mal_toolbox-1.0.4.dist-info/RECORD,,
+maltoolbox/visualization/neo4j_utils.py,sha256=FHTkkaTvlrf36RXdVdD65TYtlKLNcna9pCl39d6o8wg,3487
+mal_toolbox-1.0.6.dist-info/METADATA,sha256=E3557rDCp3rQwlv58FMjfXBHBb-y7sRNj5M1bZjKvi4,5938
+mal_toolbox-1.0.6.dist-info/WHEEL,sha256=_zCd3N1l69ArxyTb8rzEoP9TpbYXkqRFSNOD5OuxnTs,91
+mal_toolbox-1.0.6.dist-info/entry_points.txt,sha256=oqby5O6cUP_OHCm70k_iYPA6UlbTBf7se1i3XwdK3uU,56
+mal_toolbox-1.0.6.dist-info/top_level.txt,sha256=phqRVLRKGdSUgRY03mcpi2cmbbDo5YGjkV4gkqHFFcM,11
+mal_toolbox-1.0.6.dist-info/RECORD,,

maltoolbox/__init__.py

@@ -1,5 +1,5 @@
 # -*- encoding: utf-8 -*-
-# MAL Toolbox v1.0.4
+# MAL Toolbox v1.0.6
 # Copyright 2025, Andrei Buhaiu.
 #
 # Licensed under the Apache License, Version 2.0 (the "License");
@@ -21,7 +21,7 @@ MAL-Toolbox Framework
 """
 
 __title__ = "maltoolbox"
-__version__ = "1.0.4"
+__version__ = "1.0.6"
 __authors__ = [
     "Andrei Buhaiu",
     "Giuseppe Nebbione",
@@ -48,6 +48,7 @@ config: dict[str, Any] = {
         "langspec_file": "logs/langspec_file.json",
         "langgraph_file": "logs/langgraph.yml",
     },
+    "neo4j": {"uri": None, "username": None, "password": None, "dbname": None},
 }
 
 config_file = os.getenv("MALTOOLBOX_CONFIG", "maltoolbox.yml")
@@ -59,6 +60,8 @@ if os.path.exists(config_file):
 log_configs = config['logging']
 os.makedirs(os.path.dirname(log_configs["log_file"]), exist_ok=True)
 
+neo4j_configs = config['logging']
+
 formatter = logging.Formatter(
     "%(asctime)s %(name)-12s %(levelname)-8s %(message)s", datefmt="%m-%d %H:%M"
 )

maltoolbox/__main__.py

@@ -3,9 +3,9 @@ Command-line interface for MAL toolbox operations
 
 Usage:
     maltoolbox compile <lang_file> <output_file>
-    maltoolbox generate-attack-graph [--graphviz] <model_file> <lang_file>
+    maltoolbox generate-attack-graph [--graphviz] [--neo4j] <model_file> <lang_file>
     maltoolbox upgrade-model <model_file> <lang_file> <output_file>
-    maltoolbox visualize-model <model_file> <lang_file>
+    maltoolbox visualize-model [--neo4j] [--graphviz] <model_file> <lang_file>
 
 Arguments:
     <model_file>    Path to JSON instance model file.
@@ -15,6 +15,7 @@ Arguments:
 Options:
   -h --help         Show this screen.
   -g --graphviz     Visualize with graphviz
+  -n --neo4j        Send to neo4j
 
 Notes:
     - <lang_file> can be either a .mar file (generated by the older MAL
@@ -25,12 +26,17 @@ import logging
 import json
 import docopt
 
-from . import log_configs
+from . import log_configs, neo4j_configs
 from .attackgraph import create_attack_graph, AttackGraph
 from .language.compiler import MalCompiler
 from .language.languagegraph import LanguageGraph
 from .translators.updater import load_model_from_older_version
-from .visualization.graphviz_utils import render_model, render_attack_graph
+from .visualization import (
+    render_model,
+    render_attack_graph,
+    ingest_model_neo4j,
+    ingest_attack_graph_neo4j
+)
 from .model import Model
 
 logger = logging.getLogger(__name__)
@@ -78,6 +84,8 @@ def main():
         )
         if args['--graphviz']:
             render_attack_graph(attack_graph)
+        if args['--neo4j']:
+            ingest_attack_graph_neo4j(attack_graph, neo4j_configs)
 
     elif args['compile']:
         compile(
@@ -90,7 +98,12 @@ def main():
     elif args['visualize-model']:
         lang_graph = LanguageGraph.load_from_file(args['<lang_file>'])
         model = Model.load_from_file(args['<model_file>'], lang_graph)
-        render_model(model)
+        if args['--graphviz']:
+            render_model(model)
+        else:
+            print("Use flag --graphviz to generate a pdf")
+        if args['--neo4j']:
+            ingest_model_neo4j(model, neo4j_configs)
 
 if __name__ == "__main__":
     main()

maltoolbox/attackgraph/attackgraph.py

@@ -167,10 +167,10 @@ class AttackGraph():
 
         attack_graph = AttackGraph(lang_graph)
         attack_graph.model = model
-        serialized_attack_steps = serialized_object['attack_steps']
+        serialized_attack_steps: dict[str, dict] = serialized_object['attack_steps']
 
         # Create all of the nodes in the imported attack graph.
-        for node_dict in serialized_attack_steps.values():
+        for node_full_name, node_dict in serialized_attack_steps.items():
 
             # Recreate asset links if model is available.
             node_asset = None
@@ -192,7 +192,13 @@ class AttackGraph():
                 node_id = node_dict['id'],
                 model_asset = node_asset,
                 ttc_dist = node_dict['ttc'],
-                existence_status = node_dict.get('existence_status', None)
+                existence_status = (
+                    bool(node_dict['existence_status'])
+                    if 'existence_status' in node_dict else None
+                ),
+                # Give explicit full name if model is missing, otherwise
+                # it will generate automatically in node.full_name
+                full_name=node_full_name if not model else None
             )
             ag_node.tags = list(node_dict.get('tags', []))
             ag_node.extras = node_dict.get('extras', {})
@@ -608,7 +614,8 @@ class AttackGraph():
             node_id: Optional[int] = None,
             model_asset: Optional[ModelAsset] = None,
             ttc_dist: Optional[dict] = None,
-            existence_status: Optional[bool] = None
+            existence_status: Optional[bool] = None,
+            full_name: Optional[str] = None
         ) -> AttackGraphNode:
         """Create and add a node to the graph
         Arguments:
@@ -653,7 +660,8 @@ class AttackGraph():
             lg_attack_step = lg_attack_step,
             model_asset = model_asset,
             ttc_dist = ttc_dist,
-            existence_status = existence_status
+            existence_status = existence_status,
+            full_name = full_name
         )
 
         self.nodes[node_id] = node

maltoolbox/attackgraph/node.py

@@ -21,7 +21,8 @@ class AttackGraphNode:
         lg_attack_step: LanguageGraphAttackStep,
         model_asset: Optional[ModelAsset] = None,
         ttc_dist: Optional[dict] = None,
-        existence_status: Optional[bool] = None
+        existence_status: Optional[bool] = None,
+        full_name: Optional[str] = None
     ):
         self.lg_attack_step = lg_attack_step
         self.name = lg_attack_step.name
@@ -30,6 +31,7 @@ class AttackGraphNode:
         self.tags = lg_attack_step.tags
         self.detectors = lg_attack_step.detectors
 
+        self._full_name = full_name
         self.id = node_id
         self.model_asset = model_asset
         self.existence_status = existence_status
@@ -45,10 +47,12 @@ class AttackGraphNode:
             'lang_graph_attack_step': self.lg_attack_step.full_name,
             'name': self.name,
             'ttc': self.ttc,
-            'children': {child.id: child.full_name for child in
-                self.children},
-            'parents': {parent.id: parent.full_name for parent in
-                self.parents},
+            'children': {
+                child.id: child.full_name for child in self.children
+            },
+            'parents': {
+                parent.id: parent.full_name for parent in self.parents
+            },
         }
 
         for detector in self.detectors.values():
@@ -56,7 +60,7 @@ class AttackGraphNode:
         if self.model_asset is not None:
             node_dict['asset'] = str(self.model_asset.name)
         if self.existence_status is not None:
-            node_dict['existence_status'] = str(self.existence_status)
+            node_dict['existence_status'] = self.existence_status
         if self.tags:
             node_dict['tags'] = list(self.tags)
         if self.extras:
@@ -105,13 +109,19 @@ class AttackGraphNode:
     @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.
+        Return the full name of the attack step. This is normally a
+        combination of the asset name to which the attack step
+        belongs and attack step name itself, but can also be
+        explicitly set or a combination of the step id and step name.
         """
-        if self.model_asset:
+        if self._full_name:
+            # Explicitly set
+            return self._full_name
+        elif self.model_asset:
+            # Inherited from model asset
             full_name = self.model_asset.name + ':' + self.name
         else:
+            # Fallback: use ID
             full_name = str(self.id) + ':' + self.name
         return full_name
 

maltoolbox/language/languagegraph.py

@@ -10,7 +10,7 @@ import zipfile
 
 from dataclasses import dataclass, field
 from functools import cached_property
-from typing import Any, Optional
+from typing import Any, Literal, Optional
 
 from maltoolbox.file_utils import (
     load_dict_from_yaml_file, load_dict_from_json_file,
@@ -171,6 +171,18 @@ class LanguageGraphAsset:
             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]:
@@ -222,7 +234,7 @@ class LanguageGraphAsset:
         return self_superassets.intersection(other_superassets)
 
 
-@dataclass
+@dataclass(frozen=True)
 class LanguageGraphAssociationField:
     """A field in an association"""
     asset: LanguageGraphAsset
@@ -231,7 +243,7 @@ class LanguageGraphAssociationField:
     maximum: int
 
 
-@dataclass
+@dataclass(frozen=True, eq=True)
 class LanguageGraphAssociation:
     """
     An association type between asset types as defined in the MAL language
@@ -239,7 +251,7 @@ class LanguageGraphAssociation:
     name: str
     left_field: LanguageGraphAssociationField
     right_field: LanguageGraphAssociationField
-    info: dict = field(default_factory = dict)
+    info: dict = field(default_factory = dict, compare=False)
 
     def to_dict(self) -> dict:
         """Convert LanguageGraphAssociation to dictionary"""
@@ -356,7 +368,7 @@ class LanguageGraphAttackStep:
     An attack step belonging to an asset type in the MAL language
     """
     name: str
-    type: str
+    type: Literal["or", "and", "defense", "exist", "notExist"]
     asset: LanguageGraphAsset
     ttc: Optional[dict] = field(default_factory = dict)
     overrides: bool = False
@@ -739,6 +751,13 @@ class LanguageGraph():
 
         return serialized_graph
 
+    @property
+    def associations(self) -> set[LanguageGraphAssociation]:
+        """
+        Return all associations in the language graph.
+        """
+        return {assoc for asset in self.assets.values() for assoc in asset.associations.values()}
+
     @staticmethod
     def _link_association_to_assets(
         assoc: LanguageGraphAssociation,

maltoolbox/model.py

@@ -3,7 +3,6 @@ MAL-Toolbox Model Module
 """
 
 from __future__ import annotations
-from dataclasses import dataclass, field
 import json
 import logging
 from typing import TYPE_CHECKING
@@ -23,6 +22,7 @@ if TYPE_CHECKING:
     from .language import (
         LanguageGraph,
         LanguageGraphAsset,
+        LanguageGraphAssociation
     )
 
 logger = logging.getLogger(__name__)
@@ -101,6 +101,12 @@ class Model():
                         ' and we do not allow duplicates.'
                     )
 
+        if asset_type not in self.lang_graph.assets:
+            raise ValueError(
+                f'Asset type "{asset_type}" does not exist in language, '
+                'must be one of:\n -' +
+                '\n -'.join(self.lang_graph.assets.keys())
+            )
         lg_asset = self.lang_graph.assets[asset_type]
 
         asset = ModelAsset(
@@ -184,8 +190,11 @@ class Model():
         )
         return self._name_to_asset.get(asset_name, None)
 
-
     def _to_dict(self) -> dict:
+        """Backwards compatible"""
+        return self.to_dict()
+
+    def to_dict(self) -> dict:
         """Get dictionary representation of the model."""
         logger.debug('Translating model to dict.')
         contents: dict[str, Any] = {
@@ -361,6 +370,34 @@ class ModelAsset:
         return (f'ModelAsset(name: "{self.name}", id: {self.id}, '
             f'type: {self.type})')
 
+    def associations_with(
+        self, b: ModelAsset
+    ) -> set[LanguageGraphAssociation]:
+        """Returns all associations from self to `b`"""
+        assocs_in_common = set()
+        for assoc in self.lg_asset.associations.values():
+            assets_to_left = self.associated_assets.get(
+                assoc.left_field.fieldname, set()
+            )
+            assets_to_right = self.associated_assets.get(
+                assoc.right_field.fieldname, set()
+            )
+            if b in assets_to_left or b in assets_to_right:
+                assocs_in_common.add(assoc)
+
+        return assocs_in_common
+
+    def has_association_with(self, b: ModelAsset, assoc_name: str) -> bool:
+        """
+        Returns True if association `assoc_name` exists between self and `b`
+        """
+
+        for fieldname, associated_assets in self.associated_assets.items():
+            assoc = self.lg_asset.associations[fieldname]
+            if assoc.name == assoc_name and b in associated_assets:
+                return True
+
+        return False
 
     def validate_associated_assets(
             self, fieldname: str, assets_to_add: set[ModelAsset]
@@ -418,6 +455,20 @@ class ModelAsset:
         assets dictionary entry corresponding to the given fieldname.
         """
 
+        if fieldname not in self.lg_asset.associations:
+            if assets:
+                to_asset_type = next(iter(assets)).lg_asset
+                possible_associations = self.lg_asset.associations_to(to_asset_type)
+            else:
+                to_asset_type = None
+                possible_associations = self.lg_asset.associations
+            raise ValueError(
+                f'Association fieldname "{fieldname}" does not exist from '
+                f'<{self.lg_asset.name}> to <{to_asset_type.name if to_asset_type else "Any"}>'
+                ', must be one of:\n -' +
+                '\n -'.join([a for a in possible_associations])
+            )
+
         lg_assoc = self.lg_asset.associations[fieldname]
         other_fieldname = lg_assoc.get_opposite_fieldname(fieldname)
 

maltoolbox/visualization/__init__.py

@@ -0,0 +1,9 @@
+from .graphviz_utils import render_attack_graph, render_model
+from .neo4j_utils import ingest_attack_graph_neo4j, ingest_model_neo4j
+
+__all__ = [
+    'render_attack_graph',
+    'render_model',
+    'ingest_attack_graph_neo4j',
+    'ingest_model_neo4j'
+]

maltoolbox/visualization/neo4j_utils.py

@@ -0,0 +1,117 @@
+"""
+MAL-Toolbox Neo4j Ingestor Module
+"""
+# mypy: ignore-errors
+
+import logging
+
+from typing import Any
+from py2neo import Graph, Node, Relationship, Subgraph
+
+logger = logging.getLogger(__name__)
+
+def ingest_attack_graph_neo4j(
+        graph,
+        neo4j_config: dict[str, Any],
+        delete: bool = True
+    ) -> None:
+    """
+    Ingest an attack graph into a neo4j database
+
+    Arguments:
+    graph                - the attackgraph provided by the atkgraph.py module.
+    uri                  - the URI to a running neo4j instance
+    username             - the username to login on Neo4J
+    password             - the password to login on Neo4J
+    dbname               - the selected database
+    delete               - if True, the previous content of the database is deleted
+                           before ingesting the new attack graph
+    """
+
+    uri = neo4j_config.get('uri')
+    username = neo4j_config.get('username')
+    password = neo4j_config.get('password')
+    dbname = neo4j_config.get('dbname')
+
+    g = Graph(uri=uri, user=username, password=password, name=dbname)
+    if delete:
+        g.delete_all()
+
+    nodes = {}
+    rels = []
+    for node in graph.nodes.values():
+        node_dict = node.to_dict()
+        nodes[node.id] = Node(
+            node_dict['asset'] if 'asset' in node_dict else node_dict['id'],
+            name = node_dict['name'],
+            full_name = node.full_name,
+            type = node_dict['type'],
+            ttc = str(node_dict['ttc']),
+        )
+
+
+    for node in graph.nodes.values():
+        for child in node.children:
+            rels.append(Relationship(nodes[node.id], nodes[child.id]))
+
+    subgraph = Subgraph(list(nodes.values()), rels)
+
+    tx = g.begin()
+    tx.create(subgraph)
+    g.commit(tx)
+
+
+def ingest_model_neo4j(
+        model,
+        neo4j_config: dict[str, Any],
+        delete: bool = True
+    ) -> None:
+    """
+    Ingest an instance model graph into a Neo4J database
+
+    Arguments:
+    model                - the instance model dictionary as provided by the model.py module
+    uri                  - the URI to a running neo4j instance
+    username             - the username to login on Neo4J
+    password             - the password to login on Neo4J
+    dbname               - the selected database
+    delete               - if True, the previous content of the database is deleted
+                           before ingesting the new attack graph
+    """
+
+    uri = neo4j_config.get('uri')
+    username = neo4j_config.get('username')
+    password = neo4j_config.get('password')
+    dbname = neo4j_config.get('dbname')
+
+    g = Graph(uri=uri, user=username, password=password, name=dbname)
+    if delete:
+        g.delete_all()
+
+    nodes = {}
+    rels = []
+
+    for asset in model.assets.values():
+        nodes[str(asset.id)] = Node(
+            str(asset.type),
+            name=str(asset.name),
+            asset_id=str(asset.id),
+            type=str(asset.type)
+        )
+
+    for asset in model.assets.values():
+        for fieldname, other_assets in asset.associated_assets.items():
+            for other_asset in other_assets:
+                rels.append(
+                    Relationship(
+                        nodes[str(asset.id)],
+                        str(fieldname),
+                        nodes[str(other_asset.id)]
+                    )
+                )
+
+    subgraph = Subgraph(list(nodes.values()), rels)
+
+    tx = g.begin()
+    tx.create(subgraph)
+    g.commit(tx)