Metadata-Version: 2.4
Name: mal-toolbox
Version: 2.6.0
Summary: A collection of tools used to create MAL models and attack graphs.
Author-email: Andrei Buhaiu <buhaiu@kth.se>, Joakim Loxdal <loxdal@kth.se>, Nikolaos Kakouros <nkak@kth.se>, Jakob Nyberg <jaknyb@kth.se>, Giuseppe Nebbione <nebbione@kth.se>, Sandor Berglund <sandor@kth.se>
License: Apache Software License
Project-URL: Homepage, https://github.com/mal-lang/mal-toolbox
Project-URL: Bug Tracker, https://github.com/mal-lang/mal-toolbox/issues
Project-URL: Repository, https://github.com/mal-lang/mal-toolbox
Keywords: mal
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Science/Research
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: Apache Software License
Classifier: Operating System :: OS Independent
Classifier: Topic :: Scientific/Engineering
Requires-Python: >=3.10
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: AUTHORS
Requires-Dist: graphviz
Requires-Dist: antlr4-tools
Requires-Dist: antlr4-python3-runtime
Requires-Dist: docopt
Requires-Dist: PyYAML
Requires-Dist: py2neo
Requires-Dist: networkx
Requires-Dist: tree-sitter-mal<2.0.0,>=1.2.1
Requires-Dist: tree-sitter
Provides-Extra: dev
Requires-Dist: pytest; extra == "dev"
Dynamic: license-file

# MAL Toolbox
## Overview
MAL Toolbox is a collection of python modules to help developers create models and attack graphs by working with the **Meta Attack Language (MAL)**.

It allows you to:
- Create system models from MAL languages.
- Create attack graphs that can be used to run simulations in [MAL Simulator](https://github.com/mal-lang/mal-simulator) or run your own custom analysis on.

For in-depth documentation and tutorials refer to the [mal-toolbox Wiki](https://github.com/mal-lang/mal-toolbox/wiki) and the [mal-tutorials repository](https://github.com/mal-lang/mal-toolbox-tutorial).

# 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

1. Make a PR with one commit that updates the version number in `pyproject.toml` and `maltoolbox/__init__.py`.
Follow [Semantic versioning](https://semver.org/).

2. Get the PR reviewed and merged to `main`.

3. Tag the latest commit on `main` with the new version number.

4. Push the tag.

# 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](https://graphviz.org/download/).

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:
```yml
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.

```bash
# 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.```
```
