mal-simulator 1.2.0__tar.gz → 2.0.0__tar.gz
This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
- mal_simulator-2.0.0/PKG-INFO +131 -0
- mal_simulator-2.0.0/README.md +92 -0
- mal_simulator-2.0.0/mal_simulator.egg-info/PKG-INFO +131 -0
- mal_simulator-2.0.0/mal_simulator.egg-info/SOURCES.txt +71 -0
- mal_simulator-2.0.0/mal_simulator.egg-info/requires.txt +19 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/malsim/__init__.py +24 -15
- mal_simulator-2.0.0/malsim/__main__.py +68 -0
- mal_simulator-2.0.0/malsim/config/agent_settings.py +204 -0
- mal_simulator-2.0.0/malsim/config/node_property_rule.py +84 -0
- mal_simulator-2.0.0/malsim/config/sim_settings.py +76 -0
- mal_simulator-2.0.0/malsim/envs/__init__.py +18 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/malsim/envs/base_classes.py +7 -11
- mal_simulator-2.0.0/malsim/envs/graph/graph_env.py +337 -0
- mal_simulator-2.0.0/malsim/envs/graph/mal_spaces.py +949 -0
- mal_simulator-2.0.0/malsim/envs/graph/serialization.py +156 -0
- mal_simulator-2.0.0/malsim/envs/graph/utils.py +497 -0
- mal_simulator-2.0.0/malsim/envs/graph/wrapper.py +147 -0
- {mal_simulator-1.2.0/malsim/envs → mal_simulator-2.0.0/malsim/envs/legacy}/gym_envs.py +53 -60
- {mal_simulator-1.2.0/malsim/envs → mal_simulator-2.0.0/malsim/envs/legacy}/malsim_vectorized_obs_env.py +171 -195
- mal_simulator-2.0.0/malsim/mal_simulator/__init__.py +22 -0
- mal_simulator-2.0.0/malsim/mal_simulator/agent_state.py +32 -0
- mal_simulator-2.0.0/malsim/mal_simulator/attack_surface.py +93 -0
- mal_simulator-2.0.0/malsim/mal_simulator/attacker_state.py +84 -0
- mal_simulator-2.0.0/malsim/mal_simulator/attacker_state_factories.py +219 -0
- mal_simulator-2.0.0/malsim/mal_simulator/attacker_step.py +175 -0
- mal_simulator-2.0.0/malsim/mal_simulator/defender_state.py +59 -0
- mal_simulator-2.0.0/malsim/mal_simulator/defender_state_factories.py +131 -0
- mal_simulator-2.0.0/malsim/mal_simulator/defender_step.py +82 -0
- mal_simulator-2.0.0/malsim/mal_simulator/defense_surface.py +30 -0
- mal_simulator-2.0.0/malsim/mal_simulator/false_alerts.py +77 -0
- {mal_simulator-1.2.0/malsim → mal_simulator-2.0.0/malsim/mal_simulator}/graph_processing.py +69 -62
- mal_simulator-2.0.0/malsim/mal_simulator/graph_state.py +66 -0
- mal_simulator-2.0.0/malsim/mal_simulator/graph_utils.py +97 -0
- mal_simulator-2.0.0/malsim/mal_simulator/node_getters.py +46 -0
- mal_simulator-2.0.0/malsim/mal_simulator/observability.py +62 -0
- mal_simulator-2.0.0/malsim/mal_simulator/register_agent.py +163 -0
- mal_simulator-2.0.0/malsim/mal_simulator/reset_agent.py +105 -0
- mal_simulator-2.0.0/malsim/mal_simulator/rewards.py +74 -0
- mal_simulator-2.0.0/malsim/mal_simulator/run_simulation.py +60 -0
- mal_simulator-2.0.0/malsim/mal_simulator/simulator.py +731 -0
- mal_simulator-2.0.0/malsim/mal_simulator/simulator_state.py +51 -0
- mal_simulator-2.0.0/malsim/mal_simulator/state_query.py +72 -0
- {mal_simulator-1.2.0/malsim → mal_simulator-2.0.0/malsim/mal_simulator}/ttc_utils.py +165 -57
- mal_simulator-2.0.0/malsim/mal_simulator/types.py +14 -0
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/__init__.py +9 -8
- mal_simulator-2.0.0/malsim/policies/attackers/__init__.py +0 -0
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/attackers/searchers.py +9 -13
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/attackers/shortest_path.py +4 -4
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/attackers/ttc_soft_min.py +10 -7
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/decision_agent.py +2 -4
- mal_simulator-2.0.0/malsim/policies/defenders/__init__.py +0 -0
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/defenders/heuristic_agent.py +17 -32
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/keyboard_input.py +16 -20
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/passive_agent.py +3 -5
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/random_agent.py +2 -1
- {mal_simulator-1.2.0/malsim/agents → mal_simulator-2.0.0/malsim/policies}/utils/path_finding.py +27 -39
- mal_simulator-2.0.0/malsim/scenario/__init__.py +3 -0
- mal_simulator-2.0.0/malsim/scenario/scenario.py +260 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/malsim/visualization/malsim_gui_client.py +34 -63
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/pyproject.toml +45 -3
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/tests/test_graph_processing.py +47 -85
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/tests/test_main.py +10 -8
- mal_simulator-2.0.0/tests/test_mal_simulator.py +1554 -0
- mal_simulator-2.0.0/tests/test_scenario.py +565 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/tests/test_ttc_utils.py +109 -72
- mal_simulator-1.2.0/PKG-INFO +0 -613
- mal_simulator-1.2.0/README.md +0 -578
- mal_simulator-1.2.0/mal_simulator.egg-info/PKG-INFO +0 -613
- mal_simulator-1.2.0/mal_simulator.egg-info/SOURCES.txt +0 -38
- mal_simulator-1.2.0/mal_simulator.egg-info/requires.txt +0 -15
- mal_simulator-1.2.0/malsim/__main__.py +0 -67
- mal_simulator-1.2.0/malsim/envs/__init__.py +0 -10
- mal_simulator-1.2.0/malsim/mal_simulator.py +0 -1361
- mal_simulator-1.2.0/malsim/scenario.py +0 -600
- mal_simulator-1.2.0/tests/test_mal_simulator.py +0 -1223
- mal_simulator-1.2.0/tests/test_scenario.py +0 -485
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/AUTHORS +0 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/LICENSE +0 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/mal_simulator.egg-info/dependency_links.txt +0 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/mal_simulator.egg-info/entry_points.txt +0 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/mal_simulator.egg-info/top_level.txt +0 -0
- {mal_simulator-1.2.0/malsim/agents/attackers → mal_simulator-2.0.0/malsim/envs/graph}/__init__.py +0 -0
- {mal_simulator-1.2.0/malsim/agents/defenders → mal_simulator-2.0.0/malsim/envs/legacy}/__init__.py +0 -0
- {mal_simulator-1.2.0 → mal_simulator-2.0.0}/setup.cfg +0 -0
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mal-simulator
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: A MAL compliant simulator.
|
|
5
|
+
Author-email: Andrei Buhaiu <buhaiu@kth.se>, Joakim Loxdal <loxdal@kth.se>, Jakob Nyberg <jaknyb@kth.se>, Nikolaos Kakouros <nkak@kth.se>, Sandor Berglund <sandorb@kth.se>
|
|
6
|
+
License: Apache Software License
|
|
7
|
+
Project-URL: Homepage, https://github.com/mal-lang/mal-simulator
|
|
8
|
+
Project-URL: Bug Tracker, https://github.com/mal-lang/mal-simulator/issues
|
|
9
|
+
Project-URL: Repository, https://github.com/mal-lang/mal-simulator
|
|
10
|
+
Keywords: mal
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
License-File: AUTHORS
|
|
21
|
+
Requires-Dist: mal-toolbox<3.0.0,>=2.0.0
|
|
22
|
+
Requires-Dist: PyYAML>=6.0.1
|
|
23
|
+
Requires-Dist: numpy>=1.21.4
|
|
24
|
+
Requires-Dist: scipy
|
|
25
|
+
Requires-Dist: networkx
|
|
26
|
+
Requires-Dist: requests
|
|
27
|
+
Provides-Extra: ml
|
|
28
|
+
Requires-Dist: pettingzoo>=1.24.2; extra == "ml"
|
|
29
|
+
Requires-Dist: gymnasium<1.2.2,>=1.0; extra == "ml"
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest; extra == "dev"
|
|
32
|
+
Requires-Dist: mypy; extra == "dev"
|
|
33
|
+
Requires-Dist: ruff; extra == "dev"
|
|
34
|
+
Requires-Dist: types-requests; extra == "dev"
|
|
35
|
+
Requires-Dist: types-PyYAML; extra == "dev"
|
|
36
|
+
Requires-Dist: pytest-profiling; extra == "dev"
|
|
37
|
+
Requires-Dist: snakeviz; extra == "dev"
|
|
38
|
+
Dynamic: license-file
|
|
39
|
+
|
|
40
|
+
# MAL Simulator
|
|
41
|
+
|
|
42
|
+
## Overview
|
|
43
|
+
|
|
44
|
+
The **MAL Simulator** is a tool designed for running simulations on systems modeled in the **Modeling Attack Language (MAL)**.
|
|
45
|
+
|
|
46
|
+
It allows you to:
|
|
47
|
+
* Simulate the adversarial and defensive actions of intelligent agents (attackers and defenders).
|
|
48
|
+
* Analyze system security and evaluate attack/defense strategies.
|
|
49
|
+
* Develop machine learning agents (e.g., using Reinforcement Learning) in a safe, dynamic environment.
|
|
50
|
+
* Incorporate stochastic modeling through Time-to-Compromise (TTC) distributions.
|
|
51
|
+
|
|
52
|
+
For in-depth documentation please refer to the official **[Wiki](https://github.com/mal-lang/mal-simulator/wiki)**.
|
|
53
|
+
|
|
54
|
+
## Contributing
|
|
55
|
+
|
|
56
|
+
- Use [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
|
|
57
|
+
- The CI pipeline runs `mypy` and `ruff` for linting and type checking, and PRs will only be merged if pipeline succeeds.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 🛠️ How to Run a Simulation
|
|
62
|
+
|
|
63
|
+
### 1. Installation
|
|
64
|
+
|
|
65
|
+
```pip install mal-simulator```
|
|
66
|
+
|
|
67
|
+
To also get ML dependencies (pettingzoo, gymnasium):
|
|
68
|
+
|
|
69
|
+
```pip install mal-simulator[ml]```
|
|
70
|
+
|
|
71
|
+
For additional dev tools:
|
|
72
|
+
|
|
73
|
+
```pip install mal-simulator[dev]```
|
|
74
|
+
|
|
75
|
+
### 2. Running a Scenario via CLI
|
|
76
|
+
|
|
77
|
+
You can execute a simulation using a YAML scenario file, which defines the MAL model, the agents (attackers and defenders), their policies, and their goals.
|
|
78
|
+
|
|
79
|
+
The basic command structure is:
|
|
80
|
+
|
|
81
|
+
```malsim <scenario_file> [options]```
|
|
82
|
+
|
|
83
|
+
#### Example
|
|
84
|
+
|
|
85
|
+
Execute a simulation defined in ```my_scenario.yml```:
|
|
86
|
+
|
|
87
|
+
```malsim my_scenario.yml```
|
|
88
|
+
|
|
89
|
+
#### Common Options:
|
|
90
|
+
|
|
91
|
+
| Option | Description |
|
|
92
|
+
| :--- | :--- |
|
|
93
|
+
| `-s, --seed SEED` | Sets the random seed for deterministic simulations. |
|
|
94
|
+
| `-t, --ttc-mode MODE` | Sets the Time-to-Compromise mode (e.g., `DISABLED`, `PER_STEP_SAMPLE`). |
|
|
95
|
+
| `-g, --send-to-gui` | Sends simulation data to the `malsim-gui` for visualization (requires the GUI to be running). |
|
|
96
|
+
|
|
97
|
+
### 3. Programmatic Usage
|
|
98
|
+
|
|
99
|
+
For advanced and customized simulations (e.g., integrating with a custom ML training loop), you can initialize and run the simulator directly in a Python script:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
from malsim import MalSimulator, run_simulation, Scenario
|
|
103
|
+
|
|
104
|
+
# 1. Load the scenario configuration
|
|
105
|
+
SCENARIO_FILE = "my_scenario.yml"
|
|
106
|
+
scenario = Scenario.load_from_file(SCENARIO_FILE)
|
|
107
|
+
|
|
108
|
+
# 2. Create the simulator instance
|
|
109
|
+
sim = MalSimulator.from_scenario(scenario)
|
|
110
|
+
|
|
111
|
+
# 3. Run the simulation
|
|
112
|
+
agent_actions = run_simulation(sim, scenario.agents)
|
|
113
|
+
|
|
114
|
+
print("Simulation finished. Agent actions:", agent_actions)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
You can also run your own simulation loop.
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
from malsim import MalSimulator, Scenario
|
|
121
|
+
|
|
122
|
+
scenario = Scenario.load_from_file("my_scenario.yml")
|
|
123
|
+
sim = MalSimulator.from_scenario(scenario)
|
|
124
|
+
agent_states = sim.reset()
|
|
125
|
+
|
|
126
|
+
while not sim.done():
|
|
127
|
+
# ... calculate actions for each agent
|
|
128
|
+
agent_states = sim.step(actions)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Read the [Wiki](https://github.com/mal-lang/mal-simulator/wiki) for more ways to run the simulator.
|
|
@@ -0,0 +1,92 @@
|
|
|
1
|
+
# MAL Simulator
|
|
2
|
+
|
|
3
|
+
## Overview
|
|
4
|
+
|
|
5
|
+
The **MAL Simulator** is a tool designed for running simulations on systems modeled in the **Modeling Attack Language (MAL)**.
|
|
6
|
+
|
|
7
|
+
It allows you to:
|
|
8
|
+
* Simulate the adversarial and defensive actions of intelligent agents (attackers and defenders).
|
|
9
|
+
* Analyze system security and evaluate attack/defense strategies.
|
|
10
|
+
* Develop machine learning agents (e.g., using Reinforcement Learning) in a safe, dynamic environment.
|
|
11
|
+
* Incorporate stochastic modeling through Time-to-Compromise (TTC) distributions.
|
|
12
|
+
|
|
13
|
+
For in-depth documentation please refer to the official **[Wiki](https://github.com/mal-lang/mal-simulator/wiki)**.
|
|
14
|
+
|
|
15
|
+
## Contributing
|
|
16
|
+
|
|
17
|
+
- Use [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
|
|
18
|
+
- The CI pipeline runs `mypy` and `ruff` for linting and type checking, and PRs will only be merged if pipeline succeeds.
|
|
19
|
+
|
|
20
|
+
---
|
|
21
|
+
|
|
22
|
+
## 🛠️ How to Run a Simulation
|
|
23
|
+
|
|
24
|
+
### 1. Installation
|
|
25
|
+
|
|
26
|
+
```pip install mal-simulator```
|
|
27
|
+
|
|
28
|
+
To also get ML dependencies (pettingzoo, gymnasium):
|
|
29
|
+
|
|
30
|
+
```pip install mal-simulator[ml]```
|
|
31
|
+
|
|
32
|
+
For additional dev tools:
|
|
33
|
+
|
|
34
|
+
```pip install mal-simulator[dev]```
|
|
35
|
+
|
|
36
|
+
### 2. Running a Scenario via CLI
|
|
37
|
+
|
|
38
|
+
You can execute a simulation using a YAML scenario file, which defines the MAL model, the agents (attackers and defenders), their policies, and their goals.
|
|
39
|
+
|
|
40
|
+
The basic command structure is:
|
|
41
|
+
|
|
42
|
+
```malsim <scenario_file> [options]```
|
|
43
|
+
|
|
44
|
+
#### Example
|
|
45
|
+
|
|
46
|
+
Execute a simulation defined in ```my_scenario.yml```:
|
|
47
|
+
|
|
48
|
+
```malsim my_scenario.yml```
|
|
49
|
+
|
|
50
|
+
#### Common Options:
|
|
51
|
+
|
|
52
|
+
| Option | Description |
|
|
53
|
+
| :--- | :--- |
|
|
54
|
+
| `-s, --seed SEED` | Sets the random seed for deterministic simulations. |
|
|
55
|
+
| `-t, --ttc-mode MODE` | Sets the Time-to-Compromise mode (e.g., `DISABLED`, `PER_STEP_SAMPLE`). |
|
|
56
|
+
| `-g, --send-to-gui` | Sends simulation data to the `malsim-gui` for visualization (requires the GUI to be running). |
|
|
57
|
+
|
|
58
|
+
### 3. Programmatic Usage
|
|
59
|
+
|
|
60
|
+
For advanced and customized simulations (e.g., integrating with a custom ML training loop), you can initialize and run the simulator directly in a Python script:
|
|
61
|
+
|
|
62
|
+
```
|
|
63
|
+
from malsim import MalSimulator, run_simulation, Scenario
|
|
64
|
+
|
|
65
|
+
# 1. Load the scenario configuration
|
|
66
|
+
SCENARIO_FILE = "my_scenario.yml"
|
|
67
|
+
scenario = Scenario.load_from_file(SCENARIO_FILE)
|
|
68
|
+
|
|
69
|
+
# 2. Create the simulator instance
|
|
70
|
+
sim = MalSimulator.from_scenario(scenario)
|
|
71
|
+
|
|
72
|
+
# 3. Run the simulation
|
|
73
|
+
agent_actions = run_simulation(sim, scenario.agents)
|
|
74
|
+
|
|
75
|
+
print("Simulation finished. Agent actions:", agent_actions)
|
|
76
|
+
```
|
|
77
|
+
|
|
78
|
+
You can also run your own simulation loop.
|
|
79
|
+
|
|
80
|
+
```
|
|
81
|
+
from malsim import MalSimulator, Scenario
|
|
82
|
+
|
|
83
|
+
scenario = Scenario.load_from_file("my_scenario.yml")
|
|
84
|
+
sim = MalSimulator.from_scenario(scenario)
|
|
85
|
+
agent_states = sim.reset()
|
|
86
|
+
|
|
87
|
+
while not sim.done():
|
|
88
|
+
# ... calculate actions for each agent
|
|
89
|
+
agent_states = sim.step(actions)
|
|
90
|
+
```
|
|
91
|
+
|
|
92
|
+
Read the [Wiki](https://github.com/mal-lang/mal-simulator/wiki) for more ways to run the simulator.
|
|
@@ -0,0 +1,131 @@
|
|
|
1
|
+
Metadata-Version: 2.4
|
|
2
|
+
Name: mal-simulator
|
|
3
|
+
Version: 2.0.0
|
|
4
|
+
Summary: A MAL compliant simulator.
|
|
5
|
+
Author-email: Andrei Buhaiu <buhaiu@kth.se>, Joakim Loxdal <loxdal@kth.se>, Jakob Nyberg <jaknyb@kth.se>, Nikolaos Kakouros <nkak@kth.se>, Sandor Berglund <sandorb@kth.se>
|
|
6
|
+
License: Apache Software License
|
|
7
|
+
Project-URL: Homepage, https://github.com/mal-lang/mal-simulator
|
|
8
|
+
Project-URL: Bug Tracker, https://github.com/mal-lang/mal-simulator/issues
|
|
9
|
+
Project-URL: Repository, https://github.com/mal-lang/mal-simulator
|
|
10
|
+
Keywords: mal
|
|
11
|
+
Classifier: Development Status :: 3 - Alpha
|
|
12
|
+
Classifier: Intended Audience :: Science/Research
|
|
13
|
+
Classifier: Programming Language :: Python :: 3
|
|
14
|
+
Classifier: License :: OSI Approved :: Apache Software License
|
|
15
|
+
Classifier: Operating System :: OS Independent
|
|
16
|
+
Classifier: Topic :: Scientific/Engineering
|
|
17
|
+
Requires-Python: >=3.10
|
|
18
|
+
Description-Content-Type: text/markdown
|
|
19
|
+
License-File: LICENSE
|
|
20
|
+
License-File: AUTHORS
|
|
21
|
+
Requires-Dist: mal-toolbox<3.0.0,>=2.0.0
|
|
22
|
+
Requires-Dist: PyYAML>=6.0.1
|
|
23
|
+
Requires-Dist: numpy>=1.21.4
|
|
24
|
+
Requires-Dist: scipy
|
|
25
|
+
Requires-Dist: networkx
|
|
26
|
+
Requires-Dist: requests
|
|
27
|
+
Provides-Extra: ml
|
|
28
|
+
Requires-Dist: pettingzoo>=1.24.2; extra == "ml"
|
|
29
|
+
Requires-Dist: gymnasium<1.2.2,>=1.0; extra == "ml"
|
|
30
|
+
Provides-Extra: dev
|
|
31
|
+
Requires-Dist: pytest; extra == "dev"
|
|
32
|
+
Requires-Dist: mypy; extra == "dev"
|
|
33
|
+
Requires-Dist: ruff; extra == "dev"
|
|
34
|
+
Requires-Dist: types-requests; extra == "dev"
|
|
35
|
+
Requires-Dist: types-PyYAML; extra == "dev"
|
|
36
|
+
Requires-Dist: pytest-profiling; extra == "dev"
|
|
37
|
+
Requires-Dist: snakeviz; extra == "dev"
|
|
38
|
+
Dynamic: license-file
|
|
39
|
+
|
|
40
|
+
# MAL Simulator
|
|
41
|
+
|
|
42
|
+
## Overview
|
|
43
|
+
|
|
44
|
+
The **MAL Simulator** is a tool designed for running simulations on systems modeled in the **Modeling Attack Language (MAL)**.
|
|
45
|
+
|
|
46
|
+
It allows you to:
|
|
47
|
+
* Simulate the adversarial and defensive actions of intelligent agents (attackers and defenders).
|
|
48
|
+
* Analyze system security and evaluate attack/defense strategies.
|
|
49
|
+
* Develop machine learning agents (e.g., using Reinforcement Learning) in a safe, dynamic environment.
|
|
50
|
+
* Incorporate stochastic modeling through Time-to-Compromise (TTC) distributions.
|
|
51
|
+
|
|
52
|
+
For in-depth documentation please refer to the official **[Wiki](https://github.com/mal-lang/mal-simulator/wiki)**.
|
|
53
|
+
|
|
54
|
+
## Contributing
|
|
55
|
+
|
|
56
|
+
- Use [Conventional commits](https://www.conventionalcommits.org/en/v1.0.0/)
|
|
57
|
+
- The CI pipeline runs `mypy` and `ruff` for linting and type checking, and PRs will only be merged if pipeline succeeds.
|
|
58
|
+
|
|
59
|
+
---
|
|
60
|
+
|
|
61
|
+
## 🛠️ How to Run a Simulation
|
|
62
|
+
|
|
63
|
+
### 1. Installation
|
|
64
|
+
|
|
65
|
+
```pip install mal-simulator```
|
|
66
|
+
|
|
67
|
+
To also get ML dependencies (pettingzoo, gymnasium):
|
|
68
|
+
|
|
69
|
+
```pip install mal-simulator[ml]```
|
|
70
|
+
|
|
71
|
+
For additional dev tools:
|
|
72
|
+
|
|
73
|
+
```pip install mal-simulator[dev]```
|
|
74
|
+
|
|
75
|
+
### 2. Running a Scenario via CLI
|
|
76
|
+
|
|
77
|
+
You can execute a simulation using a YAML scenario file, which defines the MAL model, the agents (attackers and defenders), their policies, and their goals.
|
|
78
|
+
|
|
79
|
+
The basic command structure is:
|
|
80
|
+
|
|
81
|
+
```malsim <scenario_file> [options]```
|
|
82
|
+
|
|
83
|
+
#### Example
|
|
84
|
+
|
|
85
|
+
Execute a simulation defined in ```my_scenario.yml```:
|
|
86
|
+
|
|
87
|
+
```malsim my_scenario.yml```
|
|
88
|
+
|
|
89
|
+
#### Common Options:
|
|
90
|
+
|
|
91
|
+
| Option | Description |
|
|
92
|
+
| :--- | :--- |
|
|
93
|
+
| `-s, --seed SEED` | Sets the random seed for deterministic simulations. |
|
|
94
|
+
| `-t, --ttc-mode MODE` | Sets the Time-to-Compromise mode (e.g., `DISABLED`, `PER_STEP_SAMPLE`). |
|
|
95
|
+
| `-g, --send-to-gui` | Sends simulation data to the `malsim-gui` for visualization (requires the GUI to be running). |
|
|
96
|
+
|
|
97
|
+
### 3. Programmatic Usage
|
|
98
|
+
|
|
99
|
+
For advanced and customized simulations (e.g., integrating with a custom ML training loop), you can initialize and run the simulator directly in a Python script:
|
|
100
|
+
|
|
101
|
+
```
|
|
102
|
+
from malsim import MalSimulator, run_simulation, Scenario
|
|
103
|
+
|
|
104
|
+
# 1. Load the scenario configuration
|
|
105
|
+
SCENARIO_FILE = "my_scenario.yml"
|
|
106
|
+
scenario = Scenario.load_from_file(SCENARIO_FILE)
|
|
107
|
+
|
|
108
|
+
# 2. Create the simulator instance
|
|
109
|
+
sim = MalSimulator.from_scenario(scenario)
|
|
110
|
+
|
|
111
|
+
# 3. Run the simulation
|
|
112
|
+
agent_actions = run_simulation(sim, scenario.agents)
|
|
113
|
+
|
|
114
|
+
print("Simulation finished. Agent actions:", agent_actions)
|
|
115
|
+
```
|
|
116
|
+
|
|
117
|
+
You can also run your own simulation loop.
|
|
118
|
+
|
|
119
|
+
```
|
|
120
|
+
from malsim import MalSimulator, Scenario
|
|
121
|
+
|
|
122
|
+
scenario = Scenario.load_from_file("my_scenario.yml")
|
|
123
|
+
sim = MalSimulator.from_scenario(scenario)
|
|
124
|
+
agent_states = sim.reset()
|
|
125
|
+
|
|
126
|
+
while not sim.done():
|
|
127
|
+
# ... calculate actions for each agent
|
|
128
|
+
agent_states = sim.step(actions)
|
|
129
|
+
```
|
|
130
|
+
|
|
131
|
+
Read the [Wiki](https://github.com/mal-lang/mal-simulator/wiki) for more ways to run the simulator.
|
|
@@ -0,0 +1,71 @@
|
|
|
1
|
+
AUTHORS
|
|
2
|
+
LICENSE
|
|
3
|
+
README.md
|
|
4
|
+
pyproject.toml
|
|
5
|
+
mal_simulator.egg-info/PKG-INFO
|
|
6
|
+
mal_simulator.egg-info/SOURCES.txt
|
|
7
|
+
mal_simulator.egg-info/dependency_links.txt
|
|
8
|
+
mal_simulator.egg-info/entry_points.txt
|
|
9
|
+
mal_simulator.egg-info/requires.txt
|
|
10
|
+
mal_simulator.egg-info/top_level.txt
|
|
11
|
+
malsim/__init__.py
|
|
12
|
+
malsim/__main__.py
|
|
13
|
+
malsim/config/agent_settings.py
|
|
14
|
+
malsim/config/node_property_rule.py
|
|
15
|
+
malsim/config/sim_settings.py
|
|
16
|
+
malsim/envs/__init__.py
|
|
17
|
+
malsim/envs/base_classes.py
|
|
18
|
+
malsim/envs/graph/__init__.py
|
|
19
|
+
malsim/envs/graph/graph_env.py
|
|
20
|
+
malsim/envs/graph/mal_spaces.py
|
|
21
|
+
malsim/envs/graph/serialization.py
|
|
22
|
+
malsim/envs/graph/utils.py
|
|
23
|
+
malsim/envs/graph/wrapper.py
|
|
24
|
+
malsim/envs/legacy/__init__.py
|
|
25
|
+
malsim/envs/legacy/gym_envs.py
|
|
26
|
+
malsim/envs/legacy/malsim_vectorized_obs_env.py
|
|
27
|
+
malsim/mal_simulator/__init__.py
|
|
28
|
+
malsim/mal_simulator/agent_state.py
|
|
29
|
+
malsim/mal_simulator/attack_surface.py
|
|
30
|
+
malsim/mal_simulator/attacker_state.py
|
|
31
|
+
malsim/mal_simulator/attacker_state_factories.py
|
|
32
|
+
malsim/mal_simulator/attacker_step.py
|
|
33
|
+
malsim/mal_simulator/defender_state.py
|
|
34
|
+
malsim/mal_simulator/defender_state_factories.py
|
|
35
|
+
malsim/mal_simulator/defender_step.py
|
|
36
|
+
malsim/mal_simulator/defense_surface.py
|
|
37
|
+
malsim/mal_simulator/false_alerts.py
|
|
38
|
+
malsim/mal_simulator/graph_processing.py
|
|
39
|
+
malsim/mal_simulator/graph_state.py
|
|
40
|
+
malsim/mal_simulator/graph_utils.py
|
|
41
|
+
malsim/mal_simulator/node_getters.py
|
|
42
|
+
malsim/mal_simulator/observability.py
|
|
43
|
+
malsim/mal_simulator/register_agent.py
|
|
44
|
+
malsim/mal_simulator/reset_agent.py
|
|
45
|
+
malsim/mal_simulator/rewards.py
|
|
46
|
+
malsim/mal_simulator/run_simulation.py
|
|
47
|
+
malsim/mal_simulator/simulator.py
|
|
48
|
+
malsim/mal_simulator/simulator_state.py
|
|
49
|
+
malsim/mal_simulator/state_query.py
|
|
50
|
+
malsim/mal_simulator/ttc_utils.py
|
|
51
|
+
malsim/mal_simulator/types.py
|
|
52
|
+
malsim/policies/__init__.py
|
|
53
|
+
malsim/policies/decision_agent.py
|
|
54
|
+
malsim/policies/keyboard_input.py
|
|
55
|
+
malsim/policies/passive_agent.py
|
|
56
|
+
malsim/policies/random_agent.py
|
|
57
|
+
malsim/policies/attackers/__init__.py
|
|
58
|
+
malsim/policies/attackers/searchers.py
|
|
59
|
+
malsim/policies/attackers/shortest_path.py
|
|
60
|
+
malsim/policies/attackers/ttc_soft_min.py
|
|
61
|
+
malsim/policies/defenders/__init__.py
|
|
62
|
+
malsim/policies/defenders/heuristic_agent.py
|
|
63
|
+
malsim/policies/utils/path_finding.py
|
|
64
|
+
malsim/scenario/__init__.py
|
|
65
|
+
malsim/scenario/scenario.py
|
|
66
|
+
malsim/visualization/malsim_gui_client.py
|
|
67
|
+
tests/test_graph_processing.py
|
|
68
|
+
tests/test_main.py
|
|
69
|
+
tests/test_mal_simulator.py
|
|
70
|
+
tests/test_scenario.py
|
|
71
|
+
tests/test_ttc_utils.py
|
|
@@ -0,0 +1,19 @@
|
|
|
1
|
+
mal-toolbox<3.0.0,>=2.0.0
|
|
2
|
+
PyYAML>=6.0.1
|
|
3
|
+
numpy>=1.21.4
|
|
4
|
+
scipy
|
|
5
|
+
networkx
|
|
6
|
+
requests
|
|
7
|
+
|
|
8
|
+
[dev]
|
|
9
|
+
pytest
|
|
10
|
+
mypy
|
|
11
|
+
ruff
|
|
12
|
+
types-requests
|
|
13
|
+
types-PyYAML
|
|
14
|
+
pytest-profiling
|
|
15
|
+
snakeviz
|
|
16
|
+
|
|
17
|
+
[ml]
|
|
18
|
+
pettingzoo>=1.24.2
|
|
19
|
+
gymnasium<1.2.2,>=1.0
|
|
@@ -1,5 +1,5 @@
|
|
|
1
1
|
# -*- encoding: utf-8 -*-
|
|
2
|
-
# MAL Simulator
|
|
2
|
+
# MAL Simulator v2.0.0
|
|
3
3
|
# Copyright 2025, Andrei Buhaiu.
|
|
4
4
|
#
|
|
5
5
|
# Licensed under the Apache License, Version 2.0 (the "License");
|
|
@@ -23,21 +23,30 @@ from malsim.mal_simulator import (
|
|
|
23
23
|
run_simulation,
|
|
24
24
|
)
|
|
25
25
|
|
|
26
|
-
from malsim.scenario import
|
|
27
|
-
|
|
26
|
+
from malsim.scenario.scenario import Scenario
|
|
27
|
+
from malsim.config.agent_settings import AttackerSettings, DefenderSettings
|
|
28
|
+
|
|
29
|
+
__title__ = 'malsim'
|
|
30
|
+
__version__ = '2.0.0'
|
|
31
|
+
__authors__ = ['Andrei Buhaiu', 'Joakim Loxdal', 'Jakob Nyberg', 'Nikolaos Kakouros']
|
|
32
|
+
__license__ = 'Apache 2.0'
|
|
33
|
+
__docformat__ = 'restructuredtext en'
|
|
34
|
+
|
|
35
|
+
__all__ = [
|
|
36
|
+
'AttackerSettings',
|
|
37
|
+
'DefenderSettings',
|
|
38
|
+
'MalSimulator',
|
|
39
|
+
'MalSimulatorSettings',
|
|
40
|
+
'Scenario',
|
|
41
|
+
'run_simulation',
|
|
42
|
+
]
|
|
43
|
+
|
|
44
|
+
|
|
45
|
+
# TODO: Make sure logging dir exists and make it configurable
|
|
46
|
+
# (or use same as maltoolbox)
|
|
47
|
+
formatter = logging.Formatter(
|
|
48
|
+
'%(asctime)s %(name)-12s %(levelname)-8s %(message)s', datefmt='%m-%d %H:%M'
|
|
28
49
|
)
|
|
29
|
-
|
|
30
|
-
__title__ = "malsim"
|
|
31
|
-
__version__ = "1.2.0"
|
|
32
|
-
__authors__ = ["Andrei Buhaiu", "Joakim Loxdal", "Jakob Nyberg", "Nikolaos Kakouros"]
|
|
33
|
-
__license__ = "Apache 2.0"
|
|
34
|
-
__docformat__ = "restructuredtext en"
|
|
35
|
-
|
|
36
|
-
__all__ = ["MalSimulator", "MalSimulatorSettings", "run_simulation", "load_scenario"]
|
|
37
|
-
|
|
38
|
-
|
|
39
|
-
# TODO: Make sure logging dir exists and make it configurable (or use same as maltoolbox)
|
|
40
|
-
formatter = logging.Formatter('%(asctime)s %(name)-12s %(levelname)-8s %(message)s', datefmt='%m-%d %H:%M')
|
|
41
50
|
file_handler = logging.FileHandler('logs/malsim_log.txt', mode='w')
|
|
42
51
|
file_handler.setFormatter(formatter)
|
|
43
52
|
|
|
@@ -0,0 +1,68 @@
|
|
|
1
|
+
"""CLI to run simulations in MAL Simulator using scenario files"""
|
|
2
|
+
|
|
3
|
+
from __future__ import annotations
|
|
4
|
+
import argparse
|
|
5
|
+
import logging
|
|
6
|
+
|
|
7
|
+
from .mal_simulator import MalSimulator, MalSimulatorSettings, run_simulation, TTCMode
|
|
8
|
+
from .scenario.scenario import Scenario
|
|
9
|
+
|
|
10
|
+
logging.basicConfig(level=logging.INFO)
|
|
11
|
+
logger = logging.getLogger(__name__)
|
|
12
|
+
logging.getLogger().setLevel(logging.INFO)
|
|
13
|
+
|
|
14
|
+
|
|
15
|
+
def main() -> None:
|
|
16
|
+
"""Entrypoint function of the MAL Toolbox CLI"""
|
|
17
|
+
parser = argparse.ArgumentParser()
|
|
18
|
+
parser.add_argument(
|
|
19
|
+
'scenario_file',
|
|
20
|
+
type=str,
|
|
21
|
+
help='Can be found in https://github.com/mal-lang/malsim-scenarios/',
|
|
22
|
+
)
|
|
23
|
+
parser.add_argument(
|
|
24
|
+
'-o',
|
|
25
|
+
'--output-attack-graph',
|
|
26
|
+
type=str,
|
|
27
|
+
help='If set to a path, attack graph will be dumped there',
|
|
28
|
+
)
|
|
29
|
+
parser.add_argument(
|
|
30
|
+
'-s',
|
|
31
|
+
'--seed',
|
|
32
|
+
type=int,
|
|
33
|
+
help='If set to a seed, simulator will use it as setting',
|
|
34
|
+
)
|
|
35
|
+
parser.add_argument(
|
|
36
|
+
'-t',
|
|
37
|
+
'--ttc-mode',
|
|
38
|
+
type=int,
|
|
39
|
+
help=('\t\n'.join([f'{e.value}: {e.name}' for e in TTCMode])),
|
|
40
|
+
default=TTCMode.DISABLED.value,
|
|
41
|
+
)
|
|
42
|
+
parser.add_argument(
|
|
43
|
+
'-g',
|
|
44
|
+
'--send-to-gui',
|
|
45
|
+
action='store_true',
|
|
46
|
+
default=False,
|
|
47
|
+
help='If set, simulator will send actions to malsim-gui',
|
|
48
|
+
)
|
|
49
|
+
args = parser.parse_args()
|
|
50
|
+
scenario = Scenario.load_from_file(args.scenario_file)
|
|
51
|
+
sim = MalSimulator.from_scenario(
|
|
52
|
+
scenario,
|
|
53
|
+
MalSimulatorSettings(
|
|
54
|
+
seed=args.seed,
|
|
55
|
+
ttc_mode=TTCMode(args.ttc_mode),
|
|
56
|
+
attack_surface_skip_unnecessary=False,
|
|
57
|
+
),
|
|
58
|
+
send_to_api=args.send_to_gui,
|
|
59
|
+
)
|
|
60
|
+
|
|
61
|
+
if args.output_attack_graph:
|
|
62
|
+
sim.sim_state.attack_graph.save_to_file(args.output_attack_graph)
|
|
63
|
+
|
|
64
|
+
run_simulation(sim, scenario.agent_settings)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
if __name__ == '__main__':
|
|
68
|
+
main()
|