Skip to main content

MAL Simulator

Overview

The MAL Simulator is a tool designed for running simulations on systems modeled in the Meta Attack Language (MAL).

It allows you to:

  • Simulate the adversarial and defensive actions of intelligent agents (attackers and defenders).
  • Analyze system security and evaluate attack/defense strategies.
  • Develop machine learning agents (e.g., using Reinforcement Learning) in a safe, dynamic environment.
  • Incorporate stochastic modeling through Time-to-Compromise (TTC) distributions.

For in-depth documentation, refer to:

The simulator also has a DOI at the KTH Open and FAIR Data repository for easier referencing: 10.71775/kth.gx42q-9m748

Contributing

  • Use Conventional commits
  • The CI pipeline runs pytest, mypy and ruff format && ruff check for linting and type checking. PRs will only be merged if pipeline succeeds.

Making a release

  • Make a release PR (called release-x.y.z) with your changes. Update version number in pyproject.toml and malsim/__init__.py.
  • Merge the PR after the pipeline suceeds
  • Tag the latest commit with the new version number
  • Push the tag

🛠️ How to Run a Simulation

1. Installation

pip install mal-simulator

To also get ML dependencies (pettingzoo, gymnasium):

pip install mal-simulator[ml]

For additional dev tools:

pip install mal-simulator[dev]

2. Running a Scenario via CLI

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.

The basic command structure is:

malsim <scenario_file> [options]

Example

Execute a simulation defined in my_scenario.yml:

malsim my_scenario.yml

Common Options:

Option Description
-s, --seed SEED Sets the random seed for deterministic simulations.
-t, --ttc-mode MODE Sets the Time-to-Compromise mode (e.g., DISABLED, PER_STEP_SAMPLE).
-g, --send-to-gui Sends simulation data to the malsim-gui for visualization (requires the GUI to be running).

3. Programmatic Usage

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:

from malsim import MalSimulator, run_simulation, Scenario

# 1. Load the scenario configuration
SCENARIO_FILE = "my_scenario.yml"
scenario = Scenario.load_from_file(SCENARIO_FILE)

# 2. Create the simulator instance
sim = MalSimulator.from_scenario(scenario)

# 3. Run the simulation
agent_actions = run_simulation(sim, scenario.agents)

print("Simulation finished. Agent actions:", agent_actions)

You can also run your own simulation loop.

from malsim import MalSimulator, Scenario

scenario = Scenario.load_from_file("my_scenario.yml")
sim = MalSimulator.from_scenario(scenario)
agent_states = sim.reset()

while not sim.done():
    # ... calculate actions for each agent
    agent_states = sim.step(actions)

Read the Wiki for more ways to run the simulator.

Metadata

Release files for mal-simulator 3.3.1

For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.

Source distribution (sdist)

Source distribution for mal-simulator 3.3.1
File Size Uploaded Provenance Actions
mal_simulator-3.3.1.tar.gz 101.1 kB With provenance Details for mal_simulator-3.3.1.tar.gz

Built distribution (wheel)

Table of built distributions (wheels) for mal-simulator 3.3.1
File Interpreter ABI Platform Actions
mal_simulator-3.3.1-py3-none-any.whl Python 3 none any Details for mal_simulator-3.3.1-py3-none-any.whl

Total release size: 197.6 kB

Release files / mal_simulator-3.3.1.tar.gz

Download URL mal_simulator-3.3.1.tar.gz
Size 101.1 kB
Tags Source
SHA-256 checksum
How to use checksums
402625693e4fd0cd3bbb8c9330d7b44f68c5c5bd4a9f8e8b89689d8933fbf952
BLAKE2b-256 checksum
How to use checksums
4da0d319aff9f26ae8f860c9af9feca54f380e2c6a7451a402b2d53bf601ae40
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Release files / mal_simulator-3.3.1-py3-none-any.whl

Download URL mal_simulator-3.3.1-py3-none-any.whl
Size 96.5 kB
Tags Python 3
SHA-256 checksum
How to use checksums
f1f3ee056681b361c9a5108e8197e926cb93656e84048a3dd5bfdeb835143266
BLAKE2b-256 checksum
How to use checksums
ad2da31efb4d10c564177ac2cf53cbe72f465efc5d01cd09f591420b06d8cbca
Upload date
Uploaded using Trusted Publishing?
What is trusted publishing?
Yes
Uploaded via twine/7.0.0 CPython/3.13.16

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

Security for mal-simulator 3.3.1

Provenance

Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.

Full provenance

Both files in this release have been uploaded with provenance metadata.

Select from 2 files

Attestation for mal_simulator-3.3.1.tar.gz

PyPI Publish Attestation

PyPI verified that this artifact, at this checksum, originated from the publisher listed below.

Signed by GitHub Actions, verified by PyPI on Nov 19, 2026.

Transparency log

A note on package security

PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.

To learn more about protecting yourself from malicious actors, visit our package security documentation.

Release history Release notifications | RSS feed

This release

3.3.1 This release

2 release files Full provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page