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,mypyandruff format && ruff checkfor 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 inpyproject.tomlandmalsim/__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.
1 maintainer
Metadata
1 maintainer
Release files for mal-simulator 3.2.1
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | |
|---|---|---|---|
| mal_simulator-3.2.1.tar.gz | 81.0 kB | Details |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Reset |
|---|---|---|---|---|
| mal_simulator-3.2.1-py3-none-any.whl | Python 3 | none | any | Details |
Total release size: 162.5 kB
Release files / mal_simulator-3.2.1.tar.gz
| Download URL | mal_simulator-3.2.1.tar.gz |
|---|---|
| Size | 81.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
a3ce5a1c8ee3c91d9e84377136193d037b0cb93c2c518ce9f648a7134bb3d821
|
|
BLAKE2b-256 checksum How to use checksums |
24770154ba1cf050db716150f7c394b791e4241de8bb13cf391f9891f99f0c0e
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 29, 2026.
Transparency logRelease files / mal_simulator-3.2.1-py3-none-any.whl
| Download URL | mal_simulator-3.2.1-py3-none-any.whl |
|---|---|
| Size | 81.5 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
17c0cb23206cbede148bddddc5ed53fc186aaf6d4a72a8ada70d548b81e6d6bb
|
|
BLAKE2b-256 checksum How to use checksums |
5bfb12f171d31e171840916ae4a53ec79a6b58fd9c34a1b79f6b170fb35d7242
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
Yes |
| Uploaded via |
twine/7.0.0 CPython/3.13.14
|
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 Sep 29, 2026.
Transparency log
