| Name | mal-simulator JSON |
| Version |
0.0.38
JSON |
| download |
| home_page | None |
| Summary | A MAL compliant simulator. |
| upload_time | 2024-11-06 14:27:49 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.10 |
| license | Apache Software License |
| keywords |
mal
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# MAL Simulator
## Overview
A MAL compliant simulator.
## Installation
```pip install mal-simulator```
## MalSimulator
A `sims.mal_simulator.MalSimulator` can be created to be able to run simulations.
### MalSimulatorSettings
The constructor of MalSimulator can be given a settings object (`sims.mal_simulator.MalSimulatorSettings`)
through the parameter 'sim_settings'. Giving sim_settings is optional, otherwise default settings are used.
```python
settings = MalSimulatorSettings(
uncompromise_untraversable_steps=True, # default is False
cumulative_defender_obs=False # default is True
)
sim = MalSimulator(lang_graph, model, attack_graph, sim_settings=settings)
```
## Scenarios
To make it easier to define simulation environment you can use scenarios defined in yml-files.
Scenarios consist of MAL language, model, rewards, agent classes and attacker entrypoints,
they are a setup for running a simulation. This is how the format looks like:
```yml
lang_file: <path to .mar-archive>
model_file: <path to json/yml model>
attacker_agent_class: 'BreadthFirstAttacker' | 'DepthFirstAttacker' | 'KeyboardAgent'
# For defender_agent_class, null and False are treated the same - no defender will be used in the simulation
defender_agent_class: 'BreadthFirstAttacker' | 'DepthFirstAttacker' | 'KeyboardAgent' | null | False
# Optionally add rewards for each attack step
rewards:
<full name of attack step>: <reward>
# example:
# Program 1:notPresent: 3
# Data A:read: 100
...
# Optionally add entry points to AttackGraph with attacker name and attack step full_names.
# NOTE: If attacker entry points defined in both model and scenario,
# the scenario overrides the ones in the model.
attacker_entry_points:
<attacker name>:
- <attack step full name>
# example:
# 'Attacker1':
# - 'Credentials:6:attemptCredentialsReuse'
# Optionally add observability rules that are applied to AttackGrapNodes
# to make only certain steps observable
#
# If 'observable_steps' are set:
# - Nodes that match any rule will be marked as observable
# - Nodes that don't match any rules will be marked as non-observable
# If 'observable_steps' are not set:
# - All nodes will be marked as observable
#
observable_steps:
by_asset_type:
<asset_type>:
- <step name>
by_asset_name:
<asset_name>:
- <step name>
# Optionally add actionability rules that are applied to AttackGrapNodes
# to make only certain steps actionable
# Works exactly as observability
#
actionable_steps:
by_asset_type:
<asset_type>:
- <step name>
by_asset_name:
<asset_name>:
- <step name>
# Example:
# by_asset_type:
# Host:
# - access
# - authenticate
# Data:
# - read
# by_asset_name:
# User:3:
# - phishing
# ...
```
Note: When defining attackers and entrypoints in a scenario, these override potential attackers in the model.
### Loading a scenario from a python script
#### Load attack graph and config
If you just want to load a resulting attack graph from a scenario, use `malsim.scenarios.load_scenario`.
```python
from malsim.scenarios import load_scenario
scenario_file = "scenario.yml"
attack_graph, sim_config = load_scenario(scenario_file)
```
#### Load simulator and config
If you instead want to load a simulator, use `malsim.scenarios.create_simulator_from_scenario`.
```python
from malsim.scenarios import create_simulator_from_scenario
scenario_file = "scenario.yml"
mal_simulator, sim_config = create_simulator_from_scenario(scenario_file)
```
The returned MalSimulator contains the attackgraph created from
the scenario, as well as registered agents. At this point, simulator and sim_config
(which contains the agent classes) can be used for running a simulation
(refer to malsim.cli.run_simulation or wrappers.gym_wrappers to see example of this).
## CLI
### Running a scenario simulation with the CLI
```
usage: malsim [-h] [-o OUTPUT_ATTACK_GRAPH] scenario_file
positional arguments:
scenario_file Can be found in https://github.com/mal-lang/malsim-scenarios/
options:
-h, --help show this help message and exit
-o OUTPUT_ATTACK_GRAPH, --output-attack-graph OUTPUT_ATTACK_GRAPH
If set to a path, attack graph will be dumped there
```
This will create an attack using the configuration in the scenarios file, apply the rewards, add the attacker and run the simulation with the attacker.
Currently having more than one attacker in the scenario file will have no effect to how the simulation is run, it will only run the first one as an agent.
Raw data
{
"_id": null,
"home_page": null,
"name": "mal-simulator",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.10",
"maintainer_email": null,
"keywords": "mal",
"author": null,
"author_email": "Andrei Buhaiu <buhaiu@kth.se>, Joakim Loxdal <loxdal@kth.se>, Jakob Nyberg <jaknyb@kth.se>, Nikolaos Kakouros <nkak@kth.se>",
"download_url": "https://files.pythonhosted.org/packages/80/c2/af8bf06004df3ef3e57cdd6f2668d9de0a75435bf10444d2ff1b85e0db71/mal_simulator-0.0.38.tar.gz",
"platform": null,
"description": "# MAL Simulator\n\n## Overview\n\nA MAL compliant simulator.\n\n## Installation\n```pip install mal-simulator```\n\n## MalSimulator\n\nA `sims.mal_simulator.MalSimulator` can be created to be able to run simulations.\n\n### MalSimulatorSettings\nThe constructor of MalSimulator can be given a settings object (`sims.mal_simulator.MalSimulatorSettings`)\nthrough the parameter 'sim_settings'. Giving sim_settings is optional, otherwise default settings are used.\n\n```python\n\nsettings = MalSimulatorSettings(\n uncompromise_untraversable_steps=True, # default is False\n cumulative_defender_obs=False # default is True\n)\nsim = MalSimulator(lang_graph, model, attack_graph, sim_settings=settings)\n\n```\n\n## Scenarios\n\nTo make it easier to define simulation environment you can use scenarios defined in yml-files.\nScenarios consist of MAL language, model, rewards, agent classes and attacker entrypoints,\nthey are a setup for running a simulation. This is how the format looks like:\n\n```yml\nlang_file: <path to .mar-archive>\nmodel_file: <path to json/yml model>\n\nattacker_agent_class: 'BreadthFirstAttacker' | 'DepthFirstAttacker' | 'KeyboardAgent'\n\n# For defender_agent_class, null and False are treated the same - no defender will be used in the simulation\ndefender_agent_class: 'BreadthFirstAttacker' | 'DepthFirstAttacker' | 'KeyboardAgent' | null | False\n\n\n# Optionally add rewards for each attack step\nrewards:\n <full name of attack step>: <reward>\n\n # example:\n # Program 1:notPresent: 3\n # Data A:read: 100\n ...\n\n\n# Optionally add entry points to AttackGraph with attacker name and attack step full_names.\n# NOTE: If attacker entry points defined in both model and scenario,\n# the scenario overrides the ones in the model.\nattacker_entry_points:\n <attacker name>:\n - <attack step full name>\n\n # example:\n # 'Attacker1':\n # - 'Credentials:6:attemptCredentialsReuse'\n\n# Optionally add observability rules that are applied to AttackGrapNodes\n# to make only certain steps observable\n#\n# If 'observable_steps' are set:\n# - Nodes that match any rule will be marked as observable\n# - Nodes that don't match any rules will be marked as non-observable\n# If 'observable_steps' are not set:\n# - All nodes will be marked as observable\n#\nobservable_steps:\n by_asset_type:\n <asset_type>:\n - <step name>\n by_asset_name:\n <asset_name>:\n - <step name>\n\n# Optionally add actionability rules that are applied to AttackGrapNodes\n# to make only certain steps actionable\n# Works exactly as observability\n#\nactionable_steps:\n by_asset_type:\n <asset_type>:\n - <step name>\n by_asset_name:\n <asset_name>:\n - <step name>\n\n # Example:\n # by_asset_type:\n # Host:\n # - access\n # - authenticate\n # Data:\n # - read\n\n # by_asset_name:\n # User:3:\n # - phishing\n # ...\n\n```\n\nNote: When defining attackers and entrypoints in a scenario, these override potential attackers in the model.\n\n### Loading a scenario from a python script\n\n#### Load attack graph and config\n\nIf you just want to load a resulting attack graph from a scenario, use `malsim.scenarios.load_scenario`.\n\n```python\nfrom malsim.scenarios import load_scenario\n\nscenario_file = \"scenario.yml\"\nattack_graph, sim_config = load_scenario(scenario_file)\n\n```\n\n#### Load simulator and config\n\nIf you instead want to load a simulator, use `malsim.scenarios.create_simulator_from_scenario`.\n\n```python\nfrom malsim.scenarios import create_simulator_from_scenario\n\nscenario_file = \"scenario.yml\"\nmal_simulator, sim_config = create_simulator_from_scenario(scenario_file)\n\n```\nThe returned MalSimulator contains the attackgraph created from\nthe scenario, as well as registered agents. At this point, simulator and sim_config\n(which contains the agent classes) can be used for running a simulation\n(refer to malsim.cli.run_simulation or wrappers.gym_wrappers to see example of this).\n\n\n## CLI\n\n### Running a scenario simulation with the CLI\n\n```\nusage: malsim [-h] [-o OUTPUT_ATTACK_GRAPH] scenario_file\n\npositional arguments:\n scenario_file Can be found in https://github.com/mal-lang/malsim-scenarios/\n\noptions:\n -h, --help show this help message and exit\n -o OUTPUT_ATTACK_GRAPH, --output-attack-graph OUTPUT_ATTACK_GRAPH\n If set to a path, attack graph will be dumped there\n```\n\nThis will create an attack using the configuration in the scenarios file, apply the rewards, add the attacker and run the simulation with the attacker.\nCurrently having more than one attacker in the scenario file will have no effect to how the simulation is run, it will only run the first one as an agent.\n",
"bugtrack_url": null,
"license": "Apache Software License",
"summary": "A MAL compliant simulator.",
"version": "0.0.38",
"project_urls": {
"Bug Tracker": "https://github.com/mal-lang/mal-simulator/issues",
"Homepage": "https://github.com/mal-lang/mal-simulator",
"Repository": "https://github.com/mal-lang/mal-simulator"
},
"split_keywords": [
"mal"
],
"urls": [
{
"comment_text": "",
"digests": {
"blake2b_256": "73e1370841896e7bd05067a05c49f88f9a112cdaa3ca3e691ee6bb378047f065",
"md5": "9d0534cb3112606107c02b2b2f4e4bca",
"sha256": "f1631e2b68446e812727d008cd40723cd3287ee0a4bd731a77c4b8413099e507"
},
"downloads": -1,
"filename": "mal_simulator-0.0.38-py3-none-any.whl",
"has_sig": false,
"md5_digest": "9d0534cb3112606107c02b2b2f4e4bca",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.10",
"size": 28560,
"upload_time": "2024-11-06T14:27:48",
"upload_time_iso_8601": "2024-11-06T14:27:48.160186Z",
"url": "https://files.pythonhosted.org/packages/73/e1/370841896e7bd05067a05c49f88f9a112cdaa3ca3e691ee6bb378047f065/mal_simulator-0.0.38-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": "",
"digests": {
"blake2b_256": "80c2af8bf06004df3ef3e57cdd6f2668d9de0a75435bf10444d2ff1b85e0db71",
"md5": "715eb189f2f652f6a5149ac5d40b2087",
"sha256": "eb4771f97008c76b9f52b24293618e133758086632f5b9ebf7e32016ff812258"
},
"downloads": -1,
"filename": "mal_simulator-0.0.38.tar.gz",
"has_sig": false,
"md5_digest": "715eb189f2f652f6a5149ac5d40b2087",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.10",
"size": 33937,
"upload_time": "2024-11-06T14:27:49",
"upload_time_iso_8601": "2024-11-06T14:27:49.602352Z",
"url": "https://files.pythonhosted.org/packages/80/c2/af8bf06004df3ef3e57cdd6f2668d9de0a75435bf10444d2ff1b85e0db71/mal_simulator-0.0.38.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2024-11-06 14:27:49",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "mal-lang",
"github_project": "mal-simulator",
"travis_ci": false,
"coveralls": false,
"github_actions": true,
"lcname": "mal-simulator"
}
