Metadata-Version: 2.1
Name: mal-toolbox
Version: 0.0.12
Summary: A collection of tools used to create MAL models and attack graphs.
Author-email: Andrei Buhaiu <buhaiu@kth.se>, Giuseppe Nebbione <nebbione@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: py2neo>=2021.2.3
Requires-Dist: python-jsonschema-objects>=0.4.1

# Overview

A collection of python modules to help developers create and work with MAL
models and attack graphs.

# The Language Module

The language module provides various tools to process MAL languages.

## The Language Specification Submodule

The language specification submodule provides functions to load the
specification from a .mar archive(`load_language_specification_from_mar`) or a
JSON file(`load_language_specification_from_json`). This specification will
then be used to generate python classes representing the assets and
associations of the language and to determine the attack steps for each asset
when generating the attack graph.

## The Language Classes Factory Submodule

The language classes factory submodule is used to generate python classes
using the `python_jsonschema_objects` package from a language specification.
The classes generated by the `create_classes` function can then be accessed
from within that namespace(.e.g: `lang_classes_factory.ns.Application()`,
`lang_classes_factory.ns.AppExecution()`). Because these classes are built
using JSON Schema validators they will enforce their restrictions when using
the python objects created. These classes are typically used in conjunction
with model module to create instance models.

# The Model Module

The model module is used to create MAL instance models. The model class will
store all of the relevant information to the MAL instance model, most
importantly the assets and associations that make it up. These assets and
associations should be objects created using the language classes factory
submodule. It also allows for `Attacker` objects to be created and associated
with attack steps on assets in the model. The most relevant functions here are
the ones used to add different elements to the model, `add_asset`,
`add_association`, and `add_attacker`. Model objects can be used to generate
attack graphs using the attack graph 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.

If it is relevant the `attach_attackers` function can be called on the
resulting attack graph with the instance model given as a parameter in order
to create attack step nodes that represent the entry points of the attackers
and attach them to the attack steps specified in the instance model.

# Ingestors Module

The ingestors module contains various tools that can make use of the instance
model or attack graph. Currently the Neo4J ingestor is the only one available
and it can be used to visualise the instance model and the attack graph.

# Command Line Client

In addition to the modules that make up the MAL-Toolbox package it also
provides a simple command line client that can be used to easily generate
attack graphs from a .mar language specification file and a JSON instance
model file.

The usage is: `maltoolbox gen_ag [--neo4j] <model_json_file>
<language_mar_file>`

If the `--neo4j` flag is specified the model and attack graph will be loaded
into a local Neo4J instance.

# Configuration
A default configuration file `default.conf` can be found in the package
directory. This contains the default values to use for logging and can also be
used to store the information needed to access the local Neo4J instance.
