mal-toolbox

MAL Toolbox overview

MAL Toolbox is a collection of python modules to help developers create and work with MAL (Meta Attack Language) models and attack graphs.

Attack graphs can be used to run simulations in MAL Simulator or run your own custom analysis on.

• MAL Toolbox Documentation
• MAL Toolbox tutorial

Usage

Installation

pip install mal-toolbox

Requirements

If you wish to run visualisations with graphviz, you must first download and install it on your computer. Depending on your operating system, you can find out how to do this here: link to graphviz installation.

Once the software has been successfully installed, you must also include the python package by running:

pip install graphviz

Configuration

You can use a maltoolbox.yml file in the current working directory to configure the toolbox.

The config should look like this:

logging:
  log_level: INFO
  log_file: "logs/log.txt"
  attackgraph_file: "logs/attackgraph.json"
  model_file: "logs/model.yml"
  langspec_file: "logs/langspec_file.yml"
  langgraph_file: "logs/langspec_file.yml"
neo4j:
  uri: None
  username: None
  password: None
  dbname: None

Alternatively, you can use the MALTOOLBOX_CONFIG environment variable to set a custom config file location.

# in your shell, e.g. bash do:
export MALTOOLBOX_CONFIG=path/to/yml/config/file

The default configuration can be found here:

https://github.com/mal-lang/mal-toolbox/blob/main/maltoolbox/__init__.py#L39-L53

Command Line Client

You can use the maltoolbox cli to:

• Generate attack graphs from model files
• Compile MAL languages
• Upgrade model files from older versions

Command-line interface for MAL toolbox operations

Usage:
    maltoolbox compile <lang_file> <output_file>
    maltoolbox generate-attack-graph [--graphviz] <model_file> <lang_file>
    maltoolbox upgrade-model <model_file> <lang_file> <output_file>
    maltoolbox visualize-model <model_file> <lang_file>

Arguments:
    <model_file>    Path to JSON instance model file.
    <lang_file>     Path to .mar or .mal file containing MAL spec.
    <output_file>   Path to write the result of the compilation (yml/json).

Options:
  -h --help         Show this screen.
  -g --graphviz     Visualize with graphviz

Notes:
    - <lang_file> can be either a .mar file (generated by the older MAL
      compiler) or a .mal file containing the DSL written in MAL.```

Contributing

CI Pipeline

Checks are made with:

• mypy
• ruff
• pytest

Make sure pipeline passes before PR is marked "Ready for review".

Tests

There are unit tests inside of ./tests.

To run all tests, use the pytest command. To run just a specific file or test function use pytest tests/<filename> or pytest -k <function_name>.

Making a release

• Make a PR with one commit that updates the version number in pyproject.toml and maltoolbox/__init__.py. Follow Semantic versioning.

• Get the PR reviewed and merged to main.

• Tag the latest commit on main with the new version number.

• Push the tag.