Metadata-Version: 2.4
Name: mal-toolbox
Version: 1.1.2
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
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 and work with
MAL ([Meta Attack Language](https://mal-lang.org/)) models and attack graphs.

Attack graphs can be used to run simulations in [MAL Simulator](https://github.com/mal-lang/mal-simulator) or run your own custom analysis on.

- [MAL Toolbox Documentation](https://mal-lang.org/mal-toolbox/index.html)
- [MAL Toolbox tutorial](https://github.com/mal-lang/mal-toolbox-tutorial)

## The Language Module

The language module provides various tools to process MAL languages.

## The Model Module

With a MAL language a Model (a MAL instance model) can be created either
from a model file or empty.

The model class will store all of the relevant information to the MAL
instance model, most importantly the assets and their associations.

Model objects can be used to generate attack graphs with the AttackGraph module.

## The Attack Graph Module

The attack graph module contains tools used to generate attack graphs from
existing MAL instance models and analyse MAL attack graphs. The function used
to generate the attack graph is `generate_graph` and it requires the instance
model and language specification. The resulting attack graph will contain
nodes for each of the attack steps. The structure of the attack node data
class can be seen in `attackgraph/node.py` file. Of note are the lists of
children and parents which allow for easy reference to the other attack step
nodes related and the asset field which will contain the object in the model
instance to which this attack step belongs to, if this information is
available.


# Usage

## Installation

```
pip install mal-toolbox
```

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

## Code examples / Tutorial

To find more code examples and tutorials, visit the
[MAL Toolbox Tutorial](https://github.com/mal-lang/mal-toolbox-tutorial/tree/main) repository.

### Load a language
```python

from maltoolbox.language import LanguageGraph

# Will load the MAL language (.mal/.mar) or a saved language graph (yml/json)
lang_graph = LanguageGraph.load_from_file(lang_file_path)

```

### Generate a model
```python
from maltoolbox.model import Model

# Create an empty model
instance_model = Model("Example Model", lang_graph)

# Create and add assets of type supported by the MAL language
asset1 = instance_model.add_asset('Application', 'Application1')
asset2 = instance_model.add_asset('Application', 'Application2')

# Create association between the assets
asset1.add_associated_assets('appExecutedApps', asset2)
```

## Generate an attack graph

```python

from maltoolbox.attackgraph import AttackGraph

attack_graph = AttackGraph(lang_graph, model)

```


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