Skip to main content

A MAL compliant simulator.

Project description

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.

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:

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.

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.

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.

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Source Distribution

mal_simulator-0.0.39.tar.gz (33.9 kB view details)

Uploaded Source

Built Distribution

mal_simulator-0.0.39-py3-none-any.whl (28.6 kB view details)

Uploaded Python 3

File details

Details for the file mal_simulator-0.0.39.tar.gz.

File metadata

  • Download URL: mal_simulator-0.0.39.tar.gz
  • Upload date:
  • Size: 33.9 kB
  • Tags: Source
  • Uploaded using Trusted Publishing? Yes
  • Uploaded via: twine/5.1.1 CPython/3.12.7

File hashes

Hashes for mal_simulator-0.0.39.tar.gz
Algorithm Hash digest
SHA256 7d4b5274d43428c8d3688964cfaaa629d0573a928bb90ce46682eecaf9ecaa78
MD5 93da28ce28d176cde3e9124058f4ccda
BLAKE2b-256 86e59388ab7047cb6461b1fb79be6d05ae5c8fbf528adfef0df3916b1c335d57

See more details on using hashes here.

Provenance

The following attestation bundles were made for mal_simulator-0.0.39.tar.gz:

Publisher: publish-to-pypi-and-test-pypi.yml on mal-lang/mal-simulator

Attestations:

File details

Details for the file mal_simulator-0.0.39-py3-none-any.whl.

File metadata

File hashes

Hashes for mal_simulator-0.0.39-py3-none-any.whl
Algorithm Hash digest
SHA256 c7486d5c6cefe0570ef37ff542e4cb5ad77b9e62716512f8a1f3c3016105f1a4
MD5 3236d5eaa2a1e707d24aa9e25d41c90b
BLAKE2b-256 3a4dfff29e48a1d8a5fdd8dd22e0427465c2eaa6ad1b0b60b0845d71d5b54b4a

See more details on using hashes here.

Provenance

The following attestation bundles were made for mal_simulator-0.0.39-py3-none-any.whl:

Publisher: publish-to-pypi-and-test-pypi.yml on mal-lang/mal-simulator

Attestations:

Supported by

AWS AWS Cloud computing and Security Sponsor Datadog Datadog Monitoring Fastly Fastly CDN Google Google Download Analytics Microsoft Microsoft PSF Sponsor Pingdom Pingdom Monitoring Sentry Sentry Error logging StatusPage StatusPage Status page