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

maltoolbox/language/specification.py

@@ -1,265 +0,0 @@
-"""
-MAL-Toolbox Language Specification Module
-
-"""
-
-import logging
-import json
-import zipfile
-import copy
-
-logger = logging.getLogger(__name__)
-
-def load_language_specification_from_mar(mar_archive: str) -> dict:
-    """
-    Read a ".mar" archive provided by malc (https://github.com/mal-lang/malc)
-    and return a dictionary representing a MAL language structure
-
-    Arguments:
-    mar_archive     -   the path to a ".mar" archive
-
-    Return:
-    A dictionary representing the language specification
-    """
-
-    logger.info(f'Load language specfication from \'{mar_archive}\' mar archive.')
-    with zipfile.ZipFile(mar_archive, 'r') as archive:
-        langspec = archive.read('langspec.json')
-        return json.loads(langspec)
-
-def load_language_specification_from_json(json_file: str) -> dict:
-    """
-    Read a MAL language JSON specification file
-
-    Arguments:
-    file_spec       - a language specification file that can be for example
-                      provided by malc (https://github.com/mal-lang/malc)
-
-    Return:
-    A dictionary representing the language specification
-    """
-
-    logger.info(f'Load language specfication from \'{json_file}\'.')
-    with open(json_file, 'r', encoding='utf-8') as spec:
-        data = spec.read()
-    return json.loads(data)
-
-
-def save_language_specification_to_json(lang_spec: dict, filename: str) -> dict:
-    """
-    Save a MAL language specification dictionary to a JSON file
-
-    Arguments:
-    lang_spec       - a dictionary containing the MAL language specification
-    filename        - the JSON filename where the language specification will
-                      be written
-    """
-
-    logger.info(f'Save language specfication to {filename}.')
-
-    with open(filename, 'w', encoding='utf-8') as file:
-        json.dump(lang_spec, file, indent=4)
-
-
-def get_attacks_for_class(lang_spec: dict, asset_type: str) -> dict:
-    """
-    Get all Attack Steps for a specific Class
-
-    Arguments:
-    lang_spec       - a dictionary containing the MAL language specification
-    asset_type      - a string representing the class for which we want to list
-                      the possible attack steps
-
-    Return:
-    A dictionary representing the set of possible attacks for the specified
-    class. Each key in the dictionary is an attack name and is associated
-    with a dictionary containing other characteristics of the attack such as
-    type of attack, TTC distribution, child attack steps and other information
-    """
-    attacks = {}
-    asset = next((asset for asset in lang_spec['assets'] if asset['name'] == \
-        asset_type), None)
-    if not asset:
-        logger.error(f'Failed to find asset type {asset_type} when '\
-            'looking for attack steps.')
-        return None
-
-    logger.debug(f'Get attack steps for {asset["name"]} asset from '\
-        'language specification.')
-    if asset['superAsset']:
-        logger.debug(f'Asset extends another one, fetch the superclass '\
-            'attack steps for it.')
-        attacks = get_attacks_for_class(lang_spec, asset['superAsset'])
-
-    for attack in asset['attackSteps']:
-        if attack['name'] not in attacks:
-            attacks[attack['name']] = copy.deepcopy(attack)
-        else:
-            if not attack['reaches']:
-                # This attack step does not lead to any attack steps
-                continue
-            if attack['reaches']['overrides'] == True:
-                attacks[attack['name']] = copy.deepcopy(attack)
-            else:
-                attacks[attack['name']]['reaches']['stepExpressions'].\
-                    extend(attack['reaches']['stepExpressions'])
-
-    return attacks
-
-def get_associations_for_class(lang_spec: dict, asset_type: str) -> dict:
-    """
-    Get all Associations for a specific Class
-
-    Arguments:
-    lang_spec       - a dictionary containing the MAL language specification
-    asset_type      - a string representing the class for which we want to list
-                      the associations
-
-    Return:
-    A dictionary representing the set of associations for the specified
-    class. Each key in the dictionary is an attack name and is associated
-    with a dictionary containing other characteristics of the attack such as
-    type of attack, TTC distribution, child attack steps and other information
-    """
-    logger.debug(f'Get associations for {asset_type} asset from '\
-        'language specification.')
-    associations = []
-
-    asset = next((asset for asset in lang_spec['assets'] if asset['name'] == \
-        asset_type), None)
-    if not asset:
-        logger.error(f'Failed to find asset type {asset_type} when '\
-            'looking for associations.')
-        return None
-
-    if asset['superAsset']:
-        logger.debug(f'Asset extends another one, fetch the superclass '\
-            'associations for it.')
-        associations.extend(get_associations_for_class(lang_spec,
-            asset['superAsset']))
-    assoc_iter = (assoc for assoc in lang_spec['associations'] \
-        if assoc['leftAsset'] == asset_type or \
-            assoc['rightAsset'] == asset_type)
-    assoc = next(assoc_iter, None)
-    while (assoc):
-        associations.append(assoc)
-        assoc = next(assoc_iter, None)
-
-    return associations
-
-def get_association_by_fields_and_assets(lang_spec: dict,
-    first_field: str,
-    second_field: str,
-    first_asset: str,
-    second_asset: str) -> str:
-    """
-    Get an association based on its field names and asset types
-
-    Arguments:
-    lang_spec       - a dictionary containing the MAL language specification
-    first_field     - a string containing the first field
-    second_field    - a string containing the second field
-    first_asset     - a string representing the first asset type
-    second_asset    - a string representing the second asset type
-
-    Return:
-    The name of the association matching the fieldnames and asset types.
-    None if there is no match.
-    """
-    for assoc in lang_spec['associations']:
-        logger.debug(f'Compare (\"{first_asset}\",'
-            f'\"{first_field}\",'
-            f'\"{second_asset}\",'
-            f'\"{second_field}\") to '
-            f'(\"{assoc["leftAsset"]}\",'
-            f'\"{assoc["leftField"]}\",'
-            f'\"{assoc["rightAsset"]}\",'
-            f'\"{assoc["rightField"]}\").')
-
-        # If the asset and fields match either way we accept it as a match.
-        if assoc['leftField'] == first_field and \
-            assoc['rightField'] == second_field and \
-            extends_asset(lang_spec, first_asset, assoc['leftAsset']) and \
-            extends_asset(lang_spec, second_asset, assoc['rightAsset']):
-            return assoc['name']
-        if assoc['leftField'] == second_field and \
-            assoc['rightField'] == first_field and \
-            extends_asset(lang_spec, second_asset, assoc['leftAsset']) and \
-            extends_asset(lang_spec, first_asset, assoc['rightAsset']):
-            return assoc['name']
-
-    return None
-
-def get_variable_for_class_by_name(lang_spec: dict, asset_type: str,
-    variable_name:str) -> dict:
-    """
-    Get a variables for a specific asset type by name.
-    NOTE: Variables are the ones specified in MAL through `let` statements
-
-    Arguments:
-    lang_spec       - a dictionary containing the MAL language specification
-    asset_type      - a string representing the type of asset which contains
-                    the variable
-    variable_name   - the name of the variable to search for
-
-    Return:
-    A dictionary representing the step expressions for the specified variable.
-    """
-
-    asset = next((asset for asset in lang_spec['assets'] if asset['name'] == \
-        asset_type), None)
-    if not asset:
-        logger.error(f'Failed to find asset type {asset_type} when '\
-            'looking for variable.')
-        return None
-
-    variable_dict = next((variable for variable in \
-        asset['variables'] if variable['name'] == variable_name), None)
-    if not variable_dict:
-        if asset['superAsset']:
-            variable_dict = get_variable_for_class_by_name(lang_spec,
-                asset['superAsset'], variable_name)
-        if variable_dict:
-            return variable_dict
-        else:
-            logger.error(f'Failed to find variable {variable_name} in '\
-                f'{asset_type}\'s language specification.')
-        return None
-
-    return variable_dict['stepExpression']
-
-def extends_asset(lang_spec: dict, asset, target_asset):
-    """
-    Check if an asset extends the target asset through inheritance.
-
-    Arguments:
-    lang_spec       - a dictionary containing the MAL language specification
-    asset           - the asset name we wish to evaluate
-    target_asset    - the target asset name we wish to evaluate if it
-                      is extended
-
-    Return:
-    True if this asset extends the target_asset via inheritance.
-    False otherwise.
-    """
-
-    logger.debug(f'Check if {asset} extends {target_asset} via inheritance.')
-
-    if asset == target_asset:
-        return True
-
-    asset_dict = next((asset_info for asset_info in lang_spec['assets'] \
-        if asset_info['name'] == asset), None)
-    if not asset_dict:
-        logger.error(f'Failed to find asset type {asset} when '\
-            'looking for variable.')
-        return False
-    if asset_dict['superAsset']:
-        if asset_dict['superAsset'] == target_asset:
-            return True
-        else:
-            return extends_asset(lang_spec, asset_dict['superAsset'],
-                target_asset)
-
-    return False
-

maltoolbox/main.py

@@ -1,84 +0,0 @@
-"""
-MAL-Toolbox Main Module
-"""
-
-import sys
-
-import logging
-import json
-
-import maltoolbox
-import maltoolbox.cl_parser
-from maltoolbox.language import classes_factory
-from maltoolbox.language import specification
-from maltoolbox.model import model
-from maltoolbox.attackgraph import attackgraph
-from maltoolbox.attackgraph.analyzers import apriori
-from maltoolbox.ingestors import neo4j
-
-logger = logging.getLogger(__name__)
-
-def main():
-    """Main routine of maltoolbox command line interface."""
-    args = maltoolbox.cl_parser.parse_args(sys.argv[1:])
-    cmd_params = vars(args)
-    logger.info('Received the following command line parameters:\n' +
-        json.dumps(cmd_params, indent = 2))
-
-    match(cmd_params['command']):
-        case 'gen_ag':
-            model_filename = cmd_params['model']
-            langspec_filename = cmd_params['language']
-
-            # Load language specification and generate classes based on it.
-            lang_spec = specification. \
-                load_language_specification_from_mar(langspec_filename)
-            if maltoolbox.log_configs['langspec_file']:
-                specification.save_language_specification_to_json(lang_spec,
-                    maltoolbox.log_configs['langspec_file'])
-            lang_classes_factory = \
-                classes_factory.LanguageClassesFactory(lang_spec)
-            lang_classes_factory.create_classes()
-
-            # Load instance model.
-            instance_model = model.Model('Test model', lang_spec,
-                lang_classes_factory)
-            instance_model.load_from_file(model_filename)
-            if maltoolbox.log_configs['model_file']:
-                instance_model.save_to_file( \
-                    maltoolbox.log_configs['model_file'])
-
-            graph = attackgraph.AttackGraph()
-            result = graph.generate_graph(lang_spec, instance_model)
-            if result > 0:
-                logger.error('Attack graph generation failed!')
-                print('Attack graph generation failed!')
-                exit(result)
-
-            apriori.calculate_viability_and_necessity(graph)
-
-            graph.attach_attackers(instance_model)
-
-            if maltoolbox.log_configs['attackgraph_file']:
-                graph.save_to_file(
-                    maltoolbox.log_configs['attackgraph_file'])
-
-            if cmd_params['neo4j']:
-                # Injest instance model and attack graph into Neo4J.
-                logger.debug('Ingest model graph into Neo4J database.')
-                neo4j.ingest_model(instance_model,
-                    maltoolbox.neo4j_configs['uri'],
-                    maltoolbox.neo4j_configs['username'],
-                    maltoolbox.neo4j_configs['password'],
-                    maltoolbox.neo4j_configs['dbname'],
-                    delete=True)
-                logger.debug('Ingest attack graph into Neo4J database.')
-                neo4j.ingest_attack_graph(graph,
-                    maltoolbox.neo4j_configs['uri'],
-                    maltoolbox.neo4j_configs['username'],
-                    maltoolbox.neo4j_configs['password'],
-                    maltoolbox.neo4j_configs['dbname'],
-                    delete=False)
-
-        case _:
-            logger.error(f'Received unknown command: {cmd_params["command"]}.')

maltoolbox/model/model.py

@@ -1,282 +0,0 @@
-"""
-MAL-Toolbox Model Module
-"""
-
-import json
-import logging
-
-from dataclasses import dataclass
-from typing import List
-
-logger = logging.getLogger(__name__)
-
-@dataclass
-class Attacker:
-    id: str = None
-    name: str = None
-    entry_points: List[tuple] = None
-
-class Model:
-    latestId = 0
-
-    def __repr__(self) -> str:
-        return f'Model {self.name}'
-
-    def __init__(self, name, lang_spec, lang_classes_factory):
-        self.name = name
-        self.assets = []
-        self.associations = []
-        self.attackers = []
-        self.lang_spec = lang_spec
-        self.lang_classes_factory = lang_classes_factory
-
-    def add_asset(self, asset, asset_id: int = None):
-        """
-        Add an asset to the model.
-        """
-        if asset_id is not None:
-            for existing_asset in self.assets:
-                if asset_id == existing_asset.id:
-                    raise ValueError(f'Asset index {asset_id} already in use.')
-            asset.id = asset_id
-        else:
-            asset.id = self.latestId
-        self.latestId = max(asset.id + 1, self.latestId)
-
-        asset.associations = []
-        if not hasattr(asset, 'name'):
-            asset.name = asset.metaconcept + ':' + str(asset.id)
-        self.assets.append(asset)
-
-    def add_association(self, association):
-        """
-        Add an association to the model.
-        """
-        for prop in range(0, 2):
-            for asset in getattr(association,
-                list(vars(association)['_properties'])[prop]):
-                assocs = list(asset.associations)
-                assocs.append(association)
-                asset.associations = assocs
-        self.associations.append(association)
-
-    def add_attacker(self, attacker, attacker_id: int = None):
-        """
-        Add an attacker to the model.
-        """
-        if attacker_id:
-            attacker.id = attacker_id
-        else:
-            attacker.id = self.latestId
-        self.latestId = max(attacker.id + 1, self.latestId)
-
-        if not hasattr(attacker, 'name') or not attacker.name:
-            attacker.name = 'Attacker:' + str(attacker.id)
-        self.attackers.append(attacker)
-
-    def get_asset_by_id(self, asset_id):
-        """
-        Find an asset in the model based on its id.
-
-        Arguments:
-        asset_id        - the id of the asset we are looking for
-
-        Return:
-        An asset matching the id if it exists in the model.
-        """
-        return next((asset for asset in self.assets if asset.id == asset_id),
-            None)
-
-    def get_attacker_by_id(self, attacker_id):
-        """
-        Find an attacker in the model based on its id.
-
-        Arguments:
-        attacker_id     - the id of the attacker we are looking for
-
-        Return:
-        An attacker matching the id if it exists in the model.
-        """
-        return next((attacker for attacker in self.attackers \
-            if attacker.id == attacker_id), None)
-
-    def get_associated_assets_by_field_name(self, asset, field_name):
-        """
-        Get a list of associated assets for an asset given a fieldname.
-
-        Arguments:
-        asset           - the asset whose fields we are interested in
-        fieldname       - the field name we are looking for
-
-        Return:
-        A list of assets associated with the asset given that match the
-        fieldname.
-        """
-        logger.debug(f'Get associated assets for asset '
-            f'{asset.name}(id:{asset.id}) by field name {field_name}.')
-        associated_assets = []
-        for association in asset.associations:
-            # Determine which two of the end points leads away from the asset.
-            # This is particularly relevant for associations between two
-            # assets of the same type.
-            if asset in getattr(association,
-                list(vars(association)['_properties'])[0]):
-                elementName = list(vars(association)['_properties'])[1]
-            else:
-                elementName = list(vars(association)['_properties'])[0]
-
-            if elementName == field_name:
-                associated_assets.extend(getattr(association, elementName))
-
-        return associated_assets
-
-    def asset_to_json(self, asset):
-        """
-        Convert an asset to its JSON format.
-        """
-        defenses = {}
-        logger.debug(f'Translating {asset.name} to json.')
-        for defense in list(vars(asset)['_properties'])[1:]:
-            defenseValue = getattr(asset, defense)
-            logger.debug(f'Translating {defense}: {defenseValue} defense '\
-                'to json.')
-            if defenseValue != getattr(asset, defense).default():
-            # Save the default values that are not the default ones.
-                defenses[str(defense)] = str(defenseValue)
-        return (str(asset.id), {
-                'name': str(asset.name),
-                'metaconcept': str(asset.metaconcept),
-                'eid': str(asset.id),
-                'defenses': defenses
-                }
-            )
-
-    def association_to_json(self, association):
-        """
-        Convert an association to its JSON format.
-        """
-        firstElementName = list(vars(association)['_properties'])[0]
-        secondElementName = list(vars(association)['_properties'])[1]
-        firstElements = getattr(association, firstElementName)
-        secondElements = getattr(association, secondElementName)
-        json_association = {
-            'metaconcept': type(association).__name__,
-            'association': {
-                str(firstElementName): [str(asset.id) for asset in firstElements],
-                str(secondElementName): [str(asset.id) for asset in secondElements]
-            }
-        }
-        return json_association
-
-    def attacker_to_json(self, attacker):
-        """
-        Convert an attacker to its JSON format.
-        """
-        logger.debug(f'Translating {attacker.name} to json.')
-        json_attacker = {
-            'name': str(attacker.name),
-            'entry_points': {},
-        }
-        for (asset, attack_steps) in attacker.entry_points:
-            json_attacker['entry_points'][str(asset.id)] = {
-                'attack_steps' : attack_steps
-            }
-        return (str(attacker.id), json_attacker)
-
-    def model_to_json(self):
-        """
-        Convert the model to its JSON format.
-        """
-        logger.debug(f'Converting model to JSON format.')
-        contents = {
-            'metadata': {},
-            'assets': {},
-            'associations': [],
-            'attackers' : {}
-        }
-        contents['metadata'] = {
-            'name': self.name,
-            'langVersion': self.lang_spec['defines']['version'],
-            'langID': self.lang_spec['defines']['id'],
-            'malVersion': '0.1.0-SNAPSHOT',
-            'info': 'Created by the mal-toolbox model python module.'
-        }
-
-        logger.debug('Translating assets to json.')
-        for asset in self.assets:
-            (asset_id, asset_json) = self.asset_to_json(asset)
-            contents['assets'][asset_id] = asset_json
-
-        logger.debug('Translating associations to json.')
-        for association in self.associations:
-            assoc_json = self.association_to_json(association)
-            contents['associations'].append(assoc_json)
-
-        logger.debug('Translating attackers to json.')
-        for attacker in self.attackers:
-            (attacker_id, attacker_json) = self.attacker_to_json(attacker)
-            contents['attackers'][attacker_id] = attacker_json
-        return contents
-
-    def save_to_file(self, filename):
-        """
-        Save model to a json file.
-
-        Arguments:
-        filename        - the name of the output file
-        """
-
-        logger.info(f'Saving model to {filename} file.')
-        contents = self.model_to_json()
-        fp = open(filename, 'w')
-        json.dump(contents, fp, indent = 2)
-
-    def load_from_file(self, filename):
-        """
-        Load model from a json file.
-
-        Arguments:
-        filename        - the name of the input file
-        """
-        logger.info(f'Loading model from {filename} file.')
-        with open(filename, 'r', encoding='utf-8') as model_file:
-            json_model = json.loads(model_file.read())
-
-        self.name = json_model['metadata']['name']
-
-        # Reconstruct the assets
-        for asset_id in json_model['assets']:
-            asset_object = json_model['assets'][asset_id]
-            logger.debug(f'Loading asset from {filename}:\n' \
-                + json.dumps(asset_object, indent = 2))
-            asset = getattr(self.lang_classes_factory.ns,
-                asset_object['metaconcept'])(name = asset_object['name'])
-            for defense in asset_object['defenses']:
-                setattr(asset, defense,
-                    float(asset_object['defenses'][defense]))
-            self.add_asset(asset, asset_id = int(asset_id))
-
-        # Reconstruct the associations
-        if 'associations' in json_model:
-            for association_object in json_model['associations']:
-                association = getattr(self.lang_classes_factory.ns,
-                    association_object['metaconcept'])()
-                for field in association_object['association']:
-                    asset_list = []
-                    for asset_id in association_object['association'][field]:
-                        asset_list.append(self.get_asset_by_id(int(asset_id)))
-                    setattr(association, field, asset_list)
-                self.add_association(association)
-
-        # Reconstruct the attackers
-        if 'attackers' in json_model:
-            attackers_info = json_model['attackers']
-            for attacker_id in attackers_info:
-                attacker = Attacker(name = attackers_info[attacker_id]['name'])
-                attacker.entry_points = []
-                for asset_id in attackers_info[attacker_id]['entry_points']:
-                    attacker.entry_points.append(
-                        (self.get_asset_by_id(int(asset_id)),
-                        attackers_info[attacker_id]['entry_points']\
-                            [asset_id]['attack_steps']))
-                self.add_attacker(attacker, attacker_id = int(attacker_id))