csle-attack-profiler 0.5.2__tar.gz

csle_attack_profiler-0.5.2/PKG-INFO

@@ -0,0 +1,17 @@
+Metadata-Version: 2.1
+Name: csle_attack_profiler
+Version: 0.5.2
+Summary: Library with MITRE attack profiler for CSLE
+Author: Bength Pappila
+Author-email: brpa@kth.se
+License: Creative Commons Attribution-ShareAlike 4.0 International
+Keywords: Reinforcement-Learning Cyber-Security Markov-Games Markov-Decision-Processes
+Platform: unix
+Platform: linux
+Classifier: Programming Language :: Python :: 3
+Classifier: Programming Language :: Python :: 3 :: Only
+Classifier: Programming Language :: Python :: 3.8
+Classifier: Programming Language :: Python :: 3.9
+Classifier: Intended Audience :: Science/Research
+Requires-Python: >=3.8
+Provides-Extra: testing

csle_attack_profiler-0.5.2/README.md

@@ -0,0 +1,177 @@
+# `csle-attack-profiler`
+
+Scripts and programs to profile attacks, attack sequences, and a probabilistic HMM profiler 
+using data from the csle platform, profiling attacks to MITRE ATT&CK techniques, and tactics.
+
+[![PyPI version]] 0.5.1
+![PyPI - Downloads] (https://pypi.org/project/csle-attack-profiler/)
+
+## Requirements
+
+- Python 3.8+
+- `csle-common`
+- `csle-base`
+- `mitreattack-python`
+
+
+## Development Requirement`
+
+- Python 3.8+
+- `flake8` (for linting)
+- `flake8-rst-docstrings` (for linting docstrings)
+- `tox` (for automated testing)
+- `pytest` (for unit tests)
+- `pytest-cov` (for unit test coverage)
+- `mypy` (for static typing)
+- `mypy-extensions` (for static typing)
+- `mypy-protobuf` (for static typing)
+- `types-PyYaml` (for static typing)
+- `types-paramiko` (for static typing)
+- `types-protobuf` (for static typing)
+- `types-requests` (for static typing)
+- `types-urllib3` (for static typing)
+- `sphinx` (for API documentation)
+- `sphinxcontrib-napoleon` (for API documentation)
+- `sphinx-rtd-theme` (for API documentation)
+- `pytest-mock` (for mocking tests)
+- `pytest-grpc` (for grpc tests)
+
+## Installation
+
+```bash
+# install from pip
+pip install csle-attack-profiler==<version>
+# local install from source
+$ pip install -e csle-attack-profiler
+# or (equivalently):
+make install
+# force upgrade deps
+$ pip install -e csle-attack-profiler --upgrade
+# git clone and install from source
+git clone https://github.com/Limmen/csle
+cd csle/simulation-system/libs/csle-attack-profiler
+pip3 install -e .
+# Install development dependencies
+$ pip install -r requirements_dev.txt
+```
+
+### Development tools 
+
+Install all development tools at once:
+```bash
+make install_dev
+```
+or
+```bash
+pip install -r requirements_dev.txt
+```
+## API documentation
+
+This section contains instructions for generating API documentation using `sphinx`.
+
+### Latest Documentation
+
+The latest documentation is available at [https://limmen.dev/csle/docs/csle-base](https://limmen.dev/csle/docs/csle-base)
+
+### Generate API Documentation
+
+First make sure that the `CSLE_HOME` environment variable is set:
+```bash
+echo $CSLE_HOME
+```
+Then generate the documentation with the commands:
+```bash
+cd docs
+sphinx-apidoc -f -o source/ ../src/csle_attack_profiler/
+make html
+```
+To update the official documentation at [https://limmen.dev/csle](https://limmen.dev/csle), 
+copy the generated HTML files to the documentation folder:
+```bash
+cp -r build/html ../../../../docs/_docs/csle-attack-profiler
+```
+
+To run all documentation commands at once, use the command:
+```bash
+make docs
+```
+
+## Static code analysis
+
+To run the Python linter, execute the following command:
+```
+flake8 .
+# or (equivalently):
+make lint
+```
+
+To run the mypy type checker, execute the following command:
+```
+mypy .
+# or (equivalently):
+make types
+```
+
+## Unit tests
+
+To run the unit tests, execute the following command:
+```
+pytest
+# or (equivalently):
+make unit_tests
+```
+
+To run tests of a specific test suite, execute the following command:
+```
+pytest -k "ClassName"
+```
+
+To generate a coverage report, execute the following command:
+```
+pytest --cov=csle_attack_profiler
+```
+
+## Run tests and code analysis in different python environments
+
+To run tests and code analysis in different python environments, execute the following command:
+
+```bash
+tox
+# or (equivalently):
+make tests
+```
+
+## Create a new release and publish to PyPi
+
+First build the package by executing:
+```bash
+python3 -m build
+# or (equivalently)
+make build
+```
+After running the command above, the built package is available at `./dist`.
+
+Push the built package to PyPi by running:
+```bash
+python3 -m twine upload dist/*
+# or (equivalently)
+make push
+```
+
+To run all commands for the release at once, execute:
+```bash
+make release
+```
+
+## Author & Maintainer
+
+Bength Pappila <brpa@kth.se>
+
+## Copyright and license
+
+[LICENSE](LICENSE.md)
+
+Creative Commons
+
+(C) 2024, Bength Pappila
+

csle_attack_profiler-0.5.2/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools==68.0.0"]
+build-backend = "setuptools.build_meta"
+
+[tool.pytest.ini_options]
+addopts = "--cov=csle_attack_profiler -p no:warnings"
+testpaths = [
+    "tests",
+]
+log_cli = 1
+log_cli_level = "INFO"
+log_cli_format = "%(asctime)s [%(levelname)8s] %(message)s (%(filename)s:%(lineno)s)"
+log_cli_date_format="%Y-%m-%d %H:%M:%S"
+
+[tool.mypy]
+mypy_path = "src"
+check_untyped_defs = true
+disallow_any_generics = true
+ignore_missing_imports = true
+no_implicit_optional = true
+show_error_codes = true
+strict_equality = true
+warn_redundant_casts = true
+warn_return_any = true
+warn_unreachable = true
+warn_unused_configs = true
+no_implicit_reexport = true

csle_attack_profiler-0.5.2/setup.cfg

@@ -0,0 +1,74 @@
+[metadata]
+name = csle_attack_profiler
+version = attr: csle_attack_profiler.__version__
+description = Library with MITRE attack profiler for CSLE
+author = Bength Pappila
+author_email = brpa@kth.se
+license = Creative Commons Attribution-ShareAlike 4.0 International
+keywords = Reinforcement-Learning Cyber-Security Markov-Games Markov-Decision-Processes
+license_files = 
+	- LICENSE.md
+	- README.md
+platforms = unix, linux
+classifiers = 
+	Programming Language :: Python :: 3
+	Programming Language :: Python :: 3 :: Only
+	Programming Language :: Python :: 3.8
+	Programming Language :: Python :: 3.9
+	Intended Audience :: Science/Research
+
+[options]
+python_requires = >=3.8
+package_dir = 
+	=src
+packages = find:
+zip_safe = no
+install_requires = 
+	mitreattack-python==2.0.14
+	csle-base==0.5.2
+	csle-common==0.5.2
+
+[options.packages.find]
+where = src
+
+[options.extras_require]
+testing = 
+	pytest>=6.0
+	pytest-cov>=2.0
+	pytest-mock>=3.6.0
+	grpcio>=1.57.0
+	grpcio-tools>=1.57.0
+	pytest-grpc>=0.8.0
+	mypy>=1.4.1
+	mypy-extensions>=1.0.0
+	mypy-protobuf>=3.5.0
+	types-PyYAML>=6.0.12.11
+	types-paramiko>=3.2.0.0
+	types-protobuf>=4.23.0.3
+	types-requests>=2.31.0.1
+	types-urllib3>=1.26.25.13
+	flake8>=6.1.0
+	flake8-rst-docstrings>=0.3.0
+	tox>=3.24
+	sphinx>=5.3.0
+	sphinxcontrib-napoleon>=0.7
+	sphinx-rtd-theme>=1.1.1
+	twine>=4.0.2
+	build>=0.10.0
+
+[options.package_data]
+csle_attack_profiler = py.typed
+
+[flake8]
+max-line-length = 120
+exclude = .git,__pycache__,docs/source/conf.py,old,build,dist,*_pb2*,*init__*,.tox
+ignore = E741, W503, W504, F821, W605
+rst-roles = class, func, ref
+rst-directives = envvar, exception
+rst-substitutions = version
+extend-ignore = D401, D400, D100, RST305, RST219, D205, D202, D200, D204, RST206, W293, D403, D402, RST306
+
+[egg_info]
+tag_build = 
+tag_date = 0
+

csle_attack_profiler-0.5.2/setup.py

@@ -0,0 +1,4 @@
+from setuptools import setup
+
+if __name__ == '__main__':
+    setup()

csle_attack_profiler-0.5.2/src/csle_attack_profiler/__init__.py

@@ -0,0 +1 @@
+from . __version__ import __version__

csle_attack_profiler-0.5.2/src/csle_attack_profiler/__version__.py

@@ -0,0 +1 @@
+__version__ = '0.5.2'

csle_attack_profiler-0.5.2/src/csle_attack_profiler/attack_profiler.py

@@ -0,0 +1,204 @@
+from csle_common.dao.emulation_action.attacker.emulation_attacker_action \
+    import EmulationAttackerAction
+from csle_common.dao.emulation_action.attacker.emulation_attacker_action_id \
+    import EmulationAttackerActionId
+from csle_attack_profiler.dao.tactics import Tactics
+from csle_attack_profiler.dao.attack_mapping import EmulationAttackerMapping
+from csle_attack_profiler.dao.attack_graph import AttackGraph
+from mitreattack.stix20 import MitreAttackData
+from typing import List, Dict, Union
+import os
+
+
+class AttackProfiler:
+    """
+    Class representing the attack profile based on the MITRE ATT&CK framework for Enterprise.
+    """
+
+    def __init__(self, techniques_tactics: Dict[str, List[str]], mitigations: Dict[str, List[str]],
+                 data_sources: Dict[str, List[str]], subtechniques: Dict[str, str],
+                 action_id: EmulationAttackerActionId) -> None:
+        """
+        Class constructor
+
+        :params techniques_tactics: the techniques and tactics used by the attacker action.
+                                    The key is the technique and the value is the tactics
+        :params mitigations: the mitigations used by the attacker action. The key is the technique and the
+                             value is the mitigations
+        :params data_sources: the data sources used by the attacker action. The key is the technqiue and the value is
+                              the data sources
+        :params sub_techniques: the sub-techniques used by the attacker action. The key is the technique and
+                                the value is the sub-techniques
+        :params action_id: the id of the attacker action
+        """
+        
+        self.techniques_tactics = techniques_tactics
+        self.mitigations = mitigations
+        self.data_sources = data_sources
+        self.subtechniques = subtechniques
+        self.action_id = action_id
+
+    @staticmethod
+    def get_attack_profile(attacker_action: EmulationAttackerAction) -> 'AttackProfiler':
+        """
+        Returns the attack profile of the actions
+
+        :params attacker_action: the attacker action
+        :return: the attack profile of the action
+        """
+        current_dir = os.path.dirname(__file__)
+        path = os.path.join(current_dir, "./dao/enterprise-attack.json")
+        mitre_attack_data = MitreAttackData(path)
+
+        # Retrieve the id from the attacker action
+        attacker_id = attacker_action.id
+        # Get the defined tactics and techniques for the attack
+        attack_mapping = EmulationAttackerMapping.get_attack_info(attacker_id)
+        if attack_mapping is None:
+            return AttackProfiler({}, {}, {}, {}, EmulationAttackerActionId.CONTINUE)
+
+        attack_techniques_vals = [technique.value for technique in attack_mapping['techniques']]
+        
+        attacker_action_id = attacker_action.id
+        techniques_tactics = {}
+        mitigations = {}
+        data_sources = {}
+        sub_techniques = {}
+        # Loop over the techniques associated with the attack
+        for technique_name in attack_techniques_vals:
+            # Get technique from MitreAttackData, stix_id maps to technique in the library.
+            try:
+                obj = mitre_attack_data.get_objects_by_name(technique_name, "attack-pattern")
+            except Exception as e:
+                os.system("echo 'Error in getting technique: {}'".format(e))
+                continue
+            technique = obj[0]
+            stix_id = technique.id
+
+            # Collect the tactics and add it to the dictionary
+            tactics = [phase['phase_name'] for phase in technique.kill_chain_phases]
+            techniques_tactics[technique_name] = tactics
+            
+            # Add the data sources to the dictionary
+            if hasattr(technique, 'x_mitre_data_sources'):
+                data_sources[technique_name] = technique.x_mitre_data_sources
+            # Fetch the mitigations from the technique and add it to the dictionary
+            try:
+                mitigations_object = mitre_attack_data.get_mitigations_mitigating_technique(stix_id)
+                mitigations_list = [mitig['object']['name'] for mitig in mitigations_object]
+                mitigations[technique_name] = mitigations_list
+            except Exception as e:
+                os.system("echo 'Error in getting mitigations: {}'".format(e))
+                continue
+        
+        # Add the sub-technique to the dictionary
+        if 'subtechniques' in attack_mapping:
+            sub_techniques_mapping = [sub_technique.value for sub_technique in attack_mapping['subtechniques']]
+            for st in sub_techniques_mapping:
+                try:
+                    sub_technique_obj = mitre_attack_data.get_objects_by_name(st, "attack-pattern")
+                    parent_technique_obj = mitre_attack_data.get_parent_technique_of_subtechnique(
+                        sub_technique_obj[0].id)
+                    sub_techniques[parent_technique_obj[0]['object'].name] = st
+                except Exception as e:
+                    os.system("echo 'Error in getting sub-techniques: {}'".format(e))
+                    continue
+
+        return AttackProfiler(techniques_tactics, mitigations, data_sources, sub_techniques, attacker_action_id)
+    
+    @staticmethod
+    def get_attack_profile_sequence(attacker_actions: List[EmulationAttackerAction],
+                                    attack_graph: Union[AttackGraph, None] = None) -> List['AttackProfiler']:
+        """
+        Returns the attack profile of the actions in a sequence
+
+        :params attacker_action: a list of attacker actions
+
+        :return: a list of attack profiles of the actions
+        """
+
+        attack_profiles = []
+        for action in attacker_actions:
+            attack_profiles.append(AttackProfiler.get_attack_profile(action))
+        
+        # IF attack graph is provided
+        if attack_graph:
+
+            node = attack_graph.get_root_node()
+            for profile in attack_profiles:
+                # Get the mappings of the techniques and tactics
+                techniques_tactics = profile.techniques_tactics
+                techniques_to_keep = []
+                children = attack_graph.get_children(node[0], node[2])
+                possible_nodes = []
+                # First we check the techniques in node we are currently at
+                for technique in techniques_tactics:
+                    # If the node.name is in the techniques_tactics, add it to the techniques_to_keep
+                    if node[0].value in techniques_tactics[technique]:
+                        techniques_to_keep.append(technique)
+                        if node not in possible_nodes:
+                            possible_nodes.append(node)
+                if children is None:
+                    continue
+                for child in children:
+                    # Child is a list of tuples, where the first element is the node name,
+                    # and the second element is the node id
+                    for technique in techniques_tactics:
+                        if child[0].value in techniques_tactics[technique]:
+                            
+                            techniques_to_keep.append(technique)
+                            # If the child is not in the possible_children, add it to the list.
+                            if attack_graph.get_node(child[0], child[1]) not in possible_nodes:
+                                p_node = attack_graph.get_node(child[0], child[1])
+                                if p_node is not None:
+                                    possible_nodes.append(p_node)
+
+                # If the possible node is just one node, move to that node
+                if len(possible_nodes) == 1:
+                    node = possible_nodes[0]
+                if not techniques_to_keep:
+                    continue
+                # Remove the techniques and associated tactics, data sources,
+                # mitigations and sub-techniques that are not in the techniques_to_keep
+                techniques_to_remove = set(profile.techniques_tactics.keys()) - set(techniques_to_keep)
+                for technique in techniques_to_remove:
+                    try:
+                        del profile.techniques_tactics[technique]
+                        del profile.mitigations[technique]
+                        del profile.data_sources[technique]
+                        del profile.subtechniques[technique]
+                    except Exception as e:
+                        os.system("echo 'Error in removing techniques: {}'".format(e))
+                        continue
+                            
+        # ELSE Baseline conditions
+        else:
+            initial_access = False
+            for profile in attack_profiles:
+                techniques_tactics = profile.techniques_tactics
+                techniques_to_remove = set()
+                # Loop over the mappings of the techniques to tactics
+                for technique in techniques_tactics:
+                    if Tactics.DISCOVERY.value in techniques_tactics[technique] and not initial_access:
+                        techniques_to_remove.add(technique)
+                    elif Tactics.RECONNAISSANCE.value in techniques_tactics[technique] and initial_access:
+                        techniques_to_remove.add(technique)
+                    if Tactics.INITIAL_ACCESS.value in techniques_tactics[technique] and not initial_access:
+                        initial_access = True
+                    elif Tactics.INITIAL_ACCESS.value in techniques_tactics[technique] and initial_access:
+                        techniques_to_remove.add(technique)
+                    elif Tactics.LATERAL_MOVEMENT.value in techniques_tactics[technique] and not initial_access:
+                        techniques_to_remove.add(technique)
+                
+                # Remove the techniques and associated tactics, data sources, mitigations and sub-techniques
+                for technique in techniques_to_remove:
+                    try:
+                        del profile.techniques_tactics[technique]
+                        del profile.mitigations[technique]
+                        del profile.data_sources[technique]
+                        del profile.subtechniques[technique]
+                    except Exception as e:
+                        os.system("echo 'Error in removing techniques: {}'".format(e))
+                        continue
+                
+        return attack_profiles